Migration Plan

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

1. Core Rules

• Block registry + BlockBase shape is frozen at M2 start (F17). New block kinds additive; existing kind data stable.
• PlayPackage manifest (F15, M1 start) evolution coordinated with content-service.
• AI prompts append-only per tenant; deprecated callable ≥ 1 milestone.
• Draft state machine transitions frozen; new states additive only.

2. Database Evolution

• Add column (nullable): ✅
• Add column (NOT NULL): two-step.
• JSONB payload (blocks): versioned per block kind. Each block has schemaVersion.
• Yjs document store: yjs_doc column (binary); backward-compat via Yjs merge semantics.

3. API Evolution

• URL major for breaking; dual-serve ≥ 1 milestone.
• Block kinds: new kinds additive to discriminated union; consumers ignore unknown kinds.
• Publish endpoint idempotent: replaying with same Idempotency-Key returns existing saga state.

4. Block Schema Evolution

4.1 Adding a New Block Kind

1. RFC in docs/rfcs/blocks/.
2. Add TypeScript type to Block union.
3. Register in block registry with schemaVersion: 1.
4. Player falls back to "unsupported" stub if not recognized.
5. Publish → PlayPackage manifest version incremented only if runtime needs changes.

4.2 Evolving an Existing Block Kind

• Add optional field: same schemaVersion, minor bump.
• Add required field: new schemaVersion; migrate existing blocks (lazy on next read or one-time job).
• Remove field: deprecation ≥ 2 milestones; migrate blocks to remove; drop.
• Rename field: additive rename (write both, read new, deprecate old).

5. AI Prompt Evolution

• Prompts versioned (SemVer).
• New version auto-selected after eval passes.
• Deprecated version callable ≥ 1 milestone.
• Per-tenant pin: admin can freeze prompt version.
• Regression suite must pass before publishing new version.
• Safety eval must pass on red-team corpus.

6. Publish Saga Versioning

• Saga steps + compensations are frozen (F20 for purchase, analogous for publish).
• Adding a step: new saga v2; dual-run window; old sagas finish on old version.
• Removing a step: deprecate; no new sagas use it; drop after zero in-flight.

7. Event Evolution

Event	Version	Evolution
authoring.course_draft.published.v1	v1	Additive payload only
authoring.block.added.v1	v1	New block kinds additive
authoring.block.ai_generated.v1	v1	Provenance schema additive
authoring.publish_saga.step_completed.v1	v1	New steps additive

8. Offline Bundle Migration (Authoring-Side)

• Offline drafts encrypted per-(tenant, author, device) → same rules as PlayPackage bundles.
• Draft-schema version in bundle manifest; player refuses to resume on major mismatch.

9. Yjs Document Migration

• Yjs CRDT merges preserve history; no destructive migration.
• Renaming a shared type requires new doc; old docs read-only + auto-converted to new on next save.

10. SCORM Import Version Support

Version	Status	Notes
SCORM 1.2	Active	M2
SCORM 2004 (3rd edition)	Active	M3
SCORM 2004 (4th edition)	Active	M3
AICC	Deprecated	Not supported
xAPI	Active	Export only (progress-service is LRS)
LTI 1.3	Active	M4 (launch, not import)
cmi5	Active	M4

11. Tenant Migration Runbook

For breaking block-kind changes, follow ../tenant-service/MIGRATION_PLAN.md §10.

12. Changelog

All breaking changes tagged with semver + GitHub release notes.