BRIDGE-1: bus bridge and opaque relay specification

[JarbasAl]

Companion issue: #42

Summary

Defines the bus bridge — a participant on the internal message bus that terminates an external communication channel and relays messages between the bus and remote participants.

The spec carries minimal normative weight. Most of what it documents are emergent patterns that arise from composing MSG-1 + SESSION-1/2 + PIPELINE-1 + TRANSFORM-1 + CONTEXT-1 + INTENT-4 at a bus boundary.

What the spec covers

• §2 — Bridge role: enforcement point, producer on the internal bus
• §3 — Normative core:
  • §3.1 Inbound identity stamping (source)
  • §3.2 Outbound routing — destination (primary, MUST), session_id (secondary, MAY), site_id (group, MUST when grouping). Known-participant lifecycle. NAT/session-id bijection
  • §3.4 site_id assignment — bridge evaluates client-supplied value vs. its own determination (geolocation, home-automation area names); downstream MUST NOT overwrite
  • §3.5 Session preservation — relaying mode (spec-aware clients, transparent carrier) and managing mode (opaque clients, bridge owns session lifecycle)
• §4 — Emergent patterns:
  • §4.1 Policy injection via session fields (denylist model, pipeline/transformer preferences, context pre-population)
  • §4.2 Multi-deployment topology (satellite/hub with local/hub-side audio stacks, cascading intelligence, multi-participant session identity, per-satellite response personalisation via dialog transformers)
  • §4.3 Out-of-utterance session sync (ovos.session.sync relay)
  • §4.4 Satellite skill registration (transparent via INTENT-4 §11; disconnect/reconnect; bridge-own session)
• §5 — Ordering guidance (FIFO SHOULD where transport supports it)
• §6 — Conformance (5 MUSTs, 1 SHOULD, 6 MAYs)

Key design decisions

• Destination-based routing provides client isolation. The orchestrator uses .reply() setting destination to the original source; two participants sharing session_id: "default" are distinguished by destination alone
• Two session-preservation modes. Relaying (spec-aware satellite: transparent carrier) vs. managing (opaque client: bridge owns session lifecycle, MUST assign distinct session_id per participant)
• site_id owned by BRIDGE-1. Bridge is the natural assignment point; client MAY report, bridge MAY override
• Satellite skill registration is transparent. No new protocol — INTENT-4 §11 session-scoped registration + existing destination routing handles it
• Dialog transformers run on the satellite. The audio-output layer is local; ovos.utterance.speak carries the session back so each satellite's transformer preferences apply locally

Companion PR

INTENT-4 §11 (PR #45) defines session-scoped registration that §4.4 depends on.

[coderabbitai]

Warning

Review limit reached

@JarbasAl, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 41 minutes and 16 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more credits in the billing tab to continue.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based credits.

🚦 How do rate limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 519c8434-9f02-4845-b297-1f935df4090d

📥 Commits

Reviewing files that changed from the base of the PR and between bcaa32b and c929cbc.

📒 Files selected for processing (5)

• CHANGELOG.md
• appendix/divergences.md
• appendix/gaps.md
• appendix/rationale.md
• bridge-1.md

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch spec/bridge

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[JarbasAl]

Merge-readiness: resolved.

Conflicts resolved (commit 9a008a4):

• README.md spec table: PR branch had added COMMON-QUERY-1 and BRIDGE-1 rows; dev added AUDIO-IN-1 in separate commit. Kept all rows. Corrected the BRIDGE-1 link to bridge-1.md (the rename this branch performs) rather than the stale ovos-bridge-1.md. Added FALLBACK-1 row to complete the in-review index.

No semantic flags. Cross-references in bridge-1.md reference spec IDs and appendix/gaps.md — both resolve on current dev.

CI: no workflow files in repo; CodeRabbit review on this PR not yet triggered.

Note on #55 (chore/normalize-spec-filenames or chore/standardize-filenames): If either filename-rename PR merges first, this branch will need a trivial refresh — bridge-1.md may be renamed again. Check bridge-1.md references in README and any cross-spec citations.