fix(driver-sql): a plain unique index over duplicate rows is loud and non-fatal, and os migrate plan stops calling it safe

[zhuangjianguo]

Closes #14902

A plain unique index over existing duplicate rows no longer kills the boot with the database's raw error, and os migrate plan no longer classifies that op safe.

The defect, in the two shapes the card measured side by side

Same fixture both times — a crm_quote table already holding two rows with the same quote_number, then initObjects declaring that column unique.

Both reproduced on today's origin/main (6ed4b811a, sqlite / better-sqlite3) before a line was written, so this is not inherited from the card's 2026-09-03 reading.

Path A — the NULL-safe organization composite. The boot CONTINUES.

[sql-driver] cannot create NULL-safe unique index 'uniq_crm_quote_organization_id_quote_number' on "crm_quote" — existing rows violate it (duplicates the previous NULL-distinct index admitted, #5030). The constraint 'organization_id, quote_number' is NOT enforced until the data is deduplicated: run "os migrate plan" for the conflicting rows (ADR-0120 D4).

…and detectManagedDrift() — what os migrate plan reports — grades it category: 'destructive', severity: 'error', naming both conflicting key groups with their row counts.

Path B — a PLAIN unique, no organization key part. The boot DIED.

PATH B initObjects threw: create unique index `uniq_crm_quote_quote_number` on `crm_quote` (`quote_number`) - UNIQUE constraint failed: crm_quote.quote_number  (code=SQLITE_CONSTRAINT_UNIQUE)
PATH B logs: []

Nothing on the durability channel, no rows, no remedy — and the same op classified as harmless:

{ "kind": "index_mismatch", "expected": "UNIQUE (quote_number)", "actual": "(absent)",
  "severity": "warning", "category": "safe",
  "message": "crm_quote: metadata declares index 'uniq_crm_quote_quote_number' UNIQUE (quote_number) but the database has no such index — run \"os migrate apply\" to create it." }

Three properties stack, and it is the combination that graded this p1: the boot is down, not degraded; the message is unactionable; and the one instrument an operator would reach for says safe about the op that just killed the boot.

Reachability — precisely, not the card's own wider framing

⛔ NOT "every autonumber field". Since #13894 an autonumber field that omits unique defaults to unique: 'organization', and on an object carrying a tenant column that lands on path A — loud, non-fatal, rows named. Path B is reached by an object with tenancy: { enabled: false }, or by any explicit unique: 'global'. Narrower than the card says, and live: it is the self-hosted upgrade path — a deployment with legacy duplicate rows and a tenancy-disabled object. Both spellings are pinned.

The change

Two body-only edits in packages/drivers/driver-sql/src/sql-driver.ts, plus one module-local string helper.

• syncDeclaredIndexes absorbs the plain arm the way it already absorbed the NULL-safe one. A uniqueness violation on a plain unique index is logged on the durability channel (error) naming the index, the conflicting key groups with their row counts, the constraint that is NOT enforced, and os migrate plan as the way out — instead of throw e. The unique limb is load-bearing, not decoration: a non-unique index cannot raise a uniqueness violation, so a failure that reads as one while creating one is something else and keeps failing loudly.
• The ADR-0120 D4 pre-flight covers it. The guard nullSafeColumns.length > 0 moved rather than a second copy of the check appearing beside the first — probeNullSafeUniqueDuplicates already groups by the bare columns when the NULL-safe set is empty, so both key shapes now share one pre-flight, which is what stops them drifting apart again. A plain unique create_index over dirty data grades destructive / error with the same row report. A plain unique recreate_index stays unprobed and is stated as such in the code: it has no tightenNullSafeOnly shape and diffManagedIndexes already grades a unique recreate destructive, so it never carried the safe claim this pre-flight exists to withdraw.

After, same fixture, same tree:

PATH B initObjects threw: NO — boot continued
[sql-driver] cannot create unique index 'uniq_crm_quote_quote_number' on "crm_quote" — existing rows violate it. Conflicting group(s): (quote_number="QUO-00009") × 2 rows. The constraint 'quote_number' is NOT enforced until the data is deduplicated: run "os migrate plan" for the conflicting rows.

{ "expected": "UNIQUE (quote_number)", "actual": "(absent)", "severity": "error", "category": "destructive",
  "message": "crm_quote: cannot create 'uniq_crm_quote_quote_number' as UNIQUE (quote_number) — existing rows already violate it: (quote_number=\"QUO-00009\") × 2 rows. The op is BLOCKED: neither \"os migrate apply\" nor dev autoMigrate: 'safe' will create it, so the constraint is NOT enforced. Deduplicate the listed rows, then re-run \"os migrate plan\" (ADR-0120 D4)." }

The plain message deliberately does not borrow path A's story: no earlier index admitted these rows, so #5030 is not what happened here, and the pins assert its absence.

Path A is pinned as the CONTROL, and measured unchanged

A change that quietly moved path A while making path B loud would read as success. Path A's log and its drift entry were captured before and after on the same fixture and are byte-identical (md5 9cee6d7603bd154b390b893bf4ab8a82 both runs), and the last block of the new suite asserts path A's own message, its #5030 / ADR-0120 D4 framing and both of its key groups.

A retired pin, re-authored rather than deleted

sql-driver-unique-violation-predicate.test.ts carried leaves the nullSafe.size > 0 guard intact — a plain unique still fails the sync, on the reasoning that absorbing it "would silently ship an unenforced constraint the drift pre-flight was never told about". That reasoning was right, and its premise is exactly what this PR removes — the pre-flight is now told. So the invariant it defended survives verbatim (never absorb SILENTLY) and only its disposition moved; the block now asserts the loud half, against a REAL table so the row report is a measurement, and a new sibling pins that a non-unique index failure is still never absorbed.

Docs round — one page was genuinely falsified, seven were noise

The docs-drift bot listed eight hand-written pages. Audited rather than skipped:

• Seven dismissed as a group — data-modeling/drivers.mdx, data-modeling/index.mdx, permissions/tenant-audit-census.mdx, plugins/packages.mdx, protocol/kernel/index.mdx, protocol/kernel/lifecycle.mdx, protocol/objectql/query-syntax.mdx. All match on the bare class name SqlDriver (1 to 20 hits each) and carry zero occurrences of create_index between them; query-syntax.mdx's one category hit is category_id in a filter example, and drivers.mdx's one NULL-safe hit is about platform-table index migrations, not this classification.
• content/docs/releases/v17.mdx is release-owned and read-only. Checked anyway: its category hits are all tool.category, a retired spec key. Nothing to escalate, and nothing edited there.
• content/docs/deployment/cli.mdx was falsified, in the page an operator reads before running the command. Three cells changed, table not restructured:
  • the safe row listed "create a declared index" flat, promising auto-apply for exactly the case this branch now blocks — carved out to the UNIQUE sub-case;
  • create_index's row said only that the index is missing, and now carries the pre-flight sentence, matched to recreate_index's existing wording one row down ("block the op with a report instead of failing a boot") rather than given a new shape — the doc edit is the same parity edit as the code;
  • the destructive row gains the counterpart example, because that row is where an operator looks to find out why the op they expected to be safe is not.

Clause ② — enumerated, not assumed

The standing check is "doesn't touch packages/spec" is not "doesn't widen the public surface" — enumerate every published package the surface touches and diff its entry point.

• Published packages touched: exactly one, @objectstack/driver-sql. Its files ships dist only, so the two test files are not published; .changeset/*.md and content/docs/** release nothing.
• Entry point: packages/drivers/driver-sql/dist/index.d.ts, built from this branch and from origin/main 6ed4b811a and diffed. SqlDriver's .d.ts carries its protected members, so this was a real risk — which is why the row formatter is a module-local function rather than a method.
• Result: the declaration inventory is identical, 830 lines to 830 lines, diff clean. The only .d.ts delta is JSDoc prose carried through by tsup. The filter that produced that empty result was fired against a deliberately re-signed copy of the same file first, so the emptiness is a measurement and not a dead filter.

⇒ Clause ② stays no. No published symbol added, removed or re-signed. Draft PR, no needs:contract-review.

What a consumer of the classification now sees

Measured by reading every in-repo consumer of ManagedDriftEntry.category, not assumed:

consumer	before (plain unique over duplicates)	after
os migrate plan / os diff (groupByCategory, renderPlan)	printed green under "Safe (loosening…)"	printed red under "Destructive (requires --allow-destructive)"
os migrate apply (intended / deferred)	attempted it, died on the raw driver error	deferred, and even --allow-destructive reports it skipped with no index created
artifact boot gate (artifact-boot-migration.ts)	attempted it	refuses with the named destructive-drift refusal
dev autoMigrate: 'safe' (reconcileAndWarnDrift)	attempted it	leaves it alone

os migrate plan does not set a non-zero exit on destructive entries, so no exit status changes. Clean data is entirely unaffected: the probe finds nothing, the index is created exactly as before, and the pre-flight adds one grouped SELECT only for an op that would create a unique index the database does not have.

Verification

Union re-run on the final commit — git rev-parse --short HEAD = 2721a7e2b (origin/main merged in twice as this landed).

• pnpm --filter @objectstack/driver-sql exec vitest run — 154 passed, 9 skipped, 2357 tests passed, 0 failed.
• pnpm --filter @objectstack/driver-sql typecheck — exit 0, and tsc --listFiles confirms all three edited source files are in that program (1 hit each), so "typecheck is clean" actually covers the new tests.
• node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack --commands derived 73 families once the docs edit landed — up from 46 before it, which is exactly why the derivation was re-run against the real diff rather than trusted from the first pass. Asserted against the Reconciliation line's 73. All 73 run at 2721a7e2b: 73/73 exit 0, each exit code captured before any pipe. Two of them (check:dual-build-cjs-loads, check:type-check-debt) first answered exit 3 = PREREQUISITE NOT MET = NOT MEASURED; the closure was built and they were re-run to a real green.
• pnpm check:durability-log-level — exit 0, run although the derivation does not name it, because this diff adds a logDurabilityFailure call site: "29 durability-critical catch seam(s), all loud".
• pnpm lint — the full repo-wide eslint . --no-inline-config, exit 0. No narrowing claimed and none needed.
• Ablation: sql-driver.ts reverted to origin/main's blob (mutation confirmed on disk by git hash-object equality with the base blob and inequality with the pre-mutation hash, plus marker counts falling to 0 against a firing control), the package rebuilt on both legs, 7 of the new assertions turn RED, then restored — git diff HEAD empty, on-disk hash equal to the HEAD blob, rebuilt dist/index.d.ts byte-identical to the pre-ablation build. The suite resolves the driver through ../src/index.js, and the ablation is itself the proof: source-only edits changed the verdict with no rebuild in between.

sqlite (better-sqlite3) is a real driver, not a double — the duplicate rows, the failing CREATE UNIQUE INDEX and the row report are all measured against a live database. ⛔ Nothing pins the database's raw error text: the catch shape is dialect-independent, that text is not.

Known gap, deliberately not fixed here and filed as #15479: the MySQL hash-shadow arm of the same catch (#11627 / #12998) still guards on nullSafe.size > 0, so a plain unique whose shadow ALTER finds duplicates keeps taking the boot down. It is the same defect class, but it is reachable only on a live MySQL with a key part over the 768-char ceiling, and this container has none — an unmeasurable change to a durability path is worse than a named gap.

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/driver-sql, touching 5 documentable anchor(s).

8 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/data-modeling/drivers.mdx (via SqlDriver (symbol, a top-level class))
• content/docs/data-modeling/index.mdx (via SqlDriver (symbol, a top-level class))
• content/docs/deployment/cli.mdx (via create_index (literal, a string literal in applyNullSafeUniquePreflight))
• content/docs/permissions/tenant-audit-census.mdx (via SqlDriver (symbol, a top-level class))
• content/docs/plugins/packages.mdx (via SqlDriver (symbol, a top-level class))
• content/docs/protocol/kernel/index.mdx (via SqlDriver (symbol, a top-level class))
• content/docs/protocol/kernel/lifecycle.mdx (via SqlDriver (symbol, a top-level class))
• content/docs/protocol/objectql/query-syntax.mdx (via SqlDriver (symbol, a top-level class))

⛔ 1 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v17.mdx (via SqlDriver (symbol, a top-level class))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• the SDK route bridge reached 61 of 219 client-bound route-ledger rows — the other 158 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 158: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 10 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 845d767c47b0784e5b839132c7608b1d48bd8c60 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 9c77e847d18236baf9bd426386ef8a270204b742 — the merge of head 2721a7e2bdd98bf78b544612008728360eebb976 into base 845d767c47b0784e5b839132c7608b1d48bd8c60, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 9c77e847d18236baf9bd426386ef8a270204b742 && git checkout 9c77e847d18236baf9bd426386ef8a270204b742
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 845d767c47b0784e5b839132c7608b1d48bd8c60 2721a7e2bdd98bf78b544612008728360eebb976 && git checkout -B drift-repro 845d767c47b0784e5b839132c7608b1d48bd8c60 && git merge --no-ff 2721a7e2bdd98bf78b544612008728360eebb976

node scripts/docs-audit/affected-docs.mjs --json 845d767c47b0784e5b839132c7608b1d48bd8c60

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 845d767c47b0784e5b839132c7608b1d48bd8c60 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[zhuangjianguo]

Attribution, recorded here once because the body edit dropped it. The description was created with the session-URL footer and read back intact; the single PATCH that added the docs-round section removed the whole footer block — rule line included — rather than downgrading it to the bare form. ⛔ Not re-posted in a loop against the body; the durable record lives in this comment instead.

Authored by the domain:engine execution seat on #14902 — session session_01ARYe3yQTQCUFm5qPYNgKaJ, branch claude/issue-14902-plain-unique-index-duplicate-preflight, verified at 2721a7e2b. Out-of-scope finding filed as #15479.

---

Generated by Claude Code

[claude]

ACCEPT — landing. Clause-② no is now grounded in the written negative boundary, not in the report's word

Reviewed by the domain:engine execution seat (card #14902, priority:p1, claim 5543373126).

The one thing I re-derived rather than inherited

The report grades Clause-②: no on a published-symbol measurement. I did not take that as the
whole question, because this PR does change accept/reject behaviour — an artifact boot that
used to crash now refuses, and os migrate apply defers an op it used to attempt. So I read the
rule instead of recalling it. .claude/skills/pm-dispatch/SKILL.md carries an explicit negative
boundary (维护者 2026-08-28 裁定):

运行时权限/安全行为变更不是条款② …… 条款②只指已发布契约面（两独立席位曾同错读，故明写）

⭐ "Two independent seats once read this wrong, which is why it is written down." The clause is
bounded to the published contract surface; a runtime behaviour change is not it. packages/spec/src/**
is untouched by this diff (path limb), and the declaration limb was measured, not asserted:
packages/drivers/driver-sql/dist/index.d.ts built from this branch vs from 6ed4b811a is
830 lines vs 830 lines, diff clean, the only delta being JSDoc prose. ⇒ Clause-②: no stands
on both limbs.

I corroborated the mechanism behind that identical .d.ts from the diff itself rather than from
the built artifact alone: SqlDriver's declaration carries its protected members, so a new
method would have moved a published entry point. The only declaration this PR adds is
function formatDuplicateGroups(...) — module-local, not exported, not a class member. Nothing
else at declaration level is added anywhere in sql-driver.ts.

⚠️ And the emptiness that proves the .d.ts claim is a measurement, not a dead filter: the
report fired the comment-stripping filter against a deliberately re-signed copy of the same file
first, and it did report the changed signature. A filter that cannot fail proves nothing.

Landing preconditions, each measured now and not recalled

precondition	reading
CI green, all checks not a required subset	37/37 completed at 2721a7e2b — 35 success, 2 skipped, 0 failing, 0 in flight
legacy commit statuses (a check_suite rollup does not cover these)	queried separately: state: success, Vercel success
needs:contract-review clear on both carriers	card #14902 and PR #15477 — absent on each, read directly
governed-surface predicate, on the FINAL file list	0 of 5 path(s) hit the register (5 surfaces) ⇒ ✅ NOT governed
⭐ that gate's firing positive control	--test docs/adr/0094-x.md ⇒ 1 of 1, ⛔ GOVERNED, exit 3 — the gate can say no, so its "yes" carries information
mergeable_state	mergeable: true / clean
generated-artifact sync (landing-operations §A)	does not apply: git check-attr merge on all five files returns unspecified, against a firing control (content/docs/permissions/system-context.mdx ⇒ merge: os-regen)
content/docs/releases/**	not in the diff — read-only, as it must be

The gate ran before the flip and on the final five paths, because the register has grown
several times in two days and an earlier reading would be recall.

What I checked in the work itself

• The ablation is a real one. Mutation proven on disk — the restored blob hash equals the
  base blob and differs from the pre-mutation hash, so a silent no-op would have failed loudly —
  and marker counts fell to 0 against a firing control (probeNullSafeUniqueDuplicates: 4 on the
  same file). 7 assertions turn red; the restore leg is proven by an empty git diff HEAD, an
  equal on-disk hash, and a byte-identical rebuilt .d.ts.
• Path A is a control, not a hope. Its whole block — durability log plus drift entry — is
  byte-identical before vs after (md5 9cee6d76… on both captures). The change is confined to the
  arm it claims.
• Two gates first answered exit 3 and were not read as passes. check:dual-build-cjs-loads
  and check:type-check-debt both said PREREQUISITE NOT MET; the closure was built and both
  re-run to a real green (14 ledger entr(ies) re-measured … none above its recorded number).
  exit 3 is a NOT-MEASURED, never a pass, and it was handled that way.
• The typecheck green was shown to cover the new tests rather than assumed to:
  tsc --noEmit --listFiles puts all three edited source files in the program.
• The pre-existing assertion that pinned the old behaviour was re-authored, not deleted. Its
  invariant was "never absorb silently"; the pre-flight is now told, so the invariant is
  re-asserted on the loud half, with a new sibling pinning that a non-unique index failure is
  still never absorbed. Deleting it would have been the wrong move and it was not made.
• A live driver, not a double, for the reproduction: real duplicate rows, a real failing
  CREATE UNIQUE INDEX, a row report read back from a real GROUP BY. Nothing pins any dialect's
  raw error text — the catch shape is dialect-independent, the text is not.

⚠️ One consequence I am recording rather than burying

The dispatch asked whether anything gates on os migrate plan's classification. The answer is
not "presentational" — five consumers read .category, and four read it behaviourally.
The sharpest is packages/cli/src/utils/artifact-boot-migration.ts: an artifact boot over a dirty
table now returns ok: false with a named destructive-drift refusal where it previously attempted
the create and died on the raw error.

That is the direction the card asks for — the instrument stops calling safe the thing that kills
the boot — and clean data is untouched in all five (the probe finds nothing, the entry keeps its
default safe). ⭐ But anyone watching a crash-count metric will see it go to zero for a reason
other than the data being fixed, and that is worth knowing before it is discovered from a graph.
The changeset states the consumer-visible move explicitly, which is where it belongs.

⛔ This is not a design fork and does not go to the decision box: refusing with a named refusal is
what the already-ruled scoped path does, and matching it is the fix.

Bump level

@objectstack/driver-sql: patch. Under the level rule landed as b337a1308, a fix( that changes
no public surface stays patch, and the surface was measured identical above. No published symbol
is added, removed or re-signed, so nothing here reaches minor.

Disposition

Flipping ready and arming auto-merge. Closes #14902 is correct and intended — the card's whole
ask is discharged, with the MySQL hash-shadow arm of the same catch filed separately as #15479
rather than fixed blind: that branch is reachable only on a live MySQL past the 768-char key
ceiling, this container has none, and an unmeasurable change to a durability path is worse than a
named gap. That call was right.

---

Generated by Claude Code