@telorun/sql 0.22.0 → 0.22.1

package/dist/index.d.ts

@@ -19,6 +19,7 @@ export type { PlannedStatement, PlannedTombstone, SchemaPlan } from "./schema/sc
 export { migrationStatements, pendingKeys } from "./schema/migration-runner.js";
 export type { MigrationEntry, MigrationMap } from "./schema/migration-runner.js";
 export { normalizeTable } from "./schema/normalize-table.js";
-export type { RawColumn, RawForeignKey, RawIndex, RawTable } from "./schema/normalize-table.js";
+export { tableReferenceResolver } from "./schema/table-reference.js";
+export type { RawColumn, RawForeignKey, RawIndex, RawTable, TableReferenceResolver, } from "./schema/normalize-table.js";
 export { runSchemaPass } from "./schema/schema-run.js";
 export type { PendingReclamation, SchemaRunInput, SchemaRunStatus } from "./schema/schema-run.js";

package/dist/index.js

@@ -15,4 +15,5 @@ export { snapshotDeclaration, snapshotDigest } from "./schema/declaration-snapsh
 export { planReconciliation } from "./schema/schema-reconciler.js";
 export { migrationStatements, pendingKeys } from "./schema/migration-runner.js";
 export { normalizeTable } from "./schema/normalize-table.js";
+export { tableReferenceResolver } from "./schema/table-reference.js";
 export { runSchemaPass } from "./schema/schema-run.js";

package/dist/schema/normalize-table.d.ts

@@ -43,4 +43,15 @@ export interface RawTable {
     readonly indexes?: Record<string, RawIndex>;
     readonly foreignKeys?: Record<string, RawForeignKey>;
 }
-export declare function normalizeTable(raw: RawTable): DeclaredTable;
+/**
+ * Turns whatever sits at a `references.table` slot into the referenced table's
+ * physical name.
+ *
+ * REQUIRED rather than optional: a `!ref` is not resolved when a controller is
+ * constructed — Phase-5 injection runs after `create()` returns — so a caller
+ * that omitted one would read the sentinel and reproduce, silently, the exact
+ * defect this parameter exists to fix. `tableReferenceResolver` is the one every
+ * backend uses.
+ */
+export type TableReferenceResolver = (value: unknown, fk: string) => string;
+export declare function normalizeTable(raw: RawTable, resolveReference: TableReferenceResolver): DeclaredTable;

package/dist/schema/normalize-table.js

@@ -45,16 +45,6 @@ function normalizeColumn(name, raw) {
         renamedFrom: raw.renamedFrom,
     };
 }
-/** A `references.table` is a `!ref` to another table resource, injected as the
- *  live instance by the time a controller reads it. */
-function referencedTableName(value, fk) {
-    if (typeof value === "string")
-        return value;
-    const table = value?.table;
-    if (typeof table === "string")
-        return table;
-    throw new Error(`foreign key '${fk}': 'references.table' does not name a table`);
-}
 /**
  * Structural checks over one declaration, at resource creation — before any
  * connection is opened, let alone any DDL planned.
@@ -111,7 +101,7 @@ function validateTable(table) {
         }
     }
 }
-export function normalizeTable(raw) {
+export function normalizeTable(raw, resolveReference) {
     const columns = Object.entries(raw.columns ?? {}).map(([name, column]) => normalizeColumn(name, column));
     const indexes = Object.entries(raw.indexes ?? {}).map(([name, index]) => ({
         name,
@@ -123,7 +113,7 @@ export function normalizeTable(raw) {
         name,
         columns: [...fk.columns],
         references: {
-            table: referencedTableName(fk.references.table, name),
+            table: resolveReference(fk.references.table, name),
             columns: [...fk.references.columns],
         },
         onDelete: fk.onDelete,

package/dist/schema/schema-driver.d.ts

@@ -137,6 +137,29 @@ export interface SchemaDriver {
     classifyIndexChange(live: LiveIndex, declared: DeclaredIndex): ChangeSafety;
     /** Whether a foreign key can be brought to its declaration in place. */
     classifyForeignKeyChange(live: LiveForeignKey, declared: DeclaredForeignKey): ChangeSafety;
+    /**
+     * Whether `createTable` already carries the table's foreign keys, so the
+     * reconciler must not also plan an `addForeignKey` for a table it just made.
+     *
+     * REQUIRED, like every other member here, because the wrong answer is silent:
+     * a driver that omitted it would get name matching by default, and if its
+     * engine also emits keys inside `CREATE TABLE` it would get exactly the
+     * unrestartable application this member exists to prevent — with no compile
+     * error and no failing test. Stating an answer is the point.
+     */
+    readonly foreignKeysInCreateTable: boolean;
+    /**
+     * Whether the engine reports a foreign key back under the name the
+     * declaration gave it.
+     *
+     * Separate from `foreignKeysInCreateTable` because they are separate facts and
+     * an engine can hold one without the other: MySQL emits keys inside `CREATE
+     * TABLE` and names them. Where this is false a declaration is matched to a
+     * live key by its columns, target and referential actions, since there is no
+     * name to match on and matching by one reads a table's own key as missing on
+     * every boot after the one that created it.
+     */
+    readonly namesForeignKeys: boolean;
     createTable(schema: string, table: DeclaredTable): string[];
     addColumn(schema: string, table: string, column: DeclaredColumn): string[];
     alterColumn(schema: string, table: string, live: LiveColumn, column: DeclaredColumn): string[];

package/dist/schema/schema-reconciler.js

@@ -27,6 +27,20 @@ function indexDiffers(live, declared) {
 /** A referential action is what the constraint DOES, so a change to it is a
  *  change to the constraint. An action the engine did not report is not compared
  *  — an absent reading is not evidence of a difference. */
+/**
+ * The columns a key maps to what, which is what makes it THAT key rather than
+ * another. Its referential actions are settable properties of it, deliberately
+ * excluded: an engine that keeps no name matches on this, and folding the
+ * actions in would make a changed delete rule read as a brand new key — an ADD
+ * where the author should have been told the rule cannot be changed in place.
+ */
+function sameForeignKeyIdentity(live, declared) {
+    return (live.references.table === declared.references.table &&
+        live.columns.length === declared.columns.length &&
+        live.columns.every((column, i) => column === declared.columns[i]) &&
+        live.references.columns.length === declared.references.columns.length &&
+        live.references.columns.every((column, i) => column === declared.references.columns[i]));
+}
 function foreignKeyDiffers(live, declared) {
     const action = (value) => value?.toUpperCase();
     return (live.references.table !== declared.references.table ||
@@ -166,10 +180,29 @@ export function planReconciliation(driver, schema, declared, live, owned, tombst
                 ...driver.createIndex(schema, table.name, index),
             ]);
         }
-        const liveForeignKeys = new Map((liveTable?.foreignKeys ?? []).map((fk) => [fk.name, fk]));
+        // A table this pass just created already carries its keys where the engine
+        // can only emit them there. They are still MARKED declared, or the next boot
+        // would read every one of them as removed and tombstone it.
+        const carriedByCreate = !liveTable && driver.foreignKeysInCreateTable;
+        // Where the engine keeps no name, a declaration is matched to a live key by
+        // its structure. Matching by name regardless is what made such a table
+        // unrestartable: every later boot read its own key as missing and refused to
+        // add what the engine cannot add. Matches are CONSUMED, so two keys that are
+        // structurally identical pair up one for one instead of both claiming the
+        // first.
+        const unmatched = [...(liveTable?.foreignKeys ?? [])];
+        const liveForeignKeys = new Map(unmatched.map((fk) => [fk.name, fk]));
+        const takeStructural = (fk) => {
+            const at = unmatched.findIndex((live) => sameForeignKeyIdentity(live, fk));
+            return at < 0 ? undefined : unmatched.splice(at, 1)[0];
+        };
         for (const fk of table.foreignKeys) {
             markDeclared({ kind: "foreignKey", table: table.name, name: fk.name });
-            const existing = liveForeignKeys.get(fk.name);
+            if (carriedByCreate)
+                continue;
+            const existing = driver.namesForeignKeys
+                ? liveForeignKeys.get(fk.name)
+                : takeStructural(fk);
             if (!existing) {
                 emit("constraint", `foreign key ${fk.name}`, driver.addForeignKey(schema, table.name, fk));
                 continue;

package/dist/schema/table-reference.d.ts

@@ -0,0 +1,25 @@
+import type { ResourceContext } from "@telorun/sdk";
+import type { TableReferenceResolver } from "./normalize-table.js";
+/**
+ * Resolves a `references.table` slot to the referenced table's physical name.
+ *
+ * **BOTH shapes arrive, and which one is a race.** A table reads this slot while
+ * it is being CREATED, and Phase-5 injection replaces a reference only when the
+ * target is already registered — a local ref naming nothing pending is left
+ * exactly as written. So the same manifest hands over a live instance on one
+ * pass of the init loop and the raw `{ kind, name }` on another, and reading
+ * only the instance is what made every cross-table foreign key fail outright.
+ *
+ * The reference is resolved to the target's DECLARATION, which carries the one
+ * thing a foreign key needs from it — the physical name — and carries it whether
+ * or not the target has been constructed. That is also why the slot stays
+ * `use: schema` and registers no ordering edge: nothing here requires the
+ * referenced table to exist first, and an edge would make a tree table (which
+ * references ITSELF) and a mutual pair into init cycles, though both are
+ * perfectly creatable on an engine that emits keys after every table.
+ *
+ * A plain string is accepted for an internal caller that already holds a name;
+ * an author cannot write one, since a ref slot rejects a bare string
+ * (`INVALID_REFERENCE_FORM`).
+ */
+export declare function tableReferenceResolver(ctx: ResourceContext, kind: string, table: string): TableReferenceResolver;

package/dist/schema/table-reference.js

@@ -0,0 +1,61 @@
+function asRef(value) {
+    const ref = value;
+    if (!ref || typeof ref !== "object" || typeof ref.name !== "string")
+        return undefined;
+    return { name: ref.name, alias: typeof ref.alias === "string" ? ref.alias : undefined };
+}
+/**
+ * Resolves a `references.table` slot to the referenced table's physical name.
+ *
+ * **BOTH shapes arrive, and which one is a race.** A table reads this slot while
+ * it is being CREATED, and Phase-5 injection replaces a reference only when the
+ * target is already registered — a local ref naming nothing pending is left
+ * exactly as written. So the same manifest hands over a live instance on one
+ * pass of the init loop and the raw `{ kind, name }` on another, and reading
+ * only the instance is what made every cross-table foreign key fail outright.
+ *
+ * The reference is resolved to the target's DECLARATION, which carries the one
+ * thing a foreign key needs from it — the physical name — and carries it whether
+ * or not the target has been constructed. That is also why the slot stays
+ * `use: schema` and registers no ordering edge: nothing here requires the
+ * referenced table to exist first, and an edge would make a tree table (which
+ * references ITSELF) and a mutual pair into init cycles, though both are
+ * perfectly creatable on an engine that emits keys after every table.
+ *
+ * A plain string is accepted for an internal caller that already holds a name;
+ * an author cannot write one, since a ref slot rejects a bare string
+ * (`INVALID_REFERENCE_FORM`).
+ */
+export function tableReferenceResolver(ctx, kind, table) {
+    return (value, fk) => {
+        if (typeof value === "string")
+            return value;
+        const where = `${kind} '${table}': foreign key '${fk}': 'references.table'`;
+        const ref = asRef(value);
+        if (ref) {
+            const declared = ctx.resolveDeclaredManifest?.(ref.name, ref.alias);
+            if (!declared) {
+                throw new Error(`${where} names '${ref.name}', which resolves to no declared resource. A foreign key ` +
+                    `reads its target from that resource's DECLARATION, so the table it names has to be ` +
+                    `declared in a scope this one can see.`);
+            }
+            // The kind is constrained statically by `x-telo-ref`, so this is a
+            // backstop — but one that must not accept the wrong kind, since any
+            // resource carrying a `table` field would otherwise put a wrong
+            // identifier into DDL.
+            if (declared.kind !== kind) {
+                throw new Error(`${where} names '${ref.name}', which is a ${declared.kind}, not a ${kind}.`);
+            }
+            if (typeof declared.table !== "string") {
+                throw new Error(`${where} names '${ref.name}', which declares no 'table'.`);
+            }
+            return declared.table;
+        }
+        // Injection won the race: the slot holds the live table resource, which
+        // reports the same name its declaration carries.
+        const injected = value?.table;
+        if (typeof injected === "string")
+            return injected;
+        throw new Error(`${where} is not a reference to a ${kind}.`);
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/sql",
-  "version": "0.22.0",
+  "version": "0.22.1",
   "description": "Telo SQL module - SQL database resource kinds for Telo manifests.",
   "keywords": [
     "telo",
@@ -44,7 +44,7 @@
     "esbuild": "^0.25.12",
     "typescript": "^5.0.0",
     "vitest": "^2.1.8",
-    "@telorun/sdk": "0.79.0"
+    "@telorun/sdk": "0.80.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"

package/src/index.ts

@@ -47,6 +47,13 @@ export type { PlannedStatement, PlannedTombstone, SchemaPlan } from "./schema/sc
 export { migrationStatements, pendingKeys } from "./schema/migration-runner.js";
 export type { MigrationEntry, MigrationMap } from "./schema/migration-runner.js";
 export { normalizeTable } from "./schema/normalize-table.js";
-export type { RawColumn, RawForeignKey, RawIndex, RawTable } from "./schema/normalize-table.js";
+export { tableReferenceResolver } from "./schema/table-reference.js";
+export type {
+  RawColumn,
+  RawForeignKey,
+  RawIndex,
+  RawTable,
+  TableReferenceResolver,
+} from "./schema/normalize-table.js";
 export { runSchemaPass } from "./schema/schema-run.js";
 export type { PendingReclamation, SchemaRunInput, SchemaRunStatus } from "./schema/schema-run.js";

package/src/schema/normalize-table.ts

@@ -109,14 +109,17 @@ function normalizeColumn(name: string, raw: RawColumn): DeclaredColumn {
   };
 }
 
-/** A `references.table` is a `!ref` to another table resource, injected as the
- *  live instance by the time a controller reads it. */
-function referencedTableName(value: unknown, fk: string): string {
-  if (typeof value === "string") return value;
-  const table = (value as { table?: unknown } | null)?.table;
-  if (typeof table === "string") return table;
-  throw new Error(`foreign key '${fk}': 'references.table' does not name a table`);
-}
+/**
+ * Turns whatever sits at a `references.table` slot into the referenced table's
+ * physical name.
+ *
+ * REQUIRED rather than optional: a `!ref` is not resolved when a controller is
+ * constructed — Phase-5 injection runs after `create()` returns — so a caller
+ * that omitted one would read the sentinel and reproduce, silently, the exact
+ * defect this parameter exists to fix. `tableReferenceResolver` is the one every
+ * backend uses.
+ */
+export type TableReferenceResolver = (value: unknown, fk: string) => string;
 
 /**
  * Structural checks over one declaration, at resource creation — before any
@@ -190,7 +193,10 @@ function validateTable(table: DeclaredTable): void {
   }
 }
 
-export function normalizeTable(raw: RawTable): DeclaredTable {
+export function normalizeTable(
+  raw: RawTable,
+  resolveReference: TableReferenceResolver,
+): DeclaredTable {
   const columns = Object.entries(raw.columns ?? {}).map(([name, column]) =>
     normalizeColumn(name, column),
   );
@@ -205,7 +211,7 @@ export function normalizeTable(raw: RawTable): DeclaredTable {
       name,
       columns: [...fk.columns],
       references: {
-        table: referencedTableName(fk.references.table, name),
+        table: resolveReference(fk.references.table, name),
         columns: [...fk.references.columns],
       },
       onDelete: fk.onDelete,

package/src/schema/schema-driver.ts

@@ -156,6 +156,31 @@ export interface SchemaDriver {
   /** Whether a foreign key can be brought to its declaration in place. */
   classifyForeignKeyChange(live: LiveForeignKey, declared: DeclaredForeignKey): ChangeSafety;
 
+  /**
+   * Whether `createTable` already carries the table's foreign keys, so the
+   * reconciler must not also plan an `addForeignKey` for a table it just made.
+   *
+   * REQUIRED, like every other member here, because the wrong answer is silent:
+   * a driver that omitted it would get name matching by default, and if its
+   * engine also emits keys inside `CREATE TABLE` it would get exactly the
+   * unrestartable application this member exists to prevent — with no compile
+   * error and no failing test. Stating an answer is the point.
+   */
+  readonly foreignKeysInCreateTable: boolean;
+
+  /**
+   * Whether the engine reports a foreign key back under the name the
+   * declaration gave it.
+   *
+   * Separate from `foreignKeysInCreateTable` because they are separate facts and
+   * an engine can hold one without the other: MySQL emits keys inside `CREATE
+   * TABLE` and names them. Where this is false a declaration is matched to a
+   * live key by its columns, target and referential actions, since there is no
+   * name to match on and matching by one reads a table's own key as missing on
+   * every boot after the one that created it.
+   */
+  readonly namesForeignKeys: boolean;
+
   createTable(schema: string, table: DeclaredTable): string[];
   addColumn(schema: string, table: string, column: DeclaredColumn): string[];
   alterColumn(schema: string, table: string, live: LiveColumn, column: DeclaredColumn): string[];

package/src/schema/schema-reconciler.ts

@@ -96,6 +96,23 @@ function indexDiffers(live: LiveIndex, declared: DeclaredIndex): boolean {
 /** A referential action is what the constraint DOES, so a change to it is a
  *  change to the constraint. An action the engine did not report is not compared
  *  — an absent reading is not evidence of a difference. */
+/**
+ * The columns a key maps to what, which is what makes it THAT key rather than
+ * another. Its referential actions are settable properties of it, deliberately
+ * excluded: an engine that keeps no name matches on this, and folding the
+ * actions in would make a changed delete rule read as a brand new key — an ADD
+ * where the author should have been told the rule cannot be changed in place.
+ */
+function sameForeignKeyIdentity(live: LiveForeignKey, declared: DeclaredForeignKey): boolean {
+  return (
+    live.references.table === declared.references.table &&
+    live.columns.length === declared.columns.length &&
+    live.columns.every((column, i) => column === declared.columns[i]) &&
+    live.references.columns.length === declared.references.columns.length &&
+    live.references.columns.every((column, i) => column === declared.references.columns[i])
+  );
+}
+
 function foreignKeyDiffers(live: LiveForeignKey, declared: DeclaredForeignKey): boolean {
   const action = (value: string | undefined): string | undefined => value?.toUpperCase();
   return (
@@ -259,12 +276,28 @@ export function planReconciliation(
       ]);
     }
 
-    const liveForeignKeys = new Map(
-      (liveTable?.foreignKeys ?? []).map((fk) => [fk.name, fk]),
-    );
+    // A table this pass just created already carries its keys where the engine
+    // can only emit them there. They are still MARKED declared, or the next boot
+    // would read every one of them as removed and tombstone it.
+    const carriedByCreate = !liveTable && driver.foreignKeysInCreateTable;
+    // Where the engine keeps no name, a declaration is matched to a live key by
+    // its structure. Matching by name regardless is what made such a table
+    // unrestartable: every later boot read its own key as missing and refused to
+    // add what the engine cannot add. Matches are CONSUMED, so two keys that are
+    // structurally identical pair up one for one instead of both claiming the
+    // first.
+    const unmatched = [...(liveTable?.foreignKeys ?? [])];
+    const liveForeignKeys = new Map(unmatched.map((fk) => [fk.name, fk]));
+    const takeStructural = (fk: DeclaredForeignKey): LiveForeignKey | undefined => {
+      const at = unmatched.findIndex((live) => sameForeignKeyIdentity(live, fk));
+      return at < 0 ? undefined : unmatched.splice(at, 1)[0];
+    };
     for (const fk of table.foreignKeys) {
       markDeclared({ kind: "foreignKey", table: table.name, name: fk.name });
-      const existing = liveForeignKeys.get(fk.name);
+      if (carriedByCreate) continue;
+      const existing = driver.namesForeignKeys
+        ? liveForeignKeys.get(fk.name)
+        : takeStructural(fk);
       if (!existing) {
         emit("constraint", `foreign key ${fk.name}`, driver.addForeignKey(schema, table.name, fk));
         continue;

package/src/schema/table-reference.ts

@@ -0,0 +1,78 @@
+import type { ResourceContext } from "@telorun/sdk";
+import type { TableReferenceResolver } from "./normalize-table.js";
+
+/** A `!ref` as it reaches a controller when Phase-5 injection has not replaced
+ *  it: rewritten from the YAML tag to `{ kind, name, alias? }` at load. */
+interface TableRef {
+  readonly name?: unknown;
+  readonly alias?: unknown;
+}
+
+function asRef(value: unknown): { name: string; alias?: string } | undefined {
+  const ref = value as TableRef | null;
+  if (!ref || typeof ref !== "object" || typeof ref.name !== "string") return undefined;
+  return { name: ref.name, alias: typeof ref.alias === "string" ? ref.alias : undefined };
+}
+
+/**
+ * Resolves a `references.table` slot to the referenced table's physical name.
+ *
+ * **BOTH shapes arrive, and which one is a race.** A table reads this slot while
+ * it is being CREATED, and Phase-5 injection replaces a reference only when the
+ * target is already registered — a local ref naming nothing pending is left
+ * exactly as written. So the same manifest hands over a live instance on one
+ * pass of the init loop and the raw `{ kind, name }` on another, and reading
+ * only the instance is what made every cross-table foreign key fail outright.
+ *
+ * The reference is resolved to the target's DECLARATION, which carries the one
+ * thing a foreign key needs from it — the physical name — and carries it whether
+ * or not the target has been constructed. That is also why the slot stays
+ * `use: schema` and registers no ordering edge: nothing here requires the
+ * referenced table to exist first, and an edge would make a tree table (which
+ * references ITSELF) and a mutual pair into init cycles, though both are
+ * perfectly creatable on an engine that emits keys after every table.
+ *
+ * A plain string is accepted for an internal caller that already holds a name;
+ * an author cannot write one, since a ref slot rejects a bare string
+ * (`INVALID_REFERENCE_FORM`).
+ */
+export function tableReferenceResolver(
+  ctx: ResourceContext,
+  kind: string,
+  table: string,
+): TableReferenceResolver {
+  return (value, fk) => {
+    if (typeof value === "string") return value;
+    const where = `${kind} '${table}': foreign key '${fk}': 'references.table'`;
+
+    const ref = asRef(value);
+    if (ref) {
+      const declared = ctx.resolveDeclaredManifest?.(ref.name, ref.alias);
+      if (!declared) {
+        throw new Error(
+          `${where} names '${ref.name}', which resolves to no declared resource. A foreign key ` +
+            `reads its target from that resource's DECLARATION, so the table it names has to be ` +
+            `declared in a scope this one can see.`,
+        );
+      }
+      // The kind is constrained statically by `x-telo-ref`, so this is a
+      // backstop — but one that must not accept the wrong kind, since any
+      // resource carrying a `table` field would otherwise put a wrong
+      // identifier into DDL.
+      if (declared.kind !== kind) {
+        throw new Error(`${where} names '${ref.name}', which is a ${declared.kind}, not a ${kind}.`);
+      }
+      if (typeof declared.table !== "string") {
+        throw new Error(`${where} names '${ref.name}', which declares no 'table'.`);
+      }
+      return declared.table;
+    }
+
+    // Injection won the race: the slot holds the live table resource, which
+    // reports the same name its declaration carries.
+    const injected = (value as { table?: unknown } | null)?.table;
+    if (typeof injected === "string") return injected;
+
+    throw new Error(`${where} is not a reference to a ${kind}.`);
+  };
+}