feat(driver-sql): MySQL joins the unresolvable-column predicate — refusal envelope and #3821 recoveries, full dialect parity (#8926)

[os-zhuang]

Fixes#8926

Ruling enacted — option A, maintainer, 2026-08-16, verbatim 「按 A」

Adds MySQL's spelling of "the statement named a column the backend could not resolve" — Unknown column 'x' in 'where clause' / 'field list' / 'order clause' (ER_BAD_FIELD_ERROR) — as the third arm of the ONE shared isUnresolvableColumnError predicate, and teaches unresolvableColumnNameOf to extract the name it carries. Full dialect parity; a split predicate (option B) and doing nothing (option C) were refused on the card.

Both directions of the accept-set change are intended and were ruled together:

• Narrowing — an unresolvable WHERE column on MySQL now refuses on both find() and count() with the ADR-0112 INVALID_FILTER / 400 envelope naming the column; the dialect message (which inlines the statement's bound literals — the finding: after the #7598 Q1=B ruling, a read scope with a driver-refused field reference answers 400 from the driver — which cuts across #5367's attribution argument on that one path #7929 disclosure shape) goes to the server log, not the caller.
• Widening — MySQL gains the fix(sharing): 共享规则新建页 — 自定义 widget 未国际化，且「接收方」永远无可选项 #3821 projection and ORDER-BY recoveries it has never had: a query that used to throw the raw dialect error now returns rows. Deliberate, ruled, and pinned as a direction in the tests.

Measured on a live MySQL 8.0.46 — all three clause positions, before and after

No OS_TEST_MYSQL_URL existed in this container and its Docker daemon is unavailable, so a real MySQL 8.0.46 (mysql-server-8.0, Ubuntu) was installed and provisioned at mysql://root:root@127.0.0.1:3306/conformance, global time zone +08:00, process TZ=America/New_York — mirroring the CI conformance job. A measurement script drove a real SqlDriver over mysql2 against the BUILT dist, with a dist marker check per leg proving each leg ran the intended predicate (marker absent in the BEFORE dist built from origin/main's source, present in the AFTER dist).

clause position	BEFORE (origin/main predicate)	AFTER (this PR)
WHERE, find()	raw ER_BAD_FIELD_ERROR, no status, bound literal inlined in the message	INVALID_FILTER / 400 naming nosuchcol; no literal, no statement
WHERE, count()	same raw throw	envelope identical to find()'s
projection	threw raw (… in 'field list')	recovered — rows returned, WHERE honoured
ORDER BY	threw raw (… in 'order clause')	recovered — rows unordered, WHERE honoured (rank at least 2 returned only t2)
dotted key title.x	raw throw, both halves	INVALID_FILTER / 400, both halves (same cell as SQLite — see below)
control (resolvable WHERE)	rows/count correct	unchanged

The structural fact the ruling carries held under measurement: the ORDER-BY recovery with a live WHERE returned exactly the matching row — every ladder rung is rebuilt from buildBase(), which re-applies query.where. No leak; no fork to report.

Full @objectstack/driver-sql suite (103 files) run with the live MySQL provisioned: 102 passed, 1 skipped — the skip is the unprovisioned live-Postgres cell reporting itself by name (CI provisions it). The refusal suite's live-mysql cell ran end-to-end: refusal pins, redaction pins, dotted status quo, and both KEEPS recovery pins, all green.

The two "NOT recognised" pins — exactly one flipped

• mysql (ER_BAD_FIELD_ERROR) — flipped to recognised: true, plus new fixtures for 'field list', 'order clause' and MySQL's dotted-key wording, and an explicit direction pin: all three clause positions ride ONE arm, so the envelope and the recoveries arrive together (matching only 'where clause' to withhold the recoveries would be the refused option B).
• postgres, DOTTED key — undefined_table — untouched, still recognised: false. That is [finding] The FILTER axis has no DOTTED-path verdict — where: { project_id.name: 'x' } rides its head segment past both doors, where SORT refuses the same spelling (#4256) #8371 / A dotted WHERE key escapes as a raw dialect error with the bound literal inlined on Postgres and MySQL — pre-existing, and measured against live servers #8931 territory: the driver's rule stays "refuse what the backend could not resolve", never "inspect the key for a dot". A dotted WHERE key escapes as a raw dialect error with the bound literal inlined on Postgres and MySQL — pre-existing, and measured against live servers #8931 is not addressed here and remains open.

DOTTED_STATUS_QUO gains a mysql row (INVALID_FILTER, enveloped): MySQL classifies a dotted key as an undefined COLUMN and spells it exactly like a plain missing one, so it lands in the same cell as SQLite — a consequence of the wording, not a dotted-path verdict; the key is never inspected for a dot.

Also in this diff

• isUnresolvableColumnError's docblock rewritten — its "REACH, deliberately UNCHANGED … matched by NEITHER arm" paragraph became false the moment the predicate widened (ruling condition 3); it now records both ruled directions and the buildBase() reason the widening is safe.
• unresolvableColumnNameOf extracts MySQL's column name (ruling condition 4) — the refusal names the column on MySQL rather than answering the legal-but-worse null.
• Changeset (@objectstack/driver-sql minor, mirroring driver-sql: one unresolvable WHERE column, two answers — find() silently returns [] while count() throws a raw dialect error with no ADR-0112 envelope #8790's lockstep convention) with ADR-0087 disposition not-required (already-registered driver-sql-unresolvable-where-column-refused) — same surface, same prescription, reach extended.

Verification — union run at 82e0925, the head of this branch, after merging origin/main

• pnpm --filter @objectstack/driver-sql test with OS_TEST_MYSQL_URL set: 102 files / 1983 tests passed, 1 file skipped (named live-PG skip).
• pnpm --filter @objectstack/driver-sql typecheck: clean.
• Gate union re-derived at this head (scripts/pm/dispatch-gates.mjs) and re-run after the merge: check:changeset-gate-self-tests, check:objectui-changeset, check:test-source-alias, check:type-source-resolution, check-adr-0087-registration, check-changeset-no-major, check-empty-changeset, check:query-options-erasure, check:type-check-coverage, check:type-check-debt (full closure built; no surplus), check:engine-double-contract, check:where-matcher, check:nul-bytes, check:error-code-casing — plus check:error-status-conformance, the ADR-0112 gate that landed on main while this branch was in flight, added to the union because this diff emits INVALID_FILTER / 400. All pass.

Out of scope, filed separately

• spec: the ADR-0087 entry driver-sql-unresolvable-where-column-refused states a MySQL reach gap that #8926's parity change retires #9060 — the ADR-0087 registry entry 18.driver-sql-unresolvable-where-column-refused (packages/spec) states in its reason that on MySQL this condition still travels out raw; true when registered, false once this merges. Amending it pulls in the spec artifact regeneration gate family, outside this card's declared file surface, so it is filed rather than ridden along.

---

Generated by Claude Code

[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.