Document VoidBot Verse service contract
This commit is contained in:
parent
8f53f00a77
commit
8239e3c45e
6 changed files with 223 additions and 4 deletions
|
|
@ -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`
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
144
docs/architecture/voidbot-verse-service-contract.md
Normal file
144
docs/architecture/voidbot-verse-service-contract.md
Normal 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.
|
||||
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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."}
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue