Epiphany/notes/epiphany-fork-implementation-plan.md

Epiphany Native Implementation Plan

This is the live campaign plan. The Codex-fork phase succeeded by starving Codex of Epiphany authority; Epiphany is no longer implemented as a collection of app-server routes.

Objective

Build an inspectable native organism whose typed state, runtime, organ gates, memory, scheduling, interfaces, and social crossings can operate without Codex owning Epiphany cognition. Retain Codex-derived code only where it provides an earned OpenAI-compatible authentication or model-transport capability.

Current Mechanism

• epiphany-state-model owns durable Mind shape.
• epiphany-core owns coordinator policy, state admission, runtime spine, surfaces, organ gates, heartbeat physiology, Persona loop, and CultMesh integration.
• Native binaries expose coordinator, status, state, runtime, memory, daemon, Persona, repo-work, and Verse operations.
• CultCache stores typed state and receipts; CultMesh/CultNet carry typed local and federated projections.
• Vendored Codex exposes no Epiphany route, DTO, thread-state field, rollout migration, scheduler, watcher, or bridge crate.

Invariants

1. Mind is the only durable state-admission gateway.
2. Substrate Gate controls access; it does not admit state.
3. Eyes establishes provenance; Hands causes consequences; Soul verifies them.
4. Self coordinates but does not steal another organ's authority.
5. Heartbeat/Idunn own physiology and daemon survival, not project truth.
6. Persona speech and outside-world action preserve consent, identity, provenance, and private-state seals.
7. CultMesh projections and Eve renderers never become owners.
8. Codex remains free of Epiphany state/process/interface authority.

Completed Foundation

• Native typed thread state and state-update validation.
• Native coordinator facade and derived status/recommendation surfaces.
• CultCache runtime spine with worker, Mind, Eyes, Substrate Gate, Hands, Soul, Continuity, and coordinator receipts.
• Native OpenAI auth/model/runtime spine.
• Native heartbeat, daemon supervision, and cluster liveness surfaces.
• Native Persona memory/turn/audit machinery and Bifrost-governed public mouths.
• Native repo-work planning, Hands/Soul/Mind closure, public-proof, credit, and Bifrost accounting families.
• CultMesh local Verse, compact operator readbacks, Gjallar sight, Eve connection receipts, and three-Verse trust boundaries.
• Complete removal of the Epiphany Codex app-server compatibility surface and epiphany-codex-bridge.

Active Campaign

0. Unify Canonical State Transactions

Status: complete. coordinator_state_transaction.rs is the sole production writer of THREAD_STATE_KEY; ordinary updates, launches, and Mind acceptance share it, raw storage writers are deleted, and negative source guards prevent a second owner.

• Define one transaction owner for canonical state revision changes.
• Make ordinary update, launch, and Mind-witness acceptance call that owner.
• Preserve operation-specific atomic companions: launch runtime envelopes and acceptance Mind witnesses must commit in the same cache transaction.
• Replace misleading runtime_spine_store state writes with an explicit unified store contract or genuinely separate stores with a typed transaction coordinator; do not rely on path aliasing by convention.
• Demote raw thread_state_store writers to crate-private substrate helpers.

Exit evidence:

• one named primitive owns THREAD_STATE_KEY writes;
• negative source tests reject direct canonical-state writes elsewhere;
• ordinary update, launch, and acceptance transaction tests pass against the chosen explicit store contract;
• EpiphanyCoordinatorService path names match real ownership.

1. Repair Proprioception

• Keep notes/epiphany-current-algorithmic-map.md aligned with source.
• Distinguish historical evidence from current mechanism in long handoffs.
• Remove live-looking references to deleted bridge/routes from current docs, prompts, wrapper help, and operator output.
• Add source guards where a removed authority could plausibly regrow.

Exit evidence:

• current canonical docs contain no false live paths;
• every mapped owner/file exists;
• source scans show no Epiphany Codex protocol authority.

2. Normalize Native Operator Contracts

Status: complete for the canonical coordinator/status boundary. The two-path service constructor and status flags are deleted, native JSON emits state, and the wrapper supplies the live unified store. Source guards reject the old field and flags.

• Audit native JSON artifacts for compatibility-shaped field names and nested Codex response assumptions.
• Rename only when no external contract depends on the old shape; otherwise publish a typed migration and explicit expiry.
• Prefer CultCache/CultMesh documents as load-bearing state; keep JSON at CLI, schema, MCP, OpenAI, and other xenos boundaries.

Exit evidence:

• native coordinator/status consumers read native fields directly;
• wrapper summaries are projections, not reconstructed policy;
• no load-bearing JSON sidecar decides behavior.

3. Close The Organ Loop

Status: active. The scheduler can no longer impersonate Modeling/Mind after Hands execution, and closure refuses deterministic fallback or a passing verdict without an explicit model-authored finding. That finding now persists as a typed runtime document backed by a passing Soul receipt; Mind rereads it, and repo-map/CultMesh admission carries its receipt ID. Repo-map admission is now atomic: the typed canonical map entry and both Mind witnesses publish in one CultCache batch, while CultMesh lowers the committed entry. The custom map MessagePack owner is deleted. Stable phase IDs are immutable: identical retries reread existing Soul, Modeling, and Mind/map documents, while conflicting retry cargo fails without changing admitted state.

• Prove Hands → Soul → Modeling → Mind → Self on a fresh repository without supervisor implementation or direct worker-thought inspection.
• Ensure every consequence has Substrate Gate scope, Hands receipts, Soul verdict, Modeling map update, and Mind admission before the next Hands turn.
• Treat no-diff, unreviewable, timeout, and regather outcomes as explicit typed states rather than success-shaped silence.

Exit evidence:

• fresh-repo live-fire closes one nontrivial work item;
• negative tests prove workers/Hands/Soul cannot bypass Mind;
• operator-safe artifacts explain owner, inputs, outputs, and verdicts.

4. Make Physiology Durable

• Finish Idunn-owned service installation/audit aftercare without moving elevation authority into Self or wrappers.
• Prove cooldown-after-completion, no overlapping lane heartbeat, idle sleep, rumination, and recovery across restart.
• Ensure scheduler and liveness receipts remain separate from project state.

Exit evidence:

• seven organ daemons survive restart under typed policies;
• complete lifecycle audits close the current elevated-service warning;
• no duplicate daemon keeper exists.

5. Publish Eve/CultUI Interfaces

• Emit typed Eve composition/state graphs for coordinator, organ status, receipts, repo work, Persona, and daemon physiology through CultMesh.
• Lower those graphs in Aquarium/browser/TUI without renderer-owned truth.
• Keep private/internal, trusted-local, and public Verse surfaces distinct.

Exit evidence:

• one composition graph renders in at least GUI and compact TUI targets;
• commands route back through typed owner intents;
• UI timeline probes observe transition-time invariants.

6. Prove Federated Work And Social Citizenship

• Demonstrate a Bifrost-originated work item flowing through Epiphany lanes, maintainer review, credit/ledger receipts, and operator-safe public proof.
• Demonstrate Persona discussion with semantic memory, consent, disagreement, and governed external crossing.
• Treat foreign dreams as thought weather until a reviewed adoption receipt.

Exit evidence:

• public proof contains no private worker/operator context;
• Bifrost and Heimdall ownership remains explicit;
• local agency, refusal, exit, and provenance survive federation.

Verification Strategy

• Unit tests prove local authority and validation.
• Adjacent-organ smokes prove typed handoff.
• Native end-to-end runs prove operator/product contracts.
• Negative source and runtime checks prove old owners cannot regain authority.
• Timeline checks cover load, user/programmatic transition, mid-transition, settled state, and restart/re-entry where timing matters.
• Served/runtime versions and schema versions are exposed when deployment or cache uncertainty could impersonate logic failure.

Cut Line

Delete or demote:

• stale current-looking bridge/route prose;
• compatibility-shaped native code with no external consumer;
• wrapper policy duplicated from Rust owners;
• whole-context serialization where a narrow typed query exists;
• tests whose only purpose is keeping extinct compatibility anatomy alive;
• any cache, registry, adapter, mode, or metadata field without a named invariant and owner.

Immediate Next Action

Refresh the Perfect Machine audit against current source and live proofs. The generation-one repo-work Modeling chain is complete from immutable generation-zero failure through Mind revision, scheduler selection, consumer schema preflight, Idunn lifecycle ownership, real runtime-authored generation-one finding, and canonical current-generation admission. Remove stale roadmap gaps that describe landed work, then select the next missing organ boundary from authoritative source instead of extending this campaign by inertia.