Skip to content

docs(migrate): add the migrate glossary and the forced-pass obligation ADR - #1220

Draft
tobyhede wants to merge 1 commit into
mainfrom
docs/migrate-context-and-adr
Draft

tobyhede wants to merge 1 commit into
mainfrom
docs/migrate-context-and-adr

Conversation

@tobyhede

Copy link
Copy Markdown
Contributor

Summary

@cipherstash/migrate moves an existing database column between plaintext and encrypted form, tracking each step in a cs_migrations table so an interrupted move can resume. The review of #1193 (the reverse, decrypt direction) kept reopening one question: may an interrupted --force backfill continue without --force? The answer was being worked out separately in each command. This PR writes down the shared vocabulary and the decision agreed for the follow-up design in #1217, so that future PRs argue from the same terms.

Changes

  • Glossary: languages/typescript/packages/migrate/CONTEXT.md defines column migration, direction, source and target column, twin, phase, dual-writing, abort, rollout, backfill pass, run, forced pass, obligation and waiver. Each entry lists the words to avoid.
  • ADR: languages/typescript/packages/migrate/docs/adr/0001-forced-pass-is-an-obligation.md. A forced pass is an obligation recorded on the column migration, and @cipherstash/migrate enforces it for every caller. While the obligation is open, every run is forced. Only a completed forced pass or, in the up-front reverse case, a recorded waiver closes it. At most one column migration is open per column pair.
  • Context map: CONTEXT-MAP.md lists the new Migrate context.

Verification

Documentation only. The new files are outside the package's files list, so nothing reaches the npm tarball and no changeset is needed.

Related

Refs #1217, #1193

Review notes

Some terms (reverse direction, waiver) describe behaviour that arrives with #1193 and #1217, so this is best merged after #1193.

…n ADR

The review of #1193 kept reopening the same question: whether a forced
backfill pass may resume without force. The rule was being worked out per
run and per command. This records the vocabulary agreed for the follow-up
design in #1217 (column migration, direction, twin, backfill pass, run,
obligation, waiver, abort) and the decision that a forced pass is an
obligation on the column migration, enforced by @cipherstash/migrate for
every caller, CLI or embedded worker.

Refs #1217
@changeset-bot

changeset-bot Bot commented Oct 15, 2026

Copy link
Copy Markdown

⚠️ No Changeset found

Latest commit: a8dcf3e

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@coderabbitai

coderabbitai Bot commented Oct 15, 2026

Copy link
Copy Markdown
Contributor

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

  • Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Comment @coderabbitai help to get the list of available commands.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant