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

.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,
  },
  ]);
  });