@@ -8,27 +8,29 @@ date: 2026-10-16
88## Decision
99
1010Whether the target column must be overwritten is a fact about the target
11- column's contents, not about one run. It is therefore recorded once, on the
12- column migration, as an obligation. An obligation opens when a forced pass
13- starts (in either direction) or when a reverse column migration begins on a twin
14- that already holds values. It closes only when a forced pass completes, or, for
15- the up-front reverse case, when the operator records a waiver asserting the
16- existing values are current. A waiver cannot close the obligation of a forced
17- pass that has already started, because by then the target column is partly
18- overwritten. While an obligation is open, every run is a forced pass, whatever
19- the caller passes. ` @cipherstash/migrate ` enforces this rule itself, not the
20- ` stash ` CLI, because customers embed ` runBackfill ` and ` runDecryptBackfill ` in
21- their own workers and would otherwise bypass it.
22-
23- #1193 and #1276 (the first part of #1217 ) implement this decision in
24- ` ColumnMigration ` . ` runBackfill ` and
25- ` runDecryptBackfill ` plan every run through it, so in both directions it forces
26- a run while an obligation is open, forces a reverse run that starts on a twin
27- that already holds values with no waiver recorded, and refuses to start a column
28- migration while another is open on the same pair.
29- ` ColumnMigration.confirmDualWrites ` records the waiver, and refuses it once a
30- forced pass has started. The ` stash ` CLI adds the flags (` --force ` ,
31- ` --confirm-plaintext-current ` ) and its own messages on top of these rules.
11+ column's contents, not about one run. It is therefore held once, on the column
12+ migration, as an obligation derived from the column migration's events. An
13+ obligation opens when a forced pass starts (in either direction) or when a
14+ reverse column migration begins on a twin that already holds values. It closes
15+ only when a forced pass completes, or, for the up-front reverse case, when the
16+ operator records a waiver asserting the existing values are current. A waiver
17+ cannot close the obligation of a forced pass that has already started, because
18+ by then the target column is partly overwritten. While an obligation is open,
19+ every run is a forced pass, whatever the caller passes. ` @cipherstash/migrate `
20+ enforces this rule itself, not the ` stash ` CLI, because customers embed
21+ ` runBackfill ` and ` runDecryptBackfill ` in their own workers and would otherwise
22+ bypass it.
23+
24+ #1193 first enforced an open obligation in the reverse direction, in
25+ ` runDecryptBackfill ` . #1276 (the first part of #1217 ) moved the decision into
26+ ` ColumnMigration ` for both directions. ` runBackfill ` and ` runDecryptBackfill `
27+ plan every run through it, so in both directions it forces a run while an
28+ obligation is open, forces a reverse run that starts on a twin that already
29+ holds values with no waiver recorded, and refuses to start a column migration
30+ while another is open on the same pair. ` ColumnMigration.confirmDualWrites `
31+ records the waiver, and refuses it once a forced pass has started. The ` stash `
32+ CLI adds the flags (` --force ` , ` --confirm-plaintext-current ` ) and its own
33+ messages on top of these rules.
3234
3335## Considered options
3436
@@ -51,12 +53,13 @@ forced pass has started. The `stash` CLI adds the flags (`--force`,
5153- Every backfill event in ` cs_migrations ` (started, checkpoint, completed and
5254 error) records the pass mode as ` details.force ` , in both directions. The
5355 dual-write confirmation and drop events do not. The obligation has no events
54- of its own: ` ColumnMigration `
55- derives it from the event trail. A dual-write confirmation with
56- ` details.existingTwinValues ` and no ` details.waiver ` opens the up-front
57- obligation, and a later confirmation with ` details.waiver ` closes it. A forced
58- pass's running events open the forced-pass obligation, and its completion
59- closes it. Events written before #1276 record the waiver choice as
60- ` details.acknowledgedWith ` and ` force ` on ` backfill_started ` only, and
61- ` ColumnMigration ` still reads them. The shape of ` details ` is effectively
62- public, so changes to it go in a changeset.
56+ of its own: ` ColumnMigration ` derives it from the event trail. A dual-write
57+ confirmation with ` details.existingTwinValues ` and no ` details.waiver ` opens
58+ the up-front obligation, and a later confirmation with ` details.waiver `
59+ closes it. A forced pass's running events open the forced-pass obligation,
60+ and its completion closes it. Events written before #1276 differ, and
61+ ` ColumnMigration ` still reads them: they record ` force: true ` on a forced
62+ pass only, on ` backfill_started ` alone in the forward direction and on every
63+ event in the reverse direction, and they record the up-front choice as
64+ ` details.acknowledgedWith ` . The shape of ` details ` is effectively public, so
65+ changes to it go in a changeset.
0 commit comments