Bifrost/docs/bridge.md

Bifrost Bridge

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 Personas, or one-off helper scripts become hidden authorities.

For the full ownership map, read docs/jurisdiction-map.md.

That means Bifrost owns the operational meaning of the crossing:

• what action is being requested
• which repo, channel, PR, or discussion surface it targets
• which agent or account is acting
• which user/member/patron/contributor capability or agent grant is involved
• which work item, priority signal, vote, bounty/reward state, or credit allocation it affects
• what permission or review state made the action acceptable
• what receipt proves the crossing happened

It does not mean Bifrost should own OAuth sludge. Heimdall owns OAuth, linked identities, token custody, grants, and signed account claims. Bifrost consumes Heimdall identity and permission facts, then decides whether a bridge action is allowed in the Bifrost domain.

Ownership

• Heimdall owns provider OAuth and account-linked credentials.
• Bifrost owns bridge action policy, request lifecycle, routing, execution receipts, Discord-native Bifrost interface transport, and governance/labor transport.
• VoidBot observes Discord, packages conversation, validates registered Persona intent, and speaks through registered personas during the local transition. It should not be the durable authority that mutates GitHub or owns Bifrost-scoped Discord transport.
• CultCache stores lightweight agent transport packets when the bridge needs file-native state.
• CultNet carries those packets between runtimes.
• Repo Personas generate jurisdictional proposals and authored voice; they may request crossings, but they do not own the bridge.

Local Bridge CLI

tools/bifrost-bridge.mjs is the current local bridge executor.

It intentionally uses boring local credentials while Heimdall's managed GitHub credential runtime is still unfinished:

• GitHub actions use the local gh authenticated account.
• Discord posts use BIFROST_DISCORD_BOT_TOKEN or DISCORD_BOT_TOKEN.

The CLI is not the final permission system. It is the working bridge actuator Bifrost owns now, so VoidBot and repo Personas can stop carrying this machinery themselves.

GitHub Draft PR

node .\tools\bifrost-bridge.mjs github-draft-pr `
  --repo-root E:\Projects\AetheriaLore `
  --identity nibu `
  --title "Nibu: Glitchcraft and reset-loop continuity" `
  --path Aetheria/Articles/Nibu/glitchcraft-and-reset-loops.md `
  --content-file E:\tmp\article.md `
  --body "Drafted from recent Aquarium consensus." `
  --base main

The command:

1. checks the target repo is clean unless --allow-dirty is set
2. creates a branch
3. writes the target file
4. commits and pushes
5. opens a draft PR through gh pr create
6. restores the original branch
7. prints a JSON receipt

Use --dry-run to print the planned action without writing or posting.

GitHub PR Comment

node .\tools\bifrost-bridge.mjs github-pr-comment `
  --repo-root E:\Projects\AetheriaLore `
  --identity nibu `
  --pr 12 `
  --content "This proposal needs a sharper leash before it becomes canon-shaped."

The command leaves a signed PR comment through gh and prints a JSON receipt. Repo Personas should use this when the argument belongs on the review artifact instead of dissolving into Discord scrollback.

Discord Post

node .\tools\bifrost-bridge.mjs discord-post `
  --channel-id 1501196543150264332 `
  --persona-name Nibu `
  --persona-avatar-url https://example.invalid/nibu.png `
  --content "Nibu drafted the article and put it in a PR: https://github.com/..."

The command posts through Discord's REST API using the configured bot token and prints a JSON receipt. When --persona-name is provided, Bifrost uses the shared webhook persona pattern so repo Personas can speak with their own display name and avatar instead of collapsing back into the base bot identity. Configure BIFROST_DISCORD_PERSONA_WEBHOOK_URL_<channelId> or DISCORD_PERSONA_WEBHOOK_URL when the bot should use an existing webhook; otherwise it creates and caches a Bifrost Persona Pipe webhook for the channel when Discord permissions allow it.

Discord DM

node .\tools\bifrost-bridge.mjs discord-dm `
  --recipient-id 123456789012345678 `
  --content "Moderation status update..."

The command opens a bot DM with the recipient, posts the message, and prints a JSON receipt. Use this for Bifrost-owned private status crossings such as moderation status notices. Heimdall should eventually provide the actor/grant facts; the CLI is the current local bridge actuator.

Discord Native Interface Target

Discord should become a native Bifrost interface for Bifrost-scoped work, not just an output pipe.

The intended shape:

1. Heimdall links a Discord user to a GameCult user/member/patron/contributor account and issues capability claims.
2. Bifrost receives Discord interactions, commands, mentions, or channel events that are relevant to work, policy, priority, reward allocation, maintainer review, or swarm routing.
3. Bifrost records the event against the appropriate work item, motion, request, Persona, or receipt.
4. Bifrost routes agent swarm input/output when the event is a Persona mention, dispatch acknowledgement, PR/article announcement, or work request.
5. Bifrost posts concise Discord receipts that identify the topic, target, status, and next place to continue.

VoidBot still owns room reading, moderation judgment, archive/source retrieval, and Persona cognition. Bifrost owns Discord when Discord is being used as the Labor Platform interface or swarm transport.

Heimdall Integration Target

The correct future credential path is:

1. Heimdall implements GitHub OAuth callback/runtime and managed credential custody.
2. Heimdall issues Bifrost-verifiable claims for account identity and bridge capabilities.
3. Bifrost records a bridge action request and checks the Heimdall-derived permission facts.
4. Bifrost executes or queues the action through the appropriate bridge executor.
5. Bifrost records the GitHub/Discord receipt and exposes it back to the requesting agent/runtime.

In that shape, Bifrost is the shiny bridge. Heimdall is the gatehouse with the keys. VoidBot is not hiding a bolt cutter in its coat.