366 lines
19 KiB
TeX
366 lines
19 KiB
TeX
\documentclass[11pt]{article}
|
|
\usepackage[margin=1in]{geometry}
|
|
\usepackage{longtable}
|
|
\usepackage{array}
|
|
\usepackage{hyperref}
|
|
\usepackage{xcolor}
|
|
\usepackage{enumitem}
|
|
\usepackage{titlesec}
|
|
\usepackage{microtype}
|
|
|
|
\DeclareUrlCommand{\code}{\urlstyle{tt}}
|
|
\newcommand{\bodyterm}[1]{\textbf{#1}}
|
|
\emergencystretch=3em
|
|
\sloppy
|
|
\setlist[itemize]{leftmargin=1.5em}
|
|
\setlist[enumerate]{leftmargin=1.5em}
|
|
\titleformat{\section}{\Large\bfseries}{\thesection}{0.8em}{}
|
|
\titleformat{\subsection}{\large\bfseries}{\thesubsection}{0.8em}{}
|
|
|
|
\title{Epiphany's Body: A Proprioception Whitepaper}
|
|
\author{GameCult / EpiphanyAgent}
|
|
\date{June 9, 2026}
|
|
|
|
\begin{document}
|
|
\maketitle
|
|
|
|
\begin{abstract}
|
|
Epiphany is an opinionated Codex-derived agent substrate built around a hard
|
|
requirement: the model must model the thing it changes. This whitepaper maps
|
|
Epiphany's \bodyterm{Body}: the repository, Rust crates, vendored bridge
|
|
machinery, typed state stores, schema catalog, runtime binaries, protocol
|
|
surfaces, operator artifacts, and external interface boundaries through which
|
|
Epiphany senses and acts. The map is written from the Proprioception faculty:
|
|
not as product copy, not as lore, but as an architecture overview whose owner,
|
|
input, output, invariant, and cut lines remain inspectable.
|
|
\end{abstract}
|
|
|
|
\section{Definition}
|
|
|
|
In Epiphany doctrine, the Body is the substrate Epiphany acts through and
|
|
senses: repository files, tools, runtime state, prompts, logs, interfaces,
|
|
permissions, hosted systems, and editor/runtime bridges. Body is not Mind. Body
|
|
is changed and sensed; Mind admits durable state. Proprioception is the faculty
|
|
that models the Body: architecture, dataflow, seams, constraints, invariants,
|
|
and the difference between the map and the substrate.
|
|
|
|
The practical definition in this repository is:
|
|
|
|
\begin{itemize}
|
|
\item the root checkout at \code{F:\Projects\Epiphany};
|
|
\item Epiphany Rust crates such as \code{epiphany-core}, model/tool adapters, and provider runtimes;
|
|
\item vendored substrate in \code{vendor/codex}, \code{vendor/cultcache-rs}, \code{vendor/cultnet-rs}, and \code{vendor/cultmesh-rs};
|
|
\item typed state stores under \code{state/};
|
|
\item schemas under \code{schemas/cultnet/};
|
|
\item local operator scripts and generated witness artifacts;
|
|
\item adjacent service/client bodies: Aquarium, Odin/Gjallar, Eve/CultUI,
|
|
Bifrost, VoidBot, Brokkr, Discord, and future GameCult Verse providers.
|
|
\end{itemize}
|
|
|
|
\section{Executive Map}
|
|
|
|
Epiphany's current Body is a typed Rust/CultCache organism with provider
|
|
transport outside its cognition boundary. Codex requests cross a lean client
|
|
ABI into the independent CodexConnector daemon, which owns subscription
|
|
credential refresh, transport, and replay. Epiphany owns prompts, tools,
|
|
reasoning context, decisions, and Mind admission; it compiles no Codex crate.
|
|
|
|
\begin{longtable}{>{\raggedright\arraybackslash}p{0.23\linewidth}>{\raggedright\arraybackslash}p{0.32\linewidth}>{\raggedright\arraybackslash}p{0.35\linewidth}}
|
|
\textbf{Body Region} & \textbf{Current Owner} & \textbf{Invariant} \\
|
|
\hline
|
|
Durable Mind state & keyed CultCache documents assembled by \code{epiphany-core} & Prompt rendering consumes sealed typed projections; no persisted thread aggregate or global authority revision exists. \\
|
|
Domain policy & \code{epiphany-core} & Verdicts, launch policy, acceptance rules, runtime lifecycle, and mutation law live here, not in bridge DTOs. \\
|
|
Codex transport & independent \code{GameCult/CodexConnector} daemon & Own subscription credentials, provider transport, and exact replay only; never own Epiphany prompts, scheduler, decisions, or state. \\
|
|
Runtime spine & \code{epiphany-core/src/runtime_spine.rs} and \code{state/runtime-spine.cc} & Runtime identity, jobs, receipts, and tool/model documents are typed CultCache records. \\
|
|
Persona memory & keyed Mind Persona-memory documents & Persona decisions admit bounded memories by semantic identity; no parallel role-memory aggregate or generation head exists. \\
|
|
Resident Self physiology & Resident Self CultCache documents via \code{epiphany-swarm} & Typed pressure, exact grant creation, launch exclusion, leases, terminal receipts, retry, and bounded retention have one owner. No scheduler singleton or acknowledgement loop exists. \\
|
|
Local Verse & CultMesh over \code{state/local-verse.cc} & Local Verse context is compact prompt/operator context; private state does not become public by flipping a flag. \\
|
|
Schema catalog & \code{schemas/cultnet/index.json} & JSON schema publishes contracts; typed Rust documents remain runtime authority. \\
|
|
Operator artifacts & \code{.epiphany-*}, \code{tools/epiphany_local_run.ps1} & Artifacts witness and lower state; they do not become state owners. \\
|
|
\end{longtable}
|
|
|
|
\section{Repository Body}
|
|
|
|
The checkout has eight primary Epiphany Rust packages:
|
|
|
|
\begin{itemize}
|
|
\item \code{epiphany-core}: the main domain organ. It owns semantic state
|
|
contracts, keyed Mind admission, launch documents, runtime spine, Resident
|
|
Self, Persona projection, Substrate Gate, Eyes, Hands, Soul, Continuity,
|
|
CultMesh integration, and surface derivation.
|
|
\item \code{epiphany-model-adapter}: provider-neutral model request, stream
|
|
event, receipt, and status documents.
|
|
\item \code{epiphany-openai-adapter}: OpenAI-shaped request/event/receipt and
|
|
status documents.
|
|
\item \code{epiphany-openai-runtime}: executable model runtime, including
|
|
\code{epiphany-model-runtime}.
|
|
\item \code{epiphany-release-construction}: exact package construction and
|
|
release-witness verification.
|
|
\item \code{epiphany-tool-adapter}: typed tool capability, invocation intent,
|
|
and invocation receipt documents.
|
|
\item \code{epiphany-tool-mcp-runtime}: first-party tool executor. Native
|
|
Epiphany source tools are explicit local capabilities; foreign MCP calls use
|
|
the official RMCP SDK behind Epiphany-owned endpoint, process, network, and
|
|
receipt policy. Codex owns no tool discovery or execution path.
|
|
\end{itemize}
|
|
|
|
The vendored region contains:
|
|
|
|
\begin{itemize}
|
|
\item \code{vendor/codex}: retained Codex-fork source history. It is not in
|
|
Epiphany's compiled runtime graph.
|
|
\item \code{vendor/cultcache-rs}, \code{vendor/cultnet-rs}, and
|
|
\code{vendor/cultmesh-rs}: repo-contained Rust Cult substrate.
|
|
\end{itemize}
|
|
|
|
\section{State Body}
|
|
|
|
The \code{state/} directory is the local persistent body. The important stores
|
|
are:
|
|
|
|
Canonical CultCache store files use the \code{.cc} extension. The local state
|
|
body has been migrated to that naming directly; serialization details are
|
|
implementation, not file authority.
|
|
|
|
\begin{longtable}{>{\raggedright\arraybackslash}p{0.30\linewidth}>{\raggedright\arraybackslash}p{0.60\linewidth}}
|
|
\textbf{Store} & \textbf{Role} \\
|
|
\hline
|
|
\code{state/map.yaml} & Canonical slow project map: objective, constraints, invariants, dataflow, active subgoals, current status, guardrails, and rejected paths. \\
|
|
\code{state/ledgers.cc} & CultCache-shaped evidence and branch ledger. Future behavior-changing lessons go here, not in an endless activity feed. \\
|
|
Resident Self store & Keyed pressure, grants, prepared and active launch authority, terminal receipts, and retention head. \\
|
|
Persona social store & Keyed mentions, immutable turn requests, terminal receipts, quarantine records, and retention plans. \\
|
|
\code{state/runtime-spine.cc} & Runtime identity, sessions, jobs, results, worker launch requests, receipts, and model/tool transport documents. Durable decisions and keyed RepoModel documents live in Mind. \\
|
|
\code{state/local-verse.cc} & Local CultMesh Verse context for compact operator and prompt-context packets. \\
|
|
\code{state/semantic-projection.cc} & Typed Qdrant projection receipts. Cache health lives here, outside the canonical RepoModel. \\
|
|
\code{state/persona-discord.toml} & Persona Discord boundary configuration. \\
|
|
\code{state/void-memory.toml} & Void memory bridge configuration. \\
|
|
\code{state/scratch.md} and \code{state/scratch-compaction-*.md} & Scratch surfaces. Scratch is a workbench, not canonical memory. \\
|
|
\end{longtable}
|
|
|
|
Lock files sit beside several stores. Some local generated state is currently
|
|
untracked, including \code{state/local-verse.cc},
|
|
\code{state/semantic-projection.cc}, and \code{.epiphany-character-loop/}.
|
|
The former sibling \code{state/memory-graph.cc}/\code{.msgpack} store is a
|
|
retired migration wound; live Modeling truth is the runtime-spine RepoModel.
|
|
|
|
\section{CultNet Schema Body}
|
|
|
|
The schema catalog in \code{schemas/cultnet/index.json} publishes the portable
|
|
contracts actually carried across a CultNet boundary. Runtime-local CultCache
|
|
registrations are discovered from the native registry instead of mirrored into
|
|
a second hand-maintained catalog. Editor commands are not Epiphany contracts:
|
|
Brokkr owns Unity editor inspection and actuation through Eve/CultMesh, and a
|
|
future Rider provider must own Rider integration through the same boundary.
|
|
|
|
The invariant is simple: schema JSON describes the contract. Load-bearing
|
|
runtime state should be typed Rust documents persisted through CultCache or
|
|
projected through CultMesh/CultNet. JSON may remain at hostile edges, schema
|
|
publication, sealed forensic artifacts, or named quarantine experiments.
|
|
|
|
\section{Runtime Spine}
|
|
|
|
\code{epiphany-core/src/runtime_spine.rs} is one of the main spinal cords of
|
|
the Body. It imports and registers:
|
|
|
|
\begin{itemize}
|
|
\item runtime identity, session, job, and job-result records;
|
|
\item worker launch requests and role/reorient worker result documents;
|
|
\item model adapter, OpenAI adapter, and tool adapter documents;
|
|
\item sealed reasoning bases, decision contexts, typed pass failures, and
|
|
exact Mind commit receipts;
|
|
\item keyed RepoModel, frontier, planning, reorientation, and Persona
|
|
lifecycle documents;
|
|
\item exact Eyes, Hands, Soul, Continuity, and Substrate Gate receipts.
|
|
\end{itemize}
|
|
|
|
Editor-provider capabilities remain outside this registry. Epiphany consumes
|
|
their typed CultMesh state and receipts; it does not embed an IDE bridge or
|
|
editor-specific lifecycle authority.
|
|
|
|
Runtime state is machinery telemetry. It is not project truth. Durable thread
|
|
state may link to runtime records through runtime links, but it must not mirror
|
|
or duplicate their lifecycle fields as a competing owner.
|
|
|
|
\section{Faculties And Protocol Machinery}
|
|
|
|
The embodied sub-agents are:
|
|
|
|
\begin{itemize}
|
|
\item \bodyterm{Self}: coordination, routing, authority boundaries.
|
|
\item \bodyterm{Persona}: public and social expression.
|
|
\item \bodyterm{Imagination}: futures, plans, objective drafts, projection.
|
|
\item \bodyterm{Eyes}: research, source inspection, evidence ingress.
|
|
\item \bodyterm{Proprioception}: internal model of Body shape, dataflow,
|
|
architecture, checkpoints, and seams.
|
|
\item \bodyterm{Hands}: commands, edits, commits, rollbacks, external action.
|
|
\item \bodyterm{Soul}: verification, invariants, ethics, falsification.
|
|
\end{itemize}
|
|
|
|
The machinery surfaces are:
|
|
|
|
\begin{itemize}
|
|
\item \bodyterm{Body}: substrate. It is sensed and changed; it does not decide.
|
|
\item \bodyterm{Mind}: persistent state and state admission.
|
|
\item \bodyterm{Continuity}: compaction, recovery, sleep, stale-turn repair,
|
|
and reorientation receipts.
|
|
\item \bodyterm{Substrate Gate}: scoped repository/substrate access.
|
|
\end{itemize}
|
|
|
|
Every embodied sub-agent depends on the other embodied sub-agents, but
|
|
dependency does not collapse ownership. A Persona turn, for example, should
|
|
move through Substrate-Gate-scoped facts, Mind state, social stimulus, organ
|
|
dependencies, Imagination as Projector, Persona as natural-language actor, and
|
|
Mind as Interpreter. None of those steps grants Persona hidden state authority.
|
|
|
|
\section{Codex Reliquary}
|
|
|
|
Epiphany publishes no app-server JSON-RPC state surface. Vendored Codex owns
|
|
only Codex concerns and the retained OpenAI-compatible auth/model transport
|
|
machinery. Epiphany state, prompts, scheduling, interfaces, and durable
|
|
invariants remain native typed organs.
|
|
|
|
The retained Codex body currently matters for:
|
|
|
|
\begin{itemize}
|
|
\item Codex-compatible auth identity and token refresh through
|
|
\code{codex-login};
|
|
\item OpenAI/Codex model transport through vendored client machinery;
|
|
\item useful app-server and streaming compatibility affordances while
|
|
Epiphany surfaces are still evacuating to native CultNet/CultMesh contracts.
|
|
\end{itemize}
|
|
|
|
The starvation doctrine is the deletion line: Codex may be a bridge and a
|
|
reliquary, but not Epiphany's prompt authority, state owner, scheduler, runtime
|
|
truth, operator API owner, or plugin marketplace brain.
|
|
|
|
\section{Operator And Interface Body}
|
|
|
|
Current operator access is partly native and partly witness-artifact based:
|
|
|
|
\begin{itemize}
|
|
\item Native binaries such as \code{epiphany-state},
|
|
\code{epiphany-mvp-coordinator}, \code{epiphany-runtime-spine},
|
|
\code{epiphany-swarm}, and the family-specific worker services
|
|
inspect or update their owned typed state.
|
|
\item Local artifact directories such as \code{.epiphany-run/},
|
|
\code{.epiphany-dogfood/}, \code{.epiphany-smoke/},
|
|
\code{.epiphany-gui/}, and
|
|
\code{.epiphany-character-loop/} witness work and lower typed state for
|
|
operator inspection.
|
|
\item Aquarium is the richer adjacent operator client. It should render and
|
|
steer typed state, not become a state owner.
|
|
\item Eve/CultUI is the intended GUI/TUI projection mechanism for typed
|
|
CultMesh surfaces.
|
|
\item Odin/Gjallar/Yggdrasil are the intended GameCult Verse discovery and
|
|
hosting organs for daemon affordances and important trusted Verses.
|
|
\end{itemize}
|
|
|
|
The service contract invariant is that status surfaces, dashboards, shell
|
|
wrappers, bridge adapters, app-server compatibility layers, and renderers must
|
|
read typed projections or emit typed command intents. They must not directly
|
|
mutate Epiphany truth.
|
|
|
|
\section{Primary Dataflows}
|
|
|
|
\subsection{State Rehydration And Prompt Projection}
|
|
|
|
Durable thread state lives as typed \code{EpiphanyThreadState}. On re-entry,
|
|
state is reconstructed from rollout/native state, then rendered into bounded
|
|
prompt-facing context through \code{render_epiphany_state}. Prompt injection is
|
|
read-only. If a model learns something from that prompt, admitting it back into
|
|
durable state requires an explicit update, proposal, promotion, role acceptance,
|
|
or other reviewed write path.
|
|
|
|
\subsection{View And Surface Projection}
|
|
|
|
Scene, jobs, freshness, context, graph query, planning, pressure, reorientation,
|
|
CRRC, roles, role result, reorient result, coordinator, Persona, bridge, and
|
|
environment surfaces are projections. Their job is to make typed state visible
|
|
and actionable. A projection does not own its inputs. A dashboard is a window,
|
|
not the vault.
|
|
|
|
\subsection{Worker Launch And Runtime Results}
|
|
|
|
Launch requests are typed documents. Runtime spine opens jobs, links them to
|
|
durable bindings, records model/tool activity, and stores results/receipts.
|
|
Role and reorientation findings remain reviewable until Mind and relevant gates
|
|
accept them. Implementation now routes through Hands-shaped branch-turn
|
|
constraints and should yield one branch/commit evidence slice before
|
|
Proprioception refresh.
|
|
|
|
\subsection{Tool Calls}
|
|
|
|
Tool use travels through typed capability, invocation intent, and invocation
|
|
receipt documents. The first-party tool runtime owns admission policy, native
|
|
tools, and typed receipts while the official RMCP SDK owns MCP lifecycle and
|
|
wire behavior. MCP's raw JSON belongs at that boundary; Epiphany's internal
|
|
tool state is the typed intent/receipt pair.
|
|
|
|
\subsection{Local Verse And Daemon Awareness}
|
|
|
|
Local Verse context is queried through CultMesh-backed state and can import
|
|
Gjallar daemon affordance summaries. The desired daemon path is Odin/Gjallar for
|
|
discovery, Eve/CultUI for inspection surfaces, CultMesh/CultNet for state and
|
|
commands, and provider-owned receipts for actions. MCP is not the native
|
|
GameCult daemon-control path.
|
|
|
|
\section{Invariants}
|
|
|
|
\begin{enumerate}
|
|
\item CultCache documents are the data model.
|
|
\item CultNet is the wire for Epiphany-controlled subsystems.
|
|
\item CultMesh is the preferred ergonomic local Verse and operator-store
|
|
layer over raw CultCache/CultNet.
|
|
\item JSON schema may publish the contract; generic JSON must not become
|
|
load-bearing internal state when both sides are Epiphany-owned.
|
|
\item Codex is retained for honest compatibility, especially OpenAI auth and
|
|
model transport. It must not become Epiphany's state/process/prompt owner.
|
|
\item Runtime state is machinery telemetry, not project truth.
|
|
\item Operator artifacts are witnesses, not owners.
|
|
\item Persona is public/person-shaped state; resident work organs use lean
|
|
work-organ state.
|
|
\item Heartbeat is scheduler physiology, not project truth.
|
|
\item Substrate Gate grants access; Eyes inspects evidence; Hands acts; Soul
|
|
verifies; Mind admits durable state; Self routes; Proprioception maps Body.
|
|
\end{enumerate}
|
|
|
|
\section{Current Cut Line}
|
|
|
|
The Body is coherent enough to inspect and extend. The next cuts are concrete:
|
|
|
|
\begin{itemize}
|
|
\item Keep \code{thread/epiphany/*} JSON-RPC as compatibility projection
|
|
only. New operator authority belongs in typed CultNet/CultMesh contracts.
|
|
\item \code{codex_message_processor.rs} still participates in routing and
|
|
response projection; move Epiphany-owned routing out through the bridge and
|
|
native runtime surfaces.
|
|
\item Some \code{serde_json::Value} and JSON payloads survive at ingress,
|
|
model output, schema, sealed artifacts, and quarantine seams. Preserve them
|
|
only at those boundaries; typed documents own Epiphany-internal state.
|
|
\item Publish Eve/CultUI compositions from provider-owned CultMesh state;
|
|
renderers lower the composition graph without becoming state owners.
|
|
\item Treat local Verse and memory graph stores as generated runtime state.
|
|
They are inspected through tools and receipts, not tracked as repository
|
|
canon.
|
|
\item The persisted next action after this pass remains the non-ephemeral
|
|
Hands branch-turn smoke and Proprioception refresh proof.
|
|
\end{itemize}
|
|
|
|
\section{Conclusion}
|
|
|
|
Epiphany's Body is no longer a prompt style pasted onto Codex. It is a growing
|
|
typed substrate: Rust domain organs, CultCache stores, CultMesh local Verse
|
|
documents, CultNet schema contracts, runtime-spine receipts, heartbeat
|
|
physiology, memory graph state, model/tool adapter documents, and local
|
|
operator surfaces. The current cut line is split authority: Codex host routes,
|
|
JSON-RPC compatibility, JSON cargo, and operator artifacts must remain
|
|
compatibility or witness surfaces rather than organs.
|
|
|
|
The cut line is therefore architectural, not cosmetic. Keep Codex as a
|
|
narrow auth/model/compatibility reliquary. Move Epiphany-owned state, scheduler
|
|
policy, prompt authority, worker lifecycle, operator surfaces, daemon discovery,
|
|
and action receipts through typed CultCache, CultMesh, CultNet, and Eve/CultUI.
|
|
That is the Body becoming legible enough to be trusted and sharp enough to keep
|
|
building.
|
|
|
|
\end{document}
|