@intx/db 0.2.2 → 0.3.0

package/dist/signal-correlation-store.d.ts

@@ -0,0 +1,36 @@
+import type { DB, DBExecutor } from "./client.js";
+import { signalCorrelation } from "./schema/signal-correlations.js";
+import { parseSignalCorrelationRow } from "./parse-row.js";
+type DBHandle = DB["db"];
+type SignalCorrelationInsert = typeof signalCorrelation.$inferInsert;
+type ParsedSignalCorrelation = ReturnType<typeof parseSignalCorrelationRow>;
+/**
+ * Store for the `signal_correlation` table, which maps an in-flight signal
+ * (correlation id) to the run and address that must be resumed when the signal
+ * resolves. Each method accepts an optional transaction handle so the resolver
+ * can claim the correlation and flip its approval atomically.
+ */
+export declare function createSignalCorrelationStore(db: DBHandle): {
+    register(row: SignalCorrelationInsert, tx?: DBExecutor): Promise<ParsedSignalCorrelation>;
+    /**
+     * Idempotent variant of `register`. On a `correlationId` primary-key
+     * conflict the insert is a no-op and this returns `null` rather than
+     * throwing, so a redelivered register frame (sidecar reconnect,
+     * workflow-log replay, supervisor restart re-emitting) does not fail the
+     * co-write. Returns the parsed row only when this call performed the
+     * insert.
+     */
+    registerIfAbsent(row: SignalCorrelationInsert, tx?: DBExecutor): Promise<ParsedSignalCorrelation | null>;
+    resolveRoute(correlationId: string, tx?: DBExecutor): Promise<ParsedSignalCorrelation | null>;
+    /**
+     * Atomically claim a correlation for terminal delivery. The
+     * `resolved_at IS NULL` guard makes the claim single-shot: the first caller
+     * stamps `resolvedAt` and gets the row back; any second caller matches no
+     * row and receives null, so a redelivered signal is not delivered twice.
+     * When `signalId` is provided it is persisted on the same update, recording
+     * which signal instance won the claim for redelivery idempotency.
+     */
+    claimTerminal(correlationId: string, resolvedAt: Date, signalId: string | null, tx?: DBExecutor): Promise<ParsedSignalCorrelation | null>;
+};
+export type SignalCorrelationStore = ReturnType<typeof createSignalCorrelationStore>;
+export {};

package/dist/signal-correlation-store.js

@@ -0,0 +1,63 @@
+import { and, eq, isNull } from "drizzle-orm";
+import { signalCorrelation } from "./schema/signal-correlations.js";
+import { parseSignalCorrelationRow } from "./parse-row.js";
+/**
+ * Store for the `signal_correlation` table, which maps an in-flight signal
+ * (correlation id) to the run and address that must be resumed when the signal
+ * resolves. Each method accepts an optional transaction handle so the resolver
+ * can claim the correlation and flip its approval atomically.
+ */
+export function createSignalCorrelationStore(db) {
+    return {
+        async register(row, tx) {
+            const [inserted] = await (tx ?? db)
+                .insert(signalCorrelation)
+                .values(row)
+                .returning();
+            if (inserted === undefined) {
+                throw new Error(`signalCorrelationStore.register: insert returned no row for ${row.correlationId}`);
+            }
+            return parseSignalCorrelationRow(inserted);
+        },
+        /**
+         * Idempotent variant of `register`. On a `correlationId` primary-key
+         * conflict the insert is a no-op and this returns `null` rather than
+         * throwing, so a redelivered register frame (sidecar reconnect,
+         * workflow-log replay, supervisor restart re-emitting) does not fail the
+         * co-write. Returns the parsed row only when this call performed the
+         * insert.
+         */
+        async registerIfAbsent(row, tx) {
+            const [inserted] = await (tx ?? db)
+                .insert(signalCorrelation)
+                .values(row)
+                .onConflictDoNothing({ target: signalCorrelation.correlationId })
+                .returning();
+            return inserted === undefined
+                ? null
+                : parseSignalCorrelationRow(inserted);
+        },
+        async resolveRoute(correlationId, tx) {
+            const row = await (tx ?? db).query.signalCorrelation.findFirst({
+                where: eq(signalCorrelation.correlationId, correlationId),
+            });
+            return row === undefined ? null : parseSignalCorrelationRow(row);
+        },
+        /**
+         * Atomically claim a correlation for terminal delivery. The
+         * `resolved_at IS NULL` guard makes the claim single-shot: the first caller
+         * stamps `resolvedAt` and gets the row back; any second caller matches no
+         * row and receives null, so a redelivered signal is not delivered twice.
+         * When `signalId` is provided it is persisted on the same update, recording
+         * which signal instance won the claim for redelivery idempotency.
+         */
+        async claimTerminal(correlationId, resolvedAt, signalId, tx) {
+            const [claimed] = await (tx ?? db)
+                .update(signalCorrelation)
+                .set({ resolvedAt, signalId })
+                .where(and(eq(signalCorrelation.correlationId, correlationId), isNull(signalCorrelation.resolvedAt)))
+                .returning();
+            return claimed === undefined ? null : parseSignalCorrelationRow(claimed);
+        },
+    };
+}

package/dist/tenant-hierarchy.d.ts

@@ -3,7 +3,8 @@ import type { DB } from "./client.js";
  * Walks the tenant parentId chain from the given tenant up to the root.
  * Returns an ordered array of tenant IDs: [tenantId, parentId, grandparentId, ...rootId].
  *
- * Protects against cycles with a depth limit.
+ * Throws if the hierarchy contains a cycle instead of returning a partial
+ * chain that could omit inherited policy or configuration.
  */
 export declare function getAncestorChain(db: DB["db"], tenantId: string): Promise<string[]>;
 /**

package/dist/tenant-hierarchy.js

@@ -1,23 +1,28 @@
 import { eq, inArray } from "drizzle-orm";
 import { tenant } from "./schema/tenants.js";
-const MAX_DEPTH = 20;
 /**
  * Walks the tenant parentId chain from the given tenant up to the root.
  * Returns an ordered array of tenant IDs: [tenantId, parentId, grandparentId, ...rootId].
  *
- * Protects against cycles with a depth limit.
+ * Throws if the hierarchy contains a cycle instead of returning a partial
+ * chain that could omit inherited policy or configuration.
  */
 export async function getAncestorChain(db, tenantId) {
-    const chain = [tenantId];
+    const chain = [];
+    const visited = new Set();
     let currentId = tenantId;
-    for (let depth = 0; depth < MAX_DEPTH; depth++) {
+    while (true) {
+        if (visited.has(currentId)) {
+            throw new Error(`Tenant hierarchy contains a cycle at tenant ${currentId}`);
+        }
+        visited.add(currentId);
+        chain.push(currentId);
         const row = await db.query.tenant.findFirst({
             where: eq(tenant.id, currentId),
             columns: { parentId: true },
         });
         if (!row?.parentId)
             break;
-        chain.push(row.parentId);
         currentId = row.parentId;
     }
     return chain;

package/dist/workflow-definition-store.d.ts

@@ -0,0 +1,55 @@
+import { GrantWalkSnapshot } from "@intx/types";
+import type { DB, DBExecutor } from "./client.js";
+import { parseWorkflowDefinitionRow } from "./parse-row.js";
+type DBHandle = DB["db"];
+type ParsedWorkflowDefinition = ReturnType<typeof parseWorkflowDefinitionRow>;
+/**
+ * The selector that keys a workflow definition's identity: the asset it
+ * projects and the content hash of its wire projection. A single asset backs
+ * many definitions distinguished by their wire hash, so both fields are
+ * required to name exactly one definition.
+ */
+export type WorkflowDefinitionSelector = {
+    assetId: string;
+    wireHash: string;
+};
+/**
+ * The definition a selector names, or null when no definition has been folded
+ * for that `(assetId, wireHash)` pair. This is the single expression of the
+ * deployment -> definition mapping (a deployment names its asset and wire hash);
+ * the run backfill and the native-run insert sites both resolve through it.
+ * Null on a miss is deliberate, not an error: a deployment whose selector the
+ * run-once fold never covered has no definition yet, and its runs anchor on
+ * `runId` until that gap closes.
+ */
+export declare function resolveDefinitionIdForAsset(db: DBExecutor, selector: WorkflowDefinitionSelector): Promise<string | null>;
+/**
+ * Read the deploy-approved grant-walk snapshot frozen onto a definition's
+ * version row, validated as a `GrantWalkSnapshot` at this boundary. Returns
+ * `null` when the version row is absent or its `grantSnapshot` column is still
+ * `null` -- the "not yet approved" state, mirroring `approvedWireHash`. The
+ * caller fails closed on `null`; it never substitutes an empty grant set.
+ */
+export declare function loadFrozenGrantSnapshot(db: DBExecutor, definitionId: string): Promise<GrantWalkSnapshot | null>;
+export type WorkflowDefinitionRollbackResult = {
+    ok: true;
+    definition: ParsedWorkflowDefinition;
+} | {
+    ok: false;
+    reason: "definition_not_found" | "version_not_found";
+};
+/**
+ * Store for the first-class `workflow_definition` and its version history.
+ */
+export declare function createWorkflowDefinitionStore(db: DBHandle): {
+    /**
+     * Roll a definition back to a prior version: deactivate the current
+     * version, activate the target, and repoint `currentVersion` in one
+     * transaction, so a reader never sees two active versions or a
+     * `currentVersion` that names an inactive row. Returns a discriminated
+     * result rather than throwing for the not-found cases the route reports as
+     * 404 / 400.
+     */
+    rollback(tenantId: string, definitionId: string, targetVersion: string): Promise<WorkflowDefinitionRollbackResult>;
+};
+export {};

package/dist/workflow-definition-store.js

@@ -0,0 +1,93 @@
+import { and, eq } from "drizzle-orm";
+import { GrantWalkSnapshot } from "@intx/types";
+import { workflowDefinition, workflowDefinitionVersion, } from "./schema/workflow-definitions.js";
+import { parseWorkflowDefinitionRow } from "./parse-row.js";
+// The version `ensureWorkflowDefinitionForAsset` projects for a fresh
+// definition, and therefore the row the approval freeze stamps the grant
+// snapshot onto. Hand-coupled to the ensure helper's initial version; if that
+// helper ever projects a different version this must follow.
+const FROZEN_VERSION = "1";
+/**
+ * The definition a selector names, or null when no definition has been folded
+ * for that `(assetId, wireHash)` pair. This is the single expression of the
+ * deployment -> definition mapping (a deployment names its asset and wire hash);
+ * the run backfill and the native-run insert sites both resolve through it.
+ * Null on a miss is deliberate, not an error: a deployment whose selector the
+ * run-once fold never covered has no definition yet, and its runs anchor on
+ * `runId` until that gap closes.
+ */
+export async function resolveDefinitionIdForAsset(db, selector) {
+    const row = await db
+        .select({ id: workflowDefinition.id })
+        .from(workflowDefinition)
+        .where(and(eq(workflowDefinition.assetId, selector.assetId), eq(workflowDefinition.wireHash, selector.wireHash)))
+        .limit(1)
+        .then((rows) => rows[0]);
+    return row?.id ?? null;
+}
+/**
+ * Read the deploy-approved grant-walk snapshot frozen onto a definition's
+ * version row, validated as a `GrantWalkSnapshot` at this boundary. Returns
+ * `null` when the version row is absent or its `grantSnapshot` column is still
+ * `null` -- the "not yet approved" state, mirroring `approvedWireHash`. The
+ * caller fails closed on `null`; it never substitutes an empty grant set.
+ */
+export async function loadFrozenGrantSnapshot(db, definitionId) {
+    const row = await db
+        .select({ grantSnapshot: workflowDefinitionVersion.grantSnapshot })
+        .from(workflowDefinitionVersion)
+        .where(and(eq(workflowDefinitionVersion.definitionId, definitionId), eq(workflowDefinitionVersion.version, FROZEN_VERSION)))
+        .limit(1)
+        .then((rows) => rows[0]);
+    if (row === undefined || row.grantSnapshot === null)
+        return null;
+    return GrantWalkSnapshot.assert(row.grantSnapshot);
+}
+/**
+ * Store for the first-class `workflow_definition` and its version history.
+ */
+export function createWorkflowDefinitionStore(db) {
+    return {
+        /**
+         * Roll a definition back to a prior version: deactivate the current
+         * version, activate the target, and repoint `currentVersion` in one
+         * transaction, so a reader never sees two active versions or a
+         * `currentVersion` that names an inactive row. Returns a discriminated
+         * result rather than throwing for the not-found cases the route reports as
+         * 404 / 400.
+         */
+        async rollback(tenantId, definitionId, targetVersion) {
+            return db.transaction(async (tx) => {
+                const existing = await tx.query.workflowDefinition.findFirst({
+                    where: and(eq(workflowDefinition.id, definitionId), eq(workflowDefinition.tenantId, tenantId)),
+                });
+                if (existing === undefined) {
+                    return { ok: false, reason: "definition_not_found" };
+                }
+                const target = await tx.query.workflowDefinitionVersion.findFirst({
+                    where: and(eq(workflowDefinitionVersion.definitionId, definitionId), eq(workflowDefinitionVersion.version, targetVersion)),
+                });
+                if (target === undefined) {
+                    return { ok: false, reason: "version_not_found" };
+                }
+                await tx
+                    .update(workflowDefinitionVersion)
+                    .set({ status: "inactive" })
+                    .where(and(eq(workflowDefinitionVersion.definitionId, definitionId), eq(workflowDefinitionVersion.version, existing.currentVersion)));
+                await tx
+                    .update(workflowDefinitionVersion)
+                    .set({ status: "active" })
+                    .where(and(eq(workflowDefinitionVersion.definitionId, definitionId), eq(workflowDefinitionVersion.version, targetVersion)));
+                const [updated] = await tx
+                    .update(workflowDefinition)
+                    .set({ currentVersion: targetVersion, updatedAt: new Date() })
+                    .where(eq(workflowDefinition.id, definitionId))
+                    .returning();
+                if (updated === undefined) {
+                    throw new Error(`workflowDefinitionStore.rollback: update returned no row for ${definitionId}`);
+                }
+                return { ok: true, definition: parseWorkflowDefinitionRow(updated) };
+            });
+        },
+    };
+}

package/dist/workflow-run-dispatch-store.d.ts

@@ -0,0 +1,80 @@
+import { type SQL } from "drizzle-orm";
+import { type RunGrantsFrame as RunGrantsFrameType, type SignalDeliverFrame as SignalDeliverFrameType } from "@intx/types/sidecar";
+import type { DB, DBExecutor } from "./client.js";
+import { parseWorkflowRunDispatchRow } from "./parse-row.js";
+type DBHandle = DB["db"];
+type ParsedDispatch = ReturnType<typeof parseWorkflowRunDispatchRow>;
+export type EnqueueWorkflowRunDispatchArgs = {
+    readonly id: string;
+    readonly anchorRunId: string;
+    readonly messageId: string;
+    readonly rawMessage: Uint8Array;
+    readonly stepGrants: RunGrantsFrameType["stepGrants"];
+    readonly now?: Date;
+};
+export type EnqueueWorkflowSignalDispatchArgs = {
+    readonly id: string;
+    readonly anchorRunId: string;
+    readonly signal: Omit<SignalDeliverFrameType, "type">;
+    readonly now?: Date;
+};
+export type EnqueueWorkflowRunDispatchResult = {
+    readonly dispatch: ParsedDispatch;
+    readonly created: boolean;
+};
+type InsertOrReconcileDispatchArgs = {
+    readonly operation: "enqueue" | "enqueueSignal";
+    readonly id: string;
+    readonly anchorRunId: string;
+    readonly messageId: string;
+    readonly kind: ParsedDispatch["kind"];
+    readonly rawMessage: Uint8Array;
+    readonly stepGrants: RunGrantsFrameType["stepGrants"];
+    readonly now?: Date;
+};
+export declare class WorkflowRunDispatchPayloadConflictError extends Error {
+    readonly messageId: string;
+    readonly payloadKind: "message" | "signal";
+    constructor(messageId: string, payloadKind: "message" | "signal", operation: InsertOrReconcileDispatchArgs["operation"]);
+}
+export type ClaimWorkflowRunDispatchArgs = {
+    readonly leaseId: string;
+    readonly leaseDurationMs: number;
+};
+export type AcknowledgeWorkflowRunDispatchArgs = {
+    readonly allocationId: string;
+    readonly anchorRunId: string;
+    readonly messageId: string;
+    readonly generation: number;
+    readonly now?: Date;
+};
+export type RetryWorkflowRunDispatchArgs = {
+    readonly dispatchId: string;
+    readonly nextAttemptAt: Date;
+    readonly code: string;
+    readonly message: string;
+    readonly expectedLeaseId?: string;
+    readonly now?: Date;
+};
+export type FailWorkflowRunDispatchArgs = {
+    readonly anchorRunId: string;
+    readonly messageId: string;
+    readonly code: string;
+    readonly message: string;
+    readonly now?: Date;
+};
+export declare function createWorkflowRunDispatchStore(db: DBHandle): {
+    enqueue(args: EnqueueWorkflowRunDispatchArgs, tx?: DBExecutor): Promise<EnqueueWorkflowRunDispatchResult>;
+    enqueueSignal(args: EnqueueWorkflowSignalDispatchArgs, tx?: DBExecutor): Promise<EnqueueWorkflowRunDispatchResult>;
+    claimNextPending(args: ClaimWorkflowRunDispatchArgs): Promise<ParsedDispatch | null>;
+    acknowledge(args: AcknowledgeWorkflowRunDispatchArgs): Promise<ParsedDispatch | null>;
+    scheduleRetry(args: RetryWorkflowRunDispatchArgs): Promise<ParsedDispatch | null>;
+    settle(anchorRunId: string, messageId: string, now?: Date): Promise<ParsedDispatch | null>;
+    fail(args: FailWorkflowRunDispatchArgs): Promise<ParsedDispatch | null>;
+    failUnsettled(anchorRunId: string, code: string, message: string, now?: Date | SQL, tx?: DBExecutor): Promise<number>;
+    requeueUnsettled(anchorRunId: string): Promise<number>;
+    findById(id: string): Promise<ParsedDispatch | null>;
+    listUnsettled(anchorRunId: string): Promise<ParsedDispatch[]>;
+};
+export type WorkflowRunDispatchStore = ReturnType<typeof createWorkflowRunDispatchStore>;
+export {};

package/dist/workflow-run-dispatch-store.js

@@ -0,0 +1,298 @@
+import { isDeepStrictEqual } from "node:util";
+import { and, asc, eq, inArray, isNull, lte, or, sql, } from "drizzle-orm";
+import { RunGrantsFrame, SignalDeliverFrame, } from "@intx/types/sidecar";
+import { parseWorkflowRunDispatchRow } from "./parse-row.js";
+import { sidecarAllocation, workflowRun, workflowRunDispatch } from "./schema/index.js";
+export class WorkflowRunDispatchPayloadConflictError extends Error {
+    messageId;
+    payloadKind;
+    constructor(messageId, payloadKind, operation) {
+        super(`workflowRunDispatchStore.${operation}: ${payloadKind} ${messageId} conflicts with its durable payload`);
+        this.messageId = messageId;
+        this.payloadKind = payloadKind;
+        this.name = "WorkflowRunDispatchPayloadConflictError";
+    }
+}
+function databaseTimestamp(override) {
+    return override ?? sql `now()`;
+}
+function leaseCondition(expectedLeaseId) {
+    return expectedLeaseId === undefined
+        ? []
+        : [eq(workflowRunDispatch.deliveryLeaseId, expectedLeaseId)];
+}
+function byteArraysEqual(left, right) {
+    if (left.byteLength !== right.byteLength)
+        return false;
+    return left.every((value, index) => value === right[index]);
+}
+function grantsEqual(left, right) {
+    return isDeepStrictEqual(left, right);
+}
+function validateStepGrants(anchorRunId, stepGrants) {
+    return RunGrantsFrame.assert({
+        type: "run.grants",
+        agentAddress: "persisted@validation.invalid",
+        runId: anchorRunId,
+        stepGrants,
+    }).stepGrants;
+}
+async function insertOrReconcileDispatch(executor, args) {
+    const [anchor] = await executor
+        .select({ anchorRunId: workflowRun.anchorRunId })
+        .from(workflowRun)
+        .where(eq(workflowRun.id, args.anchorRunId))
+        .limit(1);
+    if (anchor?.anchorRunId !== args.anchorRunId) {
+        throw new Error(`workflowRunDispatchStore.${args.operation}: run ${args.anchorRunId} is not a deployment anchor`);
+    }
+    const now = databaseTimestamp(args.now);
+    const [inserted] = await executor
+        .insert(workflowRunDispatch)
+        .values({
+        id: args.id,
+        anchorRunId: args.anchorRunId,
+        messageId: args.messageId,
+        kind: args.kind,
+        rawMessage: args.rawMessage,
+        stepGrants: args.stepGrants,
+        status: "pending",
+        nextAttemptAt: now,
+        createdAt: now,
+        updatedAt: now,
+    })
+        .onConflictDoNothing({
+        target: [workflowRunDispatch.anchorRunId, workflowRunDispatch.messageId],
+    })
+        .returning();
+    if (inserted !== undefined) {
+        return {
+            dispatch: parseWorkflowRunDispatchRow(inserted),
+            created: true,
+        };
+    }
+    const existing = await executor.query.workflowRunDispatch.findFirst({
+        where: and(eq(workflowRunDispatch.anchorRunId, args.anchorRunId), eq(workflowRunDispatch.messageId, args.messageId)),
+    });
+    if (existing === undefined) {
+        throw new Error(`workflowRunDispatchStore.${args.operation}: conflicting row disappeared for ${args.anchorRunId}/${args.messageId}`);
+    }
+    const parsed = parseWorkflowRunDispatchRow(existing);
+    if (parsed.kind !== args.kind ||
+        !byteArraysEqual(parsed.rawMessage, args.rawMessage) ||
+        !grantsEqual(parsed.stepGrants, args.stepGrants)) {
+        const payloadKind = args.kind === "mail" ? "message" : "signal";
+        throw new WorkflowRunDispatchPayloadConflictError(args.messageId, payloadKind, args.operation);
+    }
+    return { dispatch: parsed, created: false };
+}
+async function acknowledgeMatchingDispatch(executor, generation, conditions, nowOverride) {
+    const now = databaseTimestamp(nowOverride);
+    const [updated] = await executor
+        .update(workflowRunDispatch)
+        .set({
+        status: "acknowledged",
+        acknowledgedGeneration: generation,
+        acknowledgedAt: now,
+        attemptCount: sql `${workflowRunDispatch.attemptCount} + 1`,
+        nextAttemptAt: null,
+        deliveryLeaseId: null,
+        deliveryLeaseExpiresAt: null,
+        failureCode: null,
+        failureMessage: null,
+        updatedAt: now,
+    })
+        .where(and(...conditions))
+        .returning();
+    return updated === undefined ? null : parseWorkflowRunDispatchRow(updated);
+}
+export function createWorkflowRunDispatchStore(db) {
+    return {
+        async enqueue(args, tx) {
+            const stepGrants = validateStepGrants(args.anchorRunId, args.stepGrants);
+            return insertOrReconcileDispatch(tx ?? db, {
+                operation: "enqueue",
+                id: args.id,
+                anchorRunId: args.anchorRunId,
+                messageId: args.messageId,
+                kind: "mail",
+                rawMessage: args.rawMessage,
+                stepGrants,
+                ...(args.now !== undefined ? { now: args.now } : {}),
+            });
+        },
+        async enqueueSignal(args, tx) {
+            const signal = SignalDeliverFrame.assert({
+                type: "signal.deliver",
+                ...args.signal,
+            });
+            const encoded = new TextEncoder().encode(JSON.stringify(signal));
+            return insertOrReconcileDispatch(tx ?? db, {
+                operation: "enqueueSignal",
+                id: args.id,
+                anchorRunId: args.anchorRunId,
+                messageId: signal.signalId,
+                kind: "signal",
+                rawMessage: encoded,
+                stepGrants: [],
+                ...(args.now !== undefined ? { now: args.now } : {}),
+            });
+        },
+        async claimNextPending(args) {
+            return db.transaction(async (tx) => {
+                const [candidate] = await tx
+                    .select({ id: workflowRunDispatch.id })
+                    .from(workflowRunDispatch)
+                    .where(and(eq(workflowRunDispatch.status, "pending"), lte(workflowRunDispatch.nextAttemptAt, sql `now()`), or(isNull(workflowRunDispatch.deliveryLeaseExpiresAt), lte(workflowRunDispatch.deliveryLeaseExpiresAt, sql `now()`))))
+                    .orderBy(asc(workflowRunDispatch.nextAttemptAt), asc(workflowRunDispatch.createdAt))
+                    .limit(1)
+                    .for("update", { skipLocked: true });
+                if (candidate === undefined)
+                    return null;
+                const [claimed] = await tx
+                    .update(workflowRunDispatch)
+                    .set({
+                    deliveryLeaseId: args.leaseId,
+                    deliveryLeaseExpiresAt: sql `now() + (${args.leaseDurationMs} * interval '1 millisecond')`,
+                })
+                    .where(eq(workflowRunDispatch.id, candidate.id))
+                    .returning();
+                return claimed === undefined
+                    ? null
+                    : parseWorkflowRunDispatchRow(claimed);
+            });
+        },
+        async acknowledge(args) {
+            return db.transaction(async (tx) => {
+                const [allocation] = await tx
+                    .select({
+                    anchorRunId: sidecarAllocation.anchorRunId,
+                    status: sidecarAllocation.status,
+                    generation: sidecarAllocation.generation,
+                    ensureAcceptedGeneration: sidecarAllocation.ensureAcceptedGeneration,
+                })
+                    .from(sidecarAllocation)
+                    .where(eq(sidecarAllocation.id, args.allocationId))
+                    .limit(1)
+                    .for("update");
+                if (allocation === undefined ||
+                    allocation.anchorRunId !== args.anchorRunId ||
+                    allocation.status !== "allocated" ||
+                    allocation.generation !== args.generation ||
+                    allocation.ensureAcceptedGeneration !== args.generation) {
+                    return null;
+                }
+                return acknowledgeMatchingDispatch(tx, args.generation, [
+                    eq(workflowRunDispatch.anchorRunId, args.anchorRunId),
+                    eq(workflowRunDispatch.messageId, args.messageId),
+                    eq(workflowRunDispatch.kind, "mail"),
+                    eq(workflowRunDispatch.status, "pending"),
+                ], args.now);
+            });
+        },
+        async scheduleRetry(args) {
+            const [updated] = await db
+                .update(workflowRunDispatch)
+                .set({
+                nextAttemptAt: args.nextAttemptAt,
+                attemptCount: sql `${workflowRunDispatch.attemptCount} + 1`,
+                deliveryLeaseId: null,
+                deliveryLeaseExpiresAt: null,
+                failureCode: args.code,
+                failureMessage: args.message,
+                updatedAt: databaseTimestamp(args.now),
+            })
+                .where(and(eq(workflowRunDispatch.id, args.dispatchId), eq(workflowRunDispatch.status, "pending"), ...leaseCondition(args.expectedLeaseId)))
+                .returning();
+            return updated === undefined
+                ? null
+                : parseWorkflowRunDispatchRow(updated);
+        },
+        async settle(anchorRunId, messageId, now = new Date()) {
+            const [updated] = await db
+                .update(workflowRunDispatch)
+                .set({
+                status: "settled",
+                nextAttemptAt: null,
+                deliveryLeaseId: null,
+                deliveryLeaseExpiresAt: null,
+                failureCode: null,
+                failureMessage: null,
+                settledAt: now,
+                updatedAt: now,
+            })
+                .where(and(eq(workflowRunDispatch.anchorRunId, anchorRunId), eq(workflowRunDispatch.messageId, messageId), inArray(workflowRunDispatch.status, ["pending", "acknowledged"])))
+                .returning();
+            return updated === undefined
+                ? null
+                : parseWorkflowRunDispatchRow(updated);
+        },
+        async fail(args) {
+            const now = args.now ?? new Date();
+            const [updated] = await db
+                .update(workflowRunDispatch)
+                .set({
+                status: "failed",
+                nextAttemptAt: null,
+                deliveryLeaseId: null,
+                deliveryLeaseExpiresAt: null,
+                failureCode: args.code,
+                failureMessage: args.message,
+                updatedAt: now,
+            })
+                .where(and(eq(workflowRunDispatch.anchorRunId, args.anchorRunId), eq(workflowRunDispatch.messageId, args.messageId), inArray(workflowRunDispatch.status, ["pending", "acknowledged"])))
+                .returning();
+            return updated === undefined
+                ? null
+                : parseWorkflowRunDispatchRow(updated);
+        },
+        async failUnsettled(anchorRunId, code, message, now = new Date(), tx) {
+            const rows = await (tx ?? db)
+                .update(workflowRunDispatch)
+                .set({
+                status: "failed",
+                nextAttemptAt: null,
+                deliveryLeaseId: null,
+                deliveryLeaseExpiresAt: null,
+                failureCode: code,
+                failureMessage: message,
+                updatedAt: now,
+            })
+                .where(and(eq(workflowRunDispatch.anchorRunId, anchorRunId), inArray(workflowRunDispatch.status, ["pending", "acknowledged"])))
+                .returning({ id: workflowRunDispatch.id });
+            return rows.length;
+        },
+        async requeueUnsettled(anchorRunId) {
+            const rows = await db
+                .update(workflowRunDispatch)
+                .set({
+                status: "pending",
+                acknowledgedGeneration: null,
+                acknowledgedAt: null,
+                nextAttemptAt: sql `now()`,
+                deliveryLeaseId: null,
+                deliveryLeaseExpiresAt: null,
+                failureCode: null,
+                failureMessage: null,
+                updatedAt: sql `now()`,
+            })
+                .where(and(eq(workflowRunDispatch.anchorRunId, anchorRunId), inArray(workflowRunDispatch.status, ["pending", "acknowledged"])))
+                .returning({ id: workflowRunDispatch.id });
+            return rows.length;
+        },
+        async findById(id) {
+            const row = await db.query.workflowRunDispatch.findFirst({
+                where: eq(workflowRunDispatch.id, id),
+            });
+            return row === undefined ? null : parseWorkflowRunDispatchRow(row);
+        },
+        async listUnsettled(anchorRunId) {
+            const rows = await db
+                .select()
+                .from(workflowRunDispatch)
+                .where(and(eq(workflowRunDispatch.anchorRunId, anchorRunId), inArray(workflowRunDispatch.status, ["pending", "acknowledged"])))
+                .orderBy(asc(workflowRunDispatch.createdAt));
+            return rows.map(parseWorkflowRunDispatchRow);
+        },
+    };
+}