authorgravatar for julius0216@outlook.comJulius Marminge <julius0216@outlook.com> 2026-02-22 16:19:37-08:00
committergravatar for jmarminge@gmail.comJulius Marminge <jmarminge@gmail.com> 2026-02-26 13:20:36-08:00
logce841a7ef10543478823d44c73da3820b9990829
tree98ca5d78add32d3f4f5849e70a0120c1646916c1
parent54dd17e7b9f576f3219d2512497c492180b76fd1

new plan

1 files changed, 58 insertions(+), 0 deletions(-)

.plans/12-effect-new.md created+58
...@@ -0,0 +1,58 @@
1# Effect Migration Plan (From Current State)
2
3Current 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.