gnomonlearn
Docs/RFC-0016 migration rollback proposal

RFC-0016 migration rollback proposal

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.

This is a trace and gap record from the pinned draft specification. It does not establish proof or implementation conformance.

Evidence

  • RFC-0016 §1 defines a migration as a forward/rollback pair, but its grammar and §1.1 make rollback conditional. Section 4.3 permits omission for an entity addition with no existing rows. The domain node declaration/migration currently calls the pair unconditional.
  • Section 4.3 requires a preserveRows directive when rows may exist at rollback time. Neither RFC-0016’s operation grammar nor RFC-0035’s canonical core.migrations slot table defines this directive. Section 10’s footnote instead prescribes RemoveEntity { drop: true }, while §5 says an explicit drop permanently removes data from historical queries.
  • Section 2.1 requires a default for AddField when live rows exist, while §2.7 describes BackfillFrom as the alternative to a static default. The rules do not say whether a same-transaction backfill satisfies M01601. A compiler and runtime could reject the advertised alternative.

Proposed first-release contract

  1. Define a migration by a required forward block and a conditionally required rollback block. Update the declaration/migration summary and regenerate RDF only after the authored wording and Lean catalog agree.
  2. Define a rollback archive operation with a typed slot schema in RFC-0035, or remove the archive promise and explicitly state that an approved destructive rollback loses history. The archive option better preserves RFC-0007’s historical query guarantee. Specify archive location, retention, asOf(t) behavior, and transaction order before treating it as implemented. Remove the undefined preserveRows syntax and the conflicting drop: true footnote once the operation is defined.
  3. Permit AddField without default only when no live rows exist, or when a same-transaction BackfillFrom covers every live row before the new field becomes observable. Define static coverage checks and apply-time M01601 behavior for uncovered rows.

Acceptance checks

  • Parse and type-check a migration with optional rollback, and reject missing rollback for every operation that modifies existing rows.
  • Exercise an AddEntity rollback after rows were inserted; verify historical queries and the documented retention behavior after rollback.
  • Exercise default, total backfill, partial backfill, and absent backfill against live rows; verify M01601 and atomic rollback on failure.
  • Reconcile RFC-0016, RFC-0035, Lean, authored domain facts, emitted RDF, and site reference output. Run the projection drift and semantic review gates.

These are draft contract proposals. No RDF or runtime behavior is changed by this review.