Document client newable factory compatibility

This commit is contained in:
elpresidank 2026-06-02 02:21:40 -05:00
parent 1899bf1f5a
commit 54fc21b38d

View file

@ -434,6 +434,29 @@ Notes:
- `cd ts && bun run test` - `cd ts && bun run test`
- `git diff --check` - `git diff --check`
### 2026-06-02: Client Newable Factory Compatibility Decision
- Status: documented no-op for the current loop.
- Evidence:
- `ts/packages/workbench/src/atoms/workbench.ts` constructs
`new BaseApi(...)`.
- `ts/packages/client/src/__tests__/flows-api.test.ts` constructs
`new FlowsApi(...)`, and sibling API facades expose the same constructor
shape.
- `EffectRpcClient` and `BaseApi` also preserve callable factory exports for
compatibility with the vendored TrustGraph client shape.
- Decision:
- The remaining `newableFactory(... ) as unknown as NewableFactory<...>`
assertions in client socket files are TypeScript compatibility boundaries,
not Effect error/requirement channel assertions and not replacements for an
Effect primitive.
- Removing them safely requires a deliberate public API redesign or explicit
class implementations for every API facade, not a local Effect-native
rewrite.
- Verification:
- Current client/root verification from the tagged error slice covers this
no-op decision.
## Subagent Findings To Preserve ## Subagent Findings To Preserve
- MCP/workbench: - MCP/workbench:
@ -458,8 +481,9 @@ Notes:
than more assertions. than more assertions.
- Gateway/client: - Gateway/client:
- `EffectRpcClient` now owns its socket/RPC layer with `ManagedRuntime`. - `EffectRpcClient` now owns its socket/RPC layer with `ManagedRuntime`.
Remaining client cleanup should focus on `trustgraph-socket.ts` Socket errors/JSON parsing now use tagged errors and Schema decoding.
and `effect-rpc-client.ts` newable factory assertions. The remaining client `newableFactory` assertions are documented as public
API compatibility boundaries for this loop.
- Knowledge streams still duplicate legacy end-of-stream handling. - Knowledge streams still duplicate legacy end-of-stream handling.
- WebSocket adapter host fallbacks now use `Result.try` and tagged adapter - WebSocket adapter host fallbacks now use `Result.try` and tagged adapter
errors while preserving sync exports. errors while preserving sync exports.
@ -473,26 +497,6 @@ Notes:
## Ranked Findings ## Ranked Findings
### P1: Finish Client RPC Boundary Modernization
- TrustGraph evidence:
- `ts/packages/client/src/socket/effect-rpc-client.ts`
- `ts/packages/client/src/socket/trustgraph-socket.ts`
- Effect primitives:
- `effect/unstable/socket` `Socket.makeWebSocket`, `fromWebSocket`,
`toChannel`, `layerWebSocket`.
- `effect/unstable/rpc/RpcClient.layerProtocolSocket`.
- `effect/unstable/rpc/RpcSerialization.layerNdjson` or `layerNdJsonRpc`.
- `ManagedRuntime` for compatibility facades when a Promise API must remain.
- Rewrite shape:
- `EffectRpcClient` is now an internal managed runtime with Promise
compatibility facades.
- Expose Promise-returning methods through a thin adapter.
- Replace remaining client newable factory assertions with a typed factory
shape that preserves current constructor/function compatibility.
- Tests:
- `cd ts && bun run --cwd packages/client test`
### P1: Base Processor Registry And Constructor Shims ### P1: Base Processor Registry And Constructor Shims
- TrustGraph evidence: - TrustGraph evidence:
@ -563,11 +567,10 @@ Notes:
## Recommended PR Order ## Recommended PR Order
1. Client RPC managed runtime/scoped layer cleanup. 1. Base processor registry and constructor shim redesign.
2. Base processor registry and constructor shim redesign. 2. Gateway RPC callback and client streaming completion cleanup.
3. Gateway RPC callback and client streaming completion cleanup. 3. Storage/provider managed resource cleanup.
4. Storage/provider managed resource cleanup. 4. MCP parity/deletion decision and workbench platform polish.
5. MCP parity/deletion decision and workbench platform polish.
## No-Op Rules ## No-Op Rules
@ -586,6 +589,9 @@ Do not flag these as rewrite blockers without additional proof:
- JSON stringification in tests or wire-contract fixtures. Production JSON - JSON stringification in tests or wire-contract fixtures. Production JSON
encode/decode should prefer schema codecs when the encoded form can be encode/decode should prefer schema codecs when the encoded form can be
preserved. preserved.
- Client `newableFactory` assertions that preserve vendored callable-plus-new
API facades are compatibility boundaries unless the public constructor API is
intentionally redesigned.
## Acceptance For Final Loop Completion ## Acceptance For Final Loop Completion