@telorun/sql 0.21.3 → 0.22.1

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/dist/sql-connection-base.d.ts

@@ -20,6 +20,7 @@ export declare abstract class SqlConnectionBase implements SqlConnection {
     teardown(): Promise<void>;
     runInTransaction<T>(body: (bind: (entry: ZoneEntry) => void) => Promise<T>): Promise<T>;
     hasOpenTransaction(ctx?: InvokeContext): boolean;
+    bindsZone(zone: ZoneEntry): boolean;
     /**
      * Every statement this connection runs funnels through here — `executeTemplate`
      * and `executeScript` both delegate — so it is the single instrumentation point.
@@ -33,6 +34,26 @@ export declare abstract class SqlConnectionBase implements SqlConnection {
      * the hottest thing this module does.
      */
     execute<T>(sql: string, params?: unknown[], zone?: ZoneEntry, ctx?: InvokeContext): Promise<QueryResult<T>>;
+    /** The single instrumentation point, shared by every path that runs a
+     *  statement. The disabled branch allocates nothing and takes no clock
+     *  reading — a query is the hottest thing this module does. */
+    private instrument;
+    /**
+     * Run a statement on the CONNECTION, never on an ambient transaction.
+     *
+     * The complement of {@link resolveExecutor}, and it exists because "joins
+     * whatever transaction is open" is the right default and the wrong one for a
+     * particular class of write: a record ABOUT the work rather than part of it.
+     * A durable journal settling a run is the case that forced it — a settlement
+     * discarded by the caller's rollback leaves a run recorded as still executing
+     * while its effects are gone, and a claim that rolls back releases a run
+     * another poller may already hold.
+     *
+     * On the contract rather than left to each caller to reach for `kysely`,
+     * because the escape hatch is the same for everyone and a caller that reaches
+     * past `execute` also loses its instrumentation — this keeps both.
+     */
+    executeUncommitted<T>(sql: string, params?: unknown[]): Promise<QueryResult<T>>;
     executeTemplate<T>(fragments: string[], values: unknown[], zone?: ZoneEntry, ctx?: InvokeContext): Promise<QueryResult<T>>;
     /** Hand the whole script to the driver as one statement. Backends whose driver
      *  needs a dedicated multi-statement entry point override this. */

package/dist/sql-connection-base.js

@@ -54,6 +54,9 @@ export class SqlConnectionBase {
     hasOpenTransaction(ctx) {
         return this.ctx.zonesFor(this, ctx).some((entry) => this.#executors.has(entry));
     }
+    bindsZone(zone) {
+        return this.#executors.has(zone);
+    }
     /**
      * Every statement this connection runs funnels through here — `executeTemplate`
      * and `executeScript` both delegate — so it is the single instrumentation point.
@@ -68,11 +71,16 @@ export class SqlConnectionBase {
      */
     async execute(sql, params = [], zone, ctx) {
         const executor = this.resolveExecutor(zone, ctx);
-        if (!this.ctx.log.enabled(SEVERITY.debug)) {
-            return executor.executeQuery(CompiledQuery.raw(sql, params));
-        }
+        return this.instrument(sql, () => executor.executeQuery(CompiledQuery.raw(sql, params)));
+    }
+    /** The single instrumentation point, shared by every path that runs a
+     *  statement. The disabled branch allocates nothing and takes no clock
+     *  reading — a query is the hottest thing this module does. */
+    async instrument(sql, run) {
+        if (!this.ctx.log.enabled(SEVERITY.debug))
+            return run();
         const startedAt = Date.now();
-        const result = await executor.executeQuery(CompiledQuery.raw(sql, params));
+        const result = await run();
         this.ctx.log.debug("Statement executed", {
             "db.query.text": sql,
             "db.response.returned_rows": result.rows.length,
@@ -85,6 +93,24 @@ export class SqlConnectionBase {
         });
         return result;
     }
+    /**
+     * Run a statement on the CONNECTION, never on an ambient transaction.
+     *
+     * The complement of {@link resolveExecutor}, and it exists because "joins
+     * whatever transaction is open" is the right default and the wrong one for a
+     * particular class of write: a record ABOUT the work rather than part of it.
+     * A durable journal settling a run is the case that forced it — a settlement
+     * discarded by the caller's rollback leaves a run recorded as still executing
+     * while its effects are gone, and a claim that rolls back releases a run
+     * another poller may already hold.
+     *
+     * On the contract rather than left to each caller to reach for `kysely`,
+     * because the escape hatch is the same for everyone and a caller that reaches
+     * past `execute` also loses its instrumentation — this keeps both.
+     */
+    async executeUncommitted(sql, params = []) {
+        return this.instrument(sql, () => this.db.executeQuery(CompiledQuery.raw(sql, params)));
+    }
     async executeTemplate(fragments, values, zone, ctx) {
         let sql = fragments[0] ?? "";
         for (let i = 1; i < fragments.length; i++) {

package/dist/sql-connection.d.ts

@@ -42,6 +42,14 @@ export interface SqlConnection extends ResourceInstance {
     /** Assemble SQL from literal fragments by interleaving dialect-native
      *  placeholders, then bind `values` positionally. */
     executeTemplate<T>(fragments: string[], values: unknown[], zone?: ZoneEntry, ctx?: InvokeContext): Promise<QueryResult<T>>;
+    /**
+     * Run a statement on the CONNECTION, never on an ambient transaction.
+     *
+     * For a write that is a record ABOUT the work rather than part of it, and so
+     * must survive whatever the work was doing — a durable journal settling a run,
+     * releasing a claim. Everything else should use {@link execute} and join.
+     */
+    executeUncommitted<T>(sql: string, params?: unknown[]): Promise<QueryResult<T>>;
     /** Run a multi-statement script. */
     executeScript(sql: string): Promise<void>;
     /** Open a database transaction and hand the caller a `bind` that keys the
@@ -51,6 +59,17 @@ export interface SqlConnection extends ResourceInstance {
     /** True when an ambient transaction zone correlated on this connection has an
      *  open executor here — the flat-nesting check `Sql.Transaction` reuses. */
     hasOpenTransaction(ctx?: InvokeContext): boolean;
+    /**
+     * Does THIS connection hold the open executor for THIS zone?
+     *
+     * The named zone rather than whatever is ambient, which is what an attestation
+     * needs: a caller asking whether its own writes land inside a particular
+     * region gets a wrong answer from an ambient check the moment a second
+     * transaction is open somewhere in the stack. `hasOpenTransaction` answers the
+     * dispatch-time question ("is there one to execute on"); this answers the
+     * membership question ("is it that one").
+     */
+    bindsZone(zone: ZoneEntry): boolean;
     /** Rows affected by a write, normalized across drivers. */
     toRowCount(result: QueryResult<unknown>): number;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@telorun/sql",
-  "version": "0.21.3",
+  "version": "0.22.1",
   "description": "Telo SQL module - SQL database resource kinds for Telo manifests.",
   "keywords": [
     "telo",
@@ -43,12 +43,14 @@
     "@types/node": "^20.0.0",
     "esbuild": "^0.25.12",
     "typescript": "^5.0.0",
-    "@telorun/sdk": "0.77.0"
+    "vitest": "^2.1.8",
+    "@telorun/sdk": "0.80.0"
   },
   "peerDependencies": {
     "@telorun/sdk": "*"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.lib.json"
+    "build": "tsc -p tsconfig.lib.json",
+    "test": "vitest run"
   }
 }

package/src/index.ts

@@ -11,8 +11,49 @@ export { isSqlConnection, resolveSqlConnection } from "./sql-connection-ref.js";
 // these by PURL fragment, so the whole module is one bundle and its shared
 // state is one module scope.
 export * as SqlCommandController from "./sql-command-controller.js";
-export * as SqlMigrationController from "./sql-migration-controller.js";
-export * as SqlMigrationsController from "./sql-migrations-controller.js";
 export * as SqlQueryController from "./sql-query-controller.js";
 export * as SqlSelectionController from "./sql-selection-controller.js";
 export * as SqlTransactionController from "./sql-transaction-controller.js";
+
+// Declarative schema. The shared half only — the diff, the ledger, the
+// tombstones and the ordering. Every backend implements `SchemaDriver` and owns
+// its own type vocabulary, DDL rendering, introspection and locking, so nothing
+// here is a lowest-common-denominator type layer.
+export type {
+  DeclaredColumn,
+  DeclaredForeignKey,
+  DeclaredIndex,
+  DeclaredTable,
+  SchemaObjectId,
+  SchemaObjectKind,
+} from "./schema/declared-schema.js";
+export { describeObject, objectKey } from "./schema/declared-schema.js";
+export type {
+  ChangeSafety,
+  LiveColumn,
+  LiveForeignKey,
+  LiveIndex,
+  LiveTable,
+  SchemaDriver,
+} from "./schema/schema-driver.js";
+export { ledgerTables, SchemaLedger } from "./schema/schema-ledger.js";
+export type { LedgerTables, TombstoneRecord, VersionRecord } from "./schema/schema-ledger.js";
+export { assessTombstone } from "./schema/reclaim-policy.js";
+export type { Eligibility, ReclaimPolicy } from "./schema/reclaim-policy.js";
+export { snapshotDeclaration, snapshotDigest } from "./schema/declaration-snapshot.js";
+export type { DeclarationSnapshot } from "./schema/declaration-snapshot.js";
+export { planReconciliation } from "./schema/schema-reconciler.js";
+export type { PlannedStatement, PlannedTombstone, SchemaPlan } from "./schema/schema-reconciler.js";
+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 { 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/declaration-snapshot.ts

@@ -0,0 +1,71 @@
+import { createHash } from "node:crypto";
+import type { DeclaredTable, SchemaObjectId } from "./declared-schema.js";
+import { objectKey } from "./declared-schema.js";
+
+/**
+ * The declaration, flattened to one entry per schema object.
+ *
+ * Recording the snapshot rather than only its digest is what answers the
+ * question reconciliation cannot answer from live state alone: which objects
+ * THIS schema resource owns. An object in the namespace that has never appeared
+ * in a snapshot was never declared here — a legacy table, another application's,
+ * one predating adoption — and is invisible to both the diff and reclamation.
+ * Inferring ownership from presence would make adopting an existing database a
+ * data-loss event.
+ *
+ * It also supplies a tombstone's last-known definition for free, so nothing has
+ * to reconstruct what a dropped object was after the declaration stopped
+ * describing it.
+ */
+export type DeclarationSnapshot = Record<string, string>;
+
+function stable(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(stable);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(
+      Object.entries(value as Record<string, unknown>)
+        .filter(([, v]) => v !== undefined)
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+        .map(([k, v]) => [k, stable(v)]),
+    );
+  }
+  return value;
+}
+
+function entry(snapshot: DeclarationSnapshot, id: SchemaObjectId, definition: unknown): void {
+  snapshot[objectKey(id)] = JSON.stringify(stable(definition));
+}
+
+export function snapshotDeclaration(tables: readonly DeclaredTable[]): DeclarationSnapshot {
+  const snapshot: DeclarationSnapshot = {};
+  for (const table of tables) {
+    entry(snapshot, { kind: "table", table: table.name }, { name: table.name });
+    for (const column of table.columns) {
+      entry(snapshot, { kind: "column", table: table.name, name: column.name }, column);
+    }
+    for (const index of table.indexes) {
+      entry(snapshot, { kind: "index", table: table.name, name: index.name }, index);
+    }
+    for (const fk of table.foreignKeys) {
+      entry(snapshot, { kind: "foreignKey", table: table.name, name: fk.name }, fk);
+    }
+  }
+  return snapshot;
+}
+
+/** Stable digest of a snapshot — what the ledger compares boots against. */
+export function snapshotDigest(snapshot: DeclarationSnapshot): string {
+  const canonical = JSON.stringify(
+    Object.keys(snapshot)
+      .sort()
+      .map((key) => [key, snapshot[key]]),
+  );
+  return createHash("sha256").update(canonical).digest("hex");
+}
+
+export function parseObjectKey(key: string): SchemaObjectId {
+  const [kind, rest] = key.split(":", 2) as [SchemaObjectId["kind"], string];
+  const dot = rest.indexOf(".");
+  if (kind === "table" || dot < 0) return { kind, table: rest };
+  return { kind, table: rest.slice(0, dot), name: rest.slice(dot + 1) };
+}

package/src/schema/declared-schema.ts

@@ -0,0 +1,73 @@
+/**
+ * The normalized declaration a backend's `Table` kind reduces to.
+ *
+ * Backends declare columns in their own vocabulary — `citext`, `jsonb`, SQLite
+ * storage classes — and this model carries the type through as an opaque
+ * `type` plus its structured `params`. Nothing here parses a type; only the
+ * driver understands one. What IS shared is the shape of a table: named
+ * columns, named indexes, named foreign keys, each with the durable identity
+ * reconciliation diffs and tombstones key on.
+ */
+
+export interface DeclaredColumn {
+  /** Durable identity. Tombstones key on it; renaming is expand-contract. */
+  readonly name: string;
+  /** Backend-native type name, never parsed here. */
+  readonly type: string;
+  /** Structured type parameters (`length`, `precision`, …), never spelled into `type`. */
+  readonly params: Readonly<Record<string, unknown>>;
+  readonly nullable: boolean;
+  readonly array: boolean;
+  readonly primaryKey: boolean;
+  readonly unique: boolean;
+  /** A typed literal. Mutually exclusive with {@link defaultExpression}. */
+  readonly default?: unknown;
+  /** Raw backend SQL evaluated by the database. */
+  readonly defaultExpression?: string;
+  /** Backend-specific identity/auto-increment mode, passed through to the driver. */
+  readonly identity?: string;
+  /** The column this one supersedes. The pass adds, copies, then tombstones the source. */
+  readonly renamedFrom?: string;
+}
+
+export interface DeclaredIndex {
+  readonly name: string;
+  readonly columns: readonly string[];
+  readonly unique: boolean;
+  /** Backend-specific extras (partial predicate, method), passed through. */
+  readonly options: Readonly<Record<string, unknown>>;
+}
+
+export interface DeclaredForeignKey {
+  readonly name: string;
+  readonly columns: readonly string[];
+  readonly references: { readonly table: string; readonly columns: readonly string[] };
+  readonly onDelete?: string;
+  readonly onUpdate?: string;
+}
+
+export interface DeclaredTable {
+  /** Physical table name. */
+  readonly name: string;
+  readonly columns: readonly DeclaredColumn[];
+  readonly indexes: readonly DeclaredIndex[];
+  readonly foreignKeys: readonly DeclaredForeignKey[];
+}
+
+/** Every schema object reconciliation tracks, by the identity a tombstone keys on. */
+export type SchemaObjectKind = "table" | "column" | "index" | "foreignKey";
+
+export interface SchemaObjectId {
+  readonly kind: SchemaObjectKind;
+  readonly table: string;
+  /** The column / index / constraint name; absent for a table. */
+  readonly name?: string;
+}
+
+export function objectKey(id: SchemaObjectId): string {
+  return id.name == null ? `${id.kind}:${id.table}` : `${id.kind}:${id.table}.${id.name}`;
+}
+
+export function describeObject(id: SchemaObjectId): string {
+  return id.name == null ? `table ${id.table}` : `${id.kind} ${id.table}.${id.name}`;
+}

package/src/schema/migration-runner.ts

@@ -0,0 +1,69 @@
+import type { SchemaLedger } from "./schema-ledger.js";
+import type { SchemaDriver } from "./schema-driver.js";
+
+/**
+ * A migration is one `statement` or an ordered list of `statements`, keyed by a
+ * durable id. Phase is NOT part of identity: keys are unique across both maps
+ * and the ledger stores the key alone, so moving a migration between
+ * `beforeMigrations:` and `migrations:` keeps its identity and does not re-run
+ * it.
+ */
+export interface MigrationEntry {
+  readonly statement?: string;
+  readonly statements?: readonly string[];
+}
+
+export type MigrationMap = Record<string, MigrationEntry>;
+
+export function migrationStatements(key: string, entry: MigrationEntry): string[] {
+  const statements = entry.statements ?? (entry.statement != null ? [entry.statement] : []);
+  if (statements.length === 0) {
+    throw new Error(
+      `migration '${key}' has no statement(s) — set 'statement' or a non-empty 'statements'`,
+    );
+  }
+  return [...statements];
+}
+
+/** Keys not yet in the ledger, in key order — the order they are applied in. */
+export function pendingKeys(migrations: MigrationMap, applied: ReadonlySet<string>): string[] {
+  return Object.keys(migrations)
+    .filter((key) => !applied.has(key))
+    .sort();
+}
+
+/**
+ * Apply the pending migrations in key order, each with its ledger row in the
+ * SAME atomic group.
+ *
+ * Applying and recording are one operation, not two: a crash between them would
+ * re-run a migration that may not be idempotent. Whether the group is genuinely
+ * atomic is the engine's to say — {@link SchemaDriver.runAtomically} groups it
+ * where DDL is transactional and runs it sequentially where it is not — but the
+ * ledger write is never the thing left outstanding, because it is last in the
+ * group.
+ */
+export async function runMigrations(
+  driver: SchemaDriver,
+  ledger: SchemaLedger,
+  migrations: MigrationMap,
+  applied: ReadonlySet<string>,
+  now: () => Promise<string>,
+): Promise<string[]> {
+  const pending = pendingKeys(migrations, applied);
+  for (const key of pending) {
+    await driver.runAtomically([
+      ...migrationStatements(key, migrations[key]!),
+      ledger.migrationRecordStatement(key, await now()),
+    ]);
+  }
+  return pending;
+}
+
+export function orphanedKeys(
+  applied: ReadonlySet<string>,
+  ...declared: readonly MigrationMap[]
+): string[] {
+  const known = new Set(declared.flatMap((map) => Object.keys(map)));
+  return [...applied].filter((key) => !known.has(key)).sort();
+}