Real-Time Media ConductorArchitecture · Design decisions
Proposed changes and acceptance criteria
Requirements and validation needed before extending runtime contracts or adding shared infrastructure.
This page describes conditions for extending RMC: an integration needs behavior the current contracts cannot express, a failure requires additional recovery, or independently maintained implementations need compatibility rules.
These are candidate steps and acceptance criteria. They are not committed delivery dates or claims that the experiments have already passed.
Begin with a product requirement
Write one user flow and the behavior that the current implementation cannot provide. Examples include an independently deployed reasoner, a second media transport, an extension that must recover missed work, or a team that cannot safely upgrade a shared adapter.
Use the open questions to identify the exact boundary. If a direct integration can satisfy the requirement, prove it there before extracting a more general module.
Step 1: document and validate current contracts
Maintain the client guides, integration catalog, runnable examples, and source links. Document what each adapter receives, emits, and owns. Keep the current LiveKit and reasoning integrations directly wired.
Evidence: a second team can run an example and integrate it without discovering undocumented authority, lifetime, or retry rules. Record the questions they had to ask; use those to improve the contract.
Use integration feedback to identify missing documentation or required API changes.
Step 2: prove one replacement
Choose one contract with a real second implementation. For reasoning, preserve the agreed semantic request/result and cancellation behavior. For media, include browser capture, provider credentials, track distribution, processor input, and cleanup.
Evidence: run the same product flow with both implementations and explain every remaining provider-specific change. Document any provider-specific browser changes; those changes are part of the replacement cost.
Only generalize the common behavior the two implementations demonstrate. Declare optional capabilities separately so clients can detect unsupported operations.
Step 3: prove the required failure behavior
Use an isolated stack for failure experiments; do not infer the result from code structure alone.
| Proposed experiment | Evidence to collect | Decision it informs |
|---|---|---|
| Delay or stop the reasoner during a live interaction | What the customer can still do; task terminal status; cancellation behavior | Whether reasoning needs stronger process or service isolation |
| Disconnect LiveKit while chat remains active | Native track status, visible error, durable chat continuity, recovery | How the UI degrades across modality failures |
| Restart RMC with pending work | Persisted facts, interrupted tasks, client replay, provider coordination | Whether the product needs durable worker recovery or a stronger session-resume contract |
| Revoke access during media use and reconnect | RMC denial, provider removal, cached-token behavior for the deployed provider | Whether current cleanup meets the product's access-ending requirement |
| Repeat a consumer action after a lost acknowledgment | Duplicate behavior at the actual destination | Whether a local idempotency policy is enough |
The repository's unit/integration tests cover important pieces. These experiments ask broader product questions, especially about established native sessions. Track them as unverified until run in the intended deployment.
Step 4: support independent releases where they exist
If interaction and reasoning teams release separately, agree on versioned request/result fixtures, schema ownership, deprecation, and a small integration check. Keep package version and provider/model version distinct from contract version.
Evidence: an interaction change can ship against the existing reasoner, and a reasoner change can ship against the existing interaction client, within the stated compatibility policy. Include behavior such as cancellation and stale-result handling; a JSON parse test alone is insufficient.
A generalized substitution suite becomes useful when there are multiple maintained implementations to validate. It is not a prerequisite for the first narrow extension.
Step 5: grow distribution when reuse demands it
A reviewed package catalog can become deployment-time selection when hosts need to choose among approved integrations. Customer installation is a separate step with isolation, credential, policy, and support requirements.
Evidence: the proposed installation flow solves an actual adoption problem, and the host can enforce what an installed integration may execute and where it may send data. The marketplace discussion separates these stages.
Keep deferred work tied to a trigger
| Area | Trigger before expanding it |
|---|---|
| General adapter host or named bindings | Multiple concrete compositions cannot be expressed cleanly through direct wiring |
| Remote processor framework | A maintained remote worker needs lifecycle semantics beyond a small HTTP integration |
| Atomic external-output/checkpoint machinery | A durable external side effect has a demonstrated restart failure that destination idempotency cannot address |
| Broader topology, lag, or health reporting | An operator has a decision that existing diagnostics cannot support |
| Migration/backfill framework | A specific schema or retained-history change requires more than a targeted compatible migration |
| Multi-provider conformance platform | Several maintained providers share a contract and independent releases need a common gate |
Keep live-only presence, typing, and meters in the existing provider or UI state. Preserve SQLite compatibility while it remains the current store. Reassess after each completed product requirement before extracting more modules.