Migration Plan

:::info Source Sourced from services/delivery-service/MIGRATION_PLAN.md in the documentation repo. :::

1. Core Rules

• PlaySession state machine transitions frozen; new states additive only.
• Navigation cursor shape versioned; backward-compatible.
• AI tutor prompts append-only; deprecated callable ≥ 1 milestone.
• Offline bundles live forever; player must support historical bundle versions.

2. Schema Evolution

• PlaySession columns: add nullable freely; NOT NULL two-step.
• cursor JSONB versioned (cursor.schemaVersion).

3. API Evolution

• URL major → major (/api/v1/play-sessions → /api/v2/… on breaking).
• New SSE event types additive; clients ignore unknown.
• Tutor turn schema: additive fields; provenance evolving via AI services migration plan.

4. AI Tutor Prompt Evolution

• Prompts versioned; eval-gated.
• Deprecated prompts callable ≥ 1 milestone.
• Per-tenant pin honored.
• Accept-rate regression gate: new prompt must meet ≥ 50% accept within 7 days or rollback.

5. Event Evolution

Event	Version	Policy
delivery.play_session.started.v1	v1	Additive
delivery.play_session.navigated.v1	v1	Cursor shape versioned additive
delivery.play_session.completed.v1	v1	Additive; outcome enum additive
delivery.tutor_turn.completed.v1	v1	Provenance additive
delivery.offline_mounted.v1	v1	Additive

6. Offline Session Format Evolution

• Offline session state in IndexedDB / SQLite versioned via schemaVersion.
• Player migrates on app upgrade via Dexie/Drizzle migrations.
• Unmigratable → prompt user to sync + reinstall.

7. Player Version Compatibility

• Player should support bundles for ≥ 2 previous manifest versions.
• Bundle manifest minPlayerVersion field specifies minimum compatible player.
• Older players refuse newer bundles; prompt upgrade.

8. SCORM Runtime Migration

• SCORM 1.2 runtime stable; 2004 runtime adds interactions and sequencing.
• cmi.* → xAPI adapter versioned; new verbs additive.

9. LTI 1.3 Migration

• Platform keys (LMS side) cached; rotation via LTI Advantage Registration protocol.

10. Data Residency

• Sessions pinned to tenant homeRegion.
• Migration: freeze session creation; snapshot; migrate; unfreeze.
• Active sessions end gracefully (saved, replay-able in target region).

11. Changelog

Per-release changelog with: schema changes, prompt versions, new block-kind support, breaking SSE message types.