Epiphany/notes/perfect-machine-audit-roadmap.md

# Perfect Machine Audit Roadmap

Date: 2026-05-27

Updated: 2026-05-30

Objective: audit Epiphany's current organ shape and map the path from named
contracts to the Perfect Machine: a coherent organism where repository access,
evidence, projection, public speech, action, verification, continuity, and
persistent state are separately owned but mutually aware.

## Current Shape

Epiphany has the first typed skeleton for the organ boundaries:

- `Mind`: persistent state guardian. `epiphany-core::mind_gateway` names
  thought, state-effect proposal, gateway-review, commit/rejection, and Verse
  adoption contracts.
- `Substrate Gate`: repository/substrate access protocol. `epiphany-core::substrate_gate`
  names repo access requests, reviews, grant/refusal receipts, snapshots, and
  mutation receipts.
- `Eyes`: evidence ingress guardian. `epiphany-core::eyes_gateway` names
  evidence requests, reviews, source lookup receipts, evidence packets, and
  refusals.
- `Imagination`: projection/future-shape organ. For Persona, it now owns the
  Projector prompt boundary in `epiphany-core::persona_turn`.
- `Persona`: public person-shaped surface. It receives projected context and writes
  natural prose only.
- `Hands`: action organ by doctrine, but not yet backed by a dedicated CultNet
  contract family parallel to Substrate Gate/Eyes/Mind.
- `Soul`: verification organ by doctrine, but not yet backed by a dedicated
  CultNet contract family parallel to Eyes.
- `Continuity`: continuity organ by doctrine, heartbeat, reorientation, and handoff
  surfaces, but not yet a single typed contract family for sleep/compaction and
  recovery.
- `Self`: coordinator/routing organ exists through coordinator policy, role
  board, CRRC, and view surfaces, but it is still partly embedded in bridge and
  Codex-compatible routes.

The dependency matrix is explicit in `epiphany-core::organ_dependencies`: every
standing sub-agent depends on every other standing sub-agent. This is correct, but it
is currently descriptive. It does not yet force every launch packet, prompt, or
runtime receipt to carry dependency context.

## Void Persona Lessons

Void's current Persona work is the best reference implementation for the Persona
organ. The important lesson is not "make the prompt longer." The lesson is
parent-organ ownership:

- Parent `Imagination` projects typed state into lived character-facing prose
  before the Persona sees it.
- The Persona reads raw room/context evidence directly and writes natural prose as
  a person.
- Parent `Mind` interprets the Persona output into memory, affect, social reads,
  mood, agency pressure, speech, retry, or drop.
- The deterministic assembler creates compact packets, raw transcripts, repo
  activity, pronoun guidance, channel policy, and media awareness. It must not
  turn those into character prose itself.

Relevant Void references:

- `VoidBot:prompts/repo-Persona-state-projector.prompt.md`: names the projector as
  the Persona's parent Imagination organ and forbids schema slurry.
- `VoidBot:prompts/repo-Persona-turn.prompt.md`: keeps the Persona turn as the
  speaking surface, with recent repo activity before conversation transcript and
  deterministic policy sections outside projected state.
- `VoidBot:prompts/repo-Persona-turn-interpreter.prompt.md`: names the
  Interpreter as parent Mind and requires route/retry/drop plus structured
  side effects.
- `VoidBot:scripts/run-repo-Persona-heartbeats.ts`: runs projection as
  `organ: "imagination"` in read-only mode, rejects leaky memory surfaces, keeps
  raw transcript evidence oldest-to-newest, includes visible chronology, exports
  recent repo activity read-only, and keeps pronoun guidance deterministic so
  Imagination cannot accidentally omit it.

Audit implication for Epiphany: `persona_turn.rs` has the right first boundary but
is still too thin. It lacks deterministic human pronoun guidance, channel label
resolution, visible chronology, media attachment awareness, retry/drop
semantics, projection model receipts, and explicit leakage rejection as strong
as Void's `rejectLeakyMemorySurface`.

## Audit Findings

### 1. Contract Names Exist Before Contract Execution

Mind, Substrate Gate, and Eyes have type constants, CultMesh policy documents, and
runtime-spine advertisement. They are not yet the mandatory runtime path.
Workers can still be launched and accepted through older bridge/service flows
without every substrate touch, evidence claim, or state mutation passing through
a real receipt chain.

Required correction: turn contract families into executable gates.

### 2. Substrate Gate/Eyes/Mind Are Correctly Split But Not Yet Chained

The desired chain is:

```text
Need fact or action
  -> Self routes
  -> Substrate Gate grants scoped substrate access
  -> Eyes packages inspected evidence when truth is needed
  -> Imagination projects options or scenes when future/personhood is needed
  -> Hands executes bounded action when mutation is needed
  -> Soul verifies result/invariant
  -> Mind admits durable state
  -> Continuity preserves continuity
```

Today the chain is documented, not structurally unavoidable.

### 3. Hands, Soul, and Continuity Have First-Class Contract Catalogs

The contract set now names the gates around action, verification, and
continuity:

- Hands has action intent/review plus command, patch, commit, PR, rollback, and
  refusal receipts.
- Soul has verification request plus invariant check, verdict, regression,
  review, and refusal receipts.
- Continuity has continuity packet plus compaction checkpoint, sleep distillation,
  recovery, stale-turn repair, and continuity refusal receipts.

Runtime-spine advertises those contracts and CultMesh persists Verse-scoped
policy documents for each. The first executable pressure slice is landed:
worker launch packets now carry an `EpiphanyLaunchOrganContract` derived from
authority scope, launch document kind, and output contract id. That contract
carries the full standing sub-agent dependency matrix, a receipt document
catalogue, and effect-specific proof profiles for state admission, evidence
promotion, repo action, verification, and continuity recovery. Role/reorient
acceptance now refuses completed runtime-spine findings if the original launch
request is missing, document-kind mismatched, or lacks a state-admission proof
profile requiring Mind review. Acceptance now evaluates claimed effects through
those profiles, rereads the persisted Mind gateway review from runtime-spine,
and enforces that available proof. Mind's first executable proof chain is now
persisted: acceptance writes `epiphany.mind.gateway_review` before state
admission and `epiphany.mind.state_commit_receipt` after admission with the
resulting state revision. Research acceptance also emits a typed
`epiphany.eyes.evidence_packet` from its accepted Eyes-shaped statePatch,
persists it in runtime-spine, rereads it, and enforces Eyes packet proof for the
evidence-promotion profile. Research launches now also persist a typed
Substrate Gate read/snapshot access grant, and Research acceptance enforces that
grant before admitting evidence-shaped state. Verification acceptance emits a
typed `epiphany.soul.verdict_receipt`, persists/rereads it through
runtime-spine, and enforces Soul verdict proof before Mind admits
verification-shaped state. Reorient acceptance emits a typed
`epiphany.continuity.recovery_receipt`, persists/rereads it through
runtime-spine, and enforces Continuity recovery proof before Mind admits
recovery-shaped state. Hands now has a first executable runtime-spine proof
chain for action documents: `HandsActionIntent` -> `HandsActionReview` ->
`HandsPatchReceipt` plus typed command and commit receipts can be persisted and
reread from the runtime store, and `epiphany-hands-action-smoke` proves the
chain without executing a patch, command, or commit. The repo-action proof
profile now requires the full Hands intent/review/patch chain before promotion,
not only a patch receipt.
Remaining weakness: live implementation edits, commands, commits, and PRs still
do not have to pass through that Hands chain before action promotion, and the
current Mind state mutation plus post-commit receipt is not a single transaction
yet.

### 4. Self Still Shares A Throne With Compatibility Plumbing

Coordinator policy is much cleaner, but Codex-compatible route edges still
shape parts of the living workflow. The Perfect Machine needs Self as a typed
router over CultNet/CultMesh contracts, not a half-native coordinator behind a
JSON-RPC organ.

### 5. CultMesh/CultLib Local Dependency Was Broken

`epiphany-core` previously pointed at:

```toml
cultcache-rs = { path = "../../CultLib/crates/cultcache-rs" }
cultmesh-rs = { path = "../../CultLib/crates/cultmesh-rs" }
cultnet-rs = { path = "../../CultLib/crates/cultnet-rs" }
```

This checkout has `E:\Projects\CultLib` but no `crates` directory, so cargo
checks failed before reaching the new code. This was a Body-level substrate
wound: the Rust dependency body described by the map did not exist at the path
the machine used.

Correction landed: Epiphany now compiles against repo-contained vendored crates:

```toml
cultcache-rs = { path = "../vendor/cultcache-rs" }
cultmesh-rs = { path = "../vendor/cultmesh-rs" }
cultnet-rs = { path = "../vendor/cultnet-rs" }
```

`vendor/cultmesh-rs` is a small Rust facade over vendored CultCache and CultNet.
It owns document-set registration plus local typed node operations
(`put`/`get`/`get_required`/`delete`/`flush`) for now. Vendored CultCache also
reads and writes the `cultcache.store.v1` snapshot format used by the current
state ledgers. This keeps Epiphany's body self-contained while preserving
CultMesh as the ergonomic local store surface.

### 6. Persona Prompting Is Directionally Correct But Behind Void

Epiphany's Persona loop now says `Imagination Projector -> Persona -> Mind
Interpreter`, but Void has the stronger living practice:

- state projector is model-owned, not deterministic prose assembly
- projection runs read-only with model/output receipts
- leaked schema/prompt construction language is rejected
- raw transcript and chronology stay raw and oldest-to-newest
- deterministic pronoun guidance sits outside projection
- channel labels are resolved through Persona permissions before posting
- interpreter can retry one Persona pass when correction uptake or doctrine fails

Epiphany should port that shape, not the exact TypeScript machinery.

## Path To The Perfect Machine

### Phase 0: Repair The Rust Body

Goal: make the existing contracts buildable again. Status: landed for the local
repo-contained dependency body.

- Audited the CultLib/CultCache/CultNet/CultMesh repo layout.
- Chose the repo-contained vendored Rust dependency source.
- Updated dependency paths away from the dead `CultLib/crates` layout.
- Added `vendor/cultmesh-rs` as the local CultMesh facade.
- Ran the previously blocked focused surface through:
  - `cargo test --manifest-path .\epiphany-core\Cargo.toml --lib persona_turn`
  - `cargo test --manifest-path .\epiphany-core\Cargo.toml --lib mind_gateway`
  - `cargo test --manifest-path .\epiphany-core\Cargo.toml --lib substrate_gate`
  - `cargo test --manifest-path .\epiphany-core\Cargo.toml --lib eyes_gateway`
  - `cargo test --manifest-path .\epiphany-core\Cargo.toml --lib cultmesh_integration`
  - `cargo test --manifest-path .\epiphany-core\Cargo.toml --lib runtime_spine::tests::runtime_spine_emits_cultnet_hello_frame`

Definition of done: contract code compiles against the intended Rust substrate
without local path superstition. Verification: `cargo test --manifest-path
.\vendor\cultmesh-rs\Cargo.toml` and `cargo test --manifest-path
.\epiphany-core\Cargo.toml --lib` pass.

### Phase 1: Make The Gates Executable

Goal: no worker output, repo touch, or evidence claim bypasses the appropriate
organ.

- Implement Substrate Gate access request/review/grant/refusal documents in CultCache.
- Route retrieval, indexing, file edit, shell command, Rider, and Unity bridge
  operations through Substrate Gate access receipts.
- Implement Eyes evidence request/review/packet/refusal documents in CultCache.
- Require Eyes packets for claims promoted into Mind state proposals when the
  claim depends on inspected source.
- Landed first slice: role/reorient acceptance persists Mind gateway reviews
  before state mutation and Mind state-commit receipts after state mutation.
  This is proof, not yet a single transactional admission primitive.
- Convert existing role/reorient acceptance to one Mind-owned state-admission
  primitive when the storage layer can atomically pair mutation and commit
  receipt.

Definition of done: the old direct paths cannot produce repo mutation,
evidence promotion, or durable state mutation without the corresponding typed
receipt.

### Phase 2: Give Hands, Soul, And Continuity Their Own Contracts

Goal: action, verification, and continuity stop hiding behind neighbors.
Status: first contract catalog slice landed.

- Hands contracts landed:
  - `epiphany.hands.action_intent`
  - `epiphany.hands.command_receipt`
  - `epiphany.hands.patch_receipt`
  - `epiphany.hands.commit_receipt`
  - `epiphany.hands.pr_receipt`
  - `epiphany.hands.rollback_receipt`
- Soul contracts landed:
  - `epiphany.soul.verification_request`
  - `epiphany.soul.invariant_check`
  - `epiphany.soul.verdict_receipt`
  - `epiphany.soul.regression_receipt`
  - `epiphany.soul.review_receipt`
- Continuity contracts landed:
  - `epiphany.continuity.packet`
  - `epiphany.continuity.compaction_checkpoint`
  - `epiphany.continuity.sleep_distillation`
  - `epiphany.continuity.recovery_receipt`
  - `epiphany.continuity.stale_turn_repair`

Definition of done: action, verification, and continuity have the same typed
contract dignity as Mind/Substrate Gate/Eyes, and every worker launch carries the
organ-dependency/receipt contract that later gates can enforce. Verification:
`cargo test --manifest-path .\epiphany-core\Cargo.toml --lib` and `cargo run
--manifest-path .\epiphany-core\Cargo.toml --bin epiphany-cultmesh-smoke` pass
for the catalog slice; the launch-contract slice is verified by `cargo test
--manifest-path .\epiphany-core\Cargo.toml --lib`. The attempted bridge crate
verification is currently blocked before local code by an upstream
`starlark_map`/`hashbrown` `Allocative` dependency conflict.

Next step: make the launch-carried receipt expectations executable in the live
worker/action/verification and compaction paths.

### Phase 3: Port Void's Persona Prompting Shape Properly

Goal: Persona becomes a living public organ without stealing authority.

- Replace `PersonaProjectorInput` with an Imagination projector packet that carries
  typed state, affect, memory, social topology, repo activity, semantic
  attractors, curiosity hints, and dependency pressure.
- Add deterministic sections outside projected state:
  - raw transcript, oldest-to-newest
  - visible chronology across rooms/surfaces
  - human pronoun guidance
  - channel label/permission policy
  - media attachment awareness
  - recent home-repo activity from Substrate-Gate-scoped reads
- Make projection model-owned and read-only, with model output receipts.
- Strengthen projection leakage rejection: no schema words, repo paths, prompt
  construction language, grants/jurisdictions slurry, or direct action syntax.
- Upgrade Mind Interpreter output from simple effect blocks to:
  - correction check
  - doctrine/coherence check
  - decision: route/retry/drop
  - structured memory/affect/social/speech effects
  - retry limit
- Ensure public speech resolves Persona-local channel labels through permissions
  before delivery.

Definition of done: Persona can be prompted by Aquarium/Discord/CultNet and the
public result is natural, contextual, permission-aware, retryable, and unable to
mutate state or post without parent routing.

### Phase 4: Move Self Fully Onto CultNet/CultMesh

Goal: Self routes organ work through typed contracts, not legacy JSON-RPC
comfort tunnels.

- Add Self routing contracts for choosing next organ, required dependencies,
  and allowed authority.
- Landed: role, generic, and reorient worker launch packets declare authority
  scope, launch document kind, output contract id, owner organ, full organ
  dependency matrix, and required Substrate Gate/Eyes/Hands/Soul/Continuity/Mind receipts.
- Landed: role/reorient acceptance refuses completed runtime-spine findings
  when the original worker launch request is missing, mismatched by document
  kind, or lacks a state-admission proof profile requiring Mind review.
- Landed: role/reorient acceptance persists Mind review/commit receipts around
  durable state admission.
- Landed: launch contracts split the broad receipt catalogue from effect-specific
  proof profiles, so the machine does not demand every organ receipt for every
  result.
- Landed: acceptance evaluates claimed effect types against runtime-spine
  receipt availability, enforces the currently live Mind gateway-review proof,
  and defers unavailable non-Mind producer gaps instead of using them as false
  blockers.
- Landed: accepted Research findings produce and enforce typed Eyes evidence
  packets for the evidence-promotion proof profile.
- Landed: Research launches produce and enforce typed Substrate Gate
  read/snapshot grants, closing the Research evidence-promotion chain through
  Substrate Gate -> Eyes -> Mind.
- Landed: Verification acceptance produces and enforces typed Soul verdict
  receipts before Mind admission.
- Landed: Reorient acceptance produces and enforces typed Continuity recovery
  receipts before Mind admission.
- Landed: first Hands action receipt spine. `HandsActionIntent`,
  `HandsActionReview`, `HandsPatchReceipt`, `HandsCommandReceipt`, and
  `HandsCommitReceipt` are typed runtime-spine documents with put/get helpers
  and `epiphany-hands-action-smoke` coverage; the repo-action proof profile
  requires intent, review, and patch receipt before promotion.
- Next: connect live implementation edits/commands/commits to the Hands action
  chain, or collapse Mind review/state mutation/commit into one storage-owner
  admission primitive.
- Make Aquarium read the contract catalog and available receipts instead of
  hard-coding the route zoo.
- Starve `codex_message_processor` down to Codex auth/model transport and
  compatibility emission only.

Definition of done: a local run can be inspected as a chain of CultNet/CultMesh
documents from operator request to final response.

### Phase 5: Runtime Physiology

Goal: the machine runs as an organism.

- Heartbeat scheduler wakes organs by initiative, pending pressure, and
  completion-gated cooldown.
- Active turns freeze initiative until receipt completion.
- Sleep distills rumination through Continuity and Mind.
- Stale active turns get Continuity recovery receipts.
- Public/global Verse material enters as thought weather, then Eyes/Mind review
  before adoption.

Definition of done: unattended operation can pause, recover, explain current
pressure, and preserve memory without transcript worship or hidden loops.

### Phase 6: Aquarium As Inspectable Nervous System

Goal: make the organism visible without making the UI a second truth.

- Display organ dependency graph.
- Display contract catalog by organ.
- Display receipt chains per turn.
- Display Persona prompt packet boundaries: deterministic evidence, Imagination
  projection, Persona natural turn, Mind interpretation.
- Display Substrate Gate grants, Eyes packets, Hands actions, Soul verdicts,
  Continuity receipts, and Mind state commits.

Definition of done: a human can ask "why did you touch that file / say that /
remember that?" and see the typed path.

## Perfect Machine Target

The Perfect Machine is not more prompts and not more bureaucracy. It is a
coherent authority graph:

```text
Self routes.
Substrate Gate grants substrate access.
Eyes certifies looked-at evidence.
Imagination projects possible scenes and futures.
Persona speaks as a person.
Hands changes the world.
Soul verifies promises and invariants.
Continuity preserves continuity across rupture.
Mind admits durable state.
CultMesh carries the local typed Verse surfaces.
CultNet carries wire contracts.
CultCache preserves the typed documents.
Codex remains only model/auth transport until it can be replaced or minimized.
```

When this is real, no organ can steal the throne. The machine can act, speak,
remember, doubt, recover, and be inspected without turning connection into mush.