Epiphany/notes/native-coordinator-liberation-map.md

# Native Coordinator Liberation Map

## Objective

Make `epiphany-mvp-coordinator` an Epiphany-native control loop. It must read
and mutate typed Epiphany state, launch and inspect runtime work, and accept or
refuse findings without sending `thread/epiphany/*` JSON-RPC requests through
Codex.

Codex remains the OpenAI authentication/model-transport bridge and may retain
legacy app-server wrappers for named Codex clients. It is not the coordinator's
nervous system.

## Current Mechanism

The coordinator is compiled from
`epiphany-core/src/bin/epiphany-mvp-coordinator.rs`, but starts a Codex app-server
process and uses `status_cli::AppServerClient` for the authoritative loop:

- state bootstrap and revision writes use `thread/epiphany/update`
- freshness and coordinator projections use `thread/epiphany/freshness` and
  `thread/epiphany/view`
- specialist lifecycle uses `thread/epiphany/roleLaunch`,
  `thread/epiphany/roleResult`, and `thread/epiphany/roleAccept`
- recovery lifecycle uses `thread/epiphany/reorientLaunch` and
  `thread/epiphany/reorientResult`

The typed machinery already exists below that shell:

- `epiphany-core/src/thread_state_store.rs` owns CultCache-backed typed thread
  state persistence.
- `epiphany-core/src/runtime_spine.rs` owns typed job, launch, result, event, and
  receipt persistence.
- `epiphany-core/src/agent_launch.rs` builds typed role and reorientation launch
  documents.
- `epiphany-core/src/surfaces/role_result.rs` interprets typed findings and
  constructs acceptance bundles.
- `epiphany-core/src/mind_gateway.rs`, `hands_gateway.rs`, and the receipt proof
  machinery own admission, action, and verification contracts.
- `epiphany-codex-bridge/src/mutation_service.rs` currently composes much of
  this policy behind an `EpiphanyMutationHost`, but its host contract still
  assumes a Codex-hosted compatibility snapshot and persistence hook.
- `vendor/codex/codex-rs/app-server/src/codex_message_processor/
  epiphany_mutation_routes.rs` is already mostly a transport shell over that
  bridge service. It should become a compatibility caller of the native owner,
  not the place where the owner remains hosted.

## Authority Map

### Owner

One Epiphany-native coordinator service owns the control decision and delegates
typed persistence to the thread-state store and runtime-spine.

### Inputs

- typed operator/coordinator intent
- CultCache-backed `EpiphanyThreadState`
- runtime-spine job, result, and receipt documents
- typed watcher, retrieval, token-pressure, and dynamic prompt context
- model events returned by the model-transport adapter

### Outputs

- revision-gated typed state updates
- typed runtime launch and interrupt receipts
- typed role/reorientation findings
- Mind review and state-commit receipts
- read-only typed coordinator, freshness, role, and recovery projections

### Derived State

JSON-RPC responses, app-server notifications, Aquarium panels, CLI JSON, TUI
rows, CultMesh mirrors, and operator summaries are projections. They do not own
lifecycle, scheduling, acceptance, prompt doctrine, or durable truth.

### Forbidden Writers

- `codex_message_processor.rs` and its route modules
- Codex thread/session prompt machinery
- JSON-RPC request/response types
- GUI/Aquarium clients
- CultMesh mirrors and status snapshots
- watcher or reorientation verdicts
- raw model or MCP JSON

Each may submit or translate a typed intent. None may preserve an independent
decision after the native owner responds.

### Shared Paths

Manual CLI actions, programmatic coordinator turns, heartbeat scheduling,
Aquarium actions, and legacy Codex JSON-RPC calls must use the same native
operations for:

1. state read/update
2. freshness and coordinator derivation
3. role/reorientation launch
4. result readback
5. accept/refuse
6. interrupt

### Deletion Line

Delete `status_cli::AppServerClient` from the coordinator control path. Delete
its direct `thread/epiphany/*` request construction. After the native loop is
proved, reduce Codex mutation routes to protocol parsing, native service calls,
response mapping, and compatibility notifications. Then remove bridge policy
that exists only to compensate for Codex-hosted state.

## Migration Order

This is one vertical ownership migration, landed in buildable cuts. No cut may
introduce a second authoritative store or a native/JSON-RPC mode flag.

1. Move route-independent mutation/launch/accept orchestration out of
   `epiphany-codex-bridge` into an Epiphany-native service whose host ports are
   typed state persistence, runtime-spine, clock, and context inputs. Preserve
   the existing bridge service as a thin delegating compatibility wrapper.
2. Add native read operations for state, freshness, coordinator/role views, and
   typed result readback over the same stores used by mutation operations.
3. Rewire `epiphany-mvp-coordinator` to the native service and remove
   `AppServerClient` plus every `thread/epiphany/*` request from the binary.
4. Prove bootstrap, manual/programmatic launch, pending/completed result,
   acceptance, refusal, interruption, and recovery against native stores.
5. Make Codex JSON-RPC routes delegate to the same service. Remove duplicated
   route/bridge policy and mapper-only tests that no longer protect a boundary.

## Native Organ Boundary

The native service is a façade, not a new host brain. The first extraction
proved the authority direction but allowed `epiphany-core/src/coordinator_service.rs`
to grow to 1,122 lines, almost the same size as the 1,143-line bridge mutation
service it is starving. That shape is rejected. Do not continue pouring bridge
functions into one core file.

The native body must be split before further authority moves:

- coordinator state owner: CultCache thread-state load, revision gate,
  validation, write, and changed-field report
- coordinator result reader: runtime-link selection, runtime-spine lifecycle,
  typed finding interpretation, and result notes
- coordinator acceptance organ: completed-finding admission, launch-contract
  proof checks, role/reorientation acceptance construction, receipt persistence,
  proof enforcement, and Mind commit
- coordinator launch organ: typed dynamic context, launch document construction,
  runtime-spine opening/interruption, and state linkage
- coordinator projection organ: freshness, role board, CRRC, and coordinator
  views derived from typed inputs without persistence
- coordinator façade: narrow composition over those organs; no policy bodies,
  protocol DTOs, JSON, or Codex host hooks

Each organ owns one invariant and must be testable against injected paths and
typed inputs without starting Codex. A source guard should fail if the façade
regrows policy bodies or if any native organ imports app-server protocol types.

## Invariants

- There is one durable thread-state owner and one runtime lifecycle owner.
- Revision validation is identical for CLI, coordinator, heartbeat, Aquarium,
  and compatibility JSON-RPC callers.
- A view or watcher verdict cannot launch or accept work.
- Raw JSON is parsed once at a hostile edge and does not cross native service
  ports.
- Model transport cannot inject organ doctrine, scheduler decisions, or state
  mutation policy.
- Compatibility wrappers cannot override or repair the native result after the
  fact.

## Verification Layer

The proof must observe the stores and receipts where the invariant lives:

- unit tests for each native operation with injected state store, runtime
  store, clock, and context inputs
- adjacent-operation smokes for launch -> result -> review -> state commit
- a native coordinator smoke with no app-server binary available
- a compatibility smoke proving JSON-RPC delegates to the same native result
- negative tests proving Codex routes cannot write around revision/admission
  gates and the coordinator binary contains no `thread/epiphany/*` methods

The migration is not complete because the coordinator eventually converges on
the same state after an app-server round trip. The old path must be structurally
unable to decide the result.