Content & Versioning Model

Today everything ships as one blob, so any change is a forced change. The “forced upgrade” pain is a coupling problem, not an isolation problem. The fix is to split “the product” into independently versioned axes, each with its own cadence and its own pinning:

• Platform / runtime version — The APIs, sim engine, LiveKit, and the web / VR / game clients.
• Content schema version — The format and contract a lesson is authored against.
• Content package version — The actual lesson bytes — both our upstream library and the tenant's customized fork.
• Tenant pin / channel — What each customer has chosen to take (pinned version or release channel).

Once these are separate, “the customer takes an upgrade” becomes an explicit, per-axis version bump — never a fleet-wide forced rollout. The reference experience is a self-updating desktop app: it ships often, you choose when to take it, and it doesn't break your existing work because the new runtime stays backward-compatible within a major version.

Every change is one of two kinds, and they have very different rules.

That declaration is what lets the runtime answer “yes / no, I can run this” instead of breaking silently in front of a learner.

Treat the default library exactly like an upstream open-source package, and the tenant's customization like a fork with a lockfile.

• Publish — We publish versioned content packages to a registry with semantic versions, e.g. scenario-sepsis@2.4.1.
• Fork — Tenants fork to customize; they now own a downstream branch of that scenario.
• Sync from upstream — When we ship 2.5.0, the tenant gets a 'sync from upstream' prompt — they choose to merge, with conflict resolution against their customizations.
• Pin & channel — Tenants pin versions and subscribe to a release channel (stable / beta / pinned). Our release cadence is decoupled from their adoption.

This single pattern solves both stated pains at once: customer-controlled upgrades and content versioning that preserves customization.

Borrowed from package.json engines / capability negotiation — this is what stops a lesson from breaking when services change:

• Each content package declares what it requires: requires: { schema: "^3", capabilities: ["sim.vitals.v2", "branching.v1"] }.
• Each runtime / client advertises the capabilities it provides.
• A lesson only launches if the contract is satisfiable; otherwise the tenant sees a clear “this lesson needs runtime ≥ X” message instead of a silent failure.
• Breaking change = major version bump. Tenants on the old major keep working; upgrading is an explicit, migration-gated action.

The versioning must feel familiar to clinician-authors, not developers. The key is to separate storage semantics from presentation.

The upstream merge becomes a field-level three-way merge, presented gently: “We updated 3 sections of the library scenario. You've customized 1 of them — review that one; we'll auto-apply the other 2.”

The internal content model stays clean; interoperability standards live at the boundaries as adapters.

SCORM's tracking model is dated and tightly coupled to a browser + LMS runtime, so it must not shape the core — cmi5 & xAPI fit the multi-client world far better.

A multi-modal “lab” — videos → reading → quiz → sim scenario → debrief → quiz — is just a sequenced lesson of mixed activities. It maps onto cmi5's hierarchy almost 1:1:

Each Activity is independently versioned, capability-declaring, and launchable on the appropriate client. Sequencing / gating rules (must-pass-quiz-before-sim) live at the lesson level. No new primitive is needed for a “lab” — a good sign the model is right.

AI services change constantly, so a lesson must depend on capabilities, not model strings. The config tree is Lesson → Scenario → Agent (patient) → { llm, tts, stt }, each independently selectable.

Selection should be constraint-driven to avoid runtime footguns (e.g. Deepgram strong at STT for one language, ElevenLabs better at TTS for another):

1. Author picks language + desired features for the agent.
2. System shows only compatible providers / models (capability profiles filtered by that constraint).
3. Author pins one or accepts the default.

The LLM side can ride a provider-neutral SDK (e.g. Vercel AI SDK); TTS / STT use a thin equivalent with the same capability-profile shape (languages, streaming, latency class, features).

The rule that keeps lessons portable and credentials secure:

Localization runs through three distinct layers — don't collapse them:

• UI chrome — Portal labels; classic i18n (ICU message catalogs), per-user locale.
• Content — Per-lesson locale variants within the structured model; versioning works per-locale, so 'the English changed' can flag 'the French is now stale.'
• AI capability + prompts — Language constrains valid LLM / TTS / STT providers (the support gap problem) and prompts often need per-language tuning, not literal translation.

Language is therefore a first-class axis woven through content variants, provider selection, and prompt authoring — retrofitting locale-aware versioning later is brutal, so it's designed in from the start.

This reframing answers the tenancy question by splitting data into two planes with different isolation needs:

So we likely don't need one isolation model — we need a different one per plane.

• Forking semantics — when a tenant customizes, is it a copy, an override layer, or a true branch? This drives how painful upstream-merge becomes.
• Standalone-ness — must a lesson be a fully offline-runnable bundle (important for VR / game clients), or may it call home at runtime?
• Authoring scope — do tenants author net-new content, only customize ours, or is there a co-author / marketplace ambition?
• Merge UX — exactly how “take the library update” looks to a non-technical author.
• Launch-resolution flow — capability check → provider / key binding → xAPI emission, end to end.