@hyperfixation/db 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Graham Lutz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/app-state.d.ts

@@ -0,0 +1,12 @@
+import type { ClientBase, Pool } from "pg";
+/**
+ * The pause flag, read the way the step gate reads it: `COALESCE` over a missing singleton, so
+ * an app whose `hf_app_state` row has not been seeded is not paused rather than an error.
+ */
+export declare const APP_PAUSED_STATEMENT = "SELECT COALESCE((SELECT paused FROM hf_app_state WHERE id = 1), false) AS paused";
+/** Written by `pause`/`resume` only, inside a control-plane transaction. */
+export declare const SET_APP_PAUSED_STATEMENT = "UPDATE hf_app_state SET paused = $1, paused_by = $2 WHERE id = 1";
+export declare class AppStateMissing extends Error {
+    constructor(operation: string);
+}
+export declare function appPaused(queryable: Pool | ClientBase): Promise<boolean>;

package/dist/app-state.js

@@ -0,0 +1,18 @@
+/**
+ * The pause flag, read the way the step gate reads it: `COALESCE` over a missing singleton, so
+ * an app whose `hf_app_state` row has not been seeded is not paused rather than an error.
+ */
+export const APP_PAUSED_STATEMENT = "SELECT COALESCE((SELECT paused FROM hf_app_state WHERE id = 1), false) AS paused";
+/** Written by `pause`/`resume` only, inside a control-plane transaction. */
+export const SET_APP_PAUSED_STATEMENT = "UPDATE hf_app_state SET paused = $1, paused_by = $2 WHERE id = 1";
+export class AppStateMissing extends Error {
+    constructor(operation) {
+        super(`AppStateMissing: ${operation} matched no hf_app_state row; the singleton is seeded by ` +
+            "`hf bootstrap` and nothing else can pause an app that has never been bootstrapped");
+        this.name = "AppStateMissing";
+    }
+}
+export async function appPaused(queryable) {
+    const { rows } = await queryable.query(APP_PAUSED_STATEMENT);
+    return rows[0].paused;
+}

package/dist/boot-checks.d.ts

@@ -0,0 +1,56 @@
+import type { RecordTable } from "./delete-guard.js";
+export type BootCheckCode = "E001" | "E002" | "E003" | "E004" | "E005" | "E006";
+export declare const BOOT_CHECK_CODES: readonly BootCheckCode[];
+export declare class BootCheckFailure extends Error {
+    readonly code: BootCheckCode;
+    readonly details: readonly string[];
+    constructor(code: BootCheckCode, summary: string, details?: readonly string[]);
+}
+export interface Queryable {
+    query(text: string, values?: unknown[]): Promise<{
+        rows: unknown[];
+    }>;
+}
+export interface BootCheckOptions {
+    /** Connection the process itself uses — for `web` and `worker`, the application role. */
+    databaseUrl: string;
+    /** Tables registered with `defineRecord`; empty until an app exists. */
+    recordTables?: readonly RecordTable[];
+    /** Directory of the app's own migrations, for E005. */
+    appMigrationsDir?: string;
+}
+/**
+ * E001–E006 in order, as the first statements of `startWorker()` and
+ * `getClient()`. Throws `BootCheckFailure` naming the first check that fails.
+ */
+export declare function runBootChecks(options: BootCheckOptions): Promise<void>;
+/** E001 — every registered record table has a `bigint` identity primary key named `id`. */
+export declare function checkE001(db: Queryable, recordTables: readonly RecordTable[]): Promise<void>;
+/** E002 — every `record_type` stored in a machinery table is registered. */
+export declare function checkE002(db: Queryable, recordTables: readonly RecordTable[]): Promise<void>;
+/** E003 — every registered record table has the trigram index on `normalized_name`. */
+export declare function checkE003(db: Queryable, recordTables: readonly RecordTable[]): Promise<void>;
+/** E004 — no app table references an `hf_*` table with a foreign key. */
+export declare function checkE004(db: Queryable): Promise<void>;
+/** E005 — no app migration creates, alters or drops an `hf_*` table. */
+export declare function checkE005(appMigrationsDir?: string): Promise<void>;
+/**
+ * E006 — the application role has `USAGE` on schema `dbos` and `INSERT` on
+ * `dbos.workflow_status`.
+ *
+ * Only the migrator's `dbos schema -s dbos -r hf_<app>` step grants these; the
+ * SDK's own system-database migrations contain no `GRANT` at all. Without it the
+ * worker dies at `DBOS.launch` with a bare `42501`, and `enqueueInTransaction`
+ * raises it from inside somebody's open transaction. So this runs before any
+ * statement that could hit `dbos.*`, and it reads privileges rather than
+ * exercising them.
+ *
+ * Two traps in reading them, both of which raise the very error the check exists
+ * to preempt: `has_*_privilege` on a missing schema raises `3F000`, and
+ * `to_regclass('dbos.workflow_status')` raises `42501` when the role has no
+ * `USAGE` on `dbos`, because resolving a qualified name needs the schema. Hence
+ * the nested `CASE` — arms are evaluated lazily, so the table lookup is never
+ * reached without `USAGE` — and the catch. The process must fail naming E006,
+ * never with a raw permission error.
+ */
+export declare function checkE006(db: Queryable): Promise<void>;

package/dist/boot-checks.js

@@ -0,0 +1,228 @@
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { Client } from "pg";
+import { parse } from "pgsql-ast-parser";
+export const BOOT_CHECK_CODES = [
+    "E001",
+    "E002",
+    "E003",
+    "E004",
+    "E005",
+    "E006",
+];
+export class BootCheckFailure extends Error {
+    code;
+    details;
+    constructor(code, summary, details = []) {
+        super(`${code}: ${summary}${details.length > 0 ? `\n  - ${details.join("\n  - ")}` : ""}`);
+        this.name = "BootCheckFailure";
+        this.code = code;
+        this.details = details;
+    }
+}
+/**
+ * E001–E006 in order, as the first statements of `startWorker()` and
+ * `getClient()`. Throws `BootCheckFailure` naming the first check that fails.
+ */
+export async function runBootChecks(options) {
+    const recordTables = options.recordTables ?? [];
+    const client = new Client({ connectionString: options.databaseUrl });
+    await client.connect();
+    try {
+        await checkE001(client, recordTables);
+        await checkE002(client, recordTables);
+        await checkE003(client, recordTables);
+        await checkE004(client);
+        await checkE005(options.appMigrationsDir);
+        await checkE006(client);
+    }
+    finally {
+        await client.end();
+    }
+}
+/** E001 — every registered record table has a `bigint` identity primary key named `id`. */
+export async function checkE001(db, recordTables) {
+    const failures = [];
+    for (const { table } of recordTables) {
+        const { rows } = (await db.query(`SELECT a.attname AS name,
+              format_type(a.atttypid, a.atttypmod) AS type,
+              a.attidentity AS identity
+         FROM pg_index i
+         JOIN pg_class c ON c.oid = i.indrelid
+         JOIN pg_namespace n ON n.oid = c.relnamespace
+         JOIN pg_attribute a ON a.attrelid = c.oid AND a.attnum = ANY(i.indkey)
+        WHERE n.nspname = 'public' AND c.relname = $1 AND i.indisprimary`, [table]));
+        if (rows.length === 0) {
+            failures.push(`${table}: no primary key (or the table does not exist)`);
+            continue;
+        }
+        if (rows.length > 1) {
+            failures.push(`${table}: composite primary key (${rows.map((r) => r.name).join(", ")})`);
+            continue;
+        }
+        const [pk] = rows;
+        if (pk.name !== "id")
+            failures.push(`${table}: primary key is "${pk.name}", not "id"`);
+        else if (pk.type !== "bigint")
+            failures.push(`${table}: id is ${pk.type}, not bigint`);
+        else if (pk.identity !== "a" && pk.identity !== "d") {
+            failures.push(`${table}: id is not an identity column`);
+        }
+    }
+    if (failures.length > 0) {
+        throw new BootCheckFailure("E001", "a registered record table has no bigint identity primary key named id", failures);
+    }
+}
+/** E002 — every `record_type` stored in a machinery table is registered. */
+export async function checkE002(db, recordTables) {
+    const registered = new Set(recordTables.map((r) => r.recordType));
+    const { rows: tableRows } = (await db.query(`SELECT c.relname AS table_name
+       FROM pg_attribute a
+       JOIN pg_class c ON c.oid = a.attrelid
+       JOIN pg_namespace n ON n.oid = c.relnamespace
+      WHERE n.nspname = 'public' AND c.relkind = 'r'
+        AND a.attname = 'record_type' AND a.attnum > 0 AND NOT a.attisdropped
+        AND c.relname LIKE 'hf\\_%'
+      ORDER BY c.relname`));
+    const failures = [];
+    for (const { table_name } of tableRows) {
+        // A null `record_type` is a row attached to no record — every `hf_run` that is not about
+        // one — not a row naming a type nobody registered.
+        const { rows } = (await db.query(`SELECT DISTINCT record_type FROM "${table_name.replace(/"/g, '""')}" WHERE record_type IS NOT NULL`));
+        for (const { record_type } of rows) {
+            if (!registered.has(record_type))
+                failures.push(`${table_name}: "${record_type}"`);
+        }
+    }
+    if (failures.length > 0) {
+        throw new BootCheckFailure("E002", "a machinery row references a record type no app registered", failures);
+    }
+}
+/** E003 — every registered record table has the trigram index on `normalized_name`. */
+export async function checkE003(db, recordTables) {
+    const failures = [];
+    for (const { table } of recordTables) {
+        const { rows } = (await db.query(`SELECT 1
+         FROM pg_index i
+         JOIN pg_class c ON c.oid = i.indrelid
+         JOIN pg_class ic ON ic.oid = i.indexrelid
+         JOIN pg_am am ON am.oid = ic.relam
+         JOIN pg_namespace n ON n.oid = c.relnamespace
+        WHERE n.nspname = 'public' AND c.relname = $1 AND am.amname = 'gin'
+          AND pg_get_indexdef(i.indexrelid) ILIKE '%normalized\\_name%gin\\_trgm\\_ops%'`, [table]));
+        if (rows.length === 0) {
+            failures.push(`${table}: no GIN index on normalized_name using gin_trgm_ops`);
+        }
+    }
+    if (failures.length > 0) {
+        throw new BootCheckFailure("E003", "a registered record table is missing its trigram index", failures);
+    }
+}
+/** E004 — no app table references an `hf_*` table with a foreign key. */
+export async function checkE004(db) {
+    const { rows } = (await db.query(`SELECT con.conname AS constraint_name,
+            child.relname AS referencing,
+            parent.relname AS referenced
+       FROM pg_constraint con
+       JOIN pg_class child ON child.oid = con.conrelid
+       JOIN pg_class parent ON parent.oid = con.confrelid
+       JOIN pg_namespace n ON n.oid = child.relnamespace
+      WHERE con.contype = 'f' AND n.nspname = 'public'
+        AND parent.relname LIKE 'hf\\_%' AND child.relname NOT LIKE 'hf\\_%'
+      ORDER BY con.conname`));
+    if (rows.length > 0) {
+        throw new BootCheckFailure("E004", "an app table has a foreign key into an hf_* table", rows.map((r) => `${r.referencing} -> ${r.referenced} (${r.constraint_name})`));
+    }
+}
+/** E005 — no app migration creates, alters or drops an `hf_*` table. */
+export async function checkE005(appMigrationsDir) {
+    if (appMigrationsDir === undefined)
+        return;
+    const failures = [];
+    for (const file of await migrationFiles(appMigrationsDir)) {
+        const sql = await readFile(path.join(appMigrationsDir, file), "utf8");
+        for (const statement of splitStatements(sql)) {
+            let parsed;
+            try {
+                parsed = parse(statement);
+            }
+            catch (cause) {
+                failures.push(`${file}: unparseable statement (${cause.message})`);
+                continue;
+            }
+            for (const name of parsed.flatMap(hfTablesTouched)) {
+                failures.push(`${file}: ${name}`);
+            }
+        }
+    }
+    if (failures.length > 0) {
+        throw new BootCheckFailure("E005", "an app migration creates, alters or drops an hf_* table", failures);
+    }
+}
+/**
+ * E006 — the application role has `USAGE` on schema `dbos` and `INSERT` on
+ * `dbos.workflow_status`.
+ *
+ * Only the migrator's `dbos schema -s dbos -r hf_<app>` step grants these; the
+ * SDK's own system-database migrations contain no `GRANT` at all. Without it the
+ * worker dies at `DBOS.launch` with a bare `42501`, and `enqueueInTransaction`
+ * raises it from inside somebody's open transaction. So this runs before any
+ * statement that could hit `dbos.*`, and it reads privileges rather than
+ * exercising them.
+ *
+ * Two traps in reading them, both of which raise the very error the check exists
+ * to preempt: `has_*_privilege` on a missing schema raises `3F000`, and
+ * `to_regclass('dbos.workflow_status')` raises `42501` when the role has no
+ * `USAGE` on `dbos`, because resolving a qualified name needs the schema. Hence
+ * the nested `CASE` — arms are evaluated lazily, so the table lookup is never
+ * reached without `USAGE` — and the catch. The process must fail naming E006,
+ * never with a raw permission error.
+ */
+export async function checkE006(db) {
+    const failures = [];
+    try {
+        const { rows } = (await db.query(`SELECT CASE WHEN to_regnamespace('dbos') IS NULL THEN false
+                   ELSE has_schema_privilege('dbos', 'USAGE') END AS schema_usage,
+              CASE WHEN to_regnamespace('dbos') IS NULL THEN false
+                   WHEN NOT has_schema_privilege('dbos', 'USAGE') THEN false
+                   WHEN to_regclass('dbos.workflow_status') IS NULL THEN false
+                   ELSE has_table_privilege('dbos.workflow_status', 'INSERT') END AS table_insert`));
+        const [row] = rows;
+        if (!row.schema_usage)
+            failures.push("has_schema_privilege('dbos', 'USAGE') is false");
+        if (!row.table_insert) {
+            failures.push("has_table_privilege('dbos.workflow_status', 'INSERT') is false");
+        }
+    }
+    catch (cause) {
+        failures.push(`privilege lookup failed: ${cause.message}`);
+    }
+    if (failures.length > 0) {
+        throw new BootCheckFailure("E006", "the application role lacks its dbos grants; run `dbos schema -s dbos -r <app role>`", failures);
+    }
+}
+function hfTablesTouched(node) {
+    switch (node.type) {
+        case "create table":
+            return isHfTable(node.name.name) ? [`CREATE TABLE ${node.name.name}`] : [];
+        case "alter table":
+            return isHfTable(node.table.name) ? [`ALTER TABLE ${node.table.name}`] : [];
+        case "drop table":
+            return node.names.filter((n) => isHfTable(n.name)).map((n) => `DROP TABLE ${n.name}`);
+        default:
+            return [];
+    }
+}
+function isHfTable(name) {
+    return name.toLowerCase().startsWith("hf_");
+}
+async function migrationFiles(dir) {
+    const entries = await readdir(dir).catch(() => []);
+    return entries.filter((f) => f.endsWith(".sql")).sort();
+}
+function splitStatements(sql) {
+    return sql
+        .split("--> statement-breakpoint")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}

package/dist/classify.d.ts

@@ -0,0 +1,6 @@
+export type StatementKind = "read" | "write";
+/**
+ * Anything that is not provably a read is a write: unparseable text, transaction control, `SET`,
+ * and every statement type the whitelist below omits.
+ */
+export declare function classify(sql: string): StatementKind;

package/dist/classify.js

@@ -0,0 +1,75 @@
+import { astVisitor, parse } from "pgsql-ast-parser";
+/**
+ * Real volatility lives in `pg_proc.provolatile`, which a pure function with no connection cannot
+ * read; this denylist stands in for it, so it is deliberately incomplete rather than authoritative.
+ */
+const MUTATING_FUNCTIONS = new Set([
+    "pg_notify",
+    "setval",
+    "nextval",
+    "lastval",
+    "pg_advisory_lock",
+    "pg_advisory_unlock",
+    "pg_advisory_xact_lock",
+    "dblink_exec",
+]);
+const cache = new Map();
+/**
+ * Anything that is not provably a read is a write: unparseable text, transaction control, `SET`,
+ * and every statement type the whitelist below omits.
+ */
+export function classify(sql) {
+    const cached = cache.get(sql);
+    if (cached !== undefined)
+        return cached;
+    const kind = classifyUncached(sql);
+    cache.set(sql, kind);
+    return kind;
+}
+function classifyUncached(sql) {
+    let statements;
+    try {
+        statements = parse(sql);
+    }
+    catch {
+        return "write";
+    }
+    if (statements.length === 0)
+        return "write";
+    if (!statements.every(isReadStatement))
+        return "write";
+    return callsMutatingFunction(statements) ? "write" : "read";
+}
+function isReadStatement(statement) {
+    switch (statement.type) {
+        case "select":
+            // `FOR UPDATE`/`FOR SHARE` take row locks, which only a fenced transaction may hold.
+            return !statement.for;
+        case "union":
+        case "union all":
+            return isReadStatement(statement.left) && isReadStatement(statement.right);
+        case "values":
+        case "show":
+            return true;
+        case "with":
+            return (statement.bind.every((b) => isReadStatement(b.statement)) &&
+                isReadStatement(statement.in));
+        case "with recursive":
+            return isReadStatement(statement.bind) && isReadStatement(statement.in);
+        default:
+            return false;
+    }
+}
+function callsMutatingFunction(statements) {
+    let found = false;
+    const visitor = astVisitor((self) => ({
+        call: (expr) => {
+            if (MUTATING_FUNCTIONS.has(expr.function.name.toLowerCase()))
+                found = true;
+            self.super().call(expr);
+        },
+    }));
+    for (const statement of statements)
+        visitor.statement(statement);
+    return found;
+}

package/dist/control-plane.d.ts

@@ -0,0 +1,75 @@
+import type { ClientBase, Pool, PoolClient } from "pg";
+/**
+ * The bound on a control-plane wait. Fenced writes are short by construction, so a wait this
+ * long is a bug being reported rather than work being lost.
+ */
+export declare const CONTROL_PLANE_LOCK_TIMEOUT = "30s";
+/** Postgres `lock_not_available`, what `lock_timeout` raises. */
+export declare const LOCK_NOT_AVAILABLE = "55P03";
+export declare class ControlPlaneInWorkflow extends Error {
+    readonly operation: string;
+    constructor(operation: string);
+}
+export declare class CommitLost extends Error {
+    readonly operation: string;
+    readonly commandTag: string | undefined;
+    constructor(operation: string, commandTag: string | undefined);
+}
+export declare class RunNotFound extends Error {
+    readonly runId: string;
+    constructor(runId: string);
+}
+export declare class ConcurrentBump extends Error {
+    readonly runId: string;
+    readonly attempt: number;
+    constructor(runId: string, attempt: number);
+}
+export declare class WorkflowIdCollision extends Error {
+    readonly runId: string;
+    readonly workflowId: string;
+    constructor(runId: string, workflowId: string);
+}
+export declare class RunLockTimeout extends Error {
+    readonly code = "55P03";
+    readonly runId: string;
+    constructor(runId: string, cause: unknown);
+}
+/**
+ * The first thing every control-plane operation does, before any statement. `DBOS` is read on
+ * each call rather than destructured, so a stubbed predicate is seen (`fence.test.ts` (vii)).
+ */
+export declare function assertNotInWorkflow(operation: string): void;
+export interface ControlPlaneTxOptions {
+    /** Names the operation in `ControlPlaneInWorkflow` and `CommitLost`. */
+    operation: string;
+    /** A Postgres interval literal; tests shorten it to reach `55P03` in test time. */
+    lockTimeout?: string;
+}
+/**
+ * The only way a control-plane transaction is opened or committed. **Nothing inside `work` may
+ * catch**: a swallowed error leaves the transaction aborted, and Postgres then answers `COMMIT`
+ * with a `ROLLBACK` command tag that node-pg does not raise — the tag assert below is what makes
+ * that loud instead of silent (round-3 finding 5).
+ */
+export declare function controlPlaneTx<T>(pool: Pool, options: ControlPlaneTxOptions, work: (client: PoolClient) => Promise<T>): Promise<T>;
+/** Attempt 1 runs under the run's own id; attempt N under `${runId}:${N}`. */
+export declare function attemptWorkflowId(runId: string, attempt: number): string;
+export declare const LOCK_RUN_STATEMENT = "SELECT attempt, current_workflow_id, flow, input FROM hf_run WHERE run_id = $1 FOR UPDATE";
+export declare const BUMP_STATEMENT: string;
+export declare const WORKFLOW_ID_TAKEN_STATEMENT = "SELECT 1 FROM dbos.workflow_status WHERE workflow_uuid = $1";
+export interface BumpedAttempt {
+    runId: string;
+    /** The flow and input the new attempt is to be enqueued with. */
+    flow: string;
+    input: unknown;
+    previousAttempt: number;
+    attempt: number;
+    workflowId: string;
+}
+/**
+ * The one attempt-bump path — `runs.start`, `decide()`, `resume` and `reconcile()` all bump
+ * through this function and no other. `client` must already be inside a `controlPlaneTx`; the
+ * caller enqueues the returned `workflowId` on the same client, so the enqueue commits with the
+ * bump or not at all.
+ */
+export declare function bumpAttempt(client: ClientBase, runId: string): Promise<BumpedAttempt>;

package/dist/control-plane.js

@@ -0,0 +1,155 @@
+import { DBOS } from "@dbos-inc/dbos-sdk";
+/**
+ * The bound on a control-plane wait. Fenced writes are short by construction, so a wait this
+ * long is a bug being reported rather than work being lost.
+ */
+export const CONTROL_PLANE_LOCK_TIMEOUT = "30s";
+/** Postgres `lock_not_available`, what `lock_timeout` raises. */
+export const LOCK_NOT_AVAILABLE = "55P03";
+const LOCK_TIMEOUT_PATTERN = /^\d+(?:ms|s|min)$/;
+export class ControlPlaneInWorkflow extends Error {
+    operation;
+    constructor(operation) {
+        super(`ControlPlaneInWorkflow: ${operation} is a control-plane operation and cannot run inside a run`);
+        this.name = "ControlPlaneInWorkflow";
+        this.operation = operation;
+    }
+}
+export class CommitLost extends Error {
+    operation;
+    commandTag;
+    constructor(operation, commandTag) {
+        super(`CommitLost: ${operation} answered COMMIT with ${commandTag ?? "no command tag"}; ` +
+            "nothing the transaction wrote is durable");
+        this.name = "CommitLost";
+        this.operation = operation;
+        this.commandTag = commandTag;
+    }
+}
+export class RunNotFound extends Error {
+    runId;
+    constructor(runId) {
+        super(`RunNotFound: no hf_run row for ${runId}`);
+        this.name = "RunNotFound";
+        this.runId = runId;
+    }
+}
+export class ConcurrentBump extends Error {
+    runId;
+    attempt;
+    constructor(runId, attempt) {
+        super(`ConcurrentBump: hf_run ${runId} left attempt ${attempt} before this bump could write it`);
+        this.name = "ConcurrentBump";
+        this.runId = runId;
+        this.attempt = attempt;
+    }
+}
+export class WorkflowIdCollision extends Error {
+    runId;
+    workflowId;
+    constructor(runId, workflowId) {
+        super(`WorkflowIdCollision: a dbos.workflow_status row already exists for ${workflowId}, ` +
+            `the id ${runId}'s next attempt was about to take`);
+        this.name = "WorkflowIdCollision";
+        this.runId = runId;
+        this.workflowId = workflowId;
+    }
+}
+export class RunLockTimeout extends Error {
+    code = LOCK_NOT_AVAILABLE;
+    runId;
+    constructor(runId, cause) {
+        super(`RunLockTimeout (${LOCK_NOT_AVAILABLE}): waiting on the hf_run row of ${runId} ` +
+            "exceeded the control-plane lock_timeout", { cause });
+        this.name = "RunLockTimeout";
+        this.runId = runId;
+    }
+}
+/**
+ * The first thing every control-plane operation does, before any statement. `DBOS` is read on
+ * each call rather than destructured, so a stubbed predicate is seen (`fence.test.ts` (vii)).
+ */
+export function assertNotInWorkflow(operation) {
+    if (DBOS.isWithinWorkflow())
+        throw new ControlPlaneInWorkflow(operation);
+}
+/**
+ * The only way a control-plane transaction is opened or committed. **Nothing inside `work` may
+ * catch**: a swallowed error leaves the transaction aborted, and Postgres then answers `COMMIT`
+ * with a `ROLLBACK` command tag that node-pg does not raise — the tag assert below is what makes
+ * that loud instead of silent (round-3 finding 5).
+ */
+export async function controlPlaneTx(pool, options, work) {
+    assertNotInWorkflow(options.operation);
+    const lockTimeout = options.lockTimeout ?? CONTROL_PLANE_LOCK_TIMEOUT;
+    if (!LOCK_TIMEOUT_PATTERN.test(lockTimeout)) {
+        throw new TypeError(`lockTimeout must be a Postgres interval literal such as '30s': ${lockTimeout}`);
+    }
+    const client = await pool.connect();
+    let result;
+    try {
+        await client.query("BEGIN");
+        await client.query(`SET LOCAL lock_timeout = '${lockTimeout}'`);
+        result = await work(client);
+        const commit = await client.query("COMMIT");
+        if (commit.command !== "COMMIT")
+            throw new CommitLost(options.operation, commit.command);
+    }
+    catch (error) {
+        // The connection's transaction state is aborted or unknown, so it goes back *with* the error
+        // and the pool destroys it. `ROLLBACK`'s own failure must not mask the error that got here.
+        await client.query("ROLLBACK").catch(() => undefined);
+        client.release(error);
+        throw error;
+    }
+    client.release();
+    return result;
+}
+/** Attempt 1 runs under the run's own id; attempt N under `${runId}:${N}`. */
+export function attemptWorkflowId(runId, attempt) {
+    return attempt === 1 ? runId : `${runId}:${attempt}`;
+}
+export const LOCK_RUN_STATEMENT = "SELECT attempt, current_workflow_id, flow, input FROM hf_run WHERE run_id = $1 FOR UPDATE";
+export const BUMP_STATEMENT = "UPDATE hf_run SET attempt = $1, current_workflow_id = $2, status = 'running' " +
+    "WHERE run_id = $3 AND attempt = $4";
+export const WORKFLOW_ID_TAKEN_STATEMENT = "SELECT 1 FROM dbos.workflow_status WHERE workflow_uuid = $1";
+/**
+ * The one attempt-bump path — `runs.start`, `decide()`, `resume` and `reconcile()` all bump
+ * through this function and no other. `client` must already be inside a `controlPlaneTx`; the
+ * caller enqueues the returned `workflowId` on the same client, so the enqueue commits with the
+ * bump or not at all.
+ */
+export async function bumpAttempt(client, runId) {
+    const locked = await client.query(LOCK_RUN_STATEMENT, [runId]).catch((error) => {
+        // Rethrown, not handled: the transaction stays aborted and `controlPlaneTx` rolls it back.
+        // This only attaches the run id, which the raw `lock_timeout` message does not carry.
+        throw isLockTimeout(error) ? new RunLockTimeout(runId, error) : error;
+    });
+    if (locked.rowCount === 0)
+        throw new RunNotFound(runId);
+    const previousAttempt = Number(locked.rows[0].attempt);
+    // Computed here rather than as `attempt = attempt + 1` in SQL: the SQL form has no old value
+    // to compare against, so two bumps that both read N both "succeed" (round-2 finding 2). The
+    // number computed here is what the next statement's compare-and-set is against.
+    const attempt = previousAttempt + 1;
+    const workflowId = attemptWorkflowId(runId, attempt);
+    const bumped = await client.query(BUMP_STATEMENT, [attempt, workflowId, runId, previousAttempt]);
+    if (bumped.rowCount !== 1)
+        throw new ConcurrentBump(runId, previousAttempt);
+    // The id is fresh by construction, so a row under it is a bug in the construction — never a
+    // silent no-op, which would strand the run under a workflow this transaction did not enqueue.
+    const taken = await client.query(WORKFLOW_ID_TAKEN_STATEMENT, [workflowId]);
+    if (taken.rowCount !== 0)
+        throw new WorkflowIdCollision(runId, workflowId);
+    return {
+        runId,
+        flow: locked.rows[0].flow,
+        input: locked.rows[0].input,
+        previousAttempt,
+        attempt,
+        workflowId,
+    };
+}
+function isLockTimeout(error) {
+    return error?.code === LOCK_NOT_AVAILABLE;
+}