fix(driver-sql): refuse and roll back a MySQL upsert that merges onto a row the caller never identified (#8807) (#8940)

* wip(driver-sql): post-hoc identity check for the unnamed-key merge (#8807)

* test(driver-sql): pin both branches per dialect for #8807

* docs+ledger(driver-sql): archiver measurement, MySQL dialect docs, ADR-0087 entry, changeset (#8807)

* docs(driver-sql): retire the stale 'residue is only documented' claims (#8807)

* fix(driver-sql): bind and tenant-scope the identity read; pin the scoping decision (#8807)

* chore(spec): regenerate the migration registry after the origin/main merge (#8807)

Both entries stack: #8936's engine-dotted-filter-refused and this card's
driver-sql-upsert-cross-row-identity-merge-refused. 97 semantic entries.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XeQRiAa7vYRVX5Fog7Zby8

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: hotlong

.changeset/mysql-upsert-cross-row-identity-merge.md

@@ -0,0 +1,45 @@
+---
+"@objectstack/driver-sql": minor
+"@objectstack/spec": patch
+---
+
+fix(driver-sql): refuse — and roll back — a MySQL upsert that merges onto a row the caller never identified (#8807)
+
+`ON DUPLICATE KEY UPDATE` carries no conflict target, so on MySQL a merge lands on
+whichever UNIQUE key the row collides with first. `#8621` closed the half where
+nothing backed a caller-named target; `#8755` closed the half where a rival key
+could absorb a caller-named one. This closes the residue those two left by
+construction: the `conflictKeys`-less call and the `['id']` call, which compile
+byte-identically and which no pre-flight can judge, because neither names anything.
+
+Measured on live MySQL 8.0.46, `email` and `tax_id` both `unique: true`, **no**
+`conflictKeys`: seeding `{email:'d@b.com', tax_id:'T-9'}` inserted one row, and
+`{email:'e@b.com', tax_id:'T-9'}` then resolved with no error — one row, the
+*seeded* one, its `email` rewritten `d@b.com` to `e@b.com`, and the id the caller
+was handed back present in no row at all. The identical pair on SQLite raises
+`UNIQUE constraint failed: …tax_id` and leaves the seeded row untouched.
+
+Per the maintainer ruling on #8807 this enforces a contract principle, not a MySQL
+detail: *an `upsert` must never modify a row whose identity the caller did not
+supply and whose conflict key it did not name.*
+
+**Accept-set change, MySQL only.** After the statement and inside the same
+transaction, the driver checks whether the row it landed on is the one the call
+supplied. If it is not, the write is **rolled back** and the call refuses with
+`code: 'VALIDATION_ERROR'`, `status: 400`, naming the UNIQUE key that absorbed the
+merge and stating that nothing was changed.
+
+The check is exact rather than heuristic — `id` is insert-only on the merge path
+(#8622), so a row merged on the primary key always still carries the supplied id
+and a row merged on any other key never does — which is why it has no false
+refusals.
+
+Deliberately unchanged: tables whose only key is the primary key are not verified
+and open no transaction, so the ordinary upsert keeps its single round trip; every
+insert and every re-upsert of the same row still merges; the caller-named
+single-unique-key fast path is untouched; and SQLite and PostgreSQL are unaffected,
+because `ON CONFLICT (...)` already honours the named arbiter. The lifecycle
+archiver's hot→cold copy passes by construction — it supplies each row's own id —
+and of the two objects declaring `lifecycle.archive`, neither carries a
+non-primary unique field. The dialect limit is documented under
+*Database Drivers → MySQL*.

content/docs/data-modeling/drivers.mdx

@@ -339,8 +339,8 @@ before any row is written and before any auto-number is reserved:
 
 | Call, on MySQL | Result |
 | :--- | :--- |
-| `upsert(o, row)` — no `conflictKeys` | Merges. Not pre-flighted (see the residue below). |
-| `upsert(o, row, ['id'])` — the primary key | Merges. Compiles identically to the line above. |
+| `upsert(o, row)` — no `conflictKeys` | Merges on the primary key. **Refused** if the merge lands on a different row (see below). |
+| `upsert(o, row, ['id'])` — the primary key | Identical to the line above — same statement, same answer. |
 | `upsert(o, row, ['email'])`, the table's only UNIQUE key being on `email` | Merges on `email`. **The common shape is unaffected.** |
 | `upsert(o, row, ['email'])`, the table also carrying `UNIQUE(tax_id)` | **Refused.** The message names `tax_id`'s index and the workarounds. |
 | `upsert(o, row, ['email'])`, no unique index on `email` at all | **Refused** on every dialect ([#8621](https://github.com/objectstack-ai/objectstack/issues/8621)). |
@@ -353,13 +353,43 @@ Two ways out, both stated in the error message:
    appropriate when both keys are genuine business constraints, since one of them
    must otherwise be given up.
 
+### The merge that lands on a row you never identified
+
+The pre-flight above covers a *caller-named* non-primary target. It cannot cover
+the `conflictKeys`-less default or an explicitly named primary key, because
+neither call names anything a pre-flight could check — and those two compile to
+the same statement. On a table with several UNIQUE keys that statement can still
+collide on a key you did not name, and MySQL will merge there:
+
+```text
+seed  upsert({ email: 'd@b.com', tax_id: 'T-9', title: 'first'  })  -- no conflictKeys
+      -> inserted, id = iVvD35rMk4BIayYc
+B     upsert({ email: 'e@b.com', tax_id: 'T-9', title: 'second' })  -- no conflictKeys
+      -> the fresh id did not collide; `tax_id` did, so MySQL merged onto the
+         SEEDED row — rewriting an `email` this call never asked to touch.
+```
+
+So the driver checks, after the statement and inside the same transaction,
+whether the row it landed on is the one the call supplied. If it is not, the
+write is **rolled back** and the call is refused with `code: 'VALIDATION_ERROR'`
+and `status: 400`. Nothing is left changed.
+
+| Call, on MySQL, table carrying a rival UNIQUE key | Result |
+| :--- | :--- |
+| The row is new, or matches an existing row's `id` | **Merges**, exactly as before. |
+| The row collides on a UNIQUE key you did not name | **Refused**, and the write is rolled back. |
+
 <Callout type="info">
-**The residue, stated rather than hidden.** The refusal covers a *caller-named*
-non-primary target. It does not cover the `conflictKeys`-less default or an
-explicitly named primary key: those two compile to the same statement, and on a
-table with several UNIQUE keys that statement can still merge on one you did not
-name. If you need the target honoured exactly, name it — and on MySQL, keep one
-UNIQUE key per table.
+**This check is selective, and only MySQL pays for it.** A table whose only key
+is its primary key can never exhibit the condition, so nothing is verified and
+no transaction is opened there. SQLite and PostgreSQL compile
+`ON CONFLICT (id)`, which honours the arbiter and raises a unique violation on
+any other key — they already behave this way and are unchanged.
+
+If you meant to merge on a business key, **name it** (`conflictKeys`), which
+makes the intent checkable. On MySQL, a table with more than one UNIQUE key
+cannot have every merge honoured — keep one UNIQUE key per table, or run the
+object on SQLite/PostgreSQL.
 </Callout>
 
 ## MongoDB