Epiphany/notes/epiphany-current-algorithmic-map.md

Epiphany current algorithmic map

Updated: 2026-08-22 Latest committed implementation cut: d48f69b7 on codex/epiphany-shakedown-live Current worktree cut: Ox10 documentation and evidence reconciliation

This document describes the live machine. Historical cuts, rejected paths, and proof chronology belong in git, state/ledgers.msgpack, and bounded smoke artifacts.

Objective

Epiphany is a native typed organism whose durable decisions can answer one question without consulting a transcript:

What exact typed state and governed observations was this pass reasoning from when it produced this decision?

CultCache is the decision-bearing substrate. CultNet/CultMesh carry typed projections and crossings. The model-provider boundary explicitly selects a typed provider dialect and internally derives the exact provider request from the canonical native request. OpenRouter/Ox is the current Yggdrasil provider; Codex-derived code remains only where an OpenAI provider needs its earned authentication or transport. Neither owns Epiphany Mind, scheduler, route, or interface authority.

Canonical authority map

Owner	Inputs	Outputs	Invariant
keyed Mind documents	typed semantic documents keyed by logical identity	deterministic EpiphanyMindView	There is no persisted aggregate Mind head or global revision.
reasoning_context.rs Mind commit owner	invariant-owned strong reads and complete typed writes	atomic batch CAS plus EpiphanyMindCommitReceipt	Disjoint identities merge; same-identity or changed-strong-read conflicts refuse without partial mutation.
concrete family admission owners	sealed decision context, exact family request/result chain, affected semantic documents	one family-specific MindMutation	The model cannot choose which stale state is safe to ignore.
current_work.rs	keyed Mind view and exact runtime request/job/result/decision families	pure family scheduling and continuation projections	Events, timestamps, role lanes, and thread provenance cannot create or suppress work.
coordinator policy/status	current-work projections, Resident pressure, and exact runtime receipts	one prioritized recommendation and read-only operator views	Coordinator presence is derived; no mutable coordinator head exists.
runtime worker attempt owner	immutable launch, exact process claim, typed result, job result, archival evidence	one terminal attempt authority	Scheduling, process liveness, and semantic admission remain distinct authorities.
model-provider boundary	sealed native model request plus explicit provider configuration and injected credential	exact internally derived provider request and transport result	Provider selection cannot author a second request truth or admit Mind state.
OpenAI Responses schema projector	full native typed output schema	one provider-legal strict generation schema	Provider formatting preserves useful supported constraints but never replaces native decoding or Mind admission.
model-pass terminal owner	sealed reasoning basis/context and typed failure class	exact transport closure plus EpiphanyModelPassFailure and terminal session/event in one batch CAS	The caller cannot nominate a job/session; the context-derived binding closes role, reorient, and Persona failures without granting generic transport results decision authority.
Substrate Gate	exact worker/job authority and requested operation	scoped grant or refusal	Access permission does not admit Mind state.
Eyes	explicit external-evidence obligation plus governed source receipts	typed evidence packet and Mind observations	Eyes gathers outside evidence; it does not gate Modeling over the Body.
Modeling	Body basis, keyed RepoModel view, verified consequences, and explicit proposals	typed graph/frontier mutations	Modeling processes the Body directly and owns no external-source permission.
Hands	adopted route/plan plus exact capability receipts	typed consequences	A claimed intention is not a consequence.
Soul	exact consequence and invariant/evidence obligations	verification audit or refusal	Work is not true merely because it ran.
Persona	unread typed social/relationship state plus exact Persona projection	typed effects, speech intent, and consequence receipts	Persona work cannot block unrelated Hands or Modeling documents.
CultMesh/Eve	typed provider-owned documents and deterministic views	private/local/public projections	Visibility and rendering never create authority.

External lifecycle boundary: Idunn remains available when Epiphany is missing, failed, or braked. Epiphany's swarm brake is an input only to an Idunn transaction that changes Epiphany's deployed body; it cannot gate Idunn startup, self-bootstrap, observation, same-release recovery, or another target's lifecycle. The persisted Epiphany brake survives that recovery and continues to block cognition/consequence ingress. Treating the target brake as a deployer prerequisite reverses the owner and creates an unrecoverable cycle.

Idunn's CI/CD loop also owns the source-change path on upgraded Yggdrasil: observe pushed commit, compile, test, construct the exact release, admit/deploy it, and publish service-health receipts. Starfire is an operator/source body; it does not run a parallel release build when Idunn owns the same change.

Canonical Mind

The runtime Mind .cc is the sole decision-bearing store. Other .cc files may own physiology or external transport, but facts from them must enter Mind as typed observations or receipts before an agent pass consumes them.

Singleton semantic identities:

• objective;
• focus;
• mode;
• RepoModel identity/body binding.

Keyed semantic identities include subgoals, invariants, evidence, observations, checkpoints, planning items, Persona memories and social reads, Hands receipts, Verification audits, and RepoModel domains/nodes/edges/summaries/frontier/ lifecycle receipts/per-claim obligation guards.

EpiphanyMindView and EpiphanyRepoModelView are deterministic assemblies of exact envelopes. Their projection digests identify a view for audit/display; they are not mutable authority revisions.

Deleted authority:

• EpiphanyThreadStateEntry and EpiphanyThreadState;
• coordinator_state_transaction and generic state-update services;
• generic coordinator launch/accept/interrupt requests;
• global expectedRevision and worker-launch stateRevision;
• aggregate prompt, freshness, and graph-context surfaces;
• aggregate RepoModel persistence and global model revision/hash causality.

There is no dual reader, bootstrap aggregate, migrator, or compatibility write path.

Reasoning audit path

flowchart LR
    S["Exact typed Mind envelopes"] --> B["Sealed EpiphanyReasoningBasis"]
    B --> N["Final native model request"]
    N --> P["Internally derived provider request"]
    P --> T["Governed tool intents and receipts"]
    T --> C["Sealed EpiphanyDecisionContext"]
    C --> D["Typed terminal decision or pass failure"]
    D --> M["Invariant-owned MindMutation"]
    M --> R["EpiphanyMindCommitReceipt"]

The sealed basis contains pass/organ identity, projection-policy version, exact source document versions, immutable Body basis where applicable, and a closed typed reasoning-projection variant.

The terminal context contains the exact basis ID, exact final native request, the exact internally derived provider request, and ordered governed tool intent/receipt versions actually supplied to the pass.

Provider credentials remain deployment-substrate inputs. Yggdrasil injects the OpenRouter key through systemd LoadCredential; readiness is checked inside Resident Self's mount namespace. The key is neither prompt cargo nor Mind state.

Structured decisions are authoritative; token streams and assistant deltas are optional retention. A model-backed failure is also a typed terminal decision record. Generic diagnostic model runs cannot produce Mind-admissible decisions.

Current migration boundary: the typed basis/context foundation, concrete Body, frontier, Research, Verification, Planning, Reorientation, and Persona paths, plus worker/session/Persona archive reachability are landed. Exact f8412b69 adds one read-only context-ID audit projection and deletes the digest-only worker archive: the typed role and generic terminal result family now survives retention, and runtime schema v2 refuses the earlier writable shape. Exact f7948795 deletes MindGatewayReview, MindStateCommitReceipt v0, the generic Mind interpreter prompt, and their false CultNet mutation mouths. Exact e0e75a30 deletes the residual aggregate-shaped role patch, its parser, and its family-policy tribunals. Research now authors one closed typed decision whose admission owner derives keyed Mind writes; the unowned generic Imagination planning patch is gone. Exact 1c9aafd8 seals one decision context before model-backed frontier-Planning failure terminalization and binds both the typed faculty failure and generic job result to it. Shared runtime validators own the store-backed model/tool refusal matrix used by both execution and sealing. Exact 553f79d9 gives every role and Persona pass one shared Responses dialect compiler. The provider sees a closed, generation-useful subset; native typed decoding still sees the full schema and alone decides whether a terminal decision can enter Mind. Provider success therefore cannot launder malformed semantic output.

Exact a8f3c1f0 makes the authenticated runtime Body route own initial RepoModel binding. Bootstrap derives the keyed model identity from the admitted Body observation instead of confusing Git source identity with Body-store identity, and initialize_keyed_repo_model independently refuses a seed whose runtime, swarm, workspace, or Body-binding digest disagrees with the live route. The refusal is whole-store byte-identical. Later Modeling decisions remain bound to their exact observation version and are never rebased.

Exact bb823c54 adds one shared failure terminal owner after a native provider refusal exposed split Persona closure. The failure cites the sealed basis/context and exact model request; runtime derives the exact transport binding from that context and atomically closes a still-live transport job plus the exact model session. Role, reorient, and Persona failures use that same owner; a generic transport result remains physiological and carries no decision context. Persona re-entry first consults the typed failure, so failure cannot resurrect inference. Successful Persona turns close only after their effect document and terminal receipt exist. Runtime execution opening and context sealing both derive provider requests internally from native requests; the caller-authored provider-request entrance is deleted. A native negative replay proves transcript-free audit plus byte-identical runtime/heartbeat restart. Reorientation's family admission additionally requires the exact canonical model-pass failure; a generic failed worker result plus context cannot mint a Continuity failure decision. Exact failure replay includes the terminal time, and audit/lookup revalidate the failure against its runtime model binding.

Concurrent Mind mutation

Each concrete invariant owner builds a MindMutation containing exact decision context, exact strong-read envelopes, exact inserts/replacements, its invariant owner identity, and an atomically written commit receipt.

Merge law:

1. Different document identities merge regardless of commit order.
2. Distinct inserts merge.
3. Same-identity byte-identical replay returns the original receipt.
4. Same-identity divergent writes conflict.
5. Changed strong reads conflict before mutation.
6. Observational-only source changes do not block an unrelated mutation.
7. Multi-document invariants commit entirely or not at all.
8. Model output is never silently rebased; conflict creates fresh work.

Collection members therefore remain separate CultCache identities. Shared vectors and mutable global heads are forbidden because they manufacture false conflict between Persona, Hands, Modeling, and Verification.

The semantic projector applies the same doctrine to derived cache work. Before acquisition, completion, retention, or retirement, it reconstructs the complete current Modeling basis from the opening snapshot and requires the supplied content-addressed obligation to match. Acquisition is full-snapshot CAS, so a concurrent keyed insert is fenced even though none of the older source envelopes changed. Semantic cache generations and times remain diagnostic cargo; they do not establish direction or currentness.

State-driven work

Coordinator priority is a pure projection:

1. missing keyed Mind preparation;
2. exact Reorientation work;
3. Resident pressure;
4. explicit operator regather;
5. exact Planning/PlanMind work;
6. Proposal, Body, or verdict Modeling work;
7. Verification work;
8. explicit external-evidence Research work;
9. exact consideration families;
10. Hands work;
11. otherwise await a frontier proposal.

No default Modeling job, latest lane, accepted-at comparison, runtime event, or generic interrupt can manufacture work.

flowchart TD
    Body["Typed Body observation"] --> MO["Modeling obligation"]
    MO --> Model["Modeling pass"]
    Claim["Claim requiring outside evidence"] --> EO["Eyes obligation"]
    EO --> Eyes["Eyes pass"]
    Eyes --> Evidence["Typed evidence/observation documents"]
    Evidence --> MO
    Plan["Mind-adopted plan and route"] --> Hands
    Hands --> Consequence["Typed Hands receipts"]
    Consequence --> Verify["Verification obligation"]
    Verify --> Audit["Soul audit/verdict"]
    Audit --> MO
    Social["Unread typed social state"] --> Persona

Eyes may create evidence that creates Modeling work. Eyes acceptance never suppresses or authorizes ordinary Body Modeling.

Each unresolved pass-family projection includes the semantic obligation, its continuation action, and the last exact runtime job identity when one exists. Those fields form one current-work identity. Body Modeling no longer stores bodyModelingAction beside a launch-only work value. Its one EpiphanyBodyModelingCurrentWorkProjection remains visible through Launch, Wait, and Review and binds the latest job. A failed or cancelled attempt therefore changes the projection digest and permits one fresh Resident Self pressure/grant; replaying the unchanged failed state remains idempotent. No retry counter, timestamp comparison, coordinator receipt, or event acquires scheduling authority.

Runtime and attempt lifecycle

These are distinct authorities and must not be collapsed into one state enum:

• Heartbeat owns scheduling pressure and terminal acknowledgement consumption.
• Resident Self owns grant, coordinator lease, settlement, cooldown, and requeue.
• Coordinator process owns its incarnation receipt or exact-death closure.
• Runtime worker attempt owns immutable launch, process claim, activation, typed result, job result, and terminal attempt classification.
• Mind owns adoption of a successful semantic result.
• Retention owns deletion only after all live authorities are terminal.

The attempt aggregate centralizes exact request association and typed terminal classification. Archived fulfilled attempts must retain recoverable decision authority, not merely an ID/digest tombstone.

RepoModel and semantic projection

RepoModel persistence is keyed by semantic identity: identity/body binding, domain, node, edge, summary, frontier, lifecycle receipt, and per-node claim- obligation guard.

EpiphanyRepoModelView sorts and assembles those documents. Frontier dependency and cycle checks include the exact reachable closure in strong reads. Per-node guards make node retirement versus concurrent frontier targeting physically conflict without serializing unrelated graph writes.

Semantic vector projection is derived cache work. Readiness is based on exact projection obligations and receipts; semantic cache state never admits Mind or routes an agent pass.

For Modeling, each projector pulse assembles the complete current keyed RepoModel view, authenticates every exact document version through the Mind commit receipt that owns it, and derives a content-addressed projection work item from that basis. The work item is not written inside a Mind mutation: doing so would recreate a singleton conflict domain across disjoint graph commits. An older bootstrap or concurrent work item remains harmless cache history and cannot suppress the newly assembled basis. Modeling retention uses exact basis identity, not the graph-shaped projector DTO's synthetic revision; that DTO is compatibility-shaped cache cargo only.

External and social facts

• Repository Body bytes enter through typed observations and exact digests.
• Immutable public Git content may remain external, but its canonical identity, digest, governed receipt, and exact observed excerpt enter Mind.
• Social reads enter as typed Persona observations before cognition.
• Crossings own transport and signed receipts; they never impersonate local cognition or Mind admission.
• Content-addressed artifacts may remain external, but the exact identity and decision-bearing excerpt/version are stored in the basis/context.

Retention

Preserve reasoning bases, decision contexts, structured terminal decisions and typed failures, Mind commit receipts, Persona effects, speech/consequence receipts, and their direct context links.

Runtime retention may remove SSE frames, deltas, intermediate requests, provider events, and tool scaffolding only after the terminal context is sealed and the retained decision can still reach its basis/context without them. The v1 worker-attempt archive embeds the exact typed role result and its context-bound generic result family. The read-only decision audit consumes the same durable records before and after archival.

Verification and open gates

Accepted through the local d48f69b7 source boundary:

• every Epiphany core target compiles;
• core library 496/496;
• OpenAI runtime library 25/25;
• model-runtime binary 10/10;
• OpenAI-runtime binary 10/10.
• Persona service 1/1.
• tool runtime 14/14, with the explicitly live immutable-GitHub test ignored.
• release construction 21/21.
• all core targets compile; generic role-patch source guards pass.
• authenticated Persona re-entry refuses naked typed input, performs no external observation or model call, and preserves the exact three-stage decision chain;
• reopened current-work projection is identical and byte-for-byte read-only at Launch, Wait, Review, completed, and post-Research boundaries; a failed Body attempt changes exact identity, receives one fresh grant, and identical failure replay cannot mint another pressure.
• epiphany-model-runtime audit-decision reconstructs an exact terminal pass from typed durable records only; the query is byte-for-byte read-only and remains complete after live worker result retirement.
• exact source 5f66d6c9 adds epiphany-model-runtime list-decisions, a deterministic read-only index of contexts whose terminal audit chain already validates. It omits sealed nonterminal pass physiology and cannot author or admit state.
• exact ab321b34 adds explicit OpenAI/OpenRouter transport lowering while preserving the native request as the only canonical request. Exact c1a6034f keeps read-only physiology alive under the brake; exact 6b44b4d3 emits Idunn's shared signed-health schema.
• exact source 470d4cb5b46f94a5490a479dba19604828e1b5d1 passed Idunn's native serialized Yggdrasil workspace gate under test receipt SHA-256 c6594f0a857c77ca3280864231930fa62c928f76cb807c89f321fde21ed14b66 and is deployed as 26 binaries plus witness in release sha256-ce4a287ebb915ff9410dd04e022285d82998e0bf4c9acb3b04a44db661aea90c.
• the supervisor, heartbeat, and Resident Self units are active with zero restarts, the body is authenticated-health admitted by Idunn, and the swarm and deployment brakes are engaged.
• runtime schema v2 refuses the prior digest-only worker archive epoch without mutation.

Open before Model Atlas Gate 1 resumes:

1. deploy exact build-affecting source d48f69b7 through Idunn's native compile/test/package path, verify signed health, and restore the deployment brake after the transaction;
2. run the fresh exact-package capstone over a new store with OpenRouter stealth/ox-alpha, concurrent Persona and repository work, Body direct to Modeling without Eyes, Hands through Verification, exact context audit, and restart/re-entry;
3. only then restart Model Atlas Gate 1 from a new external root.

Ox10 is preserved failed evidence under /var/lib/gamecult/epiphany/capstones/ox10-470d4cb5. It proved the direct Body route and exact failure sealing, then failed closed when Ox emitted a duplicate tension field and three Persona projector connections timed out. The malformed Modeling result made no Mind commit. The run also falsified the old Body retry projection: its failed job was omitted from current-work identity, so Resident Self saw no new pressure under the old schema. The run is braked, all transient units are inactive, and it must not be resumed or used as accepted capstone state.

Historical c011 and partial Gate roots remain read-only. The pre-upgrade Yggdrasil's old capacity/topology is obsolete; the upgraded 16-vCPU host is the intended swarm and CI/CD body. Idunn owns the installed Epiphany source-change path. The former Discord/Bifrost/VoidBot operator bridge and its deployment gate are deleted; Bifrost remains Persona and governed-consequence transport. The prior package is not capstone or service-health evidence. Operational topology registration and autonomous scheduling remain forbidden until their owning gates pass.

Primary source anchors

• epiphany-core/src/mind_documents.rs
• epiphany-core/src/reasoning_context.rs
• epiphany-core/src/current_work.rs
• epiphany-core/src/repo_model_documents.rs
• epiphany-core/src/runtime_worker_attempt.rs
• epiphany-core/src/runtime_spine.rs
• epiphany-core/src/resident_self.rs
• epiphany-core/src/reorientation_work.rs
• epiphany-core/src/surfaces/coordinator.rs
• epiphany-core/src/surfaces/worker_launch.rs
• epiphany-openai-runtime/src/lib.rs
• epiphany-openai-runtime/src/persona_executor.rs