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]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 6f073114-98af-41a6-bed9-2046d73eb02e

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ 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.