@hyperfixation/db 0.1.0

package/dist/delete-guard.d.ts

@@ -0,0 +1,32 @@
+import type { Client } from "pg";
+/**
+ * Machinery tables that point at an app record through `(record_type, record_id)`
+ * and whose history is meant to outlive the record. There is deliberately no
+ * foreign key — the core cannot know an app's tables at migration time — so the
+ * delete-guard trigger is the only thing standing between a hard `DELETE` and a
+ * lost approval, link, label or outcome.
+ */
+export declare const DELETE_GUARD_REFERENCING_TABLES: readonly ["hf_approval", "hf_record_link", "hf_label", "hf_outcome"];
+export declare const DELETE_GUARD_FUNCTION = "hf_delete_guard";
+export interface RecordTable {
+    /** The app table carrying a `bigint` identity primary key named `id`. */
+    table: string;
+    /** The name the app registered with `defineRecord`; machinery rows store it. */
+    recordType: string;
+}
+export interface DeleteGuardResult {
+    referencingTables: string[];
+    guardedTables: string[];
+}
+/**
+ * Installs `hf_delete_guard()` and a `BEFORE DELETE` trigger on every registered
+ * record table. `records.archive()` is the supported path for making a record go
+ * away; a hard `DELETE` of a referenced record raises `restrict_violation`.
+ *
+ * The function body is regenerated on every deploy from the referencing tables
+ * that exist *now*: plpgsql bodies are validated at `CREATE FUNCTION` time, so a
+ * body naming a machinery table a later phase has not added yet would fail to
+ * install at all.
+ */
+export declare function installDeleteGuards(client: Client, recordTables?: readonly RecordTable[]): Promise<DeleteGuardResult>;
+export declare function deleteGuardFunctionSql(referencingTables: readonly string[]): string;

package/dist/delete-guard.js

@@ -0,0 +1,62 @@
+import { quoteIdent } from "./roles.js";
+/**
+ * Machinery tables that point at an app record through `(record_type, record_id)`
+ * and whose history is meant to outlive the record. There is deliberately no
+ * foreign key — the core cannot know an app's tables at migration time — so the
+ * delete-guard trigger is the only thing standing between a hard `DELETE` and a
+ * lost approval, link, label or outcome.
+ */
+export const DELETE_GUARD_REFERENCING_TABLES = [
+    "hf_approval",
+    "hf_record_link",
+    "hf_label",
+    "hf_outcome",
+];
+export const DELETE_GUARD_FUNCTION = "hf_delete_guard";
+/**
+ * Installs `hf_delete_guard()` and a `BEFORE DELETE` trigger on every registered
+ * record table. `records.archive()` is the supported path for making a record go
+ * away; a hard `DELETE` of a referenced record raises `restrict_violation`.
+ *
+ * The function body is regenerated on every deploy from the referencing tables
+ * that exist *now*: plpgsql bodies are validated at `CREATE FUNCTION` time, so a
+ * body naming a machinery table a later phase has not added yet would fail to
+ * install at all.
+ */
+export async function installDeleteGuards(client, recordTables = []) {
+    const referencingTables = await existingReferencingTables(client);
+    await client.query(deleteGuardFunctionSql(referencingTables));
+    for (const { table, recordType } of recordTables) {
+        const ident = quoteIdent(table);
+        await client.query(`DROP TRIGGER IF EXISTS ${quoteIdent(DELETE_GUARD_FUNCTION)} ON ${ident}`);
+        await client.query(`CREATE TRIGGER ${quoteIdent(DELETE_GUARD_FUNCTION)} BEFORE DELETE ON ${ident} ` +
+            `FOR EACH ROW EXECUTE FUNCTION ${quoteIdent(DELETE_GUARD_FUNCTION)}('${recordType.replace(/'/g, "''")}')`);
+    }
+    return { referencingTables, guardedTables: recordTables.map((r) => r.table) };
+}
+async function existingReferencingTables(client) {
+    const { rows } = await client.query(`SELECT c.relname AS table_name
+       FROM pg_class c
+       JOIN pg_namespace n ON n.oid = c.relnamespace
+      WHERE n.nspname = 'public' AND c.relkind = 'r' AND c.relname = ANY($1::text[])
+      ORDER BY c.relname`, [[...DELETE_GUARD_REFERENCING_TABLES]]);
+    return rows.map((r) => r.table_name);
+}
+export function deleteGuardFunctionSql(referencingTables) {
+    const checks = referencingTables
+        .map(
+    // `record_id` is text on every machinery table — a record id is carried, not joined on —
+    // while a record table's `id` is the bigint identity E001 insists on.
+    (t) => `  IF EXISTS (SELECT 1 FROM ${quoteIdent(t)} WHERE record_type = TG_ARGV[0] AND record_id = OLD.id::text) THEN
+    RAISE EXCEPTION 'delete-guard: % % is referenced by ${t}; use records.archive()', TG_ARGV[0], OLD.id
+      USING ERRCODE = 'restrict_violation';
+  END IF;`)
+        .join("\n");
+    return `CREATE OR REPLACE FUNCTION ${quoteIdent(DELETE_GUARD_FUNCTION)}() RETURNS trigger
+LANGUAGE plpgsql AS $hf_delete_guard$
+BEGIN
+${checks}
+  RETURN OLD;
+END;
+$hf_delete_guard$`;
+}

package/dist/fenced-client.d.ts

@@ -0,0 +1,35 @@
+import type { Pool, PoolClient, QueryConfig, Submittable } from "pg";
+export type QueryArg = string | QueryConfig | Submittable;
+/**
+ * Stands in for a `Submittable` that carries no SQL text of its own. It does not parse, so
+ * `classify()` calls it a write.
+ */
+export declare const OPAQUE_SUBMITTABLE = "<opaque submittable>";
+/**
+ * Normalises the three shapes node-pg's `query()` accepts down to the SQL text `classify()` reads.
+ * `pg-copy-streams`, `pg-cursor` and `pg-query-stream` all expose their statement as `.text`.
+ */
+export declare function extractStatementText(queryArg: QueryArg): string;
+export declare class UnfencedWrite extends Error {
+    readonly statement: string;
+    constructor(statement: string);
+}
+/**
+ * Drizzle rethrows a driver error as `DrizzleQueryError`, so a refusal that reached the
+ * caller through a Drizzle handle is somewhere down the `cause` chain rather than at the top.
+ */
+export declare function unfencedWriteOf(error: unknown): UnfencedWrite | undefined;
+/** Tags a checked-out step-pool client for the life of one `ctx.tx` transaction. */
+export declare function tagForTransaction(client: PoolClient): void;
+/**
+ * Turns `pool` into the step pool by patching the instance — node-pg has no plugin hook,
+ * and patching the `pg` module would fence the control pool too. Every statement that is
+ * not a pure `SELECT` is refused with `UnfencedWrite` unless the specific connection it
+ * runs on is currently tagged by `ctx.tx`. No async context is consulted.
+ *
+ * What it does not stop, deliberately: the pool still hands the raw client to `'acquire'`,
+ * `'connect'`, `'release'` and `'remove'` listeners, and still carries its own
+ * `options.connectionString`. Those are bypasses someone has to reach for; the fence exists
+ * for the shapes that look like ordinary code.
+ */
+export declare function fencePool(pool: Pool): Pool;

package/dist/fenced-client.js

@@ -0,0 +1,153 @@
+import { classify } from "./classify.js";
+/**
+ * Stands in for a `Submittable` that carries no SQL text of its own. It does not parse, so
+ * `classify()` calls it a write.
+ */
+export const OPAQUE_SUBMITTABLE = "<opaque submittable>";
+/**
+ * Normalises the three shapes node-pg's `query()` accepts down to the SQL text `classify()` reads.
+ * `pg-copy-streams`, `pg-cursor` and `pg-query-stream` all expose their statement as `.text`.
+ */
+export function extractStatementText(queryArg) {
+    if (typeof queryArg === "string")
+        return queryArg;
+    const text = queryArg.text;
+    return typeof text === "string" ? text : OPAQUE_SUBMITTABLE;
+}
+export class UnfencedWrite extends Error {
+    statement;
+    constructor(statement) {
+        super(`UnfencedWrite: the step pool refused a write issued outside ctx.tx: ${statement}`);
+        this.name = "UnfencedWrite";
+        this.statement = statement;
+    }
+}
+/**
+ * Drizzle rethrows a driver error as `DrizzleQueryError`, so a refusal that reached the
+ * caller through a Drizzle handle is somewhere down the `cause` chain rather than at the top.
+ */
+export function unfencedWriteOf(error) {
+    let current = error;
+    while (current instanceof Error) {
+        if (current instanceof UnfencedWrite)
+            return current;
+        current = current.cause;
+    }
+    return undefined;
+}
+/**
+ * The lease that currently holds the tag on a connection, keyed by the underlying
+ * `pg.Client`. A lease is minted per checkout, so re-checking out the same connection
+ * mints a different one and a handle from an earlier checkout can never match again.
+ */
+const taggedLease = new WeakMap();
+const FENCE = Symbol("hyperfixation.fence");
+function fenceOf(client) {
+    const fence = client[FENCE];
+    if (!fence)
+        throw new TypeError("not a step-pool client");
+    return fence;
+}
+/** Tags a checked-out step-pool client for the life of one `ctx.tx` transaction. */
+export function tagForTransaction(client) {
+    const fence = fenceOf(client);
+    taggedLease.set(fence.client, fence.lease);
+}
+function isTagged(fence) {
+    return taggedLease.get(fence.client) === fence.lease;
+}
+function refuse(args, statement) {
+    const error = new UnfencedWrite(statement);
+    const callback = args.find((arg) => typeof arg === "function");
+    if (!callback)
+        throw error;
+    setImmediate(() => callback(error));
+    return undefined;
+}
+function guard(args, tagged) {
+    const [first] = args;
+    if (typeof first === "function")
+        return undefined;
+    const statement = extractStatementText(first);
+    return !tagged && classify(statement) === "write" ? statement : undefined;
+}
+/**
+ * Wraps one checkout of a step-pool connection. The wrapper is per-checkout, never shared:
+ * that is what makes a handle captured inside `ctx.tx` inert after the transaction ends,
+ * whether the connection then sits idle or is re-tagged by a later transaction.
+ */
+function fenceClient(client) {
+    const fence = { client, lease: Symbol("hyperfixation.lease") };
+    let released = false;
+    // Untagging here rather than in `ctx.tx` makes it structural: no path returns a
+    // connection to the pool still carrying this checkout's tag. Idempotent because a refused
+    // query also releases (see below) — a caller's own release-in-finally must then be a no-op,
+    // not a double-release.
+    const release = (err) => {
+        if (released)
+            return;
+        released = true;
+        if (isTagged(fence))
+            taggedLease.delete(fence.client);
+        client.release(err);
+    };
+    const query = (...args) => {
+        const refused = guard(args, isTagged(fence));
+        if (refused !== undefined) {
+            // A refused statement never reaches the real connection, so it is always safe to hand
+            // straight back here. Without this, Drizzle's own `db.transaction()` leaks a checkout on
+            // every refusal: it checks a client out and issues `BEGIN` before opening the try/finally
+            // that would otherwise release it, so a refusal here would strand the connection forever.
+            release();
+            return refuse(args, refused);
+        }
+        return client.query.apply(client, args);
+    };
+    return new Proxy(client, {
+        get(target, property) {
+            if (property === FENCE)
+                return fence;
+            if (property === "query")
+                return query;
+            if (property === "release")
+                return release;
+            const value = Reflect.get(target, property, target);
+            return typeof value === "function" ? value.bind(target) : value;
+        },
+    });
+}
+/**
+ * Turns `pool` into the step pool by patching the instance — node-pg has no plugin hook,
+ * and patching the `pg` module would fence the control pool too. Every statement that is
+ * not a pure `SELECT` is refused with `UnfencedWrite` unless the specific connection it
+ * runs on is currently tagged by `ctx.tx`. No async context is consulted.
+ *
+ * What it does not stop, deliberately: the pool still hands the raw client to `'acquire'`,
+ * `'connect'`, `'release'` and `'remove'` listeners, and still carries its own
+ * `options.connectionString`. Those are bypasses someone has to reach for; the fence exists
+ * for the shapes that look like ordinary code.
+ */
+export function fencePool(pool) {
+    const poolQuery = pool.query.bind(pool);
+    const poolConnect = pool.connect.bind(pool);
+    pool.query = ((...args) => {
+        // `pool.query` checks a connection out and returns it within the one call, so it can
+        // never be inside `ctx.tx`; refusing before `connect()` keeps a refusal free.
+        const refused = guard(args, false);
+        if (refused !== undefined)
+            return refuse(args, refused);
+        return poolQuery(...args);
+    });
+    pool.connect = ((callback) => {
+        if (typeof callback !== "function") {
+            return poolConnect().then(fenceClient);
+        }
+        return poolConnect((err, client) => {
+            if (err || !client)
+                return callback(err, client, undefined);
+            const fenced = fenceClient(client);
+            return callback(undefined, fenced, fenced.release);
+        });
+    });
+    return pool;
+}

package/dist/grant-ro.d.ts

@@ -0,0 +1,23 @@
+import type { Client } from "pg";
+/**
+ * Tables the read-only role is never granted. Metabase reaches the database
+ * through this role, so anything that would let a reader mint or replay a staff
+ * session — credentials, sessions, verification codes, passkeys, linked social
+ * accounts — is excluded and actively revoked, not merely left ungranted.
+ */
+export declare const GRANT_RO_EXCLUDED_TABLES: readonly ["hf_user", "hf_session", "hf_account", "hf_verification", "hf_passkey"];
+export interface GrantRoResult {
+    /** False when the role does not exist: Metabase is optional per deployment. */
+    applied: boolean;
+    granted: string[];
+    revoked: string[];
+}
+/**
+ * Grants the read-only role `SELECT` on every table the migrator owns in
+ * `public` except the auth set, and revokes everything on that set.
+ *
+ * Per-table rather than `ON ALL TABLES` because the exclusion cannot be
+ * expressed as a default privilege, which is also why this is the migrator's
+ * last step: it has to see the tables the deploy's migrations just created.
+ */
+export declare function grantReadOnly(client: Client, readonlyRole: string): Promise<GrantRoResult>;

package/dist/grant-ro.js

@@ -0,0 +1,49 @@
+import { quoteIdent } from "./roles.js";
+/**
+ * Tables the read-only role is never granted. Metabase reaches the database
+ * through this role, so anything that would let a reader mint or replay a staff
+ * session — credentials, sessions, verification codes, passkeys, linked social
+ * accounts — is excluded and actively revoked, not merely left ungranted.
+ */
+export const GRANT_RO_EXCLUDED_TABLES = [
+    "hf_user",
+    "hf_session",
+    "hf_account",
+    "hf_verification",
+    "hf_passkey",
+];
+/**
+ * Grants the read-only role `SELECT` on every table the migrator owns in
+ * `public` except the auth set, and revokes everything on that set.
+ *
+ * Per-table rather than `ON ALL TABLES` because the exclusion cannot be
+ * expressed as a default privilege, which is also why this is the migrator's
+ * last step: it has to see the tables the deploy's migrations just created.
+ */
+export async function grantReadOnly(client, readonlyRole) {
+    const { rows: roleRows } = await client.query("SELECT EXISTS (SELECT 1 FROM pg_roles WHERE rolname = $1) AS exists", [readonlyRole]);
+    if (!roleRows[0]?.exists)
+        return { applied: false, granted: [], revoked: [] };
+    const role = quoteIdent(readonlyRole);
+    const excluded = [...GRANT_RO_EXCLUDED_TABLES];
+    const { rows } = await client.query(`SELECT c.relname AS table_name, (c.relname = ANY($1::text[])) AS excluded
+       FROM pg_class c
+       JOIN pg_namespace n ON n.oid = c.relnamespace
+      WHERE n.nspname = 'public'
+        AND c.relkind IN ('r', 'p', 'v', 'm')
+        AND pg_get_userbyid(c.relowner) = current_user
+      ORDER BY c.relname`, [excluded]);
+    const granted = [];
+    const revoked = [];
+    for (const row of rows) {
+        if (row.excluded) {
+            await client.query(`REVOKE ALL ON ${quoteIdent(row.table_name)} FROM ${role}`);
+            revoked.push(row.table_name);
+        }
+        else {
+            await client.query(`GRANT SELECT ON ${quoteIdent(row.table_name)} TO ${role}`);
+            granted.push(row.table_name);
+        }
+    }
+    return { applied: true, granted, revoked };
+}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export * from "./schema/index.js";
+export { classify, type StatementKind } from "./classify.js";
+export { UnfencedWrite, unfencedWriteOf } from "./fenced-client.js";
+export { createStepPool, StaleAttempt, FENCE_STATEMENT, STEP_POOL_SIZE, type StepDatabase, type StepPool, type StepPoolOptions, } from "./step-pool.js";
+export { assertNotInWorkflow, attemptWorkflowId, bumpAttempt, controlPlaneTx, CommitLost, ConcurrentBump, ControlPlaneInWorkflow, RunLockTimeout, RunNotFound, WorkflowIdCollision, CONTROL_PLANE_LOCK_TIMEOUT, LOCK_NOT_AVAILABLE, BUMP_STATEMENT, LOCK_RUN_STATEMENT, WORKFLOW_ID_TAKEN_STATEMENT, type BumpedAttempt, type ControlPlaneTxOptions, } from "./control-plane.js";
+export { loadSource, type SourceRowInput, type SourceRun } from "./loader.js";
+export { appPaused, AppStateMissing, APP_PAUSED_STATEMENT, SET_APP_PAUSED_STATEMENT, } from "./app-state.js";
+/** `runBootChecks` takes these, so the type travels with `.` even though the guards do not. */
+export type { RecordTable } from "./delete-guard.js";
+/** `records.archive()` names a registered record table in SQL; it quotes it with this. */
+export { quoteIdent } from "./roles.js";
+export { runBootChecks, checkE001, checkE002, checkE003, checkE004, checkE005, checkE006, BootCheckFailure, BOOT_CHECK_CODES, type BootCheckCode, type BootCheckOptions, type Queryable, } from "./boot-checks.js";

package/dist/index.js

@@ -0,0 +1,10 @@
+export * from "./schema/index.js";
+export { classify } from "./classify.js";
+export { UnfencedWrite, unfencedWriteOf } from "./fenced-client.js";
+export { createStepPool, StaleAttempt, FENCE_STATEMENT, STEP_POOL_SIZE, } from "./step-pool.js";
+export { assertNotInWorkflow, attemptWorkflowId, bumpAttempt, controlPlaneTx, CommitLost, ConcurrentBump, ControlPlaneInWorkflow, RunLockTimeout, RunNotFound, WorkflowIdCollision, CONTROL_PLANE_LOCK_TIMEOUT, LOCK_NOT_AVAILABLE, BUMP_STATEMENT, LOCK_RUN_STATEMENT, WORKFLOW_ID_TAKEN_STATEMENT, } from "./control-plane.js";
+export { loadSource } from "./loader.js";
+export { appPaused, AppStateMissing, APP_PAUSED_STATEMENT, SET_APP_PAUSED_STATEMENT, } from "./app-state.js";
+/** `records.archive()` names a registered record table in SQL; it quotes it with this. */
+export { quoteIdent } from "./roles.js";
+export { runBootChecks, checkE001, checkE002, checkE003, checkE004, checkE005, checkE006, BootCheckFailure, BOOT_CHECK_CODES, } from "./boot-checks.js";

package/dist/internal/control-pool.d.ts

@@ -0,0 +1,20 @@
+import { type NodePgDatabase } from "drizzle-orm/node-postgres";
+import { Pool, type PoolConfig } from "pg";
+import * as schema from "../schema/index.js";
+export declare const CONTROL_POOL_SIZE = 2;
+export type ControlDatabase = NodePgDatabase<typeof schema>;
+export interface ControlPool {
+    readonly pool: Pool;
+    readonly db: ControlDatabase;
+    end(): Promise<void>;
+}
+/**
+ * Core's own control-plane handle: the same `pg.Pool` usage as the step pool with no fence,
+ * because a control-plane operation's fence is a predicate (`WHERE current_workflow_id = …`)
+ * rather than a row lock.
+ *
+ * Unreachable by construction, not by convention: `package.json`'s `exports` map resolves
+ * only `.` (`src/index.ts`) and `./migrator`, neither of which re-exports this module, so
+ * no `import "@hyperfixation/db/…"` from another package can produce a control pool.
+ */
+export declare function createControlPool(options: PoolConfig): ControlPool;

package/dist/internal/control-pool.js

@@ -0,0 +1,17 @@
+import { drizzle } from "drizzle-orm/node-postgres";
+import { Pool } from "pg";
+import * as schema from "../schema/index.js";
+export const CONTROL_POOL_SIZE = 2;
+/**
+ * Core's own control-plane handle: the same `pg.Pool` usage as the step pool with no fence,
+ * because a control-plane operation's fence is a predicate (`WHERE current_workflow_id = …`)
+ * rather than a row lock.
+ *
+ * Unreachable by construction, not by convention: `package.json`'s `exports` map resolves
+ * only `.` (`src/index.ts`) and `./migrator`, neither of which re-exports this module, so
+ * no `import "@hyperfixation/db/…"` from another package can produce a control pool.
+ */
+export function createControlPool(options) {
+    const pool = new Pool({ max: CONTROL_POOL_SIZE, ...options });
+    return { pool, db: drizzle(pool, { schema }), end: () => pool.end() };
+}

package/dist/loader.d.ts

@@ -0,0 +1,15 @@
+import { hfSourceRun } from "./schema/machinery.js";
+import type { StepDatabase } from "./step-pool.js";
+/** Structurally what `@hyperfixation/core`'s `SourceRow<P>` is; `db` cannot import `core`. */
+export interface SourceRowInput {
+    readonly externalId: string;
+    readonly payload: unknown;
+}
+export type SourceRun = typeof hfSourceRun.$inferSelect;
+/**
+ * COPYs `rows` into a staging table and upserts them into `hf_source_record`, all inside the
+ * caller's `ctx.tx`: the `hf_source_run` row and the records commit together or not at all.
+ * An unchanged payload moves only `last_seen`; a changed one resets the record to `new` so
+ * resolution reruns over it, and never touches its `hf_record_link`.
+ */
+export declare function loadSource(tx: StepDatabase, source: string, rows: AsyncIterable<SourceRowInput>): Promise<SourceRun>;

package/dist/loader.js

@@ -0,0 +1,82 @@
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { eq, sql } from "drizzle-orm";
+import { from as copyFrom } from "pg-copy-streams";
+import { hfSourceRun } from "./schema/machinery.js";
+/**
+ * `jsonb`'s text form is canonical, so two payloads differing only in key order hash the same.
+ */
+const PAYLOAD_HASH = "encode(sha256(convert_to(payload::text, 'UTF8')), 'hex')";
+/** The last occurrence of an external id in the batch wins. */
+const deduped = (stage) => `SELECT DISTINCT ON (external_id) external_id, payload, ${PAYLOAD_HASH} AS payload_hash
+   FROM ${stage} ORDER BY external_id, seq DESC`;
+function csvField(value) {
+    return `"${value.replaceAll('"', '""')}"`;
+}
+async function* csvLines(rows) {
+    for await (const row of rows) {
+        const payload = JSON.stringify(row.payload ?? null);
+        yield `${csvField(row.externalId)},${csvField(payload)}\n`;
+    }
+}
+/**
+ * COPYs `rows` into a staging table and upserts them into `hf_source_record`, all inside the
+ * caller's `ctx.tx`: the `hf_source_run` row and the records commit together or not at all.
+ * An unchanged payload moves only `last_seen`; a changed one resets the record to `new` so
+ * resolution reruns over it, and never touches its `hf_record_link`.
+ */
+export async function loadSource(tx, source, rows) {
+    const client = tx.$client;
+    const [run] = await tx
+        .insert(hfSourceRun)
+        .values({ source, status: "running" })
+        .returning({ id: hfSourceRun.id });
+    const runId = run.id;
+    // TEMP, not UNLOGGED: the application role holds USAGE but not CREATE on `public`, and
+    // `ON COMMIT DROP` makes the cleanup structural rather than another statement to get right.
+    const stage = `hf_source_stage_${runId}`;
+    await client.query(`CREATE TEMP TABLE ${stage} (
+       seq bigint GENERATED ALWAYS AS IDENTITY,
+       external_id text NOT NULL,
+       payload jsonb NOT NULL
+     ) ON COMMIT DROP`);
+    const copy = client.query(copyFrom(`COPY ${stage} (external_id, payload) FROM STDIN WITH (FORMAT csv)`));
+    await pipeline(Readable.from(csvLines(rows)), copy);
+    const counted = await client.query(`WITH deduped AS (${deduped(stage)})
+     SELECT
+       (SELECT count(*) FROM ${stage}) AS rows_in,
+       count(*) FILTER (WHERE r.external_id IS NULL) AS rows_new,
+       count(*) FILTER (WHERE r.external_id IS NOT NULL
+                          AND r.payload_hash <> d.payload_hash) AS rows_changed
+     FROM deduped d
+     LEFT JOIN hf_source_record r ON r.source = $1 AND r.external_id = d.external_id`, [source]);
+    const counts = counted.rows[0];
+    const changed = (column) => `CASE WHEN hf_source_record.payload_hash <> EXCLUDED.payload_hash
+          THEN EXCLUDED.${column} ELSE hf_source_record.${column} END`;
+    await client.query(`WITH deduped AS (${deduped(stage)})
+     INSERT INTO hf_source_record (source, external_id, payload, payload_hash, run_id)
+     SELECT $1, d.external_id, d.payload, d.payload_hash, $2 FROM deduped d
+     ON CONFLICT (source, external_id) DO UPDATE SET
+       last_seen = now(),
+       payload = ${changed("payload")},
+       payload_hash = ${changed("payload_hash")},
+       run_id = ${changed("run_id")},
+       status = CASE WHEN hf_source_record.payload_hash <> EXCLUDED.payload_hash
+                     THEN 'new' ELSE hf_source_record.status END,
+       attempts = CASE WHEN hf_source_record.payload_hash <> EXCLUDED.payload_hash
+                       THEN 0 ELSE hf_source_record.attempts END,
+       error = CASE WHEN hf_source_record.payload_hash <> EXCLUDED.payload_hash
+                    THEN NULL ELSE hf_source_record.error END`, [source, runId]);
+    const [finished] = await tx
+        .update(hfSourceRun)
+        .set({
+        status: "ok",
+        finishedAt: sql `clock_timestamp()`,
+        rowsIn: Number(counts.rows_in),
+        rowsNew: Number(counts.rows_new),
+        rowsChanged: Number(counts.rows_changed),
+    })
+        .where(eq(hfSourceRun.id, runId))
+        .returning();
+    return finished;
+}

package/dist/migrate.d.ts

@@ -0,0 +1,54 @@
+import { type DeleteGuardResult, type RecordTable } from "./delete-guard.js";
+import { type GrantRoResult } from "./grant-ro.js";
+export declare const CORE_MIGRATIONS_TABLE = "hf_core_migrations";
+export declare const CORE_MIGRATIONS_SCHEMA = "drizzle";
+export declare const DBOS_SCHEMA = "dbos";
+export declare const CORE_MIGRATIONS_DIR: string;
+export declare class MigratorError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+export interface MigrateOptions {
+    appName: string;
+    /** Defaults to `hf_<appName>`; this is the role `dbos schema -r` grants. */
+    applicationRole?: string;
+    /** Defaults to `hf_<appName>_ro`; skipped when the role does not exist. */
+    readonlyRole?: string;
+    coreMigrationsDir?: string;
+    appMigrationsDir?: string;
+    /** Tables registered with `defineRecord`; each gets a delete-guard trigger. */
+    recordTables?: readonly RecordTable[];
+    /**
+     * Runs step 3 as `dbos schema -s dbos` with no `-r`. Exists only so a test can
+     * reproduce the deployment mistake E006 catches: the system schema is created
+     * and the application role is granted nothing on it. A real deploy that sets
+     * this produces a worker that cannot launch — the name is loud on purpose.
+     */
+    dangerouslySkipApplicationRoleGrant?: boolean;
+}
+export interface MigrateResult {
+    applicationRole: string;
+    dbosSchemaGranted: boolean;
+    appMigrationsApplied: boolean;
+    deleteGuards: DeleteGuardResult;
+    grantRo: GrantRoResult;
+}
+/**
+ * The five-step migrator, run as the migrator role on every deploy:
+ * core migrations, app migrations, `dbos schema -s dbos -r hf_<app>`,
+ * delete-guard triggers, `hf_grant_ro`.
+ *
+ * Order is load-bearing at both ends. Step 3 runs on every deploy, not just the
+ * first, so an SDK upgrade that adds a system table grants it before the worker
+ * that needs it starts; steps 4 and 5 run last because both have to see the
+ * tables steps 1 and 2 just created.
+ */
+export declare function migrate(migratorConnectionString: string, options: MigrateOptions): Promise<MigrateResult>;
+/**
+ * `dbos schema -s dbos -r <role>`: creates the DBOS system schema and grants the
+ * application role on it. The `-r` flag is the only path to those grants — the
+ * SDK's `getDbosSchemaPermissionsSql` is the sole source of `GRANT` statements
+ * anywhere in it — and without them the worker cannot launch at all.
+ */
+export declare function runDbosSchema(migratorConnectionString: string, applicationRole: string | null, schema?: string): Promise<void>;