feat(driver-sql,objectql): qualify cross-schema foreign keys with referencedSchema; refuse to wire the bare name - #11906

Fixes #11377

Maintainer ruling (carried out; 引文保持原文,未翻译)

Provenance: maintainer, 2026-08-24, live PM chat, ruling on the four-facet analysis (issue comment 5393638385), verbatim:

接受你的建议。

The accepted recommendation, verbatim from that block:

推荐:选项 1(加可选 referencedSchema,越界时填),且同一张卡带消费端半边:util.ts 对带 schema 且不可解析的目标响亮跳过并标记,⛔ 不裸名接线(否则加了键没人读,声明无强制原地复发)。四轴同向。

Clause-②: yes (widens a public contract shape).

What landed

Driver half (packages/drivers/driver-sql/src/sql-driver.ts):

• IntrospectedForeignKey gains an optional referencedSchema, present when — and only when — the referenced parent lives outside the session's resolution scope. referencedTable stays a bare name always (option 2's conditional spelling rejected as a trap; option 3 rejected as hiding truth). The interface TSDoc states the per-arm semantics.
• PG arm: joins the parent's namespace and projects its schema when it is not in current_schemas(false) — the same search_path scoping driver-sql (PG): introspectForeignKeys' information_schema query is not schema-scoped — a same-named table in another schema contributes its foreign keys #11201 gave the child side, asked about the parent. Measured on live PostgreSQL 16.13 with the card's fixture shape before wiring: a parent in os11377_far answers referenced_schema = os11377_far with the table name bare; an in-path parent answers NULL.
• The key is absent (never undefined) for an in-scope parent — presence itself carries the fact.

Consumer half (packages/objectql/src/util.ts — same PR, per the ruling):

• The local IntrospectedForeignKey mirror gains the same key (consumer-side copy of the producer contract, the isUnique pattern).
• convertIntrospectedSchemaToObjects refuses to wire a lookup for a foreign key carrying referencedSchema: a loud flag through the new options.logger (default console, so a bare call is loud) names the constraint, the qualified address, the consequence, and the remedy; the column converts as a plain field so its data stays visible while the false address does not ship. Foreign keys with in-scope targets keep wiring byte-identically (whole-object pins). The warn idiom was measured from the package (action-governance.ts's minimal injected-logger surface, matching PluginContext.logger); util.ts itself had none.

MySQL-arm measurement (confidence-gap check folded in from the four-facet block)

The MySQL arm can fill the key symmetrically, and now does: information_schema.KEY_COLUMN_USAGE carries the parent's database as REFERENCED_TABLE_SCHEMA on the same row the arm already reads; InnoDB permits cross-database foreign keys; and the child-side filter TABLE_SCHEMA = DATABASE() never constrained the referenced side — so a cross-database foreign key was already being returned, bare. The arm now projects the parent's database when it differs from DATABASE(), compared with MySQL's null-safe equality operator (with no default database selected, no bare name resolves, so every parent is qualified). No live MySQL exists in this container: the new test file's live-MySQL cell runs in CI's Temporal Conformance (live PG + MySQL) job (a named skip elsewhere, per the matrix contract), and a no-server emission probe (the #11379 pattern) pins the projection and the TS row mapping in every job. #11379's separate MySQL ordering issue was not touched.

SQLite: never fills the key — no schemas, and a foreign key cannot cross an ATTACHed database; documented in the interface TSDoc.

Reverse verification (RED first, both halves)

Fixture: live PostgreSQL 16.13 in this container; the card's shape — a _far-suffixed sibling schema holding os11377_remote_parent, referenced from an in-path child, with an in-path parent as the sibling control.

• (a) driver, cross-schema pin — RED by the key's absence against pre-fix source: toStrictEqual diff shows the expected referencedSchema line missing from the received answer (2 PG tests failed: the direct pin and the introspectSchema carry-through; the MySQL emission-probe pins failed alongside — 4 failed, 1 passed [the fixture control], 1 skipped). GREEN after: 5 passed, 1 skipped (live MySQL, named skip).
• (b) driver, in-path pin — byte-identical answer with NO referencedSchema key, asserted with toStrictEqual plus an explicit Object.keys absence read (toEqual would accept referencedSchema: undefined). Preservation pin: green on both sides by design.
• (c) consumer — RED against pre-fix util.ts: all 4 new pins failed (a lookup wired to the bare name, no flag); the 22 pre-existing tests stayed green. GREEN after: 26/26. The flag message and meta are pinned fragment by fragment.
• (d) consumer, resolvable FK — whole-object byte-identical lookup, exactly one warn emitted (the cross-schema refusal, not about the resolvable key). Preservation pin.

Each mutation and each restore was confirmed on disk before reading any run: grep -c referencedSchema (driver: 0 pre-fix / 5 fixed; consumer: 0 pre-fix / 9 fixed) and git status --porcelain (lone unstaged M during the leg; clean after restore). Both RED legs ran from committed fixes via git restore --source=$BASE (tree-only), never against uncommitted work.

Verification (local; head d67d937)

• @objectstack/driver-sql: full suite green in Test Core posture (no live URLs — live cells report named skips); the whole introspection family additionally run against live PostgreSQL 16.13: 9 files, 48 passed, 2 skipped (the two live-MySQL cells — named skips, unprovisioned in this container; they run in CI's Temporal Conformance (live PG + MySQL) job). One pre-existing pin updated: driver-sql (PG): introspectForeignKeys' JOIN correlations are wrong in two ways — a cross-schema FK target vanishes, and a composite FK is returned as a cartesian product #11324's cross-schema fixture IS the shape this card qualifies, so its two cross-schema assertions now expect referencedSchema (its own subject — the key is returned at all — is untouched).
• @objectstack/objectql: pnpm test green (util suite 26/26 within it); typecheck green.
• Downstream-closure typecheck, 48 packages — every package that can see the widened declarations (a package outside the dependents closure of driver-sql/objectql has no import path to the changed types): green, 0 TS errors.
• node scripts/pm/dispatch-gates.mjs (no paths — the script derives the change set itself): 16 path-derived + 6 convention-triggered families run locally at the final head; results and the derivation line are quoted in the report comment on driver-sql (PG): a cross-schema foreign key is reported with an UNQUALIFIED referencedTable, and the bare name does not resolve on the session's search_path #11377.
• Changeset: one entry, driver-sql minor + objectql minor (no major — launch-window rule).

Generated by Claude Code