Summary
The ADR-002 upgrade path requires a two-hop deploy: an operator on a pre-#229 release
must first deploy the release containing the db:backfill-identity target, run the backfill,
and only then upgrade to a release with migration 0011 applied. There is no tag that names
the intermediate release, so the instruction cannot actually be followed as written.
The only tag in the repository is v0.1.0-rc.0 (2026-07-25), which postdates migration
0011. So the "deploy the previous release first" hop has nothing to point at.
Why it matters
Migration 0011 is destructive and unrecoverable: it drops users.email,
users.email_normalized and users.password_hash, and password hashes cannot be
reconstructed. CHANGELOG.md states there is no rollback after 0011 and that a backup taken
immediately beforehand is the only undo.
Worse, the step that the intermediate release exists to enable — the identity backfill — fails
silently if skipped. Existing users, including users whose email is verified, lose their
email and email_verified claims on token, refresh and userinfo responses. No error, no
migration failure; the claims simply stop being emitted.
So the one procedure where precise version pinning matters most is the one where we cannot
offer it. The best an operator can currently be told is a commit range, which is a poor
instrument for a production upgrade with no rollback.
Tasks
Acceptance Criteria
Additional Notes
Surfaced while writing the operator upgrade runbook: the runbook documents the commit range
and flags this gap on the page, because inventing a tag reference that does not exist would be
worse than admitting the limitation.
References
Summary
The ADR-002 upgrade path requires a two-hop deploy: an operator on a pre-#229 release
must first deploy the release containing the
db:backfill-identitytarget, run the backfill,and only then upgrade to a release with migration 0011 applied. There is no tag that names
the intermediate release, so the instruction cannot actually be followed as written.
The only tag in the repository is
v0.1.0-rc.0(2026-07-25), which postdates migration0011. So the "deploy the previous release first" hop has nothing to point at.
Why it matters
Migration 0011 is destructive and unrecoverable: it drops
users.email,users.email_normalizedandusers.password_hash, and password hashes cannot bereconstructed.
CHANGELOG.mdstates there is no rollback after 0011 and that a backup takenimmediately beforehand is the only undo.
Worse, the step that the intermediate release exists to enable — the identity backfill — fails
silently if skipped. Existing users, including users whose email is verified, lose their
emailandemail_verifiedclaims on token, refresh and userinfo responses. No error, nomigration failure; the claims simply stop being emitted.
So the one procedure where precise version pinning matters most is the one where we cannot
offer it. The best an operator can currently be told is a commit range, which is a poor
instrument for a production upgrade with no rollback.
Tasks
db:backfill-identitytarget and the feat: [T4] PasswordProvider + auth-engine refactor onto CredentialProvider (ADR-002, ADR-003) #228/feat: [T4] Trust-ordered email claim resolution — breaking change (ADR-002) #229dual-write behaviour, so the intermediate hop is nameable
CHANGELOG.md's ADR-002 entry and from the operator upgraderunbook, replacing the commit-range workaround
v0.1.0-rc.0should be documented as post-0011, so nobody reads it asa safe starting point for the two-hop path
Acceptance Criteria
<tag>, run the backfill, verify, then upgrade" usingreal tags rather than SHAs
Additional Notes
Surfaced while writing the operator upgrade runbook: the runbook documents the commit range
and flags this gap on the page, because inventing a tag reference that does not exist would be
worse than admitting the limitation.
References
CHANGELOG.md— the ADR-002 entry and its deploy-ordering requirements