fix(driver-sql): refuse a MySQL upsert whose named conflict target another unique key can absorb (#8755)

[hotlong]

Fixes#8755

Implements the maintainer ruling in comment 5299846509: option A (pre-flight refusal when a second unique key exists on the target table) plus option C's documentation half. Option B — probe-then-write / SELECT ... FOR UPDATE emulation — is not built and the comparison is not re-opened.

The condition, reproduced before it was fixed

Live MySQL 8.0.46 in this container, driven through the same knex + mysql2 path SqlDriver.upsert takes, both business columns unique: true so the named target email is backed and #8621's pre-flight passes it:

CREATE TABLE `probe_two_unique` (
`id` varchar(255) NOT NULL, `email` varchar(255) DEFAULT NULL,
`tax_id` varchar(255) DEFAULT NULL, `title` varchar(255) DEFAULT NULL,
PRIMARY KEY (`id`),
UNIQUE KEY `uniq_probe_two_unique_email` (`email`),
UNIQUE KEY `uniq_probe_two_unique_tax_id` (`tax_id`)
)
seed upsert({email:'a@b.com', tax_id:'T-1', title:'first'}, ['email']) -> RESOLVED
B upsert({email:'other@b.com', tax_id:'T-1', title:'second'}, ['email']) -> RESOLVED
rows = 1 [{email:'other@b.com', tax_id:'T-1', title:'second'}]
`email` did not collide; `tax_id` did, and MySQL merged on it.

One correction to the card's body, measured. It says the identical call on SQLite and Postgres "inserts a second row" — its own next clause says the opposite, and the measurement agrees with the next clause. Measured on SQLite through the same driver:

B upsert({email:'other@b.com', tax_id:'T-1', ...}, ['email'])
-> UNIQUE constraint failed: probe_two_unique.tax_id
rows = 1, still the seeded row, untouched.

The divergence is real and is exactly what the card is about — a silent wrong write on MySQL versus a legible error elsewhere — but the docs in this PR state the measured shape, not the "second row" one.

What changed

assertConflictTargetBacked is extended (renamed assertConflictTargetHonoured) rather than joined by a second introspection: same physicalKeyIndexes read, same cache, same invalidation, same stale-cache re-read before any refusal — now answering two questions off one index list instead of one. The call site, its MySQL-only gate and its position beforefillAutoNumberFields are unchanged, so a refusal still never burns an autonumber.

The refusal fires when, and only when: the caller named conflictKeys, the dialect is MySQL, the named target is backed, the named target is not the primary key, and a UNIQUE key exists whose columns differ from the target's.

The wording is its own, not a reuse of the unbacked refusal — #5240 is one condition, one wording, and this is a different condition; the unbacked sentence would tell an author to declare a unique: true they already declared. VALIDATION_ERROR / 400 rather than NOT_IMPLEMENTED / 501, by the #5907 classifier this file already applies twice: the refusal is conditional on the table (the same server merges the same statement fine once the table carries one unique key), not a capability gap in the backend. 400 also keeps the sentence on the wire, and the sentence is the deliverable the ruling asks for.

Cannot upsert into "os8621_wrong_key" on conflict keys ("email"): a UNIQUE key other than the
conflict target exists on "os8621_wrong_key" — uniq_os8621_wrong_key_tax_id(tax_id) — and this
backend is MySQL, whose only merge statement is ON DUPLICATE KEY UPDATE. That statement carries no
conflict target, so the merge lands on whichever UNIQUE key the row collides with FIRST: the
conflict target is backed, but a collision on uniq_os8621_wrong_key_tax_id(tax_id) would silently
merge a row the caller never targeted, across two different values of the named key. Fix by
dropping or renaming the extra UNIQUE key(s) so the conflict target is the only one on the table,
or by running this object on a dialect that honours the target — SQLite and PostgreSQL compile
ON CONFLICT (...), which merges on the named key alone. Upserting on the primary key is
unaffected: supply "id" and omit conflictKeys.

What is deliberately NOT refused

The PRIMARY KEY is never counted as a rival key, and a named primary key is never refused. Both are load-bearing, not oversights:

• Every table this driver creates carries an id PRIMARY KEY, so counting it would refuse everyconflictKeys upsert on MySQL — the ruling's "the single-key fast path stays untouched" would describe nothing — and the remedy the message states ("drop or rename the extra key") is not available for a primary key.
• upsert(o, row, ['id']) compiles byte-identically to the conflictKeys-less default that no pre-flight has ever probed, so refusing the explicit spelling while merging the implicit one would make the accept set a property of how the caller typed the same statement. It is also the only conflictKeys shape the platform itself issues (lifecycle-service.ts, the archiver's hot-to-cold copy), whose refusal would read "drop the unique constraint you declared on your own business column".

That residue is documented rather than silent — in the new docs section, in refuseAmbiguousConflictTarget's docblock, and as a pin. It is also filed as #8807, with its own measurement and options, so it is not lost.

Verification

Live MySQL 8.0.46 raised in the container (default_time_zone='+08:00', process TZ=America/New_York, so the D-B2 zone-skew guard is satisfied), plus the SQLite cell.

Both branches pinned as the ruling requires, on the live MySQL cell:

Pin	Assertion
two unique keys, named email	refused, VALIDATION_ERROR / 400, nothing written
the message	contains uniq_os8621_wrong_key_tax_id, tax_id, "email", the drop/rename workaround, the named alternative dialects, primary key is unaffected
payload contract	no row values in message or cause; rival keys on cause
single unique key, named email	still merges — the discriminating control
explicit ['id'], two unique keys	still merges (the documented residue)
#8622's identity pin	moved fixture to the default-path merge, assertion untouched

Reverse verification, direction predicted before running, both matched:

1. Ablation — delete the ambiguity arm: predicted exactly the three new [#8755] refusal pins red and every control green. Measured: 3 failed | 24 passed, the three being precisely those pins.
2. Ablation — count the PRIMARY KEY as a rival: predicted the refusal pins stay green while the merge pins go red. Measured: 4 failed | 23 passed — MERGES when a declared unique index does back the conflict target, accepts the primary key as an explicit conflict target, the single-unique-key control, and the PK fast path. The asymmetry between the two ablations is the evidence that the narrowing is narrow rather than blanket.

Both ablations were run against a committed fix and restored with git checkout of the branch's own copy of the file; git status clean afterwards.

Verified at 967916b05 (the tree of the final commit — both the test run and the gate union below were taken at this sha):

pnpm --filter @objectstack/driver-sql typecheck -> clean
pnpm --filter @objectstack/driver-sql test -> 100 passed | 1 skipped (101 files)
1895 passed | 23 skipped [live MySQL cells ON]

Gate union, derived from the actual changed paths with node scripts/pm/dispatch-gates.mjs and re-run at 967916b05 — all green: check:changeset-gate-self-tests, check:docs-audit-scope, check:objectui-changeset, check:role-word, check:test-source-alias, check:type-source-resolution, check:query-options-erasure, check:nul-bytes, check:type-check-coverage, check:type-check-debt (re-measured on a built closure: 33 ledger entries, none above ceiling), check-adr-0087-registration, check-changeset-no-major, check-empty-changeset.

Scope

#8740 is not addressed here — the empty-merge-set fallback in the same function stays on hold, and this change does not make it easier or harder (the fallback is reached only when the merge set is empty, which is orthogonal to how many unique keys the table carries).

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectstack	Ignored		Aug 15, 2026 3:36am

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/driver-sql.

8 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:

• content/docs/data-modeling/drivers.mdx(via @objectstack/driver-sql)
• content/docs/getting-started/glossary.mdx(via @objectstack/driver-sql)
• content/docs/kernel/services-checklist.mdx(via @objectstack/driver-sql)
• content/docs/plugins/anatomy.mdx(via @objectstack/driver-sql)
• content/docs/plugins/packages.mdx(via @objectstack/driver-sql)
• content/docs/protocol/kernel/index.mdx(via @objectstack/driver-sql)
• content/docs/protocol/kernel/lifecycle.mdx(via @objectstack/driver-sql)
• content/docs/protocol/objectql/query-syntax.mdx(via @objectstack/driver-sql)

⛔ 1 release-owned page(s) also reference the affected code. These are read-only:

• content/docs/releases/implementation-status.mdx(via @objectstack/driver-sql)

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.

Advisory only. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs origin/main → pass the list as args.docs.