@intx/db 0.1.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

@@ -0,0 +1,23 @@
+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].
+ *
+ * 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[]>;
+/**
+ * Returns the tenant and every distinct tenant in its subtree (children,
+ * their children, and so on), discovered breadth-first. Used to find every
+ * tenant whose resolved catalog a change at `tenantId` affects — descendants
+ * inherit the ancestor's catalog, so a catalog edit must reach their running
+ * agents too.
+ *
+ * Each level queries children by `parentId` membership rather than walking
+ * one tenant at a time. A `visited` set both deduplicates the result and
+ * guarantees termination: a tenant enters the frontier at most once, so even
+ * a malformed cyclic hierarchy drains the frontier instead of looping. No
+ * depth cap is imposed, so an arbitrarily deep tree is returned in full.
+ */
+export declare function getDescendantTenants(db: DB["db"], tenantId: string): Promise<string[]>;

package/dist/tenant-hierarchy.js

@@ -0,0 +1,60 @@
+import { eq, inArray } from "drizzle-orm";
+import { tenant } from "./schema/tenants.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].
+ *
+ * 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 = [];
+    const visited = new Set();
+    let currentId = tenantId;
+    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;
+        currentId = row.parentId;
+    }
+    return chain;
+}
+/**
+ * Returns the tenant and every distinct tenant in its subtree (children,
+ * their children, and so on), discovered breadth-first. Used to find every
+ * tenant whose resolved catalog a change at `tenantId` affects — descendants
+ * inherit the ancestor's catalog, so a catalog edit must reach their running
+ * agents too.
+ *
+ * Each level queries children by `parentId` membership rather than walking
+ * one tenant at a time. A `visited` set both deduplicates the result and
+ * guarantees termination: a tenant enters the frontier at most once, so even
+ * a malformed cyclic hierarchy drains the frontier instead of looping. No
+ * depth cap is imposed, so an arbitrarily deep tree is returned in full.
+ */
+export async function getDescendantTenants(db, tenantId) {
+    const visited = new Set([tenantId]);
+    let frontier = [tenantId];
+    while (frontier.length > 0) {
+        const children = await db.query.tenant.findMany({
+            where: inArray(tenant.parentId, frontier),
+            columns: { id: true },
+        });
+        frontier = [];
+        for (const child of children) {
+            if (visited.has(child.id))
+                continue;
+            visited.add(child.id);
+            frontier.push(child.id);
+        }
+    }
+    return [...visited];
+}

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 {};