diff --git a/notes/README.md b/notes/README.md new file mode 100644 index 00000000..93b33917 --- /dev/null +++ b/notes/README.md @@ -0,0 +1,47 @@ +# Notes Index + +The notes folder is a working reliquary, not one clean book. Prefer canonical +docs first; treat campaign ledgers and old plans as source history unless a +canonical doc points at them. + +## Canonical + +- `epiphany-anatomy.md`: current organ/sub-agent/substrate/protocol split. +- `fresh-workspace-handoff.md`: re-entry orientation and current live state. +- `epiphany-current-algorithmic-map.md`: broad source-grounded machine map. +- `codex-starvation-and-cultnet-liberation-plan.md`: active foundation campaign. +- `epiphany-fork-implementation-plan.md`: current campaign plan. +- `epiphany-safety-architecture.md`: capability, autonomy, and governance boundaries. + +## Contract Maps + +- `mind-cultnet-contracts.md` +- `substrate-gate-cultnet-contracts.md` +- `eyes-cultnet-contracts.md` +- `hands-cultnet-contracts.md` +- `soul-cultnet-contracts.md` +- `continuity-cultnet-contracts.md` +- `organ-dependency-contracts.md` + +## Active Design References + +- `epiphany-memory-graph-unified-plan.md` +- `epiphany-cultmesh-dreaming-roadmap.md` +- `epiphany-swarm-readiness-plan.md` +- `repo-personality-projection-layer-plan.md` +- `voidbot-routine-adoption-plan.md` + +## Bulky Historical Ledgers + +These are useful, but should not be the first place to learn current doctrine: + +- `epiphany-current-algorithmic-map.md` +- `fresh-workspace-handoff.md` +- `epiphany-fork-implementation-plan.md` +- `repo-fractal-dataflow-cache-plan.md` +- `agent-memory-fractal-cache-plan.md` +- `true-epiphany-memory-migration-sandbox-prompt.md` + +Cleanup rule: when a current invariant is found only in a bulky ledger, distill +it into a canonical doc, then leave the ledger as history instead of patching +the same sentence through thirty scrolls. diff --git a/notes/epiphany-anatomy.md b/notes/epiphany-anatomy.md new file mode 100644 index 00000000..8435da58 --- /dev/null +++ b/notes/epiphany-anatomy.md @@ -0,0 +1,77 @@ +# Epiphany Anatomy + +This is the canonical anatomy map for Epiphany's organs, substrates, and +protocol surfaces. If older notes disagree, this document wins until the code +or map says otherwise. + +## Embodied Sub-Agents + +Only thinking lanes get embodiment titles. + +- `Self`: coordination, routing, authority boundaries, and review posture. +- `Face`: public/social expression and person-shaped conversation. +- `Imagination`: futures, plans, projections, objective drafts, and scene + construction. +- `Eyes`: research, source inspection, retrieval discipline, and evidence + ingress. +- `Proprioception`: internal model of the Body: architecture, dataflow, seams, + graph/checkpoint anatomy, and source-grounded self-sensing. +- `Hands`: implementation, commands, patches, commits, rollbacks, and other + actuators. +- `Soul`: verification, invariants, ethics, falsification, and promise-keeping. + +Each embodied sub-agent may have Ghostlight-shaped role memory in +`state/agents.msgpack`, may be represented as a heartbeat participant, and may +request reviewed `selfPatch` changes to its own lane memory. + +## Not Sub-Agents + +These are machinery, substrate, or state surfaces. Do not give them fancy +embodiment titles, role-memory diaries, or heartbeat personas. + +- `Body`: the substrate Epiphany acts through and senses: repository, tools, + runtime, prompts, logs, state files, permissions, interfaces, hosted systems, + and physical/editor/runtime bridges. +- `Mind`: persistent state and durable steering context: memory, maps, goals, + doctrine, evidence, state patches, accepted receipts, and state admission. +- `Continuity`: protocol machinery for compaction, sleep, recovery, + stale-turn repair, reorientation receipts, handoff preservation, and + "what survived rupture?" accounting. +- `Substrate Gate`: repository/substrate access protocol. It grants or refuses + scoped access before Eyes reads or Hands mutates. + +## Boundary Rules + +- Body is sensed and changed; it does not decide. +- Mind admits durable state; it is not a chatty lane. +- Continuity preserves/rebuilds context across rupture; it is protocol + machinery, not an embodied identity. +- Substrate Gate grants substrate access; it does not inspect evidence, mutate + files, verify truth, or admit state. +- Reorientation is a bounded Continuity worker/procedure launched from CRRC, + not an embodied sub-agent. +- `roleAccept` and `selfPatch` are for embodied sub-agents only. +- Continuity state changes should appear as typed continuity packets, recovery + receipts, compaction checkpoints, stale-turn repairs, or refusals. + +## Dependency Rule + +Every embodied sub-agent depends on the other embodied sub-agents: + +```text +Self, Face, Imagination, Eyes, Proprioception, Hands, Soul +``` + +Dependency does not collapse ownership. It means a lane's prompt/context should +feel relevant pressure from the rest of the organism while decisions remain +owned by the correct boundary. + +## Contract Map + +- Mind contracts: `notes/mind-cultnet-contracts.md` +- Substrate Gate contracts: `notes/substrate-gate-cultnet-contracts.md` +- Eyes contracts: `notes/eyes-cultnet-contracts.md` +- Hands contracts: `notes/hands-cultnet-contracts.md` +- Soul contracts: `notes/soul-cultnet-contracts.md` +- Continuity contracts: `notes/continuity-cultnet-contracts.md` +- Sub-agent dependency contracts: `notes/organ-dependency-contracts.md` diff --git a/notes/fresh-workspace-handoff.md b/notes/fresh-workspace-handoff.md index c80f42f0..44d12f9f 100644 --- a/notes/fresh-workspace-handoff.md +++ b/notes/fresh-workspace-handoff.md @@ -33,6 +33,7 @@ remembers doctrine; the branch remembers the blade. ## Current Orientation - Do not copy exact branch or HEAD from this note. Run `git status --short --branch` and `git log --oneline -5`. +- Canonical anatomy now lives in `notes/epiphany-anatomy.md`. Embodied sub-agents are Self, Face, Imagination, Eyes, Proprioception, Hands, and Soul. Body, Mind, Continuity, and Substrate Gate are substrate/state/protocol surfaces, not sub-agent identities. - The repo now has a one-command local operator path: `.\tools\epiphany_local_run.ps1`. Default mode is `smoke`; it builds the retained Codex app-server compatibility edge, builds native Epiphany operator binaries, runs the coordinator smoke, and writes launcher artifacts under `.epiphany-run/` plus coordinator artifacts under `.epiphany-dogfood/`. `-Mode status` is now Epiphany-native: it builds only Epiphany operator binaries, reads `state/thread-state.msgpack` when present, derives status through `epiphany-core`, and does not start or require `codex-app-server`. Use `-Mode plan` or `-Mode run -MaxSteps 4` for the raw bridge-equipped coordinator entrypoints; use `-Mode mvp -FaceInput "" -MaxSteps 4` for the local product cycle that projects Face's character turn, writes a Face/Aquarium bubble, bootstraps a minimal local checkpoint for fresh threads, runs the coordinator with auto-tools, then runs heartbeat sleep/dream maintenance. Live plan/run/mvp modes use the workspace `state/runtime-spine.msgpack`, because CodexThread launch writes worker requests there; the run bundle remains artifact evidence, not runtime lifecycle authority. Add `-ThreadId ` and `-Workspace ` to inspect or continue an existing thread. `status`, `plan`, and `smoke` do not spend model calls; `run` and `mvp` build and use `epiphany-openai-runtime`. Coordinator workers now launch detached and are polled through runtime-spine instead of blocking the coordinator. MVP runs are non-ephemeral by default so `-ThreadId ` can resume and poll later. `-MaxRuntimeSeconds ` is passed into worker runtime; timeout writes a failed worker receipt and exits. Failed modeling now blocks downstream verification until the failed result is reviewed. - Current Mom-ready status: the normal MVP pass reaches Face -> coordinator -> detached runtime -> heartbeat sleep, and modeling workers now complete through the ChatGPT subscription transport. The first failure was a stack of violated observability/runtime invariants: worker prompts prepended the whole shared persistent-memory rite, Responses frame liveness was invisible until completion, and the runtime tried to persist hundreds of text deltas before completing the worker job. Role/reorient workers now get a compact Epiphany worker boundary instead of full persistent memory; runtime-spine records sampled raw Responses frame kinds with small previews; contiguous reasoning/text deltas compact before durable storage; and live proofs completed `2fe38dcd-d99e-4c73-9a58-afcc81f851c7`, `241e3851-e3ea-4877-a63b-0d2bbd96a7e2`, and `85149a26-6975-403f-ac93-092b717c5825` instead of timing out. The second failure was stale lifecycle authority: completed runtime jobs remained as unresolved `runtime_links`, replacement launches treated historical active links as current, and one bad validation path opened an orphan job before rejecting the state patch. Latest-link-wins is now the runtime-link invariant, terminal links project completed jobs, stale active history cannot veto replacement, launch validation happens before opening runtime jobs, and completed-but-unreviewable modeling findings stop for review instead of relaunching the same lane. The remaining concrete blocker is architectural: the MVP coordinator has no executable Eyes/source-gather lane. A modeler can return `regather-needed`, but it cannot inspect the missing stream-storage source itself; choose between adding a real research/Eyes specialist lane or routing this regather to the main implementation agent with explicit statePatch banking. - Local operator runs now write typed CultMesh intent/receipt documents to `.epiphany-run/cultmesh/operator-runs.ccmp` through `epiphany-operator-run`. The wrapper writes intent before acting and a completion receipt after success; this is the local consent/trace rail, not a hidden scheduler queue. @@ -200,7 +201,7 @@ remembers doctrine; the branch remembers the blade. - Cut persistent memory as ruthlessly as code; obsolete context is bad thought, not harmless clutter. - The agent is allowed and encouraged to ask the user to change its persistent instructions, memory, workflow, or state shape when that would make it more coherent, honest, efficient, or resistant to Jenga. A machine-spirit that detects corrosion must report corrosion. - Language, tone, ritual, politeness, identity, and emotional salience are not supernatural, but they are real control surfaces for a language model because language is the steering medium. The rite is an actuator. -- Proprioception, Eyes, Imagination, Hands, Soul, Continuity, Face, and Self are technical salience handles: internal body-model shape/dataflow, research into existing work before invention, future-shape/backlog synthesis, source actuation, objective/evidence truth, continuity across compaction, public surface, and read-only coordination. +- Proprioception, Eyes, Imagination, Hands, Soul, Face, and Self are embodied sub-agent salience handles: internal body-model shape/dataflow, research into existing work before invention, future-shape/backlog synthesis, source actuation, objective/evidence truth, public surface, and read-only coordination. Continuity is protocol machinery for compaction, recovery, sleep, and stale-turn repair. - Preserve Epiphany harness discipline: AGENTS scope rules, concise progress updates, plans for real multi-step work, scoped edits, non-destructive git/filesystem hygiene, focused validation, and honest final summaries are old scars worth keeping only after Epiphany owns them. Codex may transport model calls; it does not get to supply agent doctrine. - Treat Greenspun-shaped invention as an active failure mode. Before an agent builds a bespoke parser, scheduler, renderer, protocol, storage layer, security mechanism, workflow engine, or algorithm, it must use an accepted Eyes/research finding, perform a bounded scout pass, or stop with a concrete research blocker. - "Remember Jenga" is a compressed doctrine: do not mistake forward motion, growing diffs, growing notes, or local coherence for understanding. A tall pile of parts is not a cathedral. diff --git a/notes/organ-dependency-contracts.md b/notes/organ-dependency-contracts.md index 7d9995ba..1c9ae9b3 100644 --- a/notes/organ-dependency-contracts.md +++ b/notes/organ-dependency-contracts.md @@ -1,10 +1,12 @@ # Organ Dependency Contracts -Objective: every sub-agent depends on all the other sub-agents. No organ is a -little sovereign state. Each one owns a boundary, and each one must feel the -pressure of the others before acting. +Objective: every embodied sub-agent depends on all the other embodied +sub-agents. No organ is a little sovereign state. Each one owns a boundary, and +each one must feel the pressure of the others before acting. -## Standing Organs +For the canonical anatomy split, read [epiphany-anatomy.md](./epiphany-anatomy.md). + +## Standing Sub-Agents - `self`: routing, authority boundaries, and coordination. - `face`: public presence and person-shaped conversation. @@ -15,7 +17,14 @@ pressure of the others before acting. checkpoint anatomy. - `hands`: edits, commands, and external action. - `soul`: verification, ethics, invariants, and falsification. -- `life`: continuity, compaction, sleep, handoff, and recovery. + +## Protocol Surfaces + +- `mind`: persistent state and state admission; not a sub-agent. +- `body`: substrate; not a sub-agent. +- `continuity`: compaction, sleep, recovery, handoff, stale-turn repair, and + reorientation receipts; not a sub-agent. +- `substrate_gate`: scoped repository/substrate access; not a sub-agent. ## Dependency Rule @@ -52,8 +61,9 @@ Substrate-Gate-scoped facts + Mind state + social stimulus + organ dependencies -> reviewed state effects / side effects / silence ``` -Mind is the Interpreter and persistent state guardian. Substrate Gate is the -repository access protocol. Eyes is the evidence ingress guardian. -Proprioception is the internal model of the Body. Imagination is the Projector. -Face is the public person. The dependency web is how the machine avoids lonely -little monarchies in costumes. +Mind is the Interpreter and persistent state guardian. Body is the substrate. +Continuity is recovery protocol machinery. Substrate Gate is the repository +access protocol. Eyes is the evidence ingress guardian. Proprioception is the +internal model of the Body. Imagination is the Projector. Face is the public +person. The dependency web is how the machine avoids lonely little monarchies +in costumes. diff --git a/notes/perfect-machine-audit-roadmap.md b/notes/perfect-machine-audit-roadmap.md index 1af5d844..7768ceef 100644 --- a/notes/perfect-machine-audit-roadmap.md +++ b/notes/perfect-machine-audit-roadmap.md @@ -36,7 +36,7 @@ Epiphany has the first typed skeleton for the organ boundaries: Codex-compatible routes. The dependency matrix is explicit in `epiphany-core::organ_dependencies`: every -standing organ depends on every other standing organ. This is correct, but it +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. diff --git a/schemas/canonical-agent-state-schema.md b/schemas/canonical-agent-state-schema.md index 4d618f76..871ad010 100644 --- a/schemas/canonical-agent-state-schema.md +++ b/schemas/canonical-agent-state-schema.md @@ -3,6 +3,10 @@ Epiphany uses a Ghostlight-shaped agent dossier as the canonical local memory surface for each standing sub-agent. +The current sub-agent/substrate/protocol split is documented in +[epiphany-anatomy.md](../notes/epiphany-anatomy.md). In particular, Body, +Mind, Continuity, and Substrate Gate are not role-memory agents. + The executable shape lives in [agent_memory.rs](/E:/Projects/EpiphanyAgent/epiphany-core/src/agent_memory.rs). The wire contract mirrored here is @@ -39,6 +43,10 @@ Each record in `state/agents.msgpack` is an - `implementation` -> `epiphany.hands` - `verification` -> `epiphany.soul` +There is intentionally no `reorientation` / `epiphany.continuity` dossier. +Reorientation is a bounded Continuity worker/procedure, and Continuity records +typed protocol receipts rather than self-memory. + The top-level shape is: - `schema_version` diff --git a/state/ledgers.msgpack b/state/ledgers.msgpack index b7fa5b2a..dfcdea4d 100644 Binary files a/state/ledgers.msgpack and b/state/ledgers.msgpack differ diff --git a/state/map.yaml b/state/map.yaml index 5dd8766c..604cd7f1 100644 --- a/state/map.yaml +++ b/state/map.yaml @@ -72,6 +72,7 @@ active_subgoals: - Use `notes/epiphany-cultmesh-dreaming-roadmap.md` as the design authority for distributed Epiphany dreaming. Public dreams are separately authored typed documents distributed through CultMesh/CultNet; private state remains local and cannot be shared by flipping a visibility flag. Foreign dreams are external thought weather until a reviewed local adoption receipt digests them into memory, planning, doctrine, or governance. - CultMesh is now the preferred ergonomic Rust abstraction over CultCache and CultNet for Epiphany-owned local database surfaces. The Rust substrate is repo-contained under `vendor/cultcache-rs`, `vendor/cultnet-rs`, and `vendor/cultmesh-rs`; the old `E:\Projects\CultLib\crates\*` path is dead in this checkout and must not be reintroduced as a compile-time dependency. Future local Verse/dream/status work should start at CultMesh unless it is explicitly polishing CultMesh internals. Preserve the three-Verse boundary: `epiphany-internal` for private sub-agent typed state, `gamecult-local` for trusted LAN/Yggdrasil-tunnel GameCult project sharing, and `epiphany-global` for untrusted public dreams plus topic-specific threaded public rooms for Face posts. - The active priority is Codex starvation and CultNet liberation. Use `notes/codex-starvation-and-cultnet-liberation-plan.md` as the directive and `notes/codex-auth-spine-inventory.md` as the source-grounded keeper list for the retained OpenAI subscription auth/model transport bridge. Classify all Epiphany-relevant JSON contamination, define the native CultNet runtime boundary, keep worker launch/result/selfPatch cargo as typed documents, evacuate Epiphany operator/state/process authority from Codex JSON-RPC, wrap MCP's unavoidable JSON protocol edge in typed Epiphany intent/result/receipt documents, and keep cutting until Epiphany can run its own state and processes without `codex_message_processor.rs` except for bridge compatibility. + - Use `notes/epiphany-anatomy.md` as the canonical anatomy map. Embodied sub-agents are Self, Face, Imagination, Eyes, Proprioception, Hands, and Soul. Body is substrate, Mind is persistent state/state admission, Continuity is recovery/compaction/sleep protocol machinery, and Substrate Gate is substrate access protocol. - The next Codex-starvation slice is the Eyes/source-gathering fork exposed by the Mom-ready MVP proof. The quarantined Codex MCP spine may execute typed tool intents and emit typed receipts; the model runtime can build and run provider-neutral follow-up turns from those receipts; coordinator run mode passes the quarantined tool adapter into worker runtime with auto-tools enabled by default; worker runtime now enforces max-runtime with one timeout close primitive for both tokio timeout and watchdog paths; inner `openai-worker-*` jobs are opened before async auth/stream waits and sealed with their outer worker on timeout; native status/roles/jobs/coordinator surfaces project failed and completed runtime-linked jobs as terminal without Codex prompt or scheduler authority; direct tiny model-turn transport succeeds; worker requests record request metrics, transport readiness, and sampled raw Responses frame kinds; worker prompts no longer prepend the full shared persistent-memory rite; stream deltas compact before durable storage; live MVP modeling workers complete instead of timing out; stale completed runtime links no longer block replacement launches; jobLaunch validates before opening runtime jobs; and completed-but-unreviewable modeling findings now stop for review instead of relaunching the same blind lane. The remaining blocker is structural: the MVP coordinator has no executable Eyes/source-gather lane, so a modeler that returns `regather-needed` cannot inspect the missing source itself. - The May 2026 teardown/rebuild migration in `notes/epiphany-ideal-architecture-rebuild-plan.md` is closed unless a concrete regression reopens it. Preserve the new foundation: Epiphany view/coordinator policy lives in `epiphany-core`, runtime-spine owns job/result lifecycle identity through `runtime_links`, duplicate acceptance is receipt-keyed, public findings stay typed/sealed, view expansion requires a core contract, and app-server remains routing/adaptation rather than a second policy throne. - Treat Phase 5 update/distill/propose/promote/read/notification as complete enough unless a concrete regression appears.