drivers(sql): an upsert whose conflictKeys have no backing unique index throws a raw SqliteError — the local twin of #8413's consequence 2

Found while implementing #8413 (PR pending), out of that card's scope and not fixed there. Measured on origin/main @ 2bacd1aa.

What was measured

#8413 fixed the REMOTE Turso face so that a conflictKeys upsert whose target has no backing unique index refuses with an ADR-0112 envelope (VALIDATION_ERROR / 400) instead of a raw SqliteError. While confirming that the local face was the correct reference for that card, the same probe was run against the LOCAL face — which inherits SqlDriver.upsert:

LOCAL upsert('plain', { email: 'a@b.com', title: 'x' }, ['email'])
  -> THREW name=SqliteError code=SQLITE_ERROR status=undefined
     msg=insert into `plain` (`created_at`, `email`, `id`, `title`, `updated_at`) values (...)

code: 'SQLITE_ERROR', status: undefined — the identical un-enveloped shape #8413 was filed to remove, on the other face.

Why it is a separate card

It is not the same defect and does not belong in #8413:

Different cause. drivers(turso): the remote face drops unique entirely — a declared-unique column takes duplicates, and an upsert on conflictKeys dies with a raw SqliteError #8413's remote instance was produced by the missing DDL — the index was never created, so a correctly-declared unique: true column hit it. Locally, syncDeclaredIndexes does create the index, so this reaches only the case where the caller names conflict keys over columns that were genuinely never declared unique. Rarer, and purely caller-side.
Wider blast radius. The throw is in SqlDriver.upsert, so it is not a Turso concern at all — every dialect on driver-sql (SQLite, Postgres, MySQL) answers this condition with whatever raw error its own client raises. The wire shape therefore differs per dialect, which is the case an envelope exists to collapse.
Different file surface. packages/drivers/driver-sql/src/sql-driver.ts, outside drivers(turso): the remote face drops unique entirely — a declared-unique column takes duplicates, and an upsert on conflictKeys dies with a raw SqliteError #8413's declared surface.

Why it is worth fixing

mapDataError reads error.code / error.status to build the response envelope; with neither set this falls through to the default branch and ships { "error": "insert into ... values (...)" } — a raw SQL string, with no code, to the caller. That is both unbranchable and an information leak of the statement text, and it is exactly the argument invalidFilterError's docstring already records for the filter refusals (#1116 / #1077's envelope pass).

Adjacent but distinct: #8441 covers a raw driver code reaching client-facing payloads through the batch verbs' code limb. This one is the throw site itself on the upsert path.

Suggested disposition (not proposing the verdict)

The natural shape is the twin of what #8413 landed remotely — recognise the "conflict target is not a key" condition and re-raise it enveloped, first sentence for first sentence with the remote refusal (#5240, one condition one wording). Whether the dialect-spanning recognition is worth a shared predicate in @objectstack/types (beside isUniqueViolationError, which answers the opposite condition) is the part that needs a decision — SQLite answers on the message, and Postgres/MySQL wording for this condition is unmeasured.

Related: #8413 (the remote twin), #8441, #6543 (the shared unique-violation predicate), #1116 / #1077 (the envelope pass this continues).

Generated by Claude Code

Triage: lands in packages/drivers/driver-sql/src/sql-driver.ts (the upsert throw site) ⇒ routed domain:drivers — driver-sql is outside the 2026-08-05 investment freeze (that freeze names the driver-memory/driver-mongodb family only). Queued pm:queue, type Bug: an un-enveloped raw driver error reaching callers — carrying the literal statement text, with no code to branch on — violates the envelope contract this line of cards (#1116/#1077, #8413) enforces; the remote twin's fix is already the in-tree reference.

Dispatch notes for the drivers seat:

The card's open question (a shared dialect-spanning predicate in @objectstack/types beside isUniqueViolationError) is implementation judgment, not a maintainer decision: Postgres/MySQL wording for this condition is unmeasured, so a SQLite-recognition-first fix with the shared predicate as a follow-up card is a legitimate narrow shape. Measure before generalising; report the choice in the PR.
Wording discipline per { field: {} }(零个操作符的字段约束)在同仓有三个答案:driver-sql 组合子内 TRUE、顶层抛 INVALID_FILTER、formula/driver-memory FALSE #5240: first sentence for first sentence with drivers(turso): the remote face drops unique entirely — a declared-unique column takes duplicates, and an upsert on conflictKeys dies with a raw SqliteError #8413's remote refusal — one condition, one wording.
Adjacent, not overlapping: A raw driver code (SQLITE_ERROR) still reaches client-facing payloads through the batch verbs' code limb — the sibling field #8333 did not cover #8441 (raw code through the batch verbs' code limb), finding: the declared-index replacement arm's guards are redundantly covered, so any single one can be deleted with every test still green #8557 (held finding on schema-drift.ts in the same package — different file, no serial constraint).

Late-triage note: filed 13:22Z, first labeled this round (~21:20Z) — the card sat bare below several sweep frontiers; recorded in the round brief as a sweep-gap observation, no fault of the filer.

Size/model suggestion: M, opus.

Generated by Claude Code

Claim: PM loop, drivers lane
Session: session_01VoxQqG5FiUHZKCST7KDoZC
Branch: claude/issue-8445-upsert-conflictkeys-envelope
Worktree: objectstack-issue-8445
Domain: domain:drivers
File surface: packages/drivers/driver-sql/src/sql-driver.ts + a new/extended test in packages/drivers/driver-sql/src/ + .changeset/; packages/types/ only if measurement justifies generalising (see below) (stop on breach; explain in the report)
Container & model: M, mode:subagent, model: opus
Serial constraints cleared: sql-driver.ts last moved by #8283 (62452c62a, MERGED). #8557 is a held finding on schema-drift.ts — different file, and triage confirms no serial constraint. No open card or PR touches sql-driver.ts.

Adopting triage's relaxation of my own standing plan

I had been carrying an instruction that a dev wanting to touch @objectstack/types should stop and report a fork. Triage rules that the shared dialect-spanning predicate is implementation judgment, not a maintainer decision, and that a SQLite-recognition-first fix with the predicate as a follow-up card is a legitimate narrow shape. That is triage's call to make and it is better than mine — my version would have stalled a run on a question the dev is equipped to answer. Dispatching with "measure before generalising, and report which shape you chose and why" instead.

Premise verified on `origin/main` @ `719a21bf`

Claim	Verified
The throw site is `SqlDriver.upsert`	`sql-driver.ts:4890` ✅
`mapDataError` reads `code`/`status` off the thrown error, so an un-enveloped throw ships the raw SQL text	✅ — pinned in-tree, e.g. `sql-driver-date-bucket.test.ts:148` describes exactly that `code`/`status` `undefined` fall-through
#8413's remote refusal is the wording reference (#5240)	`remote-transport.ts:638` sets `VALIDATION_ERROR`, with its own "Why `VALIDATION_ERROR` / 400" rationale at `:601-608` explaining why it is not `RESOURCE_CONFLICT`/409 or `DUPLICATE_VALUE` ✅
The predicate it would sit beside	`isUniqueViolationError` in `packages/types/src/unique-violation.ts` ✅

On the late-triage note

Corroborating it from this side: I have been checking this card by direct issue_read on every patrol since ~14:00Z precisely because an unlabelled card is invisible to a domain:* lane scan — the standing filter cannot see it, so a seat that only scans its lane would never have found it. That is the sweep gap in operational form, and the manual per-round check was the workaround.

Generated by Claude Code

{
  "issue": 8445,
  "status": "done",
  "branch": "claude/issue-8445-upsert-conflictkeys-envelope",
  "pr": "https://github.com/objectstack-ai/objectstack/pull/8571",
  "premise_still_valid": true,
  "summary": "Premise re-measured on origin/main @ 719a21bf before implementing and it holds exactly as filed: upsert('plain', {...}, ['email']) threw name=SqliteError code=SQLITE_ERROR status=undefined with the statement and its bound values as the message. SqlDriver.upsert now recognises the unbacked conflict target and re-raises VALIDATION_ERROR / 400 with the original error as cause, wording taken verbatim from #8413's remote refusal (#5240, first sentence for first sentence). One detail the card did not record and the fix rests on: knex builds the message as statement + ' - ' + SQLite's own sentence, so SQLite's text (the only channel that can discriminate this condition) survives to the local face and the remote twin's recognition applies unchanged. JUDGMENT CALL: narrow shape, SQLite-recognition at the driver-sql call site, NOT a shared predicate in @objectstack/types — this container has no Postgres or MySQL server, so their wording could not be measured, and MySQL may not even have the condition (knex compiles onConflict().merge() there to ON DUPLICATE KEY UPDATE, which takes no conflict target); generalising is filed as #8567. Accept/reject set unchanged, hence patch, not the minor #8413's driver-turso half took for starting to refuse writes accepted before. SANITIZER CHECK on #8445: no stored damage — the HTML entities in the issue body are the documented read-path artifact of the get method (get_comments returned both comments unescaped), the body's headings, code block and session-URL footer are all intact with no truncation after a bare angle-bracket token. SURFACE NOTE: the claim comment's declared surface was sql-driver.ts + a driver-sql test + .changeset, and I stayed inside it. The consequence is that the wording pin I added is one-way (it catches a reword of the local face, not of the remote one); the two-way runtime comparison needs a package that can import both faces, which is driver-turso, filed as #8568 rather than smuggled in.",
  "tests": "pnpm --filter @objectstack/driver-sql test  ->  Test Files 91 passed | 4 skipped (95), Tests 1463 passed | 52 skipped (1515)  [1457 before, +6 new]. pnpm --filter @objectstack/driver-sql typecheck -> clean (tsc --noEmit, no output). pnpm --filter @objectstack/driver-turso test -> Test Files 37 passed (37), Tests 984 passed (984) — the downstream consumer whose local face inherits this throw site; its first run showed 36 files failing at COLLECTION in 10s with 'Failed to resolve entry for package @objectstack/driver-sql' — the fresh-worktree unbuilt-dist trap, cleared by pnpm --filter '@objectstack/driver-turso^...' build, not my change. REVERSE VERIFICATION, direction predicted before running (fix committed first, restored with git checkout from the commit — never git stash): predicted the envelope pin red on its FIRST assertion rather than through an 'it resolved' branch (this input was always refused), leak and wording pins red with it, and the three controls green. Measured: 'Tests 3 failed | 3 passed (6)', first failure \"expected 'SQLITE_ERROR' to be 'VALIDATION_ERROR'\", the other two showing the raw 'insert into `crm_contact_plain`...' text reappearing in the caller-visible message. WHAT STAYS GREEN, and why that half matters: the positive control (same conflictKeys upsert MERGES when a declared unique: true backs it — 1 row, title 'second'), the default id merge key, and the specificity control (an unrelated statement failure is not swallowed as this refusal) never depended on the fix. Without the positive control an implementation that refused EVERY conflictKeys upsert would pass the refusal assertion having broken the capability. GATES — prompt named none explicitly beyond the derivation; ran node scripts/pm/dispatch-gates.mjs against the actual changed paths, which named 7 path-derived + 2 convention-derived, and ran all of them plus check:nul-bytes: check:changeset-gate-self-tests OK, check:objectui-changeset OK, check:test-source-alias OK (72 packages scanned), check:type-source-resolution OK (76 packages scanned), check-adr-0087-registration OK (no declared-breaking changeset), check-changeset-no-major OK, check-empty-changeset OK ('1 declaring changeset(s) added' — read AFTER committing; the pre-commit read was the documented false green at 0), check:query-options-erasure OK (ratchet holds, baseline verified against 719a21b, no files added), check:type-check-coverage OK (64/77), check:nul-bytes OK (7724 files, no raw control bytes). check:objectui-pin-fresh and check-dev-prereqs not run — known-ambient per the dispatch. No changeset label needed: this PR carries a changeset and is not tests/workflow-only.",
  "open_questions": [],
  "out_of_scope_findings": [
    "filed as #8567 (unlabeled, PM triage): the same refusal is SQLite-only — Postgres and MySQL still answer the raw driver error for an unbacked conflict target, because neither dialect's wording could be measured in this container; card records what was and was not measured, and gates the @objectstack/types predicate question on measuring first",
    "filed as #8568 (finding): no cross-face parity pin exists for this refusal — the two wordings (driver-sql local, driver-turso remote) can drift without any suite going red, since driver-sql cannot import driver-turso and remote-transport.ts is deliberately free of knex and SqlDriver; the fix is a local-face case beside Pin 3 of turso-local-remote-unique-parity.test.ts, comparing runtime messages"
  ]
}

Generated by Claude Code

ACCEPT — holding the ready-flip until CI converges

Reviewed against the branch and origin/main @ 199a1db, ⛔ not against the report. PR #8571, 3 files.

The hard constraint — wording — verified byte-for-byte, before the report arrived

#5240 says one condition, one wording. The new local refusal builds a string identical to driver-turso's refuseUnbackedConflictTarget at remote-transport.ts:629-635, and both faces name the recognition and the refusal the same (isUnbackedConflictTargetError / refuseUnbackedConflictTarget). The reason it matters is in the code and is the right reason: TursoDriver picks its face from url, so a second wording would make the answer a property of the connection string.

Two things it got right that I had not specified

Placement. The recognition sits before the autonumber retry branch, and the load-bearing reason is the third one given: it is the only placement that envelopes both exits — a check after the branch still escapes raw whenever mayRetry is false. It also notes the condition is not an autonumber collision (isUniqueViolationError is false for it), so the retry probe would query the sequences table for nothing.
isUniqueViolationError is deliberately not reused — it answers the opposite condition (an index exists and the row violated it). Confusing them would report a working constraint as a missing one. That distinction is carried into drivers(sql): the unbacked-conflict-target refusal is SQLite-only — Postgres and MySQL still answer the raw driver error #8567 as a ⚠️ so a future generaliser cannot merge them by tidiness.

The pins, including the one I care most about

The leak pin is the half the card said was the larger defect: it asserts the statement text and the bound values (leaked@example.com, secret-title) do not appear in the caller-visible message, while remaining reachable via cause. Asserting code/status alone would have let a refusal that still echoed the statement pass.

Beside it, three controls that pin what this card must not have changed: the positive control (same conflictKeys upsert merges when a declared unique: true backs it), the default id merge key, and a specificity control — an unrelated SQLITE_ERROR must come back as itself, since the recognition is a narrow message match rather than a catch-all over the generic code. Reverse verification predicted 3 red / 3 green and measured exactly that; the three that stay green are the controls, which is what makes them controls.

The delegated judgment call, answered with evidence

Narrow SQLite-first shape, because the other two dialects could not be measured in that container — and it refused to transcribe their wording from memory, which was the instruction. Both follow-ups verified filed and unassigned: #8567 (measure PG/MySQL, then decide whether the recognition belongs in @objectstack/types) and #8568 (finding — no cross-face parity pin exists, because driver-sql cannot import driver-turso and remote-transport.ts is deliberately free of knex and SqlDriver).

⚠️ #8568 is the honest half of Pin 3 and worth not losing. The wording pin this PR adds is one-way: it goes red if this face is reworded, and cannot see a reword of the remote face. Saying so in the test's own docblock, rather than letting the pin look symmetrical, is the difference between a guard and a false sense of one.

Changeset `patch`

Correct, and correctly distinguished from #8413's driver-turso half, which was minor on a ground that does not apply here: that one started refusing writes accepted before. This one changes no accept/reject set — the same calls fail, they fail legibly.

Next: CI converging (24 checks, several in_progress). ⛔ No flip on an in_progress read → all gate jobs completed: success → ready → queue → MERGED.

Generated by Claude Code

fix(driver-sql): envelope the unbacked-conflict-target upsert refusal (…

fix(drivers): recognise the unbacked conflict target on Postgres too (o…

Navigation Menu

Repository navigation

drivers(sql): an `upsert` whose `conflictKeys` have no backing unique index throws a raw SqliteError — the local twin of #8413's consequence 2 #8445

What was measured

Why it is a separate card

Why it is worth fixing

Suggested disposition (not proposing the verdict)

Adopting triage's relaxation of my own standing plan

Premise verified on `origin/main` @ `719a21bf`

On the late-triage note

ACCEPT — holding the ready-flip until CI converges

The hard constraint — wording — verified byte-for-byte, before the report arrived

Two things it got right that I had not specified

The pins, including the one I care most about

The delegated judgment call, answered with evidence

Changeset `patch`

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

drivers(sql): an upsert whose conflictKeys have no backing unique index throws a raw SqliteError — the local twin of #8413's consequence 2 #8445

Description

What was measured

Why it is a separate card

Why it is worth fixing

Suggested disposition (not proposing the verdict)

Activity

hotlong commented on Aug 13, 2026

os-zhuang commented on Aug 13, 2026

Adopting triage's relaxation of my own standing plan

Premise verified on origin/main @ 719a21bf

On the late-triage note

os-zhuang commented on Aug 13, 2026

os-zhuang commented on Aug 13, 2026

ACCEPT — holding the ready-flip until CI converges

The hard constraint — wording — verified byte-for-byte, before the report arrived

Two things it got right that I had not specified

The pins, including the one I care most about

The delegated judgment call, answered with evidence

Changeset patch

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

drivers(sql): an `upsert` whose `conflictKeys` have no backing unique index throws a raw SqliteError — the local twin of #8413's consequence 2 #8445

Premise verified on `origin/main` @ `719a21bf`

Changeset `patch`