gnomonlearn
Docs/RFC-0016/Reference catalog

RFC-0016 · Reference catalog

Versioned draft snapshot

RFCs, reference catalogs, and evidence reflect Spec 3b2e3e7a114fb826b1445d39a48756b8fff629cd. Counts and pending/status notes belong to that snapshot. Read the dated project update for later progress.

Source repositories are private during staging. Links marked “repository access required” need access to the linked repository.

← Read the authored RFC

Generated reference catalog. This page renders structured Lean data for RFC-0016: defined terms, diagnostics, dependencies, and invariants. It does not establish proof coverage or runtime conformance. The authored narrative lives in RFC-0016.

This page is generated from the lean/Gnomon/Spec/ module for RFC-0016. Edit that source and regenerate this catalog.


Title: Schema Migration and Evolution
Status: draft
Owners: Data, Platform
Diagnostic range: M01600-M01699

Proof citations in source: 8 / 8. Standalone proof verification is pending.


Definitions

TermMeaning
Migration DAGThe directed acyclic graph formed by all migrations within a module, with edges from source versions through migration nodes to target versions.
migrationA named, version-scoped declaration that describes a schema change as a pair of operations: a forward block that applies the change, and a rollback block that undoes it.

Diagnostics

CodeSeverityDescription
M01600ErrorREMOVE_FIELD_LIVE_DATA — RemoveField applied to entity with live non-null data and drop: true is absent.
M01601ErrorADD_FIELD_NO_DEFAULT — AddField with no default applied to an entity with live rows.
M01602ErrorCHANGE_TYPE_NO_TRANSFORM — ChangeType with no transform reference.
M01603ErrorCHANGE_TYPE_NON_TOTAL — Transform referenced in ChangeType is not provably total over the old type’s value domain.
M01604ErrorREMOVE_ENTITY_LIVE_DATA — RemoveEntity applied to entity with live instances and drop: true is absent.
M01605ErrorMIGRATION_CYCLE — Migration graph contains a cycle.
M01606ErrorMISSING_ROLLBACK — Migration that touches existing data has no rollback block.
M01607ErrorUNRESOLVED_FROM_RANGE — The from version range does not resolve to any installed module version.
M01608ErrorMISSING_APPROVAL_RECORD — Migration applied without required approval record.
M01609ErrorINVALID_MIGRATION_OP — Migration operation references a QUALIFIED name that is not a core.migrations.* intrinsic or a user-declared transform.
M01610ErrorVERSION_BUMP_TOO_SMALL — Migration’s from-to version bump is smaller than required for its operations.

Invariants

  1. Each migration’s forward or rollback block executes atomically in a transaction; partial schema states are not observable. (enforced by: runtime)
  2. Every migration that touches existing data must define a rollback block. (enforced by: static-check)
  3. Every migration’s from version range must resolve to at least one installed version in the target environment. (enforced by: apply-time)
  4. Every transform referenced by core.migrations.ChangeType must be provably total over the old type’s value domain. (enforced by: static-check)
  5. MAJOR breaking migrations must carry an approval record before they are applied. (enforced by: install-validation)
  6. Migration names are immutable after first application; renaming an applied migration is a static error. (enforced by: static-check)
  7. Migrations execute in topological order over the DAG, with lexicographic tie-break on migration name for determinism. (enforced by: runtime)
  8. No migration may alter valid_time or system_time of rows that predate the migration. (enforced by: runtime)
  9. Rolling back an AddEntity whose table has rows must archive (not delete) those rows via system_time before dropping the table. (enforced by: runtime)
  10. The migration DAG for a module must contain no cycles. (enforced by: static-check)

Normative Statements

Statements are structured source data. Proof citations, where present, have not passed a standalone Gnomon proof gate.

Backward-Compatibility Classification

  1. MUST — When a migration’s from-to version bump is smaller than the required bump for its operations, the compiler MUST produce error M01610. (proof citation: rfc0016_b18_grounded; verification pending)

Bitemporality Preservation

  1. MUST_NOT — Migrations MUST NOT alter valid_time or system_time of existing records. (proof citation: rfc0016_b20_grounded; verification pending)
  2. MUST_NOT — No migration operation may rewrite valid_time of a row that existed before the migration. (proof citation: rfc0016_b27_grounded; verification pending)

CLI Commands

  1. MUST — In CI environments without a TTY, —yes MUST be passed explicitly for destructive migrations; otherwise the command exits non-zero.

Invariants

  1. MUST — Every migration that touches existing data MUST define a rollback block.
  2. MUST — Every migration’s from version range MUST resolve to at least one installed version in the target environment.
  3. MUST — Every transform referenced by ChangeType MUST be provably total over the old type’s value domain.
  4. MUST — MAJOR breaking migrations MUST carry an approval record before being applied. (proof citation: rfc0016_b4_grounded; verification pending)
  5. MUST — Migration names MUST be immutable after first application. (proof citation: rfc0016_b8_grounded; verification pending)
  6. MUST_NOT — No migration may alter valid_time or system_time of rows that predate the migration.
  7. MUST — The migration DAG for a module MUST contain no cycles.

Migration Operation Kinds

  1. MUST — ChangeType’s referenced transform MUST be total over the old type’s value domain.
  2. MUST — RemoveField and RemoveEntity operations MUST require human approval per RFC-0005 §4a. (proof citation: rfc0016_b1_grounded; verification pending)

Migration Sequencing and Atomicity

  1. MUST — Each migration MUST be atomic; failure rolls back the entire forward or rollback block.
  2. MUST — Every migration whose forward block touches existing data MUST define a rollback block.
  3. MUST — Rollback of an addEntity migration with inserted rows MUST archive (not delete) those rows using system_time before dropping the table.
  4. MUST — The rollback block MUST include a preserveRows directive if any rows may exist at rollback time.

Security and Approval Requirements

  1. MUST — Migrations applied without a required approval record MUST be blocked and raise M01608. (proof citation: rfc0016_b13_grounded; verification pending)
  2. MUST — removeField, changeType, and removeEntity migrations MUST follow the human approval workflow defined in RFC-0005 §4a. (proof citation: rfc0016_b22_grounded; verification pending)

The migration Declaration Kind

  1. MUST_NOT — Migration names MUST NOT be renamed after a migration has been applied to any environment.
  2. MUST — QUALIFIED in a migration-op MUST resolve to a core.migrations.* intrinsic or a user-declared transform invocation.

Linked References

(no cross-RFC dependencies)