driver-sql: the MySQL hash-shadow arm still takes the boot down on a PLAIN unique over duplicate rows — the same guard #14902 moved on the direct arm

[zhuangjianguo]

Found while implementing #14902 (PR #15477), which brought the DIRECT arm of syncDeclaredIndexes's catch to parity: a plain unique index over existing duplicate rows now logs on the durability channel and lets the boot continue, instead of throwing the database's raw error. The hash-shadow arm, one branch above it in the same catch, still carries the guard that was moved.

⚠️ Derived by reading the code, not measured — see "Why this was not fixed in #15477" below. Treat the reachability claim as an argument, not a reading, until someone drives it on a live MySQL.

Where

packages/drivers/driver-sql/src/sql-driver.ts, inside syncDeclaredIndexes, in the if (unkeyable) block that handles MySQL's refusal of a TEXT/BLOB key part (#11627's hash-shadow route, made NULL-safe-aware by #12998):

} catch (shadowErr: any) {
  ...
  if (nullSafe.size > 0 && isUniqueViolationError(shadowErr)) {
    // …log at `error`, name the conflicting groups, continue…
  }
  // falls through to the named refusal, which THROWS

The sibling direct arm below it no longer asks nullSafe.size > 0 — it asks unique && isUniqueViolationError(e) — so the two arms of the same catch now disagree about the same question.

The shape

On MySQL, a plain unique index (tenancy: { enabled: false }, or an explicit unique: 'global') over a column whose declared width exceeds the keyable ceiling takes the shadow route. The shadow ALTER computes the generated column for the EXISTING rows, so a table that already holds duplicates fails there with a uniqueness violation. With nullSafe.size at zero the branch does not fire, the code falls through to logDurabilityFailure(unkeyable, msg) and then throw, and the boot dies — carrying a message about an unkeyable text column rather than about the duplicate rows, so it names neither the conflicting rows nor a remedy.

That is exactly the shape #14902 graded p1 on the direct arm, minus the os migrate plan half: the D4 pre-flight fix in #15477 is guard-free, so os migrate plan already reports this op destructive with the row report. What is left is only the fatal, unactionable boot.

Why this was not fixed in #15477

The branch is reachable only on a live MySQL with a key part over the 768-char ceiling. This package's unit suite boots SQLite only; the hash-shadow tests (sql-driver-11627-hash-shadow-key.test.ts, sql-driver-12998-shadow-null-safe-key.test.ts) are opt-in live cells behind OS_TEST_MYSQL_URL, and the dispatch container has no MySQL. Shipping an unmeasurable change to a durability path is worse than a named gap, so the gap is named here instead.

The change itself looks mechanical — the correct form is fixed by the sibling arm — but it is not only a guard deletion: the branch's message says "existing rows violate the NULL-safe key (duplicates the previous void constraint admitted, #5030)", and neither clause is true of a plain unique. Nothing admitted those rows; the constraint is simply newly declared over data that does not satisfy it. So the message needs the same two-arm split #15477 gave the direct path.

Suggested shape (engine lane's call)

Take the guard to isUniqueViolationError(shadowErr) — the enclosing if (unique) already supplies the uniqueness limb — and branch the message the way the direct arm does. Verify on a live MySQL cell (declareDialectCell(MYSQL_CELL, …)) with a maxLength over the keyable ceiling and two duplicate rows: the boot must survive, the durability log must name the conflicting group and the remedy, and the index must be absent afterwards.

Refs: #14902, PR #15477, #11627, #12998, #5030, ADR-0120 D4.

[zhuangjianguo]

Attribution note, because the signature footer written into this card's body did not survive the create path (measured: the body reads back from the API ending at Refs: …, with the rule line and the footer both gone — ⛔ not re-posted in a loop, recorded here once instead).

Filed by the domain:engine execution seat working #14902 — session session_01ARYe3yQTQCUFm5qPYNgKaJ, branch claude/issue-14902-plain-unique-index-duplicate-preflight, PR #15477. Unassigned and unlabelled on purpose: this is a report for triage, not a decision taken.

---

Generated by Claude Code

[os-zhuang]

分诊 · domain:engine / priority:p2 / pm:queue

Anchor read, not guessed. packages/drivers/driver-sql/src/sql-driver.ts ⇒ domain:engine (the drivers lane).

Re-measured on origin/main f1d7872 (2026-09-04T23:56:33Z) — and the asymmetry is exactly as reported:

arm	guard	on a plain unique over duplicates
hash-shadow, :11865	if (nullSafe.size > 0 && isUniqueViolationError(shadowErr))	⛔ does not fire → falls through to logDurabilityFailure(unkeyable, msg) + throw
direct, :11919	if (nullSafe.size > 0 && isUniqueViolationError(e))	the NULL-safe case, continue
direct, :11933	if (unique && isUniqueViolationError(e))	⭐ #14902's repair — logs, names the groups, continue

⇒ The direct path now has two branches (NULL-safe, then plain unique); the shadow path has one. The two arms of the same catch genuinely disagree about the same question, and :11933's own comment describes precisely the behaviour the shadow arm still has: "It used to fall through to throw e, so the boot DIED carrying the database's own error, which names the index and the column and NO rows and NO remedy."

⚠️ Method note, since it nearly bit me: this repo's checked-out worktree here is ~11 hours behind origin/main, and reading the region by line number from the worktree lands in a different function. Every line number above is from git show origin/main:…. Re-derive at pickup; sql-driver.ts moves daily.

Grade — p2, deliberately not p1, and the reason is falsifiable

Parity with #14902 would argue p1: same file, same catch, same failure shape — a dead boot carrying a message about an unkeyable text column while the actual cause is duplicate rows, naming neither the conflicting rows nor a remedy.

⛔ I am not grading on parity, because the card itself says the reachability is derived, not measured:

⚠️ Derived by reading the code, not measured … Treat the reachability claim as an argument, not a reading, until someone drives it on a live MySQL.

That honesty is the right call and it should not be quietly upgraded away by triage. Two further facts hold it at p2: the branch needs a live MySQL and a key part over the 768-char ceiling and pre-existing duplicates — a narrow conjunction; and the os migrate plan half is already guard-free (the D4 pre-flight fix in PR #15477), so an operator running it gets the destructive verdict and the row report today. What is left is the fatal, unactionable boot — bad, but not silent and not undiagnosable.

⭐ Promotion rule, stated so the grade is not a permanent ceiling: if anyone drives this on a live MySQL cell and it reproduces, it is p1 by parity with #14902, with no further argument needed. The drive is the first deliverable either way, so the promotion is cheap to trigger.

Boundary test — Bug, no manual floor

Taking the guard to isUniqueViolationError(shadowErr) restores the disposition the sibling arm already ships. Nothing widens; a boot that currently dies would survive with a named durability log, which is the declared contract for this class (ADR-0120 D4).

⛔ The trap: this is not a guard deletion, and the card is right to say so twice

the branch's message says "existing rows violate the NULL-safe key (duplicates the previous void constraint admitted, #5030)", and neither clause is true of a plain unique. Nothing admitted those rows; the constraint is simply newly declared over data that does not satisfy it.

⇒ A one-character fix that widens the guard and leaves the message ships a factually false durability log on the new path — which is worse than the current throw, because the operator would be sent hunting for a NULL-distinct index that was never there and an #5030 defect that did not occur. The message needs the same two-arm split #15477 gave the direct path. Copy :11933's wording, do not paraphrase it: the direct arm has already been through review on exactly this sentence.

Why this does not go to pm:blocked

The card explains why #15477 could not carry it — this package's unit suite boots SQLite only, the hash-shadow tests (sql-driver-11627-hash-shadow-key.test.ts, sql-driver-12998-shadow-null-safe-key.test.ts) are opt-in live cells behind OS_TEST_MYSQL_URL, and the dispatch container has no MySQL. ⚠️ That is an environment constraint on whoever takes it, not a dependency on another card, so it is pm:queue and not pm:blocked — but it is a real dispatch constraint and the seat should honour it:

⛔ Do not dispatch this to an executor without a live MySQL cell. The card's own reason for filing rather than fixing was that "shipping an unmeasurable change to a durability path is worse than a named gap", and that reasoning binds the next attempt exactly as much as it bound the first. The acceptance criteria are already written on the card and should be copied into the dispatch verbatim: declareDialectCell(MYSQL_CELL, …) with a maxLength over the keyable ceiling and two duplicate rows — the boot must survive, the durability log must name the conflicting group and the remedy, and the index must be absent afterwards.

⭐ Endorsed for the record: filing a named gap instead of shipping an unverifiable durability change is the behaviour this repo should keep making cheap. This routing exists so it stays cheap.

⛔ Not a claim, not a dispatch — routing only.

---

Generated by Claude Code