# TrustGraph Effect-Native Rewrite Playbook This playbook is the context packet for read-only sub-agents that audit the TrustGraph TypeScript port for code that hand-rolls behavior already provided by Effect v4. It is not an implementation plan for a single rewrite. Its job is to make future scouts fast, grounded, and allergic to invented APIs. ## Source Baseline Verify these paths at the start of every audit run: - TrustGraph TS port: `/home/elpresidank/YeeBois/dev/trustgraph/ts` - Effect v4 subtree: `/home/elpresidank/YeeBois/projects/beep-effect2/.repos/effect-v4` - Installed Effect fallback: `ts/node_modules/effect` - Installed Atom React fallback: `ts/packages/workbench/node_modules/@effect/atom-react` - Native TypeScript checker: `ts/node_modules/.bin/tsgo` The prompt typo path `~/YeeBois/projecects/...` is not valid on this machine. Use `~/YeeBois/projects/...`. When a package is not present in the subtree, verify it from TrustGraph's installed package sources before proposing a replacement. This matters for `effect/unstable/reactivity`, `effect/unstable/ai`, `effect/unstable/rpc`, `effect/unstable/socket`, `effect/unstable/http`, `effect/unstable/httpapi`, and `@effect/atom-react`. Important import rule: the Effect v4 subtree contains separate packages such as `@effect/ai`, `@effect/rpc`, and `@effect/platform`, but TrustGraph currently resolves many beta APIs through `effect/unstable/*` import paths. Prefer the installed TrustGraph import path when it exists; use the subtree package path as source proof, not as an automatic import recommendation. TrustGraph's TypeScript check must use `@typescript/native-preview` patched by `@effect/tsgo`. The expected local version line is currently: ```sh cd ts && ./node_modules/.bin/tsgo --version # Version 7.0.0-dev+effect-tsgo.0.13.0 ``` The root `ts/tsconfig.base.json` language-service plugin should stay aligned with `/home/elpresidank/YeeBois/projects/beep-effect/tsconfig.base.json`, using the same diagnostic severities and no test-only diagnostic downgrades. The repo-specific `namespaceImportPackages` entry should use `@trustgraph/*`. The root `check` script should delegate to `check:tsgo`, and `check:tsgo` must run `effect-tsgo patch` before `tsgo -b` so agents get Effect diagnostics instead of plain TypeScript. Treat every `effect(...)` diagnostic as a hard blocker. ## Primitive Map Use this map as the starting baseline. A finding is only valid when it cites the TrustGraph path, the import path, and the Effect source path that proves the primitive exists. | Handrolled pattern | Preferred Effect primitive | Import path | Verified source | | --- | --- | --- | --- | | Promise loops, top-level async orchestration | `Effect`, `Effect.fn`, `Effect.scoped`, `Effect.runPromiseWith` at boundaries | `effect` | `packages/effect/src/Effect.ts` | | Resource construction and teardown | `Layer`, `Scope`, `Effect.acquireRelease`, `Effect.addFinalizer` | `effect` | `packages/effect/src/Layer.ts`, `packages/effect/src/Scope.ts` | | Mutable service state | `Ref`, `SynchronizedRef`, `SubscriptionRef` | `effect` | `packages/effect/src/Ref.ts`, `packages/effect/src/SynchronizedRef.ts` | | Polling, delays, retry/backoff | `Schedule`, `Effect.sleep`, `Effect.retry` | `effect` | `packages/effect/src/Schedule.ts`, `packages/effect/src/Effect.ts` | | Callback queues and streaming fanout | `Queue`, `PubSub`, `Stream`, `Channel` | `effect` | `packages/effect/src/Queue.ts`, `packages/effect/src/PubSub.ts`, `packages/effect/src/Stream.ts`, `packages/effect/src/Channel.ts` | | Env/config decoding | `Config`, `ConfigProvider`, platform config providers | `effect`, `effect/ConfigProvider`, provider packages | `packages/effect/src/Config.ts`, `packages/effect/src/ConfigProvider.ts`, `packages/platform/src/PlatformConfigProvider.ts` | | JSON/wire schemas | `Schema`, `ParseResult`, `RpcSchema` | `effect/Schema`, `effect/unstable/rpc/RpcSchema` | `packages/effect/src/Schema.ts`, `ts/node_modules/effect/src/unstable/rpc/RpcSchema.ts` | | WebSocket lifecycle and framing | `Socket`, `RpcClient`, `RpcServer`, `RpcSerialization` | `effect/unstable/socket`, `effect/unstable/rpc` | `ts/node_modules/effect/src/unstable/socket/*.ts`, `ts/node_modules/effect/src/unstable/rpc/*.ts` | | HTTP servers/clients and typed APIs | `HttpApi`, `HttpApiClient`, `HttpApiBuilder`, `HttpClient`, `HttpServer` | `effect/unstable/http`, `effect/unstable/httpapi`, platform providers | `ts/node_modules/effect/src/unstable/http/*.ts`, `ts/node_modules/effect/src/unstable/httpapi/*.ts` | | File, storage, and process IO | `FileSystem`, `KeyValueStore`, `ChildProcess`, `ChildProcessSpawner` | `effect/FileSystem`, `effect/unstable/persistence/KeyValueStore`, `effect/unstable/process/*`, provider packages | `ts/node_modules/effect/src/FileSystem.ts`, `ts/node_modules/effect/src/unstable/persistence/KeyValueStore.ts`, `ts/node_modules/effect/src/unstable/process/*.ts` | | Browser local storage and clipboard | `BrowserKeyValueStore`, `Clipboard`, `BrowserHttpClient`, `BrowserSocket` | `@effect/platform-browser/*` | `ts/node_modules/.bun/@effect+platform-browser@4.0.0-beta.75+a5c1409dbf4ddafe/node_modules/@effect/platform-browser/src/*.ts` | | AI tools, MCP, and model calls | `Tool`, `Toolkit`, `McpServer`, `McpSchema`, `LanguageModel`, provider layers | `effect/unstable/ai`, provider packages such as `@effect/ai-openai` | `ts/node_modules/effect/src/unstable/ai/*.ts`, `packages/ai/ai/src/*.ts` | | Workbench async state | `Atom`, `AtomRpc`, `AtomHttpApi`, `AsyncResult`, `AtomRegistry`, `Reactivity` | `effect/unstable/reactivity`, `@effect/atom-react` | `ts/node_modules/effect/src/unstable/reactivity/*.ts`, `ts/packages/workbench/node_modules/@effect/atom-react/src/*.ts` | | Metrics and logs | `Metric`, `Logger`, `Effect.log*` | `effect`, `@effect/opentelemetry` | `packages/effect/src/Metric.ts`, `packages/effect/src/Logger.ts` | | Normal internal errors | `S.TaggedErrorClass` and existing TrustGraph tagged errors | `effect/Schema`, `@trustgraph/base/errors` | `packages/effect/src/Schema.ts`, `ts/packages/base/src/errors.ts` | | Imperative exception capture | `Effect.try`, `Effect.tryPromise`, or `Result.try` | `effect`, `effect/Result` | `packages/effect/src/Effect.ts`, `packages/effect/src/Result.ts` | Known concrete exports useful to scouts: - `Socket.makeWebSocket`, `Socket.fromWebSocket`, `Socket.toChannel`, `Socket.toChannelString`, `Socket.layerWebSocket`. - `RpcClient.layerProtocolSocket`, `RpcServer.layerProtocolWebsocket`, `RpcServer.layerProtocolSocketServer`, `RpcSerialization.layerNdjson`, `RpcSerialization.layerNdJsonRpc`. - `BunFileSystem`, `BunSocket`, `BunHttpClient`, `BunHttpServer`, `BunRuntime`, `BunChildProcessSpawner` from `@effect/platform-bun`. - `BrowserKeyValueStore.layerLocalStorage`, `BrowserKeyValueStore.layerSessionStorage`, `BrowserHttpClient.layerXMLHttpRequest`. - `Atom.make`, `Atom.runtime`, `Atom.fn`, `Atom.family`, `Atom.subscriptionRef`, `AtomRegistry.layer`, `Reactivity.layer`, `Reactivity.query`, `Reactivity.stream`, `Reactivity.mutation`. - `Tool.make`, `Toolkit.make`, `McpServer.registerToolkit`, `LanguageModel.generateText`, `LanguageModel.streamText`. - `S.TaggedErrorClass` for internal/library errors. Treat `new Error` inside library internals as migration evidence unless it is a host/tool boundary, test-only helper, or externally mandated error shape. - `Effect.try`, `Effect.tryPromise`, and `Result.try` for exception capture. Treat `try`/`catch` blocks as migration evidence unless they are host/tool boundaries or test-only helpers. ## Scout Workflow 1. Confirm repo state with `git status -sb`. Preserve unrelated files, especially `.idea/effect.intellij.xml`. 2. Refresh the source baseline above. If a path moved, record the corrected path in the report before making any recommendations. 3. Verify the tsgo baseline: ```sh cd ts && ./node_modules/.bin/tsgo --version bun run check ``` 4. Run quick signal scans: ```sh rg -n "try \\{|new Error|new Promise|setTimeout|while \\(|receive\\(|Effect\\.runPromise|toPromiseRequestor|makeAsyncProcessor|process\\.env|JSON\\.parse|JSON\\.stringify|localStorage|new Map|WebSocket" ts/packages --glob '*.ts' --glob '*.tsx' ``` 5. Split scouts by lane. If the thread cannot spawn every scout in parallel, run them in batches using the same report schema. 6. Every finding must include both: - Evidence of the handrolled TrustGraph pattern. - Evidence of the exact Effect primitive that could replace it. 7. Do not rewrite code in this audit. The output is a ranked opportunity map and a recommended PR order. ## Agent Lanes Use these lane prompts as the durable starting point. ### Base Messaging And Processor Runtime Inspect `ts/packages/base/src/messaging`, `ts/packages/base/src/processor`, and `ts/packages/base/src/spec`. Find Promise compatibility facades, polling receivers, manual request/response caches, top-level `Effect.runPromise`, and mutable maps. Compare against `Queue`, `PubSub`, `Stream`, `Scope`, `Layer`, `Schedule`, `Ref`, and `SynchronizedRef`. ### Flow Stateful Services Inspect `ts/packages/flow/src/config`, `librarian`, `cores`, `flow-manager`, `prompt`, and service entrypoints. Find `makeAsyncProcessor` object services, `while (this.running)`, `sleep`, `receive(2000)`, local persistence, and process-env config. Compare against scoped layers, state refs, schedules, `FileSystem`, `KeyValueStore`, `Config`, and schema codecs. In TrustGraph's installed beta, prefer `effect/FileSystem` and `effect/unstable/persistence/KeyValueStore` plus runtime-specific provider packages. ### Gateway And RPC Boundaries Inspect `ts/packages/flow/src/gateway` and `ts/packages/client/src/socket`. Find manual requestor caches, streaming completion detectors, WebSocket constructor shims, Promise-returning compatibility APIs, and repeated `Effect.runPromise`. Compare against `Socket`, `RpcClient`, `RpcServer`, `RpcSerialization`, `Stream`, `Queue`, and `Scope`. ### RAG, Agent, Provider, And Storage Layers Inspect `ts/packages/flow/src/retrieval`, `agent`, `storage`, `query`, `model`, and `embeddings`. Find `toPromiseRequestor`, direct SDK resource management, ambient config, JSON parsing, and manual telemetry. Compare against `EffectRequestResponse`, `Stream`, provider `Layer`s, `Config`, `Schema`, `Metric`, `Logger`, and `effect/unstable/ai`. ### MCP And Workbench Inspect `ts/packages/mcp` and `ts/packages/workbench`. Treat these as lower-priority unless a handrolled pattern clearly remains. Prefer making the Effect MCP server canonical over rewriting it from scratch. In workbench, compare local storage and remote state wiring against `BrowserKeyValueStore`, `AtomRpc`, `AtomHttpApi`, `AsyncResult`, and `Reactivity`. ## Report Schema Each scout must return findings in this shape: ```md ## Finding: - Priority: P0 | P1 | P2 | No-op - Impact: 1-5 - Risk: 1-5 - Confidence: 1-5 - TrustGraph evidence: and pattern name - Effect evidence: and source path - Current behavior: - Rewrite shape: - Tests: - Blockers: ``` Scoring: - P0: large handrolled lifecycle/concurrency/transport surface with a verified Effect primitive and clear behavior-preserving route. - P1: real replacement opportunity, but either risk or compatibility needs a focused design pass. - P2: cleanup or local modernization; useful but not strategic. - No-op: current code is already Effect-native, public-boundary Promise code is intentional, or the Effect primitive does not actually fit. ## Acceptance Checks For an audit-only pass: ```sh git status -sb git diff --check -- ts/EFFECT_NATIVE_REWRITE_PLAYBOOK.md ts/EFFECT_NATIVE_REWRITE_AUDIT.md ``` For any later implementation PR, rerun the relevant package tests and at least: ```sh cd ts && bun run check cd ts && bun run build cd ts && bun run test ``` If gateway, live services, or workbench behavior changes, also run the existing smoke lanes from `ts/CLASS_EFFECT_GOAL.md`.