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
rollbackconditional. Section 4.3 permits omission for an entity addition with no existing rows. The domain nodedeclaration/migrationcurrently calls the pair unconditional. - Section 4.3 requires a
preserveRowsdirective when rows may exist at rollback time. Neither RFC-0016’s operation grammar nor RFC-0035’s canonicalcore.migrationsslot table defines this directive. Section 10’s footnote instead prescribesRemoveEntity { drop: true }, while §5 says an explicit drop permanently removes data from historical queries. - Section 2.1 requires a default for
AddFieldwhen live rows exist, while §2.7 describesBackfillFromas 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
- Define a migration by a required
forwardblock and a conditionally requiredrollbackblock. Update thedeclaration/migrationsummary and regenerate RDF only after the authored wording and Lean catalog agree. - 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 undefinedpreserveRowssyntax and the conflictingdrop: truefootnote once the operation is defined. - Permit
AddFieldwithoutdefaultonly when no live rows exist, or when a same-transactionBackfillFromcovers 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
AddEntityrollback 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.