@hyperfixation/workflows 0.1.0

package/dist/approvals.js

@@ -0,0 +1,350 @@
+import { assertNotInWorkflow, controlPlaneTx, } from "@hyperfixation/db";
+import { sql } from "drizzle-orm";
+import { randomUUID } from "node:crypto";
+import { prettifyError } from "zod";
+import { bumpAndEnqueueOn } from "./bump.js";
+import { currentRun } from "./run-context.js";
+import { concludeRun } from "./run-status.js";
+import { step } from "./step.js";
+import { Suspend } from "./suspend.js";
+import { workerRuntime } from "./worker-runtime.js";
+/** Named in `ControlPlaneInWorkflow` and `CommitLost`. */
+export const DECIDE_OPERATION = "approvals.decide";
+/** The statuses `decide()` may write; `pending` is the only one it accepts as input. */
+export const APPROVAL_DECISIONS = ["approved", "rejected", "expired", "cancelled"];
+/**
+ * The gate a flow opts into. Not a `step()` itself but a pair of them plus a `Suspend`: the
+ * throw has to leave from the flow body, because a step that throws has its error checkpointed
+ * through `serialize-error` and a replay would revive a plain `Error` that `defineFlow`'s
+ * `instanceof Suspend` no longer catches.
+ *
+ * A decided row returns its decision and the flow carries on — that is how the attempt
+ * `decide()` enqueued passes through the gate it stopped at. Everything before this call runs
+ * again on that attempt and must be idempotent.
+ */
+export async function waitForApproval(options) {
+    const operation = `waitForApproval(${options.key})`;
+    const run = currentRun(operation);
+    const runtime = workerRuntime(operation);
+    const row = await step("approval", (ctx) => createOrRead(ctx, options), { key: options.key });
+    if (row.status !== "pending")
+        return decisionOf(row, options.key);
+    const notifier = options.notify ?? runtime.approvalNotifier;
+    await step("approval:notify", (ctx) => notify(ctx, options, row, notifier), {
+        key: options.key,
+    });
+    await concludeRun(runtime.control.pool, run.runId, run.workflowId, "waiting", null);
+    throw new Suspend(run.runId, "waiting", `approval ${options.key} is pending`);
+}
+/**
+ * Insert and read back in one `ctx.tx`, so the run is locked `FOR SHARE` before `hf_approval`
+ * is touched — the same order `decide()` takes them in. `ON CONFLICT DO NOTHING` is what keeps
+ * a crash inside this step from orphaning a second row for the same gate.
+ */
+async function createOrRead(ctx, options) {
+    return ctx.tx(async (db) => {
+        await db.execute(sql `
+      INSERT INTO hf_approval
+        (run_id, key, workflow_id, type, record_type, record_id, draft, status, assignee_id,
+         expires_at)
+      VALUES (${ctx.runId}, ${options.key}, ${ctx.workflowId}, ${options.type},
+              ${options.recordType ?? null}, ${options.recordId ?? null},
+              ${JSON.stringify(options.draft) ?? null}::jsonb, 'pending',
+              ${options.assigneeId ?? null},
+              ${options.expiresInMs ?? null}::bigint * interval '1 millisecond' + now())
+      ON CONFLICT (run_id, key) DO NOTHING
+    `);
+        const read = await db.execute(sql `
+      SELECT id, status, draft, edited_draft, decided_by, decided_via, notified_at,
+             assignee_id, record_type, record_id, to_json(expires_at) #>> '{}' AS expires_at
+      FROM hf_approval WHERE run_id = ${ctx.runId} AND key = ${options.key}
+    `);
+        return read.rows[0];
+    });
+}
+/** `notified_at` is set after the notifier returned, so a lost notification is retried. */
+async function notify(ctx, options, row, notifier) {
+    if (row.notified_at !== null)
+        return;
+    await notifier?.({
+        approvalId: Number(row.id),
+        runId: ctx.runId,
+        key: options.key,
+        type: options.type,
+        draft: row.draft,
+        assigneeId: row.assignee_id,
+        recordType: row.record_type,
+        recordId: row.record_id,
+        expiresAt: row.expires_at === null ? null : new Date(row.expires_at),
+    }, ctx);
+    await ctx.tx(async (db) => {
+        await db.execute(sql `
+      UPDATE hf_approval SET notified_at = now()
+      WHERE run_id = ${ctx.runId} AND key = ${options.key} AND notified_at IS NULL
+    `);
+    });
+}
+function decisionOf(row, key) {
+    return {
+        approvalId: Number(row.id),
+        key,
+        status: row.status,
+        draft: row.edited_draft ?? row.draft,
+        decidedBy: row.decided_by,
+        decidedVia: row.decided_via,
+    };
+}
+export class ApprovalBatchRefused extends Error {
+    reasons;
+    constructor(reasons) {
+        super(`ApprovalBatchRefused: ${reasons
+            .map((r) => `${r.approvalId} ${r.reason}`)
+            .join("; ")} — the whole batch was rolled back`);
+        this.name = "ApprovalBatchRefused";
+        this.reasons = reasons;
+    }
+}
+export class ApprovalRunMoved extends Error {
+    constructor(approvalId) {
+        super(`ApprovalRunMoved: approval ${approvalId} changed run between the unlocked read that ` +
+            "chose which runs to lock and the locked one");
+        this.name = "ApprovalRunMoved";
+    }
+}
+export class ApprovalWriteLost extends Error {
+    constructor(approvalId, rowCount) {
+        super(`ApprovalWriteLost: the conditional update of approval ${approvalId} matched ${rowCount} ` +
+            "rows under its own FOR UPDATE lock");
+        this.name = "ApprovalWriteLost";
+    }
+}
+const RUN_IDS_STATEMENT = "SELECT id, run_id FROM hf_approval WHERE id = ANY($1::bigint[])";
+/**
+ * The runs are locked before the approvals and in id order — the order `waitForApproval` takes
+ * them in through `ctx.tx`, and the one that stops a step's `INSERT … ON CONFLICT` deadlocking
+ * against a decision on the same run (round 3).
+ */
+const LOCK_RUNS_STATEMENT = "SELECT run_id, attempt, current_workflow_id FROM hf_run WHERE run_id = ANY($1::text[]) " +
+    "ORDER BY run_id FOR UPDATE";
+const LOCK_APPROVALS_STATEMENT = "SELECT id, run_id, key, status, decision_key, type, assignee_id, record_type, record_id " +
+    "FROM hf_approval WHERE id = ANY($1::bigint[]) ORDER BY id FOR UPDATE";
+const DECIDE_STATEMENT = "UPDATE hf_approval SET status = $2, decided_by = $3, decided_at = now(), decided_via = $4, " +
+    "edited_draft = COALESCE($5::jsonb, edited_draft), decision_key = $6, batch_id = $7 " +
+    "WHERE id = $1 AND status = 'pending'";
+const RESUME_WORKFLOW_STATEMENT = "UPDATE hf_approval SET resume_workflow_id = $2 WHERE id = ANY($1::bigint[])";
+const AUDIT_STATEMENT = "INSERT INTO hf_audit (actor_id, action, target_type, target_id, meta) " +
+    "VALUES ($1, $2, 'hf_approval', $3, $4::jsonb)";
+const ACTIVITY_STATEMENT = "INSERT INTO hf_activity (record_type, record_id, kind, actor_id, run_id, meta) " +
+    "VALUES ($1, $2, $3, $4, NULL, $5::jsonb)";
+/**
+ * The one way an approval is decided, whoever decides it: the inbox, the admin, a Telegram
+ * callback, `records.archive()` and `reconcile()`'s expiry sweep all come through here.
+ *
+ * A control-plane operation, and one transaction: the decision, the attempt bump and the
+ * enqueue of the resume workflow commit together or not at all, so a crash anywhere before the
+ * tag-asserted `COMMIT` leaves the approval `pending` and the run untouched, and a retry with
+ * the same `decisionKey` starts over. **Nothing in here catches** — a swallowed error would
+ * leave the transaction aborted and Postgres would answer `COMMIT` with a `ROLLBACK` tag
+ * (round-3 finding 5).
+ */
+export async function decide(pool, dbosClient, options) {
+    assertNotInWorkflow(DECIDE_OPERATION);
+    // A caller that hands edits with no way to validate them is a wiring bug, not a refused row.
+    if (Object.keys(options.edits ?? {}).length > 0 && options.schemaFor === undefined) {
+        throw new TypeError(`${DECIDE_OPERATION}: edits were given with no schemaFor; an edited draft is only written ` +
+            "once it parses against its approval type's schema");
+    }
+    try {
+        return await decideOnce(pool, dbosClient, options);
+    }
+    catch (error) {
+        // The read that chose which runs to lock is unlocked by necessity — an approval names its
+        // run, not the other way round. Losing that race once is ordinary; twice is not.
+        if (!(error instanceof ApprovalRunMoved))
+            throw error;
+        return await decideOnce(pool, dbosClient, options);
+    }
+}
+async function decideOnce(pool, dbosClient, options) {
+    const ids = [...new Set(options.ids)].sort((a, b) => a - b);
+    const lockTimeout = options.lockTimeout === undefined ? {} : { lockTimeout: options.lockTimeout };
+    return controlPlaneTx(pool, { operation: DECIDE_OPERATION, ...lockTimeout }, async (client) => {
+        const scouted = await client.query(RUN_IDS_STATEMENT, [ids]);
+        const runIds = [...new Set(scouted.rows.map((row) => row.run_id))].sort();
+        const runs = await client.query(LOCK_RUNS_STATEMENT, [runIds]);
+        const locked = await client.query(LOCK_APPROVALS_STATEMENT, [ids]);
+        for (const row of locked.rows) {
+            if (!runIds.includes(row.run_id))
+                throw new ApprovalRunMoved(Number(row.id));
+        }
+        const byId = new Map(locked.rows.map((row) => [Number(row.id), row]));
+        const replay = locked.rows.filter((row) => row.decision_key === options.decisionKey);
+        if (replay.length > 0) {
+            if (replay.length !== locked.rows.length) {
+                throw new ApprovalBatchRefused(locked.rows
+                    .filter((row) => row.decision_key !== options.decisionKey)
+                    .map((row) => ({
+                    approvalId: Number(row.id),
+                    reason: `was not part of the batch decided under ${options.decisionKey}`,
+                })));
+            }
+            return replayed(client, locked.rows, runs.rows);
+        }
+        const parsed = assertDecidable(ids, locked.rows, options);
+        // One id is one row; a batch id would only name a batch of it.
+        const batchId = ids.length > 1 ? randomUUID() : null;
+        for (const row of locked.rows) {
+            const id = Number(row.id);
+            const written = await client.query(DECIDE_STATEMENT, [
+                row.id,
+                options.decision,
+                options.userId ?? null,
+                options.via,
+                parsed.has(id) ? JSON.stringify(parsed.get(id)) : null,
+                options.decisionKey,
+                batchId,
+            ]);
+            if (written.rowCount !== 1)
+                throw new ApprovalWriteLost(Number(row.id), written.rowCount ?? 0);
+        }
+        const decided = [];
+        const reattempted = [];
+        for (const runId of runIds) {
+            const bumped = await bumpAndEnqueueOn(client, dbosClient, runId);
+            reattempted.push({
+                runId,
+                attempt: bumped.attempt,
+                workflowId: bumped.workflowId,
+            });
+            const theirs = locked.rows.filter((row) => row.run_id === runId);
+            await client.query(RESUME_WORKFLOW_STATEMENT, [
+                theirs.map((row) => row.id),
+                bumped.workflowId,
+            ]);
+            for (const row of theirs) {
+                decided.push({
+                    approvalId: Number(row.id),
+                    runId,
+                    key: row.key,
+                    status: options.decision,
+                    resumeWorkflowId: bumped.workflowId,
+                });
+            }
+        }
+        // Fatal by construction: an audit row this transaction could not write is a decision with
+        // no record of who made it, and there is no catch anywhere for it to be demoted by.
+        for (const row of decided) {
+            const meta = JSON.stringify({
+                runId: row.runId,
+                key: row.key,
+                via: options.via,
+                decisionKey: options.decisionKey,
+                batchId,
+                resumeWorkflowId: row.resumeWorkflowId,
+            });
+            await client.query(AUDIT_STATEMENT, [
+                options.userId ?? null,
+                `approval.${options.decision}`,
+                String(row.approvalId),
+                meta,
+            ]);
+            // Last, because `hf_activity` is in the last lock tier and every `hf_approval` write is
+            // already behind us. Fatal under the same rule as the audit row above. The record columns
+            // follow the approval's, NULL included — a stand-in type would fail E002 at the next boot.
+            const target = byId.get(row.approvalId);
+            await client.query(ACTIVITY_STATEMENT, [
+                target.record_type,
+                target.record_id,
+                `approval.${options.decision}`,
+                options.userId ?? null,
+                meta,
+            ]);
+        }
+        return { replayed: false, decided, reattempted, batchId };
+    });
+}
+/**
+ * Every reason the batch is refused, gathered in one pass before anything is written, and the
+ * parsed edits the write then stores — what the schema returned, not what the caller sent.
+ */
+function assertDecidable(ids, locked, options) {
+    const reasons = [];
+    const parsed = new Map();
+    const found = new Set(locked.map((row) => Number(row.id)));
+    for (const id of ids) {
+        // `ids` is typed `number[]`, but a caller crossing a query string or a JSON body can still
+        // hand a numeric string: Postgres accepts it, `found` is keyed by number, and the row would
+        // be reported missing when it is right there.
+        if (typeof id !== "number") {
+            reasons.push({
+                approvalId: Number(id),
+                reason: `was given as a ${typeof id}, not a number`,
+            });
+            continue;
+        }
+        if (!found.has(id))
+            reasons.push({ approvalId: id, reason: "has no hf_approval row" });
+    }
+    // `archive` and `sweep` carry no human decider — the record went, or the row timed out — so
+    // the assignee rule would only stop an assigned row from ever being cancelled or expired.
+    const humanDecision = options.via !== "archive" && options.via !== "sweep";
+    for (const row of locked) {
+        const id = Number(row.id);
+        if (row.status !== "pending") {
+            reasons.push({ approvalId: id, reason: `is already ${row.status}` });
+        }
+        if (humanDecision &&
+            row.assignee_id !== null &&
+            row.assignee_id !== options.userId &&
+            options.admin !== true) {
+            reasons.push({ approvalId: id, reason: `is assigned to ${row.assignee_id}` });
+        }
+        const edit = options.edits?.[id];
+        if (edit === undefined)
+            continue;
+        const schema = options.schemaFor?.(row.type);
+        if (schema === undefined) {
+            reasons.push({
+                approvalId: id,
+                reason: `has an edit but type ${row.type} has no registered schema`,
+            });
+            continue;
+        }
+        const result = schema.safeParse(edit);
+        if (!result.success) {
+            reasons.push({
+                approvalId: id,
+                reason: `has an edit that does not match schema for type ${row.type}: ${prettifyError(result.error)}`,
+            });
+            continue;
+        }
+        parsed.set(id, result.data);
+    }
+    if (reasons.length > 0)
+        throw new ApprovalBatchRefused(reasons);
+    return parsed;
+}
+/**
+ * What the transaction that first carried this `decisionKey` returned, read back rather than
+ * recomputed: the resume workflow it enqueued is on the rows it wrote.
+ */
+async function replayed(client, locked, runs) {
+    const { rows } = await client.query("SELECT id, run_id, key, status, resume_workflow_id, batch_id FROM hf_approval WHERE id = ANY($1::bigint[]) ORDER BY id", [locked.map((row) => row.id)]);
+    return {
+        replayed: true,
+        batchId: rows[0]?.batch_id ?? null,
+        decided: rows.map((row) => ({
+            approvalId: Number(row.id),
+            runId: row.run_id,
+            key: row.key,
+            status: row.status,
+            resumeWorkflowId: row.resume_workflow_id ?? "",
+        })),
+        reattempted: runs.map((run) => ({
+            runId: run.run_id,
+            attempt: Number(run.attempt),
+            workflowId: run.current_workflow_id,
+        })),
+    };
+}
+export const approvals = { decide, waitForApproval };

package/dist/bump.d.ts

@@ -0,0 +1,18 @@
+import type { DBOSClient } from "@dbos-inc/dbos-sdk";
+import { type BumpedAttempt } from "@hyperfixation/db";
+import type { ClientBase } from "pg";
+export declare class UnknownFlow extends Error {
+    readonly runId: string;
+    constructor(runId: string, flow: string);
+}
+/**
+ * The one attempt-bump path with its enqueue, on a client already inside a control-plane
+ * transaction: `reconcile()` opens one per run, `decide()` bumps inside the transaction that
+ * writes the decision, and neither has a bump of its own. The queue name comes from the flow
+ * registry and from nowhere else (round-2 finding 2).
+ */
+export declare function bumpAndEnqueueOn(client: ClientBase, dbosClient: DBOSClient, runId: string): Promise<BumpedAttempt>;
+export declare function flowForRun(runId: string, name: string): {
+    name: string;
+    queue: string;
+};

package/dist/bump.js

@@ -0,0 +1,29 @@
+import { bumpAttempt } from "@hyperfixation/db";
+import { definedFlows } from "./define-flow.js";
+export class UnknownFlow extends Error {
+    runId;
+    constructor(runId, flow) {
+        super(`UnknownFlow: hf_run ${runId} names flow ${JSON.stringify(flow)}, which this worker does ` +
+            "not register; its next attempt has no queue to be enqueued on");
+        this.name = "UnknownFlow";
+        this.runId = runId;
+    }
+}
+/**
+ * The one attempt-bump path with its enqueue, on a client already inside a control-plane
+ * transaction: `reconcile()` opens one per run, `decide()` bumps inside the transaction that
+ * writes the decision, and neither has a bump of its own. The queue name comes from the flow
+ * registry and from nowhere else (round-2 finding 2).
+ */
+export async function bumpAndEnqueueOn(client, dbosClient, runId) {
+    const bumped = await bumpAttempt(client, runId);
+    const flow = flowForRun(runId, bumped.flow);
+    await dbosClient.enqueueInTransaction(client, { queueName: flow.queue, workflowName: flow.name, workflowID: bumped.workflowId }, { runId, attempt: bumped.attempt, input: bumped.input });
+    return bumped;
+}
+export function flowForRun(runId, name) {
+    const flow = definedFlows().get(name);
+    if (flow === undefined)
+        throw new UnknownFlow(runId, name);
+    return flow;
+}

package/dist/client.d.ts

@@ -0,0 +1,25 @@
+import { DBOSClient } from "@dbos-inc/dbos-sdk";
+import { type RecordTable } from "@hyperfixation/db";
+export declare const CLIENT_POOL_SIZE = 2;
+export interface GetClientOptions {
+    appName: string;
+    /** The application role's connection string, the same one the worker launches on. */
+    databaseUrl: string;
+    recordTables?: readonly RecordTable[];
+    appMigrationsDir?: string;
+}
+/**
+ * The web process's whole relationship with DBOS: it enqueues through this client and never
+ * calls `DBOS.launch()`.
+ *
+ * The promise is cached rather than the client, so concurrent first callers share one
+ * boot-check pass and one client; a failed boot caches nothing, so the next caller retries.
+ */
+export declare function getClient(options: GetClientOptions): Promise<DBOSClient>;
+/**
+ * Drops the cached client so the next `getClient()` call creates a fresh one. A real process
+ * has one `databaseUrl` for its whole life and never needs this; it exists for tests that spin
+ * up more than one database in a single process, where the cache would otherwise hand a later
+ * test a client still bound to an earlier test's already-dropped database.
+ */
+export declare function resetClient(): Promise<void>;

package/dist/client.js

@@ -0,0 +1,43 @@
+import { DBOSClient } from "@dbos-inc/dbos-sdk";
+import { runBootChecks } from "@hyperfixation/db";
+import { SYSTEM_DATABASE_SCHEMA } from "./start-worker.js";
+export const CLIENT_POOL_SIZE = 2;
+let client;
+/**
+ * The web process's whole relationship with DBOS: it enqueues through this client and never
+ * calls `DBOS.launch()`.
+ *
+ * The promise is cached rather than the client, so concurrent first callers share one
+ * boot-check pass and one client; a failed boot caches nothing, so the next caller retries.
+ */
+export function getClient(options) {
+    client ??= createClient(options).catch((error) => {
+        client = undefined;
+        throw error;
+    });
+    return client;
+}
+/**
+ * Drops the cached client so the next `getClient()` call creates a fresh one. A real process
+ * has one `databaseUrl` for its whole life and never needs this; it exists for tests that spin
+ * up more than one database in a single process, where the cache would otherwise hand a later
+ * test a client still bound to an earlier test's already-dropped database.
+ */
+export async function resetClient() {
+    const current = client;
+    client = undefined;
+    await current?.then((c) => c.destroy()).catch(() => undefined);
+}
+async function createClient(options) {
+    await runBootChecks({
+        databaseUrl: options.databaseUrl,
+        recordTables: options.recordTables,
+        appMigrationsDir: options.appMigrationsDir,
+    });
+    return await DBOSClient.create({
+        systemDatabaseUrl: options.databaseUrl,
+        systemDatabaseSchemaName: SYSTEM_DATABASE_SCHEMA,
+        systemDatabasePoolSize: CLIENT_POOL_SIZE,
+        applicationName: options.appName,
+    });
+}

package/dist/control-pool.d.ts

@@ -0,0 +1,21 @@
+import * as schema from "@hyperfixation/db";
+import { type NodePgDatabase } from "drizzle-orm/node-postgres";
+import { Pool, type PoolConfig } from "pg";
+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 handle in the worker, carrying the writes whose fence is a predicate
+ * (`WHERE current_workflow_id = …`) rather than a row lock. No fence wrapper: that is the
+ * step pool's job.
+ *
+ * `@hyperfixation/db` holds the identical factory in `src/internal/`, which its `exports`
+ * map deliberately does not resolve — "no export resolves to the control pool" is contract
+ * surface, enforced by the resolver rather than by convention. Repeating ten lines of `pg`
+ * boilerplate here is what keeps that structural.
+ */
+export declare function createControlPool(options: PoolConfig): ControlPool;

package/dist/control-pool.js

@@ -0,0 +1,18 @@
+import * as schema from "@hyperfixation/db";
+import { drizzle } from "drizzle-orm/node-postgres";
+import { Pool } from "pg";
+export const CONTROL_POOL_SIZE = 2;
+/**
+ * Core's own handle in the worker, carrying the writes whose fence is a predicate
+ * (`WHERE current_workflow_id = …`) rather than a row lock. No fence wrapper: that is the
+ * step pool's job.
+ *
+ * `@hyperfixation/db` holds the identical factory in `src/internal/`, which its `exports`
+ * map deliberately does not resolve — "no export resolves to the control pool" is contract
+ * surface, enforced by the resolver rather than by convention. Repeating ten lines of `pg`
+ * boilerplate here is what keeps that structural.
+ */
+export function createControlPool(options) {
+    const pool = new Pool({ max: CONTROL_POOL_SIZE, ...options });
+    return { pool, db: drizzle(pool, { schema }), end: () => pool.end() };
+}

package/dist/define-flow.d.ts

@@ -0,0 +1,40 @@
+import { type RunContext } from "./run-context.js";
+import { type QueueName } from "./start-worker.js";
+/** What DBOS carries as the workflow's one argument. */
+export interface FlowArgs<I> {
+    runId: string;
+    attempt: number;
+    input: I;
+}
+export interface Flow<I = unknown, O = unknown> {
+    readonly name: string;
+    readonly queue: QueueName;
+    /**
+     * The registered DBOS workflow in a worker, and the bare body anywhere else — see
+     * `defineFlow`. Either way nothing calls it: `runs.start` enqueues by name, never by
+     * reference, and calling it outside a run throws `OutsideRun`.
+     */
+    readonly workflow: (args: FlowArgs<I>) => Promise<O | undefined>;
+}
+export interface DefineFlowOptions {
+    queue: QueueName;
+}
+export declare class DuplicateFlow extends Error {
+    constructor(name: string);
+}
+export declare class UnknownQueue extends Error {
+    constructor(name: string, queue: string);
+}
+/** Logged when an attempt finds the run already on a later one; it runs nothing. */
+export declare const SUPERSEDED_MARKER = "hf-run: superseded attempt, the flow was not run";
+/** The one source of a queue name for an enqueue, and of a flow name for `runs.start`. */
+export declare function definedFlows(): ReadonlyMap<string, Flow<never, unknown>>;
+/**
+ * Registers `fn` as a DBOS workflow whose lifecycle is the run's. The wrapper owns every
+ * `hf_run` status write of the attempt, and every one of them carries the
+ * `AND current_workflow_id = …` fence — the wrapper's job is as much to *not* write after a
+ * bump as it is to write.
+ *
+ * The DBOS registration itself happens only in a worker process; see the comment on it.
+ */
+export declare function defineFlow<I, O>(name: string, fn: (input: I, run: RunContext) => Promise<O>, options: DefineFlowOptions): Flow<I, O>;

package/dist/define-flow.js

@@ -0,0 +1,83 @@
+import { DBOS } from "@dbos-inc/dbos-sdk";
+import { OutsideRun, withRunContext } from "./run-context.js";
+import { claimRun, concludeRun } from "./run-status.js";
+import { QUEUES, WORKER_PROCESS } from "./start-worker.js";
+import { Suspend } from "./suspend.js";
+import { workerRuntime } from "./worker-runtime.js";
+export class DuplicateFlow extends Error {
+    constructor(name) {
+        super(`DuplicateFlow: a flow named ${JSON.stringify(name)} is already defined`);
+        this.name = "DuplicateFlow";
+    }
+}
+export class UnknownQueue extends Error {
+    constructor(name, queue) {
+        super(`UnknownQueue: flow ${JSON.stringify(name)} names queue ${JSON.stringify(queue)}; ` +
+            `the queues are ${QUEUES.map((q) => q.name).join(", ")}`);
+        this.name = "UnknownQueue";
+    }
+}
+/** Logged when an attempt finds the run already on a later one; it runs nothing. */
+export const SUPERSEDED_MARKER = "hf-run: superseded attempt, the flow was not run";
+const flows = new Map();
+/** The one source of a queue name for an enqueue, and of a flow name for `runs.start`. */
+export function definedFlows() {
+    return flows;
+}
+/**
+ * Registers `fn` as a DBOS workflow whose lifecycle is the run's. The wrapper owns every
+ * `hf_run` status write of the attempt, and every one of them carries the
+ * `AND current_workflow_id = …` fence — the wrapper's job is as much to *not* write after a
+ * bump as it is to write.
+ *
+ * The DBOS registration itself happens only in a worker process; see the comment on it.
+ */
+export function defineFlow(name, fn, options) {
+    if (flows.has(name))
+        throw new DuplicateFlow(name);
+    if (!QUEUES.some((queue) => queue.name === options.queue)) {
+        throw new UnknownQueue(name, options.queue);
+    }
+    const body = async (args) => {
+        const workflowId = DBOS.workflowID;
+        if (workflowId === undefined)
+            throw new OutsideRun(`flow ${name}`);
+        const runtime = workerRuntime(`flow ${name}`);
+        const run = { runId: args.runId, attempt: args.attempt, workflowId };
+        // The claim is the fence as well as the status write: zero rows means a bump moved the
+        // run on before this attempt was dequeued, so it stops here without touching the run.
+        // Not an error — a superseded attempt ending quietly is the design working.
+        if (!(await claimRun(runtime.control.pool, run.runId, workflowId, runtime.applicationVersion))) {
+            console.info(SUPERSEDED_MARKER, JSON.stringify({ flow: name, ...run }));
+            return undefined;
+        }
+        try {
+            const output = await withRunContext(run, () => fn(args.input, run));
+            await concludeRun(runtime.control.pool, run.runId, workflowId, "done", null);
+            return output;
+        }
+        catch (error) {
+            if (error instanceof Suspend) {
+                await concludeRun(runtime.control.pool, run.runId, workflowId, error.status, null);
+                return undefined;
+            }
+            await concludeRun(runtime.control.pool, run.runId, workflowId, "failed", messageOf(error));
+            throw error;
+        }
+    };
+    // Only in the worker, and for the same reason `DBOS.launch()` is only there: a registration
+    // is a global side effect in the one object DBOS keeps per process, and the web's copy of
+    // this module is not one per process. Next splits an app's server code per route, so
+    // `src/flows/*.ts` is evaluated once per chunk that reaches it while `@dbos-inc/dbos-sdk`
+    // stays external and singular — the second evaluation is refused and every route that
+    // touches the app 500s from then on. The web never dispatches a workflow anyway; it enqueues
+    // by name through `DBOSClient`, and the name comes from `flows` below, which is per-instance
+    // and identical in every instance.
+    const workflow = process.env.HF_PROCESS === WORKER_PROCESS ? DBOS.registerWorkflow(body, { name }) : body;
+    const flow = { name, queue: options.queue, workflow };
+    flows.set(name, flow);
+    return flow;
+}
+function messageOf(error) {
+    return error instanceof Error ? `${error.name}: ${error.message}` : String(error);
+}

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+export { startWorker, MissingBuildSha, NotAWorkerProcess, DRAIN_TIMEOUT_MS, LAUNCHED_MARKER, LAUNCHING_MARKER, MIN_BUILD_SHA_LENGTH, QUEUES, RECONCILER_POOL_SIZE, SHUTDOWN_FAILED_MARKER, SHUTDOWN_IGNORED_MARKER, SHUTDOWN_MARKER, SHUTDOWN_WATCHDOG_MS, SYSTEM_DATABASE_POOL_SIZE, SYSTEM_DATABASE_SCHEMA, WORKER_PROCESS, type QueueName, type StartWorkerOptions, type Worker, } from "./start-worker.js";
+export { registerLangfuse, LANGFUSE_ENV, type LangfuseRegistration } from "./langfuse.js";
+export { getClient, resetClient, CLIENT_POOL_SIZE, type GetClientOptions } from "./client.js";
+export { setPausedQueueConcurrency, PAUSED_CONCURRENCY, PAUSED_QUEUES, type QueueConcurrency, } from "./queue-concurrency.js";
+export { WorkerLockUnavailable, LOCK_ACQUIRED_MARKER, type WorkerLock } from "./worker-lock.js";
+export { defineFlow, definedFlows, DuplicateFlow, UnknownQueue, SUPERSEDED_MARKER, type DefineFlowOptions, type Flow, type FlowArgs, } from "./define-flow.js";
+export { step, STEP_GATE_STATEMENT, type StepContext, type StepOptions } from "./step.js";
+export { actions, perform, idempotencyKey, stubChannel, ActionUncertain, type ActionChannel, type ActionDispatch, type ActionResult, type ActionsPerformOptions, } from "./actions.js";
+export { approvals, decide, waitForApproval, ApprovalBatchRefused, ApprovalRunMoved, ApprovalWriteLost, APPROVAL_DECISIONS, DECIDE_OPERATION, type ApprovalDecision, type ApprovalDecisionKind, type ApprovalDraftSchema, type ApprovalNotice, type ApprovalNotifier, type DecideOptions, type DecideResult, type DecidedApproval, type WaitForApprovalOptions, } from "./approvals.js";
+export { createApprovalNotifier, NO_RECIPIENTS_MARKER, type ApprovalMessage, type ApprovalNotifierOptions, } from "./approval-notifier.js";
+export { handleTelegramCallback, encodeCallbackData, decodeCallbackData, decisionKeyFor, maxNonceLength, CallbackDataTooLong, CALLBACK_DATA_MAX_BYTES, CALLBACK_DATA_VERSION, type TelegramCallbackData, type TelegramCallbackFrom, type TelegramCallbackOptions, type TelegramCallbackOutcome, type TelegramCallbackResult, type TelegramDecision, } from "./telegram.js";
+export { UnknownFlow } from "./bump.js";
+export { Suspend, SUSPEND_STATUSES, type SuspendStatus } from "./suspend.js";
+export { currentRun, OutsideRun, type RunContext } from "./run-context.js";
+export { runsStart, START_RUN_STATEMENT, type RunsStartOptions, type StartedRun } from "./runs.js";
+export { reconcile, startReconciler, sweepDecisionKey, ABANDON_LLM_CALLS_STATEMENT, DRIFT_STATEMENT, EXPIRED_APPROVALS_STATEMENT, PAUSED_RUNS_STATEMENT, RECONCILE_ACTION_MARKER, RECONCILE_ANOMALY_MARKER, RECONCILE_FAILED_MARKER, RECONCILE_INTERVAL_MS, RECONCILE_PASS_MARKER, RECONCILE_QUEUE_MARKER, RUNNING_RUNS_STATEMENT, UNCERTAIN_ACTIONS_STATEMENT, type Concluded, type ExpiredApproval, type PeriodDrift, type QueueConcurrencyCorrection, type Reattempted, type ReconcileAnomaly, type ReconcileFailure, type ReconcileOptions, type ReconcileReport, type Reconciler, } from "./reconcile.js";
+/**
+ * The types travel with `Worker`, the factory does not: `startWorker()` is the only way to
+ * get a control pool, which is what keeps "no export resolves to the control pool" true of
+ * this package as well as of `@hyperfixation/db`.
+ */
+export type { ControlDatabase, ControlPool } from "./control-pool.js";