How do you migrate airframe sign-off from a role column to relation tuples while both stay authoritative, and what tells you to cut over?

## Why this is not a data migration A role column answers *what is this person*. Relation tuples answer *what path exists between this person and this object*. Those are different questions, and a script that turns each role row into a tuple produces a store that agrees with the column on the cases the column could already express and is silent on everything else — which is, generally, the reason you are moving. So the migration has two halves that must not be confused: **reproducing today's behaviour exactly**, which is the risky part and the one you must prove, and **expressing the rules the column could never hold**, which is new design and should be built only after the first half is proven. Doing both at once means every disagreement is ambiguous: you cannot tell a migration bug from an intended improvement. ## The sequence 1. **Write the schema and prove expressiveness on paper.** Enumerate every rule the current system enforces, including the ones that are not in the table at all — the chief-inspector branch in a service method, the organisation check on the endpoint, the special case for a component under quarantine. Each becomes a relation, a rewrite, or an explicit decision to stop supporting it. 2. **Dual-write.** Every domain event that grants or removes authority writes both stores. Decide the order and the partial-failure behaviour deliberately: write the authoritative store first for a grant so a crash under-grants, and write the *non*-authoritative store first for a revocation so a crash leaves the subject revoked somewhere rather than nowhere. Reconcile asynchronously. 3. **Backfill.** Convert existing state to tuples in one pass, recording the version the backfill reached so you can tell later disagreements from backfill gaps. 4. **Shadow-read.** On every real request, run the tuple check alongside the column decision, return the column's answer, and record disagreements with subject, object, relation and both verdicts. This is the only step that actually produces evidence. 5. **Cut over narrowly.** One relation, or one endpoint, at a time, with the column still written and readable. 6. **Stop writing the column,** then remove it. ## Reading the disagreement log | direction | what it means | how to treat it | |---|---|---| | tuples allow, column denied | the tuple schema grants more widely than today | a security finding, even in shadow mode — you are about to enforce it | | tuples deny, column allowed | a fact was never backfilled, or a rule is missing from the schema | a correctness bug, and the common one early on | | both allow or both deny | agreement | the only thing that may be counted as progress | The first row is the one teams under-react to, because in shadow mode nothing bad happens. But the over-grant direction is exactly what you will ship on cutover day, and a single over-broad rewrite can grant a whole organisation sign-off authority over airframes it does not hold. ## How long to shadow Long enough to see the rules that fire rarely. A maintenance organisation's year contains annual inspections, airworthiness reviews, custody transfers and audits; a rule that only fires during an annual check will not appear in a week of traffic, and the first time it appears will be in production with the tuple store authoritative. A full business cycle is the honest answer, and where that is genuinely too long, the compromise is to enumerate the rare paths and exercise them deliberately rather than to wait less. ## What cutover actually costs On the day you stop consulting the column, three things change at once: - authorization acquires a **network dependency** on the request path, with its own tail latency and its own outages; - a wrong answer is now produced by a **schema rule** rather than by a row someone can read, so the skill needed to debug a denial changes; - **revocation semantics** change, because the store serves reads at a chosen freshness rather than from the same transaction as your application data. Those are the reasons to cut over by relation rather than in one step, and to keep the column readable for a while afterwards. ## What you keep permanently Keep a low-rate sampled comparison running after cutover, against whatever remains of the old rules or against a hand-maintained expectation set. The failure mode this migration has eighteen months later is not a crash — it is a rewrite added for one customer that quietly widened a relation, and the only thing that catches it is something that keeps checking the answer against an independent expectation. That sampler is the cheapest insurance in the whole project, and it is the first thing teams delete.