| ... | ... | @@ -0,0 +1,58 @@ |
| 1 | # Effect Migration Plan (From Current State) |
| 2 | |
| 3 | Current status summary: |
| 4 | - Service contracts, typed errors, and most checkpoint/persistence services exist. |
| 5 | - `ProviderServiceLive` is already native orchestration (not a thin adapter). |
| 6 | - Production server path still uses legacy `ProviderManager`/`FilesystemCheckpointStore`. |
| 7 | - Checkpoint flow now avoids snapshot re-sync and is write-time driven. |
| 8 | |
| 9 | ## PR 1: Wire Provider/Checkpoint Effect Stack Into `wsServer` |
| 10 | - Build one runtime layer graph for provider + checkpoint + persistence + orchestration. |
| 11 | - Resolve `ProviderService` from runtime in `wsServer`. |
| 12 | - Replace `ProviderManager` method calls in WS handlers with `ProviderService` calls. |
| 13 | - Forward provider events by subscribing to `ProviderService.subscribeToEvents`. |
| 14 | - Keep WS method/push payloads identical. |
| 15 | |
| 16 | ## PR 2: Runtime Composition + Startup Ownership |
| 17 | - Create/centralize `AppLive` composition for server startup. |
| 18 | - Ensure outer runtime provides Node/platform services once. |
| 19 | - Ensure migrations run at startup via scoped/layer startup path. |
| 20 | - Remove ad-hoc service initialization in request-time paths. |
| 21 | |
| 22 | ## PR 3: Session Lifecycle Hygiene + Checkpoint Invariants |
| 23 | - Add explicit checkpoint session cleanup on `stopSession` / `stopAll`. |
| 24 | - Remove per-session lock/cwd map leaks. |
| 25 | - Keep strict invariant model: |
| 26 | - root checkpoint created at session initialization before agent modifications |
| 27 | - each completed turn captures filesystem checkpoint and persists metadata |
| 28 | - no after-the-fact metadata rebuild/sync |
| 29 | - Add tests for lifecycle cleanup and invariant-failure surfaces. |
| 30 | |
| 31 | ## PR 4: Provider Event Stream Hardening (Without Extra Service Fragmentation) |
| 32 | - Keep `ProviderService` as the public event surface. |
| 33 | - Internally move callback fanout to Effect concurrency primitives (`Queue`/`PubSub`) for ordering/backpressure control. |
| 34 | - Keep API as `subscribeToEvents` unless we explicitly choose stream API later. |
| 35 | - Add tests for ordering and subscriber isolation under load. |
| 36 | |
| 37 | ## PR 5: Codex Runtime Split (Scoped Effect Core) |
| 38 | - Extract `CodexAppServerManager` responsibilities into Effect-native layers: |
| 39 | - scoped process lifecycle |
| 40 | - RPC request/response + pending map via `Deferred` |
| 41 | - session registry/state |
| 42 | - Keep `CodexAdapter` contract stable while swapping internals. |
| 43 | - Preserve protocol behavior and timeout semantics. |
| 44 | |
| 45 | ## PR 6: Codex Protocol Decode Hardening |
| 46 | - Replace ad-hoc unknown parsing with runtime schema decode. |
| 47 | - Map decode failures to typed tagged errors with `cause` retained. |
| 48 | - Add regression tests for malformed/partial protocol frames. |
| 49 | |
| 50 | ## PR 7: Remove Legacy Provider Stack |
| 51 | - Remove `ProviderManager` + legacy checkpoint integration from runtime path. |
| 52 | - Remove `FilesystemCheckpointStore` from active server flow (keep only if explicitly needed for compatibility tooling). |
| 53 | - Update tests to assert only Effect service path is used. |
| 54 | |
| 55 | ## PR 8: Final Cleanup + Docs |
| 56 | - Update architecture docs with final layer graph and service boundaries. |
| 57 | - Document error model and recovery semantics. |
| 58 | - Trim dead compatibility code and stale plan references. |
Julius Marminge <julius0216@outlook.com> 2026-02-22 16:19:37-08:00
Julius Marminge <jmarminge@gmail.com> 2026-02-26 13:20:36-08:00