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

* feat(driver-sql): qualify a cross-schema foreign key with referencedSchema (#11377)

IntrospectedForeignKey gains an optional referencedSchema, present when -
and only when - the referenced parent lives outside the session's own
resolution scope (PG: the parent's schema vs current_schemas(false);
MySQL: REFERENCED_TABLE_SCHEMA vs DATABASE(), null-safe). referencedTable
stays a bare name unconditionally. SQLite never sets the key - no schemas,
and a foreign key cannot cross an ATTACHed database.

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

* feat(objectql): refuse to wire a lookup to a foreign key carrying referencedSchema (#11377)

convertIntrospectedSchemaToObjects reads the driver's new qualification:
a foreign key whose target carries referencedSchema is loudly skipped and
flagged through options.logger (default console) - never wired to the
bare name - and the column converts as a plain field so the data stays
visible. Resolvable foreign keys keep wiring byte-identically.

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

* test(driver-sql): expect the #11377 qualification in #11324's cross-schema pins; add changeset

The #11324 fixture IS the cross-schema shape #11377 qualifies, so its two
cross-schema assertions now carry referencedSchema; presence/absence
semantics stay pinned in the #11377 file.

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

---------

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

Author: os-warren

.changeset/cross-schema-fk-qualification.md

@@ -0,0 +1,20 @@
+---
+'@objectstack/driver-sql': minor
+'@objectstack/objectql': minor
+---
+
+Cross-schema foreign keys are now qualified instead of shipping an unusable bare name (#11377).
+
+`IntrospectedForeignKey` (driver-sql) gains an optional `referencedSchema`, present when — and
+only when — the referenced parent table lives outside the introspecting session's resolution
+scope (Postgres: the parent's schema is not on `current_schemas(false)`; MySQL: the parent's
+database differs from `DATABASE()`; SQLite never sets it — no schemas, and a foreign key cannot
+cross an ATTACHed database). `referencedTable` stays a bare name always — the qualification is a
+separate key, never a conditional spelling.
+
+`convertIntrospectedSchemaToObjects` (objectql) reads the new key: a foreign key whose target
+carries `referencedSchema` is loudly skipped and flagged through the new `options.logger`
+(default `console`) instead of being wired to the bare name — which either resolved to nothing
+or to a same-named table in the current schema, silently. The column is kept as a plain field so
+its data stays visible. Foreign keys with in-scope targets keep producing identical lookup
+fields.

packages/drivers/driver-sql/src/sql-driver-11324-introspect-fk-join-correlations.test.ts

@@ -229,6 +229,11 @@ function declareJoinCorrelationSuite(cell: DialectCell): void {
     it('returns a foreign key whose target lives in ANOTHER schema', async () => {
       const foreignKeys = await driver.foreignKeys(CROSS_CHILD);
 
+      // `referencedSchema` is #11377's half of this answer: the parent is off
+      // the session's `search_path`, so the (still bare) name arrives
+      // qualified. Presence/absence semantics and their own controls are
+      // pinned in `sql-driver-11377-introspect-fk-cross-schema-qualification`;
+      // this file keeps owning the #11324 fact — the key is RETURNED at all.
       expect(
         foreignKeys,
         `${cell.label}: ${CROSS_CHILD} has a declared foreign key into ${far} and must not be ` +
@@ -239,6 +244,7 @@ function declareJoinCorrelationSuite(cell: DialectCell): void {
           referencedTable: REMOTE_PARENT,
           referencedColumn: 'id',
           constraintName: FK_CROSS,
+          referencedSchema: far,
         },
       ]);
     });
@@ -256,6 +262,8 @@ function declareJoinCorrelationSuite(cell: DialectCell): void {
           referencedTable: REMOTE_PARENT,
           referencedColumn: 'id',
           constraintName: FK_CROSS,
+          // #11377: the off-path parent arrives qualified — see above.
+          referencedSchema: far,
         },
       ]);
     });