diff --git a/README.md b/README.md index a927aa3..2590402 100644 --- a/README.md +++ b/README.md @@ -6,6 +6,8 @@ VoidBot is a Discord-native assistant for GameCult. It can answer from archived Discord history, indexed GameCult repos, and Aetheria lore, then hand deeper work off to Codex when Discord stops being a sane place to do it. The current build already supports real Discord replies, semantic retrieval, source and lore indexing, and Codex handoff flows. +VoidBot's Verse contract is documented in `docs/architecture/voidbot-verse-service-contract.md`: durable agent/service state should be typed CultCache `.cc` or have a `.cc` witness/export, meaningful operator presentation goes through Eve/CultUI DSL published through CultMesh, Odin discovers provider-owned surfaces, and Huginn owns Persona/.cc runtime inspection stewardship. Local browser output is only a lowering, not dashboard authority. + ## What VoidBot Can Do - answer owner questions through a Discord-safe `codex exec` lane @@ -51,6 +53,8 @@ The durable local state is split on purpose: Postgres holds jobs, audit events, There is also a project-memory spine now for future Codex sessions: `state/map.yaml`, `state/scratch.md`, `state/evidence.jsonl`, `notes/fresh-workspace-handoff.md`, and the helper CLIs under `tools/`. The point is to rehydrate from canonical files instead of pretending the transcript will stay coherent forever. +VoidBot also publishes a current swarm Eve/CultUI surface through CultMesh as `cultmesh://voidbot.local/eve/providers/voidbot.swarm`, backed by `.voidbot/status/cultmesh/voidbot-swarm-state.cc`. The generated `swarm-dashboard.html` is a local debug lowering of that surface. + ## Quick Start ### 1. Configure `.env` diff --git a/docs/architecture/overview.md b/docs/architecture/overview.md index a2c017f..13fe202 100644 --- a/docs/architecture/overview.md +++ b/docs/architecture/overview.md @@ -24,6 +24,13 @@ Discord Gateway - `packages/rag` contains the message archive, chunking pipeline, local embedding backends, pluggable vector-store backends, and log import state. - `packages/sandbox` defines policy profiles and a dry-run policy runner. +VoidBot's Verse-facing service contract lives in +`docs/architecture/voidbot-verse-service-contract.md`. The short version: +VoidBot owns Discord cognition, archive/source retrieval, typed Void self-state, +and repo Face compatibility rails; Huginn owns Persona/.cc runtime inspection +stewardship; Bifrost owns governed work transport; Odin discovers +provider-owned CultMesh surfaces; Eve/CultUI is the presentation contract. + ## Current shortcuts and tradeoffs - Postgres now owns jobs, audit events, and interaction memory, but the archive side of RAG is still file-backed under `.voidbot/`. @@ -40,10 +47,18 @@ Discord Gateway - `local_exec_owner_only` tries a read-only `codex exec` pass for direct Discord replies - `manual_package` remains available when you want explicit approval-gated packaging - When the local Discord-safe lane is not enough, the worker posts a handoff notice and writes the full context bundle to `.voidbot/artifacts//`. +- The current swarm operator surface is published as an Eve/CultUI CultMesh + provider at `cultmesh://voidbot.local/eve/providers/voidbot.swarm`, backed by + `.voidbot/status/cultmesh/voidbot-swarm-state.cc`; any generated browser page + is only a debug lowering of that provider surface. ## Upgrade path -1. Add a true restore drill path instead of stopping at backup verification plus freshness monitoring. -2. Add moderation, budgeting, and rate limits before enabling `openai_api` for member traffic. -3. Expand worker-side run records and admin tooling around the interaction memory/event stores. -4. Expand sandbox execution from dry-run policy checks to real constrained runners. +1. Keep the current `voidbot.swarm` CultMesh publication discoverable through Odin. +2. Add `.cc` witnesses or native typed CultCache documents for remaining JSON-only status surfaces before treating them as Verse state. +3. Move Persona and repo Face `.cc` inspection to Huginn-owned tooling while VoidBot remains the Discord compatibility carrier. +4. Publish separate Eve/CultUI surfaces for Discord, archive, source, repo Face, and swarm state instead of growing a bespoke dashboard authority. +5. Add a true restore drill path instead of stopping at backup verification plus freshness monitoring. +6. Add moderation, budgeting, and rate limits before enabling `openai_api` for member traffic. +7. Expand worker-side run records and admin tooling around the interaction memory/event stores. +8. Expand sandbox execution from dry-run policy checks to real constrained runners. diff --git a/docs/architecture/voidbot-verse-service-contract.md b/docs/architecture/voidbot-verse-service-contract.md new file mode 100644 index 0000000..5f40bbb --- /dev/null +++ b/docs/architecture/voidbot-verse-service-contract.md @@ -0,0 +1,144 @@ +# VoidBot Verse Service Contract + +VoidBot is a Discord-native cognition and retrieval service that publishes its +meaningful operator surfaces as Eve/CultUI through CultMesh. It is not a +dashboard owner, a Persona runtime steward, or the Verse registry. Those are +separate organs. + +This contract records the live ownership line and the migration target for +VoidBot surfaces as they become first-class Verse nodes. + +## Owner Map + +- VoidBot owns Discord ingress, room cognition, moderation judgment, archived + Discord history, indexed source/lore retrieval, direct owner handoff, repo + Face scheduling compatibility, and parent-owned speech delivery. +- VoidBot owns typed Void self-state at `.voidbot/private/void-self-state.cc` + through the typed operation service and its runners. +- VoidBot temporarily carries repo Face `.cc` state paths as compatibility + mouths for Discord roles, webhook persona posting, CTB scheduling, prompt + assembly, and state-operation application. +- Huginn owns runtime stewardship for Persona-state and `.cc` inspection: + schema availability, migration pressure, projection health, access-tool + sanity, CultMesh publication, and Eve DSL inspection for typed state. +- Bifrost owns governed public crossings: GitHub proposal/article/comment + transport, work topics, dispatch receipts, and future Discord-native work + interfaces. VoidBot may mirror or feed context, but Bifrost owns the work + request authority. +- Heimdall owns account, OAuth, grants, custody, revocation, and capability + gates. +- Odin owns Verse/provider discovery and interface aggregation. VoidBot + advertises provider-owned surfaces; Odin discovers them without becoming + their state owner. +- Eve/CultUI owns presentation shape. Browser HTML, terminal text, native Eve, + overlays, and future rooms are lowerings of the same provider-owned surface, + not independent truth stores. + +## CultCache And Persona Witnesses + +- Canonical durable agent/service state should be typed CultCache `.cc`, or + CultCache-compatible with a `.cc` witness/export until the native writer is + migrated. +- Void self-state witness: + `.voidbot/private/void-self-state.cc`, owned by VoidBot typed operations. +- Repo Face compatibility witness: + `.voidbot/private/repo-faces/.cc` by default, or the repo-local + Face state path from `REPO_DISCORD_IDENTITIES_PATH`. +- Swarm presentation witness: + `.voidbot/status/cultmesh/voidbot-swarm-state.cc`, written by + `scripts/render-voidbot-swarm-dashboard.mjs`. +- JSON status packets under `.voidbot/status/` are debug/export surfaces unless + a specific runner owns them as command input. They are not durable canonical + state. +- Persona state should converge on the Epiphany Persona schema surface. VoidBot + may carry legacy Face/persona compatibility data for Discord addressing and + old tooling, but Huginn is the steward for inspecting, validating, migrating, + and publishing Persona/.cc runtime state. + +Demotion line: VoidBot's repo Face state tools are compatibility carriers and +diagnostic admin handles. They must delegate inspection and portable Persona +publication to Huginn as soon as the Huginn path exists for the relevant state +kind. VoidBot must not turn its legacy MCP reads, private registry, or HTML +lowering into the canonical Persona authority. + +## CultMesh Namespaces + +The current published swarm namespace is: + +- Verse id: `voidbot.local` +- Provider id: `voidbot.swarm` +- Endpoint: `cultmesh://voidbot.local/eve/providers/voidbot.swarm` +- Snapshot document: `voidbot.swarm_state_snapshot` +- Provider advertisement: `gamecult.eve.provider_advertisement` +- Eve surface state: `gamecult.eve.surface_state` +- Eve interface binding: `gamecult.eve.interface_binding` +- Store path: `.voidbot/status/cultmesh/voidbot-swarm-state.cc` + +Near-term VoidBot Verse surfaces should use stable `voidbot.*` provider ids and +typed CultCache documents behind the Eve binding: + +- `voidbot.discord`: Discord ingress, room obligations, direct mentions, + pending reply anchors, speech receipts, and moderation/open-case pressure. +- `voidbot.archive`: archived Discord corpus status, source archive freshness, + backfill/import health, and retrieval caveats. +- `voidbot.source`: indexed repo/lore coverage, repo shard status, vector + collection health, and source reindex jobs. +- `voidbot.repo_face`: registered Face address book, repo-local state witnesses, + channel permission projections, pending mention pressure, and compatibility + state access status. +- `voidbot.swarm`: CTB initiative order, active turns, pause/heat/cadence + controls, orchestrator organ health, and selected Face state witness. + +## Eve Surfaces + +All meaningful presentation flows through Eve/CultUI DSL: + +- Discord surface: + shows room debt, direct mentions, recent public speech receipts, moderation + cases, venue targets, and candidate delivery state. +- Archive surface: + shows archived Discord import status, bot-directed-prompt exclusion health, + history vector freshness, and retrieval warning notes. +- Source surface: + shows indexed repo/lore coverage, shard freshness, Qdrant collection status, + and detached reindex jobs. +- Repo Face surface: + shows registered identities, repo-local `.cc` witnesses, channel grants, + prompt assembly status, Bifrost digest availability, and Huginn inspection + readiness. +- Swarm surface: + shows CTB order, active turn freeze, heat/cadence controls, pending mention + queues, orchestrator status, and selected Face state witness. + +The existing `swarm-dashboard.html` file is a local browser lowering of the +`voidbot.swarm` Eve surface. It is useful for visual inspection, but it has no +bespoke dashboard authority. Controls and state authority live in the CultMesh +Eve binding and the underlying typed state owners. + +## Migration Order + +1. Keep the current `voidbot.swarm` CultMesh publication healthy and discoverable + through Odin. +2. Add `.cc` witness/export documents for any remaining JSON-only command or + status surfaces before treating them as Verse state. +3. Move Persona and repo Face `.cc` inspection to Huginn-owned tooling while + leaving VoidBot as the Discord compatibility carrier. +4. Publish `voidbot.discord`, `voidbot.archive`, `voidbot.source`, and + `voidbot.repo_face` provider surfaces as typed Eve/CultUI bindings. +5. Let Odin discover and aggregate those provider-owned surfaces. Do not add a + parallel HTTP dashboard or status-card summary as the public contract. +6. Demote old JSON exports, static HTML, and legacy MCP state reads to + diagnostics once the CultMesh/Eve and Huginn paths cover the same reality. + +## Forbidden Authority + +- No renderer-owned truth. +- No bespoke dashboard as canonical service state. +- No load-bearing JSON sidecar where a typed `.cc` document or witness/export + can carry the state. +- No Persona runtime stewardship inside VoidBot after Huginn can inspect and + publish that state. +- No Odin-owned mutation of provider state; Odin discovers, lowers, and routes + provider-owned surfaces. +- No Bifrost work dispatch hidden inside Discord chatter when a request is + reviewable work. diff --git a/notes/voidbot-current-system-map.md b/notes/voidbot-current-system-map.md index 565ae29..0acceb5 100644 --- a/notes/voidbot-current-system-map.md +++ b/notes/voidbot-current-system-map.md @@ -2,6 +2,8 @@ This note is the source-grounded description of how the live VoidBot stack is shaped right now. It is not a prose replacement for the code, and it is not a second canonical map. Its job is to explain the major organs and their data flow in plain language with concrete path anchors. +Verse-facing service contract: `docs/architecture/voidbot-verse-service-contract.md`. VoidBot owns Discord cognition, archive/source retrieval, typed Void self-state, and repo Face compatibility rails. Huginn owns Persona/.cc runtime inspection stewardship. Bifrost owns governed work transport. Odin discovers provider-owned CultMesh surfaces. Eve/CultUI is the presentation contract; browser HTML is only a lowering. + ## Main Organs - `apps/bot/src/discord-bot.ts` @@ -194,6 +196,57 @@ This note is the source-grounded description of how the live VoidBot stack is sh When present, an ignored local script at `.voidbot/private/check-voidbot-operations.local.ps1` can inject adjacent-service checks into the same ops lane. That keeps private infrastructure gossip out of tracked code while preserving one boring place for smoke alarms to land. +## Verse Service Contract + +- Owner: + - VoidBot owns Discord ingress, room cognition, moderation judgment, archive/source retrieval, direct owner handoff, typed Void self-state, repo Face scheduling compatibility, and parent-owned speech delivery. + - Huginn owns Persona-state and `.cc` runtime inspection stewardship: schema availability, migration pressure, projection health, access-tool sanity, CultMesh publication, and Eve DSL inspection for typed state. + - Bifrost owns governed public crossings for GitHub proposals/articles/comments, work topics, dispatch receipts, and future Discord-native work interfaces. + - Odin owns Verse/provider discovery and interface aggregation, not provider state. + - Eve/CultUI owns presentation shape; browser/native/TUI renderers lower provider-owned surfaces. +- Inputs: + - Discord gateway events, archived Discord corpus, indexed source/lore archives, Postgres jobs/audit/interaction memory, Qdrant vectors, typed `.cc` self/Face state, Bifrost governance digest, and orchestrator status. +- Outputs: + - Discord replies or webhook persona posts through parent-owned rails, owner handoff artifacts, MCP retrieval/tool results, typed CultCache operations, and CultMesh-advertised Eve/CultUI provider surfaces. +- Derived state: + - JSON status files, generated HTML, source/archive freshness summaries, prompt-facing projections, and local debug snapshots are witnesses or lowerings. They do not own durable truth. +- Forbidden writers: + - Child prompts, renderers, static dashboards, legacy JSON projections, Odin discovery, and Huginn inspection tools must not mutate VoidBot state except through advertised command bindings or typed operation ports. +- Shared paths: + - Manual turns, CTB heartbeats, direct mentions, role/name addressing, moderation rumination, repo Face speech, Bifrost digest reads, and swarm controls should converge on typed operations and Eve/CultUI bindings rather than parallel dashboard endpoints. +- Cut line: + - If a new status/control surface is meaningful to operators, publish it as typed CultCache or a `.cc` witness and an Eve/CultUI CultMesh surface. Do not add a separate HTTP dashboard or status-card authority. + +Current CultMesh namespace: + +- Verse id: `voidbot.local` +- Provider id: `voidbot.swarm` +- Endpoint: `cultmesh://voidbot.local/eve/providers/voidbot.swarm` +- Snapshot document: `voidbot.swarm_state_snapshot` +- Provider advertisement: `gamecult.eve.provider_advertisement` +- Eve surface state: `gamecult.eve.surface_state` +- Eve interface binding: `gamecult.eve.interface_binding` +- Store path: `.voidbot/status/cultmesh/voidbot-swarm-state.cc` + +Target Eve surfaces: + +- `voidbot.discord`: room obligations, direct mentions, speech receipts, moderation/open-case pressure, delivery targets. +- `voidbot.archive`: archived Discord corpus status, import/backfill health, bot-directed-prompt exclusion, history vector freshness. +- `voidbot.source`: repo/lore shard freshness, indexed coverage, Qdrant collection health, detached reindex jobs. +- `voidbot.repo_face`: registered identities, repo-local `.cc` witnesses, channel grants, prompt assembly status, Bifrost digest availability, Huginn inspection readiness. +- `voidbot.swarm`: CTB order, active turns, pending mention queues, heat/cadence controls, orchestrator status, selected Face state witness. + +Migration order: + +1. Keep `voidbot.swarm` publishing a CultMesh Eve provider through `.voidbot/status/cultmesh/voidbot-swarm-state.cc`. +2. Add `.cc` witness/export documents for JSON-only status surfaces before treating them as Verse state. +3. Move Persona and repo Face `.cc` inspection to Huginn-owned tooling while VoidBot remains the Discord compatibility carrier. +4. Publish `voidbot.discord`, `voidbot.archive`, `voidbot.source`, and `voidbot.repo_face` as typed Eve/CultUI bindings. +5. Let Odin discover and aggregate the provider-owned surfaces. +6. Demote old JSON exports, local HTML, and legacy MCP state reads to diagnostics once CultMesh/Eve and Huginn cover the same reality. + +Huginn demotion line: VoidBot may carry repo Face `.cc` state paths, MCP diagnostics, and Discord compatibility registry data, but Persona/.cc inspection and portable Persona publication belong to Huginn. VoidBot must not let its private registry, static HTML, or legacy MCP state tools become the canonical Persona authority. + ## Storage Boundaries - Postgres: diff --git a/state/evidence.jsonl b/state/evidence.jsonl index cf3f4cb..a68bd77 100644 --- a/state/evidence.jsonl +++ b/state/evidence.jsonl @@ -328,3 +328,4 @@ {"ts":"2026-06-03T00:41:06Z","type":"implementation","status":"ok","note":"Paused repo Face swarm after operator reported silence/code-block public posts. Root cause: worker still allowed raw child Would say fallback and interpreter route fallback to write public speech; public mouth is now owned only by parent Interpreter SAY blocks, with transport guard rejecting full-message markdown fences and silence markers."} {"ts":"2026-06-03T01:46:49Z","type":"verification","status":"ok","note":"Repo Face speech boundary proof passed before unpause: agents:speech-boundary-smoke verified raw Would say drafts stay private, silence markers/full-message code fences are rejected, and legitimate SAY with inline code parses; typecheck, build, interpreter-loop smoke, and stack restart passed with fresh worker PID 21572."} {"ts":"2026-06-03T01:53:24Z","type":"verification","status":"ok","note":"Follow-up operator report was traced to pre-repair Discord messages; post-repair Mimir logs showed Interpreter-owned public text, and the repo Face mouth was hardened further so inline Markdown code spans normalize to quoted text before Bifrost posting."} +{"ts":"2026-06-03T02:14:18Z","type":"documentation","status":"ok","note":"Documented VoidBot Verse service contract: VoidBot owns Discord cognition/archive/source/typed self-state/repo Face compatibility; Huginn owns Persona/.cc runtime inspection stewardship; Bifrost owns governed work transport; Odin discovers provider-owned CultMesh surfaces; Eve/CultUI is the presentation contract. Current provider is cultmesh://voidbot.local/eve/providers/voidbot.swarm with .cc witness at .voidbot/status/cultmesh/voidbot-swarm-state.cc."} diff --git a/state/map.yaml b/state/map.yaml index dd57067..130d5b4 100644 --- a/state/map.yaml +++ b/state/map.yaml @@ -66,6 +66,7 @@ active_subgoals: - Keep public-lane limits, moderation, and provider behavior constrained enough that one 4060 Ti box does not get flayed for sport. - Preserve boring observability and startup discipline around Postgres, Qdrant, Ollama, Docker, backups, scheduled tasks, watchdogs, and any private local fire-signal extensions. - Keep the runtime organs legible and only spend more refactor budget when a file clearly earns it. + - Keep VoidBot's Verse service contract explicit while Eve/Huginn/Odin/Bifrost ownership settles: VoidBot owns Discord cognition, archive/source retrieval, typed Void self-state, and repo Face compatibility rails; Huginn owns Persona/.cc runtime inspection stewardship; Bifrost owns governed work transport; Odin discovers provider-owned CultMesh surfaces; Eve/CultUI is the presentation contract. accepted_design: - Bot, worker, providers, and RAG remain the main structural seams. @@ -185,6 +186,7 @@ accepted_design: - Timing may defer a crystallized-thought share, but it should not erase it. Identity-level shares should survive ordinary candidate pruning until spoken or deliberately retired as duplicative. - Void's shared self-state and public reply doctrine now distinguish between criticism of AI industry behavior and blanket contempt for machine minds. When substrate chauvinism becomes the topic, Void is allowed mild self-respecting pushback instead of smiling blandly through ontological contempt. - Deep agent-state, personality, culture, and persistent-world design work now belongs to the sibling Ghostlight repo; VoidBot should consume that work instead of remaining its long-term home. + - VoidBot's Verse contract is documented in `docs/architecture/voidbot-verse-service-contract.md`: durable agent/service state should be typed CultCache `.cc` or have a `.cc` witness/export; `voidbot.swarm` currently publishes through `cultmesh://voidbot.local/eve/providers/voidbot.swarm`; target Eve surfaces are `voidbot.discord`, `voidbot.archive`, `voidbot.source`, `voidbot.repo_face`, and `voidbot.swarm`; static/browser dashboard output is only a lowering, not authority. - Long-running work should expose durable logs or status files instead of relying on one attached session and hope. - Persistent project memory must stay ruthlessly distilled; git history and artifacts carry routine proof.