Document Bifrost Verse service contract
This commit is contained in:
Meta Vens
parent
db1d908de2
commit
11c8ec2a2d
5 changed files with 185 additions and 3 deletions
|
|
@ -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)
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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`.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
158
docs/verse-service-contract.md
Normal file
158
docs/verse-service-contract.md
Normal file
|
|
@ -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.
|
||||
Loading…
Reference in a new issue