Filed unassigned from the dev seat that implemented #8725 (PR #11031). Recording a documentation/governance drift, not proposing an edit: docs/adr/ is a governed surface and this seat does not touch it.
The observation
ADR-0120 D4 (around line 344, and its summary row around line 38) decides:
os migrate plan gains a duplicate pre-flight probe per affected index
That sentence was written for the declared index class — the recreate_index drift ops the reconciler can see — and it is true there: os migrate plan reports a blocked tightening of a declared organization-unique index in full, quoting the offending group and row count. Measured.
There is a second class D4's mechanism cannot reach. Three kernel:ready migrations in packages/metadata-protocol tighten an index at runtime (ensureMetadataOverlayIndexes on sys_metadata, ensureViewDefinitionActiveIndex on sys_view_definition, ensureSysSettingIdentityIndex on sys_setting), and every one of them is invisible to the drift differ by construction:
- after the tightening,
isRuntimeManagedIndex excludes the index — isSyncReproducibleIndex is false for a partial index and for a COALESCE key part over a non-tenant column. That exclusion is correct; without it a boot would propose rebuilding away the guarantee it just created. - before it, there is nothing to see either: each migration deliberately reuses the DECLARED index's name, so the name-matched slot reads as filled whichever physical form is physically there.
Maintainer ruling 2026-08-22 on #8725 routes that class to os migrate duplicates instead, explicitly keeping os migrate plan's drift contract untouched.
Why it is worth recording
Each of the three migration modules states D4's five-element disposition in its own doc comments, and one element of that disposition is where to send the operator. After PR #11031 those comments cite D4 while naming os migrate duplicates. That is accurate about behaviour and inaccurate about D4's text, so the two now disagree in a place a later author will read as an error in the code rather than a split in the decision.
What an amendment would say, if the maintainer wants one
That D4's pre-flight is per class: declared, differ-visible indexes report through os migrate plan; runtime-managed indexes the differ excludes by construction report through os migrate duplicates, which boots read-only and owns the "inventory, never repair" contract.
Not claimed: no defect, no user-facing gap, and nothing blocked. ADR-0120 Route 2 (NULL-safe uniqueness declared in the spec, deferred to v18) would retire all three runtime migrations and take this split with them.
Filed unassigned from the dev seat that implemented #8725 (PR #11031). Recording a documentation/governance drift, not proposing an edit:
docs/adr/is a governed surface and this seat does not touch it.The observation
ADR-0120 D4 (around line 344, and its summary row around line 38) decides:
That sentence was written for the declared index class — the
recreate_indexdrift ops the reconciler can see — and it is true there:os migrate planreports a blocked tightening of a declared organization-unique index in full, quoting the offending group and row count. Measured.There is a second class D4's mechanism cannot reach. Three
kernel:readymigrations inpackages/metadata-protocoltighten an index at runtime (ensureMetadataOverlayIndexesonsys_metadata,ensureViewDefinitionActiveIndexonsys_view_definition,ensureSysSettingIdentityIndexonsys_setting), and every one of them is invisible to the drift differ by construction:isRuntimeManagedIndexexcludes the index —isSyncReproducibleIndexis false for a partial index and for aCOALESCEkey part over a non-tenant column. That exclusion is correct; without it a boot would propose rebuilding away the guarantee it just created.Maintainer ruling 2026-08-22 on #8725 routes that class to
os migrate duplicatesinstead, explicitly keepingos migrate plan's drift contract untouched.Why it is worth recording
Each of the three migration modules states D4's five-element disposition in its own doc comments, and one element of that disposition is where to send the operator. After PR #11031 those comments cite D4 while naming
os migrate duplicates. That is accurate about behaviour and inaccurate about D4's text, so the two now disagree in a place a later author will read as an error in the code rather than a split in the decision.What an amendment would say, if the maintainer wants one
That D4's pre-flight is per class: declared, differ-visible indexes report through
os migrate plan; runtime-managed indexes the differ excludes by construction report throughos migrate duplicates, which boots read-only and owns the "inventory, never repair" contract.Not claimed: no defect, no user-facing gap, and nothing blocked. ADR-0120 Route 2 (NULL-safe uniqueness declared in the spec, deferred to v18) would retire all three runtime migrations and take this split with them.