mirror of
https://github.com/trustgraph-ai/trustgraph.git
synced 2026-07-01 09:29:38 +02:00
81 lines
3.1 KiB
Markdown
81 lines
3.1 KiB
Markdown
|
# TrustGraph TS Effect-Native Status
|
||
|
|
|
||
|
|
## Current State
|
||
|
|
|
||
|
|
The TypeScript port on `ts-port-effect-v4` is Effect-first across the production
|
||
|
|
runtime surfaces completed in Phases 0-6. The law baseline is empty:
|
||
|
|
`scripts/effect-laws.allowlist.json` has no baseline entries and one documented
|
||
|
|
host-boundary exemption. The native-class inventory reports zero blocking
|
||
|
|
production native classes.
|
||
|
|
|
||
|
|
The client package's public barrel exports the Effect RPC gateway surface and
|
||
|
|
shared data models. The legacy `trustgraph-socket.ts` Promise `BaseApi` shim is
|
||
|
|
kept out of the package barrel and remains only for direct client tests.
|
||
|
|
Workbench QA uses its own minimal mock API shape.
|
||
|
|
|
||
|
|
## Adapted Effect Laws
|
||
|
|
|
||
|
|
- Data that crosses wires, persistence, or domain boundaries uses `S.Class`,
|
||
|
|
`S.Struct`, or tagged schema unions. Service contracts and option bags may
|
||
|
|
remain interfaces.
|
||
|
|
- Production code reads configuration through `Config`, not `process.env`.
|
||
|
|
- JSON encode/decode goes through Schema codecs such as
|
||
|
|
`S.UnknownFromJsonString`.
|
||
|
|
- HTTP clients use `effect/unstable/http` with platform layers.
|
||
|
|
- Effects run at entrypoints through platform `runMain`; libraries return
|
||
|
|
`Effect`, `Stream`, `Layer`, or service values.
|
||
|
|
- Deterministic ordering uses `effect/Array` and explicit `Order`s.
|
||
|
|
- File/path work uses platform services rather than `node:fs` or `node:path`.
|
||
|
|
- Errors owned by TrustGraph code use tagged errors on the Effect channel.
|
||
|
|
|
||
|
|
## Standing Exemptions
|
||
|
|
|
||
|
|
- `packages/workbench/src/main.tsx` may throw if `#root` is missing. This is a
|
||
|
|
browser host boundary and the app cannot render without the mount point.
|
||
|
|
- `packages/flow/src/agent/mcp-tool/service.ts` may use the
|
||
|
|
`@modelcontextprotocol/sdk` client behind Effect wrappers. Effect v4 provides
|
||
|
|
server-side MCP support here, not a replacement client.
|
||
|
|
- Provider SDK integrations for OpenAI, Azure OpenAI, OpenAI-compatible,
|
||
|
|
Mistral, and Ollama stay behind `Effect.tryPromise` and
|
||
|
|
`makeLanguageModelProvider`. Claude already uses `@effect/ai-anthropic`.
|
||
|
|
- `PubSubBackend` remains a broker adapter contract. Effect `PubSub` is
|
||
|
|
in-process only and is not a NATS replacement.
|
||
|
|
- Tests and QA fixtures are excluded from production law checks.
|
||
|
|
|
||
|
|
## Gate Commands
|
||
|
|
|
||
|
|
Phase 6 validation:
|
||
|
|
|
||
|
|
```sh
|
||
|
|
bun run check
|
||
|
|
bun run lint
|
||
|
|
bunx --bun turbo test build --force
|
||
|
|
git diff --check
|
||
|
|
```
|
||
|
|
|
||
|
|
Final Phase 7 acceptance, all no-cache where applicable:
|
||
|
|
|
||
|
|
```sh
|
||
|
|
bun run check:tsgo
|
||
|
|
bunx --bun turbo build lint test --force
|
||
|
|
bun run --cwd packages/mcp test
|
||
|
|
bun run workbench:qa
|
||
|
|
cd deploy && docker compose -f docker-compose.yml -f docker-compose.dev.yml up -d --build
|
||
|
|
bun run seed && bun run seed:flows && bun run seed:demo
|
||
|
|
SKIP_LLM=1 bun run test:pipeline
|
||
|
|
git diff --check
|
||
|
|
```
|
||
|
|
|
||
|
|
Final source audits:
|
||
|
|
|
||
|
|
```sh
|
||
|
|
bun scripts/check-effect-laws.ts
|
||
|
|
bun scripts/inventory-native-classes.ts
|
||
|
|
rg -n "fastify|@fastify/websocket|commander|zod" package.json packages scripts bun.lock
|
||
|
|
rg -n "@modelcontextprotocol/sdk" packages scripts package.json bun.lock
|
||
|
|
```
|
||
|
|
|
||
|
|
Expected result: no law baseline debt, zero blocking native classes, no Fastify,
|
||
|
|
Commander, Zod, or server-side MCP SDK reintroduction. The MCP SDK client
|
||
|
|
exemption remains documented above.
|