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

Perfect Machine Audit Roadmap

Updated: 2026-07-12

Objective

Prepare Epiphany as a coherent organism whose repository access, evidence, projection, public speech, action, verification, continuity, durable state, runtime physiology, and inspection surfaces have one visible owner each.

This is a live authority audit. Historical implementation scars belong in git, distilled evidence, or archived notes. A green local test proves only the seam it actually observes.

Authority Map

Faculty	Owner	Inputs	Outputs	Current proof	Live gap
Self	native coordinator and repo-work scheduler	typed state, job/result receipts, current route pressure	bounded launch/routing decisions	coordinator acceptance tests; repo-work scheduler authority tests	heartbeat is not yet an always-on Idunn-owned process
Substrate Gate	substrate_gate	scoped read/mutation request	access grant, refusal, snapshot, mutation receipt	Research launch/acceptance and Hands gate proofs	audit remaining utility/bridge substrate touches for bypasses
Eyes	eyes_gateway	inspected source under a Substrate Gate grant	evidence packet or refusal	Research acceptance proof profile	public/foreign Verse adoption still needs a full live Eyes-to-Mind proof
Imagination	planning and Persona projector boundaries	typed project/person state and candidate futures	plans, projections, consensus candidates	planning/consensus smokes and Persona projector tests	Persona projector/interpreter parity with the current Void reference needs a fresh audit
Persona	Persona turn and public mouth edges	projected context plus visible conversation	natural speech candidate and speech audit	Persona Discord/Reddit/Bifrost smokes	Aquarium-native conversational inspection remains incomplete
Hands	hands_gateway and repo-work execution	approved intent, path scope, Substrate Gate grant	patch, command, commit, PR, rollback receipts	real repo-work execution/closure and Hands receipt-chain smokes	search for non-repo-work actuators that still bypass the chain
Soul	soul_gateway and verification phase	Hands consequence receipts and changed body	verdict/invariant/regression receipts	live repo-work Soul phase and acceptance tests	unify remaining verifier-specific projections under narrow receipt queries
Modeling	typed repo-work Modeling route and model runtime	immutable Soul-verified request selected by current generation	immutable finding	generation-zero/generation-one runtime, Mind revision, Idunn launch, and admission proofs	no known authority split in the repo-work path
Mind	canonical state transaction and gateway reviews	bounded effect proposal plus required organ proofs	durable state and commit receipt	one canonical writer/store; atomic coordinator and repo-map admission proofs	audit other state families for pre-transaction legacy writers
Continuity	continuity contracts plus CRRC/stale-turn repair	pressure, checkpoint, sleep, and stale active state	checkpoint, recovery, sleep-distillation, stale-turn receipts	reorient acceptance and heartbeat stale-repair tests	sleep consolidation is callable, not continuously supervised physiology
Nervous system	heartbeat state, runtime spine, Idunn, CultMesh/CultNet	pressure, pending turns, daemon/runtime state	scheduling, lifecycle, telemetry, interrupts	typed heartbeat pump/routine, runtime-spine jobs, Idunn service receipts	the heartbeat loop is still an attached PowerShell vigil rather than a native supervised daemon
Body	repository, Rust binaries, CultCache/CultMesh stores, model transport	typed commands and granted external authority	real effects and inspectable artifacts	focused smokes and live repo work	continue cutting whole-context queries and compatibility-shaped native artifacts

Structural Invariants

1. Self routes; it does not author specialist findings or admit durable state.
2. Substrate Gate owns substrate permission. Eyes owns evidence promotion.
3. Hands alone changes the repository; Soul alone calls the consequence verified; Modeling updates the machine model after Soul.
4. Mind is the only durable-state admission owner. Reviews, state mutation, and commit witnesses share the canonical transaction boundary where atomicity is required.
5. Immutable Modeling findings never change. Mind may advance one stable typed route to a new generation; stale generations cannot close or regain current authority.
6. Idunn owns process and daemon lifecycle. Self may request a launch but may not spawn, repair, or silently replace the child.
7. CultCache documents are state, CultMesh is the local state/discovery substrate, CultNet is the wire, and Eve/CultUI is the interface projection. JSON is display or xenos-boundary cargo, not internal authority.
8. Aquarium and other renderers inspect typed owners. They do not rebuild a second route graph or dashboard-shaped truth.
9. Pending turns freeze repeat scheduling. Cooldown begins after completion. Stale turns require Continuity evidence, not timer-shaped amnesia.
10. Public connection preserves consent, identity, permission, provenance, and private-state seals at the actual mouth edge.

Evidence Ledger

Proven executable chains

• Research: Substrate Gate grant -> Eyes packet -> Mind admission.
• Implementation: scoped Hands intent/review -> patch/command/commit receipts.
• Verification: Hands consequence -> Soul verdict -> Modeling request.
• Repo map: immutable Modeling finding -> current typed route -> Mind/map transaction -> Bifrost publication gate.
• Retry: runtime-authored non-passing generation zero -> explicit Mind review -> generation-one route -> consumer schema preflight -> Idunn lifecycle receipt -> runtime-authored passing finding -> current-generation admission.
• Recovery: reorient launch -> Continuity recovery receipt -> Mind admission.
• Public crossing: Persona speech audit -> Bifrost/Heimdall authority checks -> governed receipt or sealed refusal.

Proven negative boundaries

• Scheduler cannot author Modeling findings or impersonate Mind admission.
• CLI cannot counterfeit a runtime-authored Modeling finding.
• Non-passing and stale-generation findings cannot enter the repo map.
• Passing findings cannot be revised into retries.
• epiphany-work cannot spawn the model child; Idunn owns process launch.
• Consumer schema preflight happens before the runtime job is opened.
• Extinct Codex Epiphany DTO/route/bridge paths cannot write native state.

Current Highest-Priority Gap: Native Heartbeat Daemon

Current mechanism

epiphany-heartbeat-store owns typed tick, pump, complete, repair-stale, routine, and status operations. It already enforces pending turn freeze, completion-gated cooldown, adaptive pacing, swarm brakes, stale turn repair, rumination, sleep, memory resonance, and dream maintenance.

The first native loop is landed as epiphany-heartbeat-store serve. It reuses the existing routine state owner, writes per-pulse artifact directories, emits compact sealed pulse/closure receipts, refuses a zero interval, and supports bounded clean shutdown for verification. It does not spawn or own child lifecycle. The old attached PowerShell rumination vigil has been deleted; it no longer owns timing, loop survival, or cycle status.

Intended change

The bounded Idunn launch boundary is proven: the native loop survives brake refusals, resumes from the same persisted store, and can be launched again by Idunn without duplicate pending turns. The heartbeat binary owns pulse timing and typed heartbeat receipts. Idunn owns child launch, stdout/stderr artifacts, and lifecycle receipts. Self remains only the routing organ consuming heartbeat pressure. Existing epiphany.cultmesh.daemon_restart_policy is not the right owner for the remaining step: it is keyed to standing topology daemons and their liveness status. The heartbeat loop is an Idunn-managed child service. The missing owner is a typed managed-service desired-state policy keyed by service id, plus compact operator readback; do not forge an eighth standing daemon to reuse the daemon policy table. That desired-state document is now landed as epiphany.cultmesh.managed_service_policy.v0. Idunn can write it from the same service command/args/cwd and sealed log refs used by lifecycle launch, and can read it beside the latest lifecycle receipt. Readback explicitly reports process observation as unknown until reconciliation probes reality; a past launched receipt is not allowed to impersonate a living process. Managed-service reconciliation is now implemented with a native platform PID probe (OpenProcess/GetExitCodeProcess on Windows and kill(pid, 0) on Unix). It honors enabled/restart mode/cooldown, observes alive services without duplicating them, and delegates dead/missing restarts to service-launch. Launch receipts now include an attempt timestamp so restart history is immutable instead of overwriting one service/action key. Live heartbeat proof launched, observed alive, simulated a crash, relaunched with a distinct PID and receipt, then observed the replacement alive on the same heartbeat store.

Owner

• Heartbeat scheduler: when a pulse is due and which bounded routine/pump action runs.
• Idunn: whether the heartbeat process is running and how it restarts.
• Continuity: repair of stale active turns and sleep/compaction evidence.
• Mind: admission of durable self/memory changes proposed by heartbeat work.

Inputs

• heartbeat CultCache store;
• agent-memory store;
• local Verse store and swarm brake;
• bounded interval, maximum iterations, and shutdown signal;
• current pressure and pending-turn state.

Outputs

• typed heartbeat selection/completion/routine receipts;
• compact status/telemetry projection;
• Idunn service lifecycle receipt and sealed stdout/stderr artifacts;
• explicit clean shutdown or failure status.

Durable service policy requirement

Add one typed Idunn managed-service policy with owner Idunn and key service_id. It may read the desired command/args/cwd, enabled state, restart mode, cooldown/backoff, expected heartbeat store, stdout/stderr artifact refs, and latest lifecycle receipt. It emits desired-state readback and delegates every actual start/restart to the existing service lifecycle launch primitive. It does not own heartbeat scheduling state, daemon topology, or routine output. The persistence/publication half is complete. Next add reconciliation that probes the policy's last PID or an equivalent platform process witness, applies enabled/restart-mode/cooldown intent, and delegates any restart to the existing service lifecycle launch primitive. Reconciliation is complete as an explicit Idunn command. The remaining unattended boundary is to include managed-service reconciliation in Idunn's native serve scheduler and replace service-launch's full local-Verse context load with the narrow swarm-brake query it actually needs. That boundary is now complete. Service plan/launch use the narrow typed brake loader and no longer reseed the full local Verse. A dedicated managed-service-serve loop enumerates only managed-service policies and runs their reconcile reflex independently of standing-daemon topology. Live proof observed a heartbeat alive without duplicate launch, killed it, and the next Idunn pulse restarted it from the same store with a distinct PID and immutable lifecycle receipt. The next gap is inspectability: publish compact managed service desired/observed rows through provider-owned Eve without opening command payloads or routine artifacts. The first sight organ is landed as epiphany-verse-query managed-services. Native process observation now lives in a shared core module used by both Idunn reconciliation and provider sight projection. Rows show desired enabled/restart mode, observed alive/dead/missing, PID, latest immutable lifecycle receipt, compact last heartbeat pulse status/iteration/artifact, and the private-state seal. Live proof transitioned the same row from READY/alive to ATTN/dead after a forced process death without exposing command args or routine payloads. Next lower this typed row family into the main provider-owned Eve composition graph.

Forbidden writers

• PowerShell wall-clock loops deciding heartbeat truth;
• Self spawning or restarting the heartbeat process;
• a renderer owning scheduling state;
• sleep directly mutating durable identity without Continuity/Mind review;
• overlapping pulses while a previous pulse remains active.

Shared paths

Manual tick/pump/routine, daemon pulses, recovery after restart, swarm brake refusal, and shutdown must call the same existing store primitives. The daemon is orchestration around those owners, not a second scheduler.

Cut line

The attached PowerShell rumination vigil is deleted. Do not preserve its timing, status, or cycle-directory conventions as runtime authority.

Verification

• unit test: serve refuses zero/unsafe interval and overlapping active work;
• bounded smoke: two iterations use the same typed routine/pump primitives and stop cleanly;
• restart smoke: Idunn lifecycle receipt proves child ownership and a second process resumes from persisted heartbeat state without duplicate pending turns;
• brake smoke: an engaged swarm brake prevents mutation while the daemon stays observable;
• negative source check: the native heartbeat binary contains no child spawn or second state writer;
• operator readback: status names heartbeat owner, Idunn lifecycle owner, last completed pulse, next due pulse, active turn, and private-state seal.

Subsequent Audits

1. Narrow the remaining query_epiphany_local_verse_context consumers. Daemon and operator commands should load only the typed families they own or project.
2. Re-audit Persona Projector -> Persona -> Mind Interpreter against current Void behavior and public permission boundaries.
3. Make Aquarium lower the organ graph, contract catalog, and per-turn receipt chains from CultMesh/Eve instead of hard-coded routes.
4. Audit non-repo-work actuators and legacy state families for bypasses around Substrate Gate, Hands, Soul, or the canonical Mind transaction.
5. Finish Codex starvation: retain only authenticated model transport and explicitly quarantined compatibility edges.

Perfect Machine Target

Self routes.
Substrate Gate grants substrate access.
Eyes certifies inspected evidence.
Imagination projects possible futures and lived context.
Persona speaks as a person.
Hands changes the world.
Soul verifies consequence and invariant.
Modeling updates the machine model from verified consequence.
Continuity preserves coherence across sleep, interruption, and rupture.
Mind admits durable state.
Idunn keeps the body alive.
CultMesh/CultNet carry typed signal.
CultCache preserves typed memory.
Eve/Aquarium make the organism inspectable without becoming its truth.