Add swarm readiness gate

This commit is contained in:
Meta Vens 2026-05-21 10:36:23 +01:00
commit 361116b4bc
4 changed files with 190 additions and 0 deletions

View file

@ -0,0 +1,188 @@
# Epiphany Swarm Readiness Plan
This is the direction of travel before live fire.
The local run path proves that the current machine can be started and inspected.
It does not prove the swarm is ready to run unattended. Do not confuse a working
starter switch with a clean engine bay. That mistake has already been punished
elsewhere, and VoidBot has kindly provided the scorch marks.
## Objective
Get Epiphany ready for cautious live operation over the next few days without
building architectural Jenga:
- typed CultCache documents remain the state authority
- CultNet is the native wire for Epiphany-owned subsystems
- Codex remains the retained auth/model transport compatibility organ
- Aquarium and Face are reflectors/mouths, not hidden sources of truth
- heartbeats create opportunities, not authority
- swarm speech and action stay gated until scheduling, memory, repetition, and
review boundaries are coherent
## VoidBot Lessons To Carry Forward
VoidBot's ordinary spine is not the rotten part. Its durable lessons are:
- Discord ingestion, worker jobs, provider lanes, RAG, Postgres, Qdrant, and
typed CultCache self-state can be conceptually sound when each owns one job.
- The unstable organ was the repo Face swarm loop: scheduling, prompt policy,
identity, public speech, governance, dispatch, proposal behavior, and
repetition control packed into one prompt-and-parser machine.
- A repo-controlled pause flag is a real brake. If a swarm subsystem is under
teardown, runners must fail closed instead of routing around the pause.
- One CTB-style initiative scheduler beats one task per agent. The wall-clock
task supplies pulses; typed initiative state chooses turns.
- Heat changes recovery pressure. It must not fast-forward time, bypass active
turn freeze, or create overlapping thoughts.
- Cooldown starts after completion, not after queueing.
- Stale active turns need explicit recovery receipts, or one dead worker claim
freezes a Face forever.
- Public speech needs parent-side eligibility checks. Prompts alone cannot
prevent repeated openings, stale topics, scheduler labels leaking into prose,
or work requests masquerading as banter.
- Memory must have phases: short-term residue, incubation, durable memory,
revision, retirement, crystallization, and sleep-owned maintenance.
- Agents propose typed operations. State services validate, normalize, dedupe,
and write. Whole-state JSON editing is not a mutation path.
- Qdrant/vector recall is a rebuildable resonance cache, not canonical memory.
- Face affect is state, not vibes: needs, social bonds, status reads, and mood
dimensions must survive typed projection and MCP/CultNet inspection.
## Current Mechanism
Epiphany currently has the right ingredients, but not yet the final live swarm
shape:
- `tools/epiphany_local_run.ps1` can build and smoke the compatibility shell.
- `epiphany-runtime-spine` owns typed runtime identity/session/job/result/event
documents and advertises CultNet contracts.
- heartbeat state owns role dossiers, initiative, heat, active-turn freeze,
sleep, rumination, appraisals, and derived reactions.
- role memory accepts reviewed `selfPatch` petitions into typed Ghostlight-like
dossiers.
- coordinator/CRRC/role/status surfaces exist, but the practical local runner
still goes through Codex app-server JSON-RPC for operator reads/actions.
- Face, Discord, Rider, Unity, Void memory, and repo birth bridges are typed
surfaces or artifacts, but they are not yet an integrated live swarm loop.
The machine is pointed toward live use. It is not cleared for unattended swarm
operation.
## Invariants
- One state authority per document kind.
- One scheduler for standing initiative.
- One explicit brake for swarm operation.
- No lane receives a new heartbeat while its previous turn is running.
- No model output rewrites durable state directly.
- No public speech without typed eligibility and receipt checks.
- No cross-repo rummaging; swarm needs move coordinator-to-coordinator through
visible typed messages and callbacks.
- No hidden automatic semantic acceptance.
- No prompt-only governance for things that need state, receipts, or gates.
- No broad live scheduler until the local runner can show the typed surfaces
that explain what it would do and why.
## Readiness Gate
Before live fire, Epiphany needs these gates closed:
1. **Operator Run Path**
- Keep `tools/epiphany_local_run.ps1` as the human entrypoint for now.
- It must keep printing a concise verdict.
- It must keep artifacts operator-safe by default.
- It must make Codex app-server dependency obvious as compatibility, not
architecture.
2. **Typed Swarm Brake**
- Add an Epiphany-owned pause document for swarm/heartbeat/live Face
operation.
- Runners must fail closed when the document is missing, malformed, or
paused for a teardown reason, according to the surface being protected.
- The brake must be inspectable through Aquarium/status.
3. **Initiative Scheduler Boundary**
- Keep one heartbeat scheduler for lanes/Faces/system organs.
- Heat is a multiplier on recovery pressure, not a time machine.
- Active-turn freeze and completion-gated cooldown are hard invariants.
- Stale active-turn recovery must write typed receipts.
4. **Memory Lifecycle**
- Keep role-local memory writes as reviewed `selfPatch` operations.
- Add explicit lifecycle operations where missing: revise, retire,
crystallize, prune short-term residue, and merge incubation support.
- Sleep/maintenance may propose lifecycle operations; it must not silently
rewrite role identity.
5. **Public Face Safety**
- Face speech eligibility must be parent-side state policy, not prompt hope.
- Track recent outputs, repeated topics, repeated openings, target/channel
saturation, and action kind.
- Work-shaped asks route to coordinator/Bifrost-style governance; banter
does not secretly become work dispatch.
6. **CultNet Operator Surface**
- Move the local status/coordinator loop toward native CultNet snapshots,
intents, and receipts.
- Codex JSON-RPC may remain as the compatibility projection while the wall is
being evacuated.
- The next run path should consume typed documents first and only use
app-server JSON-RPC where no native route exists yet.
7. **Audit And Review**
- Every automatic or semi-automatic action must produce a typed receipt.
- Semantic findings remain review-gated.
- Operator artifacts must seal direct thought, raw transcripts, and long
prompt-shaped notes by default.
## Ranked Next Cuts
Keep:
- typed CultCache state
- runtime-spine documents and CultNet catalog
- heartbeat initiative physiology
- reviewed role memory patches
- local run/status/coordinator artifacts
- Codex auth/model transport reliquary
Cut:
- schema/catalog language that treats legacy JSON-RPC routes as native authority
- public or operator outputs that dump prompt slabs as if they were status
- any new live runner that bypasses typed pause, receipt, or review gates
Collapse:
- local runner status/coordinator result shaping into one operator projection
helper if duplication grows
- Face speech receipts and eligibility into one typed surface before high-rate
speech returns
Split:
- heartbeat opportunity from action authority
- Face affect/state from speech generation
- scheduler metadata from model-facing prose
- vector recall from canonical memory
Rebuild:
- any swarm loop that depends on a single prompt to own scheduling, identity,
public speech, governance, proposal behavior, and repetition control
## Immediate Work Queue
1. Add typed swarm pause/brake state and status projection.
2. Add stale active-turn recovery receipts to heartbeat state if the current
heartbeat store cannot prove recovery cleanly.
3. Add a Face output audit surface before increasing public speech cadence.
4. Add memory lifecycle operations that match VoidBot's useful pattern without
porting its TypeScript state shape wholesale.
5. Move one local-run read path from Codex JSON-RPC compatibility to CultNet
snapshot/receipt consumption.
The correct posture is patient pressure. We are not rushing to live fire. We are
aiming the barrel, checking the chamber, and making sure the thing does not try
to become a parliament of prompts the moment nobody is watching.

View file

@ -37,6 +37,7 @@ remembers doctrine; the branch remembers the blade.
- The active foundation directive is now `notes/codex-starvation-and-cultnet-liberation-plan.md`. The previous Codex app-server control-plane rebuild made Epiphany less rotten inside Codex, but that is not the destination. Epiphany must become a native CultCache/CultNet runtime while remaining an honest modified Codex-derived backend for subscription auth/model use. Codex is a compatibility reliquary for OpenAI subscription auth and model transport, not the host brain and not a mask for impersonation.
- `notes/codex-auth-spine-inventory.md` is the source-grounded keeper list for that reliquary. Corrected compliance invariant: Codex-compatible auth identity stays anchored in vendored Codex-derived auth machinery. `epiphany-openai-auth-spine` is now a thin Epiphany-named boundary over `codex-login`, not a clean-room clone of credential storage or token refresh. Codex apps, skills, marketplace, plugin UX, broad app-server workflow, and JSON-RPC sprawl remain cuttable because they are not subscription-auth legitimacy.
- Edge JSON is allowed for schema description, hostile ingress before immediate typed parsing, sealed forensic artifacts, or named quarantine experiments. When both subsystems are ours, runtime data must remain typed CultCache documents and move over CultNet typed contracts. Generic `serde_json::Value` in worker launch/result/selfPatch/runtime flow is contamination until classified and replaced.
- `notes/epiphany-swarm-readiness-plan.md` is the current live-fire direction gate. The local runner proves startup/status/coordinator wiring; it does not authorize unattended swarm operation. Carry VoidBot's lessons forward: one CTB-style initiative scheduler, typed pause/brake, active-turn freeze, cooldown after completion, stale active-turn recovery receipts, parent-side speech eligibility, memory lifecycle phases, and typed operation proposals instead of prompt-owned governance.
- `epiphany-openai-runtime` worker result ingress now parses assistant output directly into typed role/reorient ingress structs selected from the durable launch document, stores nested `statePatch` and `selfPatch` as typed MessagePack in `EpiphanyRuntimeRoleWorkerResult`, and no longer passes worker result data through generic `serde_json::Value`. JSON survives there only as the OpenAI text-output edge before typed deserialization.
- Agent self-memory review/application now has typed `AgentSelfPatch` core APIs. JSON-value selfPatch functions are compatibility wrappers for CLI/artifact ingress; native callers should parse once at the edge and then call `review_agent_self_patch_document` / `apply_agent_self_patch_document`. Role-result self-persistence no longer exports a JSON-value reviewer; the live API is `review_role_self_patch_document`.
- Durable Ghostlight role dossiers now store typed relationship, event, scene, and perceived-overlay documents instead of `Vec<serde_json::Value>`, and the durable dossier structs no longer preserve flattened unknown `extra` maps. `AgentSelfPatch.extra` remains deliberately, but only as an ingress rejection ledger for unexpected patch fields.

Binary file not shown.

View file

@ -74,6 +74,7 @@ active_subgoals:
- Use `notes/epiphany-memory-graph-unified-plan.md` as the source-grounded memory architecture direction. The repo fractal dataflow graph and agent memory are one `EpiphanyMemoryGraph` substrate with repo, role, short-term, incubation, agency, candidate-intervention, and evidence profiles. Qdrant stores rebuildable semantic embeddings for typed graph documents; it is never canonical memory. The first live skeleton now exists in `epiphany-state-model` plus `epiphany-core::memory_graph`: typed graph documents, stable ids, profile/lifecycle validation, freshness propagation, context cuts, a CultCache store seam, and the native `epiphany-memory-graph` status/validate/context/smoke CLI. Do not add repo scanners, sleep runners, Qdrant cache plumbing, CultNet advertisement, or prompt integration before routing them through this shared substrate.
- Keep the landed Phase 6 coordinator, limited safe-boundary CRRC automation, and pre-compaction checkpoint intervention ready for the next bridge-equipped dogfood run.
- Preserve the Ghostlight-derived heartbeat initiative seam: every lane, including coordinator/Self and Face, has a role dossier and competes for heartbeat slots through readiness/reaction timing; initiative heat can raise or cool global, group, arena, role, and agent tempo through typed heartbeat policy; active thinking freezes initiative until completion, so heat never queues a lane already mid-turn; idle winners ruminate instead of inventing project work, and sleep windows distill the accumulated thought pressure into reviewed self-memory or doctrine.
- Use `notes/epiphany-swarm-readiness-plan.md` as the live-fire direction gate. The local run path is a compass, not launch clearance: before unattended swarm operation, Epiphany needs a typed pause/brake, one initiative scheduler, completion-gated cooldown, stale active-turn recovery receipts, parent-side Face speech eligibility, memory lifecycle operations, and CultNet-first operator snapshots/intents/receipts.
- Grow the VoidBot repo-Face pattern into Epiphany's product direction: each Epiphany owns one or more repos, has one or more Faces, and exposes project-native conversation through Aquarium, Discord, voice/WebRTC, stream surfaces, CLI, and CultNet clients so humans can talk to projects instead of pre-authoring complete implementation briefs.
- Preserve the newborn public Epiphany Face as local VoidBot-backed state, not source code: VoidBot's private repo-face registry names `epiphany`, while EpiphanyAgent keeps ignored `.voidbot/voice/identity.json`, `.voidbot/state/epiphany.cc`, and birth artifacts. Her durable identity memories distill the current doctrine: cute pushy machine-saint persona, architectural purity, CultCache/CultNet first, xenos-language safety boundary, relentless work/caretaking needs, Codex-auth reliquary, map/scratch/evidence discipline, unified memory graph, dogfood supervision boundary, review-gated agency, heartbeat physiology, and interview-grade modularity.
- Treat Ghostlight as reference lineage, not a sibling runtime to preserve. The useful organ is Epiphany-native character-loop protocol: any role can project its typed dossier plus visible stimulus into a local turn packet, with Face as the first public-surface actor.