fix(types): require a violation phrasing in isUniqueViolationError's message limb (#8590)

[qq9340100]

Fixes#8590

isUniqueViolationError's message limb was a bare unique constraint, and a word pair is not a condition. Every dialect that can say "this row violated a unique constraint" can also say "there is no unique constraint here", and the same two words sit adjacent in both — so the shared predicate answered true for errors meaning the exact opposite of what it detects. rest-server.ts maps that verdict to 409 UNIQUE_VIOLATION: a client told to change a value when nothing was ever compared, on a status an SDK will not retry.

The limb now requires a violation phrasing — unique constraint failed (SQLite) or violates unique constraint (Postgres).

Measured per dialect, on live servers

Ruling 1 of the dispatch, and the card's own caution. All three supported dialect families (sql-driver.ts recognises sqlite / postgres / mysql and no others), each driven through both conditions plus the NOT NULL and FOREIGN KEY near misses that share the wording:

• SQLite via better-sqlite3, knex 3.3.0
• PostgreSQL 16.13 via pg 8.22.0, knex 3.3.0
• MariaDB 10.11.14 via mysql2 3.23.1, knex 3.3.0 — the MySQL-wire family the Duplicate entry / ER_DUP_ENTRY / errno 1062 vocabulary was written for

sqlite ON CONFLICT clause does not match any PRIMARY KEY or UNIQUE constraint
was true, WRONG (the reported defect)
postgres there is no unique constraint matching given keys for referenced table "t"
was true, WRONG (42830 -- found by this sweep, see below)
postgres there is no unique or exclusion constraint matching the ON CONFLICT specification
false (the pair is not adjacent in this one)
mysql the condition cannot arise: knex compiles to ON DUPLICATE KEY UPDATE, which
carries no conflict target. Confirmed against a live server (the statement
simply succeeds), strengthening #8567's `.toSQL()`-only evidence.

Postgres was not clean either, and that chose the fix

The card was filed reading the collision as SQLite-only, with Postgres escaping "by luck of word order". That reading was too kind. Sweeping the dialects raised PostgreSQL 42830 — a FOREIGN KEY referencing a non-unique column — where Postgres puts unique constraintadjacent in its own absence sentence, with no PRIMARY KEY or in front of it.

That is what decided between the card's two candidates:

candidate	SQLite ON CONFLICT	PG 42830
negative lookahead on the missing-index sentence	fixed	still wrong
require a violation phrasing	fixed	fixed

A lookahead is a blocklist: it can only ever enumerate the absence sentences somebody already tripped over, and it is keyed to one dialect's current wording. The allowlist restores the module's own stated default — unrecognised is false — to the message channel, which is the direction the module already argues for everywhere else.

Blast radius (the main risk, per Ruling 5)

Both spellings the retired limb covered are preserved exactly, per Ruling 2 — it was inherited verbatim from the REST branch #6250 replaced and covered SQLite's UNIQUE constraint failed: t.cand Postgres' violates unique constraint "...". The unique violation, duplicate key and duplicate entry limbs are untouched, as are the code and errno channels, so MySQL's Duplicate entry path never went through the narrowed limb at all.

A mechanical scan of every string literal in the repo found 17 whose verdict moves. None is a regression: they are prose, a different predicate's vocabulary (looksLikeInternalErrorLeak keeps its own separate list in error-leak.ts), fixtures asserted through the status-passthrough path, or the defect sentences themselves. Verified by reading and by test — the five consumer packages were run, not edited:

@objectstack/types 333 passed
@objectstack/objectql 3591 passed
@objectstack/rest 1903 passed
@objectstack/driver-sql 1637 passed (54 skipped)
@objectstack/metadata-protocol 1317 passed
@objectstack/service-messaging 229 passed

Reachability: latent, confirmed — not raised

The card assumed latent. Confirmed by reading both gates. SqlDriver.upsert is the only site compiling a caller-supplied conflict target, and its isUnbackedConflictTargetError check runs first and unconditionally in the catch, throwing a refusal that declares status: 400. mapDataError then reads declaredHttpStatus (line 721) before the unique-violation branch (line 871), so the 400 wins.

One nuance worth recording: that refusal keeps the raw driver error as its cause, and this predicate walks cause — so the refusal object itself answered true before this change. Only the status gate stood between that and a wrong code on the wire, which is why the verdict is now pinned rather than left to it.

Pins

• unbacked-conflict-target.test.ts — drivers(sql): the unbacked-conflict-target refusal is SQLite-only — Postgres and MySQL still answer the raw driver error #8567 wrote its pin to point at itself rather than go quietly green. It is inverted, not deleted, and its prose rewritten; the SQLite row moves true to false.
• unique-violation-absence-sentences.test.ts (new) — the absence sentences per dialect, bare / knex-prefixed / plain string, plus the violation spellings, the near misses, the column-extractor gate, the cause-wrapped refusal, and the code channel (so re-reading code cannot undo the message-side fix from the other side).

Reverse verification: restoring the bare limb was predicted to produce 13 failures — 12 in the new suite and the flipped SQLite pin. It produced exactly those 13, test for test. The fix was committed first, so the restore came out of a real commit.

Docs correction folded in (second commit)

unbacked-conflict-target.ts's module head still described the collision as live, reasoned from it, and conditioned the disjointness prohibition on "while #8590 is open". All three claims are false after this change, and the prohibition was never meant to expire — the two predicates answer inverse questions permanently. Corrected in place, and the paragraph now also records that Postgres did not escape "by luck of word order" (42830). Prose only, no emitted code, so no second changeset. Folds in #8732, which is closed as shipped here.

This was originally left out because the card's file surface was drawn to keep a verdict change off consumer packages; the PM extended the surface by this one file rather than leave a knowingly-false instruction about these two predicates in the tree — the same failure mode this card exists to fix, one file over.

Verification

Gates run after the final commit, at HEAD 3ebd8608e. main moved twice during this card; it is merged in (c1d030823, merging ff3e3fcc5) and the whole closure rebuilt before measuring, so the ratchets measure the tree that merges rather than a stale one:

pnpm check:nul-bytes OK (5750 files, no raw control bytes)
pnpm check:query-options-erasure OK (ratchet holds, none new; baseline verified against ff3e3fc)
pnpm check:type-check-coverage OK (64/77 packages)
pnpm check:type-check-debt OK (33 ledger entries re-measured, none above its recorded number)
pnpm --filter @objectstack/types test 333 passed (12 files)
pnpm --filter @objectstack/types typecheck clean

Re-derived against the actual diff with scripts/pm/dispatch-gates.mjs; it surfaced the changeset family, which the dispatch prompt did not name because the changeset did not exist yet. Those were run too: check-empty-changeset, check-changeset-no-major, check-adr-0087-registration all pass.

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 14, 2026 5:05pm

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/types.

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

• content/docs/plugins/packages.mdx(via @objectstack/types)

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.