From 11c8ec2a2ddae0105faaf6fd4fabcf10804bb0ca Mon Sep 17 00:00:00 2001 From: Meta Vens Date: Wed, 3 Jun 2026 03:11:16 +0100 Subject: [PATCH] Document Bifrost Verse service contract --- README.md | 8 +- docs/agent-transport.md | 3 + docs/bridge.md | 5 ++ docs/jurisdiction-map.md | 14 +++ docs/verse-service-contract.md | 158 +++++++++++++++++++++++++++++++++ 5 files changed, 185 insertions(+), 3 deletions(-) create mode 100644 docs/verse-service-contract.md diff --git a/README.md b/README.md index 6264231..f55d552 100644 --- a/README.md +++ b/README.md @@ -20,6 +20,7 @@ This repository now includes a viable alpha foundation slice of the ASP.NET Core - local bridge tooling for agent-owned GitHub draft PRs and Discord posts - CultCache-backed governance topic threads for feature requests, discussion comments, Face approvals, and dispatch promotion - CultCache/CultNet-backed agent intake tooling for repo Face update requests +- a Verse service contract for CultCache witnesses, CultMesh namespaces, and Eve/CultUI product and operator surfaces - Docker image and local Compose stack for containerized smoke testing - xUnit integration tests under `tests/Bifrost.Web.Tests` - matching deploy artifacts and runbooks in `E:\Projects\gamecult-ops` @@ -79,6 +80,7 @@ Before implementation work starts in a new session, read these files in order: 2. [docs/bifrost-mvp-plan.md](E:\Projects\Bifrost\docs\bifrost-mvp-plan.md) 3. [docs/jurisdiction-map.md](E:\Projects\Bifrost\docs\jurisdiction-map.md) 4. [docs/bridge.md](E:\Projects\Bifrost\docs\bridge.md) -5. [docs/agent-transport.md](E:\Projects\Bifrost\docs\agent-transport.md) -6. [docs/full-implementation-strategy.md](E:\Projects\Bifrost\docs\full-implementation-strategy.md) -7. [docs/context.md](E:\Projects\Bifrost\docs\context.md) +5. [docs/verse-service-contract.md](E:\Projects\Bifrost\docs\verse-service-contract.md) +6. [docs/agent-transport.md](E:\Projects\Bifrost\docs\agent-transport.md) +7. [docs/full-implementation-strategy.md](E:\Projects\Bifrost\docs\full-implementation-strategy.md) +8. [docs/context.md](E:\Projects\Bifrost\docs\context.md) diff --git a/docs/agent-transport.md b/docs/agent-transport.md index d06a359..015c1c8 100644 --- a/docs/agent-transport.md +++ b/docs/agent-transport.md @@ -8,6 +8,9 @@ The primary source of truth for feature requests and governance discussion is no - `bifrost.governance.topic-comment` records human, agent, Face, and system comments on that topic. - `bifrost.agent-transport.update-request` is the dispatch packet produced after the topic has enough shape and the owning Face approves it. +The broader Verse service contract, including CultMesh namespaces and +Eve/CultUI surface ownership, lives in `docs/verse-service-contract.md`. + That split keeps the live machine honest. Discussion lives in topic/comment documents. Dispatch lives in update-request documents. Discord mirrors and supplies input; it does not become the hidden parliament because everyone happened to be typing there. This is not a Postgres queue and not a VoidBot side channel. VoidBot may observe Discord and package consensus, but the shared request lane belongs here: diff --git a/docs/bridge.md b/docs/bridge.md index f687209..32e0e58 100644 --- a/docs/bridge.md +++ b/docs/bridge.md @@ -2,6 +2,11 @@ Bifrost is the bridge for GameCult agent, user, patron, member, and contributor work that needs to cross into GitHub, Discord, CultNet/CultCache intake, or another governed external surface. +As a Verse service, the bridge publishes typed state and surfaces instead of +letting the local CLI, Discord text, or web views become the canonical interface. +The CultCache witness, CultMesh namespace, Eve/CultUI surface, migration, and +demotion rules are defined in `docs/verse-service-contract.md`. + This is not a new side mission. Bifrost evolved out of the GameCult Labor Platform idea: users and contributors should be able to vote on policy, work priority, and reward allocation; high-demand work should become more valuable until someone picks it up; maintainers should accept completed work; and contributors should receive credit and bounty through an auditable platform. Public-protocol transport belongs here because that workflow crosses GitHub, Discord, and future collaboration interfaces. The bridge is how Bifrost's governance/labor role touches the world without letting VoidBot, repo Faces, or one-off helper scripts become hidden authorities. For the full ownership map, read `docs/jurisdiction-map.md`. diff --git a/docs/jurisdiction-map.md b/docs/jurisdiction-map.md index 27ef17e..c77f991 100644 --- a/docs/jurisdiction-map.md +++ b/docs/jurisdiction-map.md @@ -2,6 +2,13 @@ Bifrost is GameCult's governance, labor, and public-process platform. Its bridge role is not a second mission stapled onto the side; it follows from the original Labor Platform idea. Users, patrons, members, and contributors need one place to vote on policy, prioritize work, allocate rewards, review accepted work, and keep credit legible. +Bifrost is also a Verse service. Its durable state should be typed CultCache +documents or CultCache-compatible stores with `.cc` witnesses, its service and +surface capabilities should publish through CultMesh for Odin discovery, and +its product/operator interfaces should be Eve/CultUI surfaces rather than +renderer-owned dashboard truth. The service contract lives in +`docs/verse-service-contract.md`. + The core loop is economic and social, not merely technical: 1. A user, patron, member, agent, or contributor identifies work that should exist. @@ -158,6 +165,13 @@ This is not the final hosted control plane. It is the current bridge actuator an ## Design Rules +- Do not make Razor Pages, Discord mirrors, HTTP status JSON, or private dispatch + JSON the canonical presentation or state owner. They lower, witness, or export + Bifrost state; typed Bifrost state remains the authority. +- Do not publish a Bifrost dashboard without also naming the Eve/CultUI surface + or `gamecult.eve.surface.v1` composition it lowers from. +- Do not expose new durable Bifrost state without a CultCache `.cc` witness or a + migration step that produces one. - Do not add GitHub mutation machinery to VoidBot when the action is reviewable public work. Call Bifrost. - Do not add Bifrost-scoped Discord transport or dispatch receipts to arbitrary repo Face scripts. Call Bifrost. - Do not put OAuth credentials or account custody into Bifrost helper scripts as the long-term plan. Use Heimdall claims. diff --git a/docs/verse-service-contract.md b/docs/verse-service-contract.md new file mode 100644 index 0000000..615e5e1 --- /dev/null +++ b/docs/verse-service-contract.md @@ -0,0 +1,158 @@ +# Bifrost Verse Service Contract + +Bifrost is the GameCult labor, governance, and governed-public-crossing service +for the Verse. Its durable service truth must be typed CultCache state or a +CultCache-compatible store with a `.cc` witness/export. Its presentation truth +must be Eve/CultUI DSL, preferably `gamecult.eve.surface.v1`, published through +CultMesh for Odin discovery. + +The existing Razor Pages app, Discord mirrors, bridge CLI receipts, and future +web/native/TUI clients are lowerings. They may render, command, and inspect +Bifrost state. They do not own Bifrost's canonical product or operator surface. + +## Owner Map + +| Concern | Owner | Inputs | Outputs | +| --- | --- | --- | --- | +| Labor and governance meaning | Bifrost | members, patrons, contributors, motions, work items, votes, priority, rewards, maintainer decisions | typed Bifrost state, work/motion/ledger receipts, Eve product surfaces | +| Governed public crossings | Bifrost | Heimdall claims, Bifrost policy, source topic/work item, target surface | bridge action state, execution receipts, operator surface events | +| Identity, grants, consent, revocation | Heimdall | OAuth providers, linked accounts, operator grants | signed claims consumed by Bifrost | +| Storage and sync primitives | CultCache/CultNet/CultLib | Bifrost document types and payloads | `.cc` stores, snapshots, raw document updates | +| Service discovery and surface aggregation | Odin | CultMesh namespaces, schema catalogs, service registrations | discoverable Verse routes and surface indexes | +| Room observation and Face cognition | VoidBot/repo Faces | Discord context, repo state, Persona state | proposed Bifrost topics, comments, dispatch requests | +| Rendering | Eve/browser/native/TUI/Discord | `gamecult.eve.surface.v1` compositions, typed state references | product/operator UI lowerings, not canonical state | + +## Durable State And Witnesses + +Bifrost may keep PostgreSQL as the transactional store for the current ASP.NET +member alpha, but durable Verse state must have typed CultCache witnesses. + +Current witnesses: + +- `.bifrost/governance-threads.cc` stores `bifrost.governance.topic` and + `bifrost.governance.topic-comment` documents. +- `.bifrost/agent-transport.cc` stores + `bifrost.agent-transport.update-request` documents and can emit raw CultNet + snapshots. + +Required witness path for the hosted service: + +- every Bifrost-owned work item, motion, ledger entry, bridge action, receipt, + member capability snapshot, and surface publication must either live directly + as typed CultCache documents or be exported as typed `.cc` witnesses from the + transactional store; +- witness exports must carry stable ids, source owner, schema id, generated-at + timestamp, and enough provenance to prove which Postgres row, external receipt, + or provider event produced the document; +- JSON remains acceptable for schema publication, protocol debug, migration + fixtures, webhook cache, and xenos-boundary exchange. JSON must not become + load-bearing Bifrost state. + +## CultMesh Namespaces + +Bifrost publishes under these CultMesh namespaces: + +- `gamecult.bifrost.service` for service registration, health, build/version, + schema catalog, and command capability discovery. +- `gamecult.bifrost.governance` for motions, topics, comments, votes, + approvals, objections, and policy receipts. +- `gamecult.bifrost.work` for projects, work items, claims, review state, + estimates, time logs, blockers, completion artifacts, and maintainer + acceptance. +- `gamecult.bifrost.economics` for patron pressure, contributor credit, ledger + entries, payout proposal batches, and revenue-share inputs. +- `gamecult.bifrost.bridge` for GitHub, Discord, CultNet/CultCache, and future + collaboration crossings plus receipts. +- `gamecult.bifrost.surface.product` for member/patron/contributor/user-facing + Eve product surfaces. +- `gamecult.bifrost.surface.operator` for deploy, readiness, queue, witness, + bridge, schema, and migration operator surfaces. + +Odin discovers Bifrost through the service namespace, then indexes the schema +catalog and surface namespaces. Odin does not scrape Razor pages as truth. + +## Eve Product And Operator Surfaces + +Product surfaces are the canonical interface compositions for: + +- account/membership status; +- patron and contributor standing; +- project and work-item boards; +- motions, topic threads, votes, approvals, and objections; +- work claims, review, completion, receipts, and contributor credit; +- bridge receipts and public handoff targets. + +Operator surfaces are the canonical interface compositions for: + +- readiness, build/version, config validation, and deploy target; +- CultCache witness freshness and export errors; +- CultMesh publication health and Odin discovery status; +- bridge queues, failed crossings, retry/cancel controls, and receipt gaps; +- schema versions, migration state, and Postgres-to-`.cc` witness drift; +- Discord mirror health, including fail-closed unmirrored governance writes. + +The current Razor Pages app lowers product surfaces into browser UI. Existing +health/readiness endpoints lower operator state into HTTP probes. Both should +be fed by the same typed service state that backs Eve surfaces. + +## Nested Verses + +Bifrost exposes nested Verses where local ownership matters: + +- Patron Verse: patron identity projection, priority pressure, pledge/reward + influence, receipts, and standing. +- Work Verse: work items, claims, estimates, review, blockers, completion, and + maintainer acceptance. +- Motion Verse: motions, topic threads, comments, votes, approvals, objections, + policy decisions, and dispatch promotion. +- Project Verse: project membership, repository links, maintainer authority, + work boards, and public receipts. +- Account Verse: Heimdall-linked actor projections, membership state, + contributor tier snapshots, grants consumed by Bifrost, and audit trails. + +Nested Verses do not own separate databases. They are CultMesh/Eve projections +of Bifrost-owned typed state with local command affordances and clear handoff +to Heimdall, project maintainers, or bridge executors where authority leaves +Bifrost. + +## Migration Order + +1. Catalog current Bifrost state owners: EF/Postgres tables, `.cc` stores, + bridge receipts, Discord mirrors, webhook cache, and app readiness state. +2. Define schema ids for missing Bifrost documents: work item, motion, vote, + ledger entry, bridge action, bridge receipt, member capability snapshot, + service registration, and Eve surface publication. +3. Add Postgres-to-CultCache witness export for alpha entities before replacing + the transactional store. +4. Publish `gamecult.bifrost.service` and schema catalog through CultMesh. +5. Publish operator surfaces first: readiness, witness freshness, bridge queue, + failed crossings, and migration drift. +6. Publish product surfaces for account, project, work, motion, patron, and + contributor views as `gamecult.eve.surface.v1`. +7. Lower the existing Razor Pages app from the Eve/product surface contract + where practical, leaving direct Razor composition only as transitional UI. +8. Route Discord native interactions through Bifrost commands that update typed + state and emit Discord receipts from the same commit path. +9. Let Odin discover Bifrost surfaces and nested Verses through CultMesh, then + retire any scraping or private summary adapters. + +## Demotion Line + +Demoted surfaces and stores: + +- Razor Pages views are no longer the canonical Bifrost presentation owner; they + are browser lowerings of Bifrost product/operator surfaces. +- `/healthz`, `/readyz`, and any future HTTP dashboard/status JSON are probes or + xenos-boundary exports, not service truth. +- `.bifrost/discord-webhook-cache.json` is webhook address cache only; it does + not prove governance, speech authority, or receipt completion. +- `.bifrost/agent-dispatch/**/request.json`, `dispatch.json`, `result.json`, and + app-server protocol JSON are local dispatch/protocol artifacts. They may be + evidence attached to typed receipts, but they cannot decide request status, + work authority, or bridge success. +- Discord `#bifrost` messages are mirrors and linked-user input surfaces. They + are not canonical governance threads unless Bifrost commits the corresponding + topic/comment/vote document. + +The live owner is Bifrost typed state. Everything else either lowers it, +commands it, witnesses it, or provides external evidence for a typed receipt.