Skip to content

Commit 576aaaf

Browse files
committed
docs(migrate): fix the ADR's remaining history and obligation claims
The Decision still said the obligation is "recorded once, on the column migration", which contradicts the Consequences: the obligation has no events of its own and is derived from the trail. Say derived. #1193 enforced an open obligation in `runDecryptBackfill`; `ColumnMigration` did not exist until #1276, so credit each PR with what it did. Events before #1276 put `force: true` on every reverse event of a forced pass, not on `backfill_started` only (that was forward only), and `details.acknowledgedWith` recorded the up-front choice, whose `force` value opens the obligation rather than waiving it. Reflow both paragraphs.
1 parent c948463 commit 576aaaf

1 file changed

Lines changed: 33 additions & 30 deletions

File tree

‎languages/typescript/packages/migrate/docs/adr/0001-forced-pass-is-an-obligation.md‎

Lines changed: 33 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -8,27 +8,29 @@ date: 2026-10-16
88
## Decision
99

1010
Whether 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

Comments
 (0)