Document VoidBot Verse service contract

This commit is contained in:
Meta Vens 2026-06-03 03:14:41 +01:00
commit 8239e3c45e
6 changed files with 223 additions and 4 deletions

View file

@ -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`

View file

@ -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/<job-id>/`.
- 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.

View file

@ -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/<identity>.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.

View file

@ -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:

View file

@ -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."}

View file

@ -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.