fix(driver-sql): introspectSchema() emits the spec introspection contract — primaryKey, dialect, introspectedAt (#10676, #10998) (#11124)

* fix(driver-sql): emit the spec `primaryKey` column spelling, not `isPrimary` (#10676)

`SqlDriver.introspectSchema` declared its own `IntrospectedColumn` and spelled
primary-key membership `isPrimary`, while everything downstream of `plugin.ts`
is typed against `packages/spec/src/contracts/schema-diff-service.ts`, which
spells it `primaryKey`. The value crossed between the two contracts untyped, so
`ExternalDatasourceService.generateObjectDraft` — which reads `col.primaryKey`
— saw `undefined` on every real driver result and every federated object
drafted from a remote table silently lost its remote primary key.

Maintainer ruling, 2026-08-22 (live session, 「同意所有」 item 9 =
驱动侧对齐 spec 契约): `packages/spec` is the one contract and the driver
aligns to it.

- `driver-sql` and `objectql/src/util.ts` now DERIVE `IntrospectedColumn` from
  the spec import instead of re-declaring it, so a key added to the contract
  fails their `tsc` until the producer emits it. Two divergences are kept
  explicitly (`defaultValue` stays `unknown` — Knex reports `null`; `isUnique`
  / `maxLength` are SQL extras the spec does not declare).
- The driver emits `primaryKey` and no longer emits `isPrimary`: one spelling,
  so no consumer can key off the wrong one again.
- New pin `external-object-draft-real-introspection.test.ts` drives
  `generateObjectDraft` off a REAL `introspectSchema()` result, which is what
  the ruling requires and what the hand-written fixtures could never do. It
  fails on the pre-fix driver (measured: the `// Remote primary key:` line is
  absent) and asserts the key does not return as the unauthorable
  `fields.<f>.primaryKey`.
- `external-introspection-seam.test.ts` asserted the producer's OLD spelling as
  a deliberate landmine; its producer-spelling case is flipped to the new
  direction. The service's three-signal union read is untouched.

Fixes #10676

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

* fix(driver-sql): emit the spec `dialect` and required `introspectedAt` (#10998)

`introspectSchema()` returned `{ tables }` and nothing else, while
`packages/spec/src/contracts/schema-diff-service.ts` declares `dialect` and a
REQUIRED `introspectedAt`. Measured live on in-memory SQLite before this
change: `Object.keys()` was `["tables"]`. Two silent consequences — type
mapping ran with `dialect: undefined` on the whole federation path, so every
per-dialect alias in `suggestFieldTypeForSqlType` was unreachable there, and
`refreshCatalog` persisted `dialect: undefined` into the `external_catalog`
record Studio's schema browser and the boot gate read back.

Same ruling as #10676 (2026-08-22, 「同意所有」 item 9): the driver aligns to
the one contract.

- `IntrospectedTable` / `IntrospectedSchema` now derive from the spec import in
  both `driver-sql` and `objectql/src/util.ts`, so `introspectedAt` being
  required is enforced by `tsc` rather than by remembering. `indexes` is
  `Omit`ted rather than emitted empty: this driver does not introspect indexes,
  and `[]` would claim a table has none — filed separately, not guessed.
- `dialect` is `this.dialectName` (`sqlite` / `postgres` / `mysql` /
  `unknown`), NOT the raw Knex client and NOT the spec's `SQLDialectSchema`
  enum: the only in-tree consumer keys `DIALECT_ALIASES` on the `SqlDialect`
  vocabulary of `type-compat.ts`, which spells PostgreSQL `postgres`. Emitting
  `postgresql` would satisfy `Object.keys()` while leaving the aliases just as
  unreachable.
- `introspectedAt` is stamped before the reads begin, so it never claims to
  cover a moment later than the first table actually read.

Measured after: `Object.keys()` is `["tables","dialect","introspectedAt"]`;
the persisted catalog records `dialect: 'sqlite'`. On the SQLite arm the
suggested field types are byte-identical before and after (its alias map
overlaps the base map); the per-dialect payoff is on Postgres/MySQL, which are
unreachable from this container and are therefore not claimed.

Fixes #10998

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

* chore(changeset): driver-sql emits the spec introspection contract (#10676, #10998)

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

---------

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

Author: os-zhuang

.changeset/driver-emits-spec-introspection-shape.md

@@ -0,0 +1,60 @@
+---
+"@objectstack/driver-sql": minor
+"@objectstack/objectql": minor
+---
+
+fix(driver-sql): `introspectSchema()` emits the spec introspection contract — `primaryKey`, `dialect`, `introspectedAt` (#10676, #10998)
+
+**BREAKING** change to the value `SqlDriver.introspectSchema()` returns, shipped
+as `minor` under the repo's launch-window convention for breaking changes.
+
+`packages/spec/src/contracts/schema-diff-service.ts` declares one introspection
+contract. The driver declared a second one beside it and, separately, so did
+`packages/objectql/src/util.ts`. The three agreed on the idea and disagreed on
+the vocabulary: the driver spelled a column's primary-key membership
+`isPrimary`, the spec spells it `primaryKey`; the spec declares `dialect` and a
+REQUIRED `introspectedAt` that the driver's schema type never mentioned and
+`introspectSchema()` therefore never emitted. Nothing was type-unsound — each
+side compiled against its own declaration and the value crossed between them
+with no compiler in the middle.
+
+Measured on a live in-memory SQLite database before this change: the id column
+of a `primary key (id)` table came back carrying `isPrimary: true` with no
+`primaryKey` key at all, and `Object.keys()` of the schema was `["tables"]`.
+Two consequences, both silent:
+
+- `ExternalDatasourceService.generateObjectDraft` reads `col.primaryKey`, so
+  every federated object drafted from a real remote table lost the remote
+  primary key — the addressing key for the federated table, dropped by the
+  codegen meant to produce it (#10676).
+- type mapping ran with `dialect: undefined` across the whole federation path,
+  making every per-dialect alias in `suggestFieldTypeForSqlType` unreachable
+  there, and `refreshCatalog` persisted `dialect: undefined` into the
+  `external_catalog` record Studio's schema browser and the boot gate read
+  back (#10998).
+
+Maintainer ruling, 2026-08-22 (live session, 「同意所有」 item 9 =
+驱动侧对齐 spec 契约): `packages/spec` is the one contract and the driver
+aligns to it.
+
+What the driver now returns: every column carries the boolean `primaryKey`, the
+schema carries `dialect` and `introspectedAt`, and the retired `isPrimary`
+member is gone rather than emitted alongside — one spelling, so no consumer can
+key off the wrong one again. `dialect` is the driver's canonical dialect name
+(`sqlite`, `postgres`, `mysql`, `unknown`), which is the vocabulary the only
+in-tree consumer keys its alias tables on; `introspectedAt` is an ISO 8601
+instant stamped before the reads begin.
+
+`IntrospectedColumn`, `IntrospectedTable` and `IntrospectedSchema` in both
+`@objectstack/driver-sql` and `@objectstack/objectql` are now derived from the
+spec contract instead of re-declared, so a key added there fails their `tsc`
+until the producer emits it. Two divergences are kept explicitly: `defaultValue`
+stays `unknown` at the SQL layer because Knex reports `null`, and `indexes` is
+omitted rather than emitted empty because this driver does not introspect
+indexes and an empty array would tell a schema differ that a table has none.
+
+TypeScript consumers of the removed member are told by the compiler, precisely
+and at every site: `Property 'isPrimary' does not exist on type
+'IntrospectedColumn'`.
+
+<!-- adr-0087: not-required (runtime-interface-only packages/drivers/driver-sql/src/sql-driver.ts#IntrospectedColumn, packages/drivers/driver-sql/src/sql-driver.ts#IntrospectedSchema, packages/objectql/src/util.ts#IntrospectedColumn, packages/objectql/src/util.ts#IntrospectedSchema) these are published runtime TypeScript interfaces describing a driver's introspection RESULT — not a metadata surface. There is no Zod schema, no `packages/spec` declaration of the old spelling, and no stored representation of it, so `objectstack migrate meta` has nothing to rewrite; the channel that reaches every affected consumer is the compiler. -->

packages/drivers/driver-sql/src/sql-driver-composite-primary-key-introspection.test.ts

@@ -11,8 +11,8 @@
  * the first member of a composite key and silently dropped the rest.
  *
  * Both output signals were wrong together and for the same reason:
- * `introspectSchema` derives `col.isPrimary` FROM `primaryKeys`
- * (`if (primaryKeys.includes(col.name)) col.isPrimary = true`), so a consumer
+ * `introspectSchema` derives `col.primaryKey` FROM `primaryKeys`
+ * (`if (primaryKeys.includes(col.name)) col.primaryKey = true`), so a consumer
  * could not recover the missing member by cross-checking the two. Both are
  * asserted here.
  *
@@ -80,7 +80,7 @@ describe('SqlDriver composite primary-key introspection (SQLite)', () => {
     expect(pkByName).toEqual({ order_id: 1, line_no: 2, sku: 0 });
   });
 
-  it('reports every member of a composite key, and derives isPrimary for all of them', async () => {
+  it('reports every member of a composite key, and derives primaryKey for all of them', async () => {
     await knexInstance.schema.createTable('order_lines', (t: any) => {
       t.string('order_id').notNullable();
       t.integer('line_no').notNullable();
@@ -95,8 +95,8 @@ describe('SqlDriver composite primary-key introspection (SQLite)', () => {
     expect(table.primaryKeys).toEqual(['order_id', 'line_no']);
 
     // Signal 2: the per-column flag, derived FROM signal 1 — repaired with it.
-    const isPrimaryByName = Object.fromEntries(table.columns.map((c) => [c.name, c.isPrimary === true]));
-    expect(isPrimaryByName).toEqual({ order_id: true, line_no: true, sku: false });
+    const primaryKeyByName = Object.fromEntries(table.columns.map((c) => [c.name, c.primaryKey === true]));
+    expect(primaryKeyByName).toEqual({ order_id: true, line_no: true, sku: false });
   });
 
   it('orders primaryKeys by pk ordinal, not by column position', async () => {
@@ -164,7 +164,7 @@ describe('SqlDriver composite primary-key introspection (SQLite)', () => {
     expect(schema.tables['widgets'].primaryKeys).toEqual(['id']);
     expect(schema.tables['audit_lines'].primaryKeys).toEqual([]);
 
-    const auditPrimary = schema.tables['audit_lines'].columns.map((c) => c.isPrimary === true);
+    const auditPrimary = schema.tables['audit_lines'].columns.map((c) => c.primaryKey === true);
     expect(auditPrimary).toEqual([false, false]);
   });
 });

packages/drivers/driver-sql/src/sql-driver-introspection-spec-contract.test.ts

@@ -0,0 +1,105 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * Pin: `SqlDriver.introspectSchema()` emits the `packages/spec` introspection
+ * contract — the shape every consumer downstream of `plugin.ts` is typed
+ * against — and not a second vocabulary of its own.
+ *
+ * The defect this closes was invisible to types on both sides. The driver
+ * declared its own `IntrospectedColumn` spelling key membership `isPrimary?`;
+ * `packages/spec/src/contracts/schema-diff-service.ts` declares `primaryKey`,
+ * `dialect` and a REQUIRED `introspectedAt`. Each side compiled against its
+ * own declaration, the value crossed between them untyped, and the consumer
+ * read keys no driver ever set. Maintainer ruling, 2026-08-22 (live session,
+ * 「同意所有」 item 9 = 驱动侧对齐 spec 契约): the driver aligns to the spec.
+ *
+ * Asserted on the BYTES of a live introspection rather than on a type, because
+ * a type is exactly what failed to catch this: a hand-written fixture in
+ * either spelling is blind to the seam. Only better-sqlite3 is executed here —
+ * every assertion below is on a value built at a single dialect-independent
+ * site in `introspectSchema`, downstream of the per-dialect helpers, so the
+ * SHAPE cannot vary by dialect even though the per-dialect CONTENT is not
+ * measured here.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { SqlDriver } from '../src/index.js';
+
+describe('SqlDriver.introspectSchema emits the spec introspection contract', () => {
+  let driver: SqlDriver;
+  let knexInstance: any;
+
+  beforeEach(async () => {
+    driver = new SqlDriver({
+      client: 'better-sqlite3',
+      connection: { filename: ':memory:' },
+      useNullAsDefault: true,
+    });
+    knexInstance = (driver as unknown as { knex: any }).knex;
+    await knexInstance.schema.createTable('customers', (t: any) => {
+      t.string('id').primary();
+      t.string('name');
+      t.integer('age');
+    });
+  });
+
+  afterEach(async () => {
+    await knexInstance?.destroy();
+  });
+
+  it('spells column key membership `primaryKey`, the spec spelling', async () => {
+    const schema = await driver.introspectSchema();
+    const byName = Object.fromEntries(
+      schema.tables['customers'].columns.map((c) => [c.name, c]),
+    );
+
+    expect(byName.id.primaryKey).toBe(true);
+    // Negative half: an implementation that stamped the key onto the first
+    // column, or onto every column, would satisfy the line above alone.
+    expect(byName.name.primaryKey).toBe(false);
+    expect(byName.age.primaryKey).toBe(false);
+  });
+
+  it('emits `dialect` and the required `introspectedAt`', async () => {
+    const before = Date.now();
+    const schema = await driver.introspectSchema();
+
+    // #10998's acceptance criterion, spelled exactly as it was written: the
+    // producer returned `{ tables }` alone while the contract declares three
+    // keys, so consumers read two nobody set — type mapping ran with no
+    // dialect on the whole federation path, and `refreshCatalog` persisted
+    // `dialect: undefined` into the record Studio and the boot gate read back.
+    expect(Object.keys(schema)).toEqual(
+      expect.arrayContaining(['tables', 'dialect', 'introspectedAt']),
+    );
+
+    // The dialect TOKEN, not merely the key's presence. The consumer is
+    // `suggestFieldTypeForSqlType(col.type, schema.dialect as SqlDialect)`,
+    // whose vocabulary spells these `sqlite` / `postgres` / `mysql`; a token
+    // outside it (`better-sqlite3`, or the spec enum's `postgresql`) would
+    // leave every per-dialect alias unreachable with the key still present.
+    expect(schema.dialect).toBe('sqlite');
+
+    // Required in the contract, so it is emitted unconditionally — and it is a
+    // real ISO 8601 instant, not a placeholder a consumer would have to guard.
+    expect(typeof schema.introspectedAt).toBe('string');
+    expect(new Date(schema.introspectedAt).toISOString()).toBe(schema.introspectedAt);
+    const at = Date.parse(schema.introspectedAt);
+    expect(at).toBeGreaterThanOrEqual(before - 1000);
+    expect(at).toBeLessThanOrEqual(Date.now() + 1000);
+  });
+
+  it('no longer emits the retired `isPrimary` spelling', async () => {
+    const schema = await driver.introspectSchema();
+    const id = schema.tables['customers'].columns.find((c) => c.name === 'id')!;
+
+    // `in`, not a truthiness check: the failure this closes was a consumer
+    // reading a key that was ABSENT, so absence is what has to be pinned. Two
+    // spellings emitted side by side would keep the second contract alive in
+    // the bytes even with both values agreeing today.
+    expect('isPrimary' in id).toBe(false);
+    expect(Object.keys(id)).toEqual(
+      expect.arrayContaining(['name', 'type', 'nullable', 'primaryKey']),
+    );
+  });
+});

packages/drivers/driver-sql/src/sql-driver.ts

@@ -8,6 +8,14 @@
  */
 
 import type { DriverOptions, FilterCondition, SchemaMode } from '@objectstack/spec/data';
+// The ONE introspection contract (ADR-0015 / `ISchemaDiffService`). This
+// driver's introspection types are DERIVED from these rather than
+// re-declared next to them — see the `Introspection Types` region below.
+import type {
+  IntrospectedColumn as SpecIntrospectedColumn,
+  IntrospectedSchema as SpecIntrospectedSchema,
+  IntrospectedTable as SpecIntrospectedTable,
+} from '@objectstack/spec/contracts';
 import { parseAutonumberFormat, renderAutonumber, resolveAutonumberFormat, readAutonumberCounter, missingFieldValues, isTenancyDisabled, type AutonumberToken } from '@objectstack/spec/data';
 // The DECLARED aggregate vocabulary (#5907). Read from the spec so this driver's
 // "the protocol has no such function" refusal cannot drift from what
@@ -3645,31 +3653,76 @@ function nullSafeNegationOperand(node: Record<string, unknown>): Record<string,
 
 // ── Introspection Types ──────────────────────────────────────────────────────
 
-export interface IntrospectedColumn {
-  name: string;
-  type: string;
-  nullable: boolean;
+/**
+ * These are DERIVED from `packages/spec/src/contracts/schema-diff-service.ts`,
+ * never re-declared beside it.
+ *
+ * They used to be a second, independent declaration that happened to describe
+ * the same idea in a different vocabulary: this file spelled a column's key
+ * membership `isPrimary?`, the spec spells it `primaryKey`; the spec also
+ * declares `dialect` and a REQUIRED `introspectedAt` that this file's schema
+ * type did not mention and `introspectSchema` therefore never emitted. `plugin.ts` hands
+ * this driver's result straight to `ExternalDatasourceService`, which is typed
+ * against the spec — so the consumer read a key no driver ever set and every
+ * federated object drafted from a remote table silently lost its primary key.
+ * Nothing was type-unsound; the two contracts simply never met a compiler.
+ *
+ * Maintainer ruling, 2026-08-22 (live session, 「同意所有」 item 9 =
+ * 驱动侧对齐 spec 契约): `packages/spec` is the one contract and the DRIVER
+ * aligns to it. Deriving rather than copying is what makes that mechanical —
+ * a key added to the spec contract now fails this file's `tsc` until the
+ * driver emits it, which is exactly the failure that was missing.
+ *
+ * Two divergences remain, deliberately, and neither is a second spelling of
+ * something the spec declares:
+ *
+ *  - the SQL layer carries EXTRA per-column facts (`isUnique`, `maxLength`)
+ *    and extra per-table facts (`foreignKeys`, `primaryKeys`) that the spec's
+ *    diff-facing contract does not declare;
+ *  - `defaultValue` is `unknown` here rather than the spec's `string`, because
+ *    that is what Knex's `columnInfo()` actually returns (measured on live
+ *    SQLite: `null`). Narrowing the declaration without normalising the value
+ *    would move the lie rather than remove it.
+ */
+export interface IntrospectedColumn extends Omit<SpecIntrospectedColumn, 'defaultValue'> {
+  /** Raw driver-reported default. See the note above on why this is not `string`. */
   defaultValue?: unknown;
-  isPrimary?: boolean;
+  /** SQL-introspection extra: the column carries a UNIQUE constraint. */
   isUnique?: boolean;
+  /** SQL-introspection extra: declared maximum length for string types. */
   maxLength?: number;
 }
 
+/** No spec counterpart — foreign keys are a SQL-introspection extra. */
 export interface IntrospectedForeignKey {
   columnName: string;
   referencedTable: string;
   referencedColumn: string;
   constraintName?: string;
 }
 
-export interface IntrospectedTable {
-  name: string;
+/**
+ * `indexes` is `Omit`ted from the spec table rather than emitted empty: this
+ * driver does not introspect indexes, and `indexes: []` would tell a schema
+ * differ that a table HAS none when it merely was not asked — a worse answer
+ * than an absent key. Emitting them for real is per-dialect work over arms
+ * this container cannot execute, so it is filed rather than guessed.
+ */
+export interface IntrospectedTable extends Omit<SpecIntrospectedTable, 'columns' | 'indexes'> {
   columns: IntrospectedColumn[];
+  /** SQL-introspection extra: outbound foreign keys. */
   foreignKeys: IntrospectedForeignKey[];
+  /** SQL-introspection extra: the table's primary-key columns, in key order. */
   primaryKeys: string[];
 }
 
-export interface IntrospectedSchema {
+/**
+ * `dialect` and `introspectedAt` are inherited from the spec contract, where
+ * `introspectedAt` is REQUIRED — so `tsc` now refuses an `introspectSchema`
+ * that omits them, which is the check that was missing while this type
+ * declared `{ tables }` alone.
+ */
+export interface IntrospectedSchema extends Omit<SpecIntrospectedSchema, 'tables'> {
   tables: Record<string, IntrospectedTable>;
 }
 
@@ -9798,6 +9851,10 @@ export class SqlDriver implements IDataDriver {
 
   async introspectSchema(): Promise<IntrospectedSchema> {
     const tables: Record<string, IntrospectedTable> = {};
+    // Stamped BEFORE the reads, not after: a consumer asking "has the remote
+    // changed since this snapshot?" must not be told the snapshot covers a
+    // moment later than the first table it actually read.
+    const introspectedAt = new Date().toISOString();
     let tableNames: string[] = [];
 
     if (this.isPostgres) {
@@ -9837,14 +9894,22 @@ export class SqlDriver implements IDataDriver {
       const uniqueConstraints = await this.introspectUniqueConstraints(tableName);
 
       for (const col of columns) {
-        if (primaryKeys.includes(col.name)) col.isPrimary = true;
+        if (primaryKeys.includes(col.name)) col.primaryKey = true;
         if (uniqueConstraints.includes(col.name)) col.isUnique = true;
       }
 
       tables[tableName] = { name: tableName, columns, foreignKeys, primaryKeys };
     }
 
-    return { tables };
+    // `dialectName` — not the raw Knex client, and not the spec's
+    // `SQLDialectSchema` enum. The only in-tree consumer of this key is
+    // `suggestFieldTypeForSqlType(col.type, schema.dialect as SqlDialect)`,
+    // whose `SqlDialect` vocabulary (`packages/spec/src/data/type-compat.ts`)
+    // spells PostgreSQL `postgres`, exactly as `dialectName` does. Emitting
+    // the enum's `postgresql` instead would put the key in `Object.keys()`
+    // while leaving every per-dialect type alias unreachable — the omission
+    // this repairs, wearing a fix's clothes.
+    return { tables, dialect: this.dialectName, introspectedAt };
   }
 
   // ===================================
@@ -12548,7 +12613,9 @@ export class SqlDriver implements IDataDriver {
         type,
         nullable: info.nullable !== false,
         defaultValue: info.defaultValue,
-        isPrimary: false,
+        // The spec contract's spelling, and the only one this driver emits.
+        // `introspectSchema` flips it from the table's key list below.
+        primaryKey: false,
         isUnique: false,
         maxLength,
       });
@@ -12695,7 +12762,7 @@ export class SqlDriver implements IDataDriver {
         // of the key", `1` for the first key column, `2` for the second, and so
         // on. Filtering on `pk === 1` therefore kept only the first member of a
         // composite key and silently dropped the rest, and because
-        // `introspectSchema` derives `col.isPrimary` FROM this list, both output
+        // `introspectSchema` derives `col.primaryKey` FROM this list, both output
         // signals were wrong together.
         //
         // Ordering by the ordinal (rather than taking `table_info`'s row order,