@intx/hub-sessions 0.2.2 → 0.4.0

package/dist/workflow-closure-resolution.js

@@ -0,0 +1,123 @@
+// Hub-side dependency-closure resolution for a code-sourced workflow
+// definition.
+//
+// Given a `WorkflowDefinitionSource` and a pin, walk the full dependency
+// closure to concrete versions plus integrity SRIs, reusing the tool-packaging
+// closure resolver. This is the "what exactly would we install" step: packument
+// and package.json metadata reads only, no code execution. The returned
+// `ToolPackageManifest` is the frozen closure the deploy path later ships by
+// source-ref.
+//
+// There are three arms, one per `(source.kind, package.format)`:
+//   - `registry` names an npm registry; its URL and credentials are supplied by
+//     the caller as a `RegistryConfig`, since the caller owns the registry
+//     configuration.
+//   - `asset` + `tarball` names a hub asset that publishes the definition
+//     package as a tarball; the caller supplies bound `readBlob`/`listBlobs`
+//     closures over that asset (the same shape `session-service` mints for
+//     `AssetRegistrySource`).
+//   - `asset` + `source` names a hub asset whose definition package lives as a
+//     git subtree at a pinned commit; the caller supplies a `SourceTreeReads`
+//     pinned to that commit plus a `RegistryConfig` for the external npm deps.
+//     This arm delegates to `resolveSourceWorkflowClosure`, which reads the
+//     tree directly and needs no `name@range` pin (it selects the member from
+//     the source's `packageName`).
+// Every arm takes pre-bound read capabilities, keeping this module free of any
+// asset-service or repo-store dependency.
+import { base64Encode } from "@intx/types";
+import { AssetRegistrySource, HttpRegistrySource, createClosureResolver, parsePin, } from "@intx/tool-packaging";
+import { resolveSourceWorkflowClosure, } from "./workflow-source-closure.js";
+// Both asset arms carry an identical `source` field type, so narrow on the
+// source's own `package.format` discriminant rather than adding a redundant
+// discriminant to the args.
+function isAssetSourceArgs(args) {
+    return (args.source.kind === "asset" && args.source.package.format === "source");
+}
+function isAssetTarballArgs(args) {
+    return (args.source.kind === "asset" && args.source.package.format === "tarball");
+}
+/**
+ * Resolve a workflow definition's dependency closure to concrete versions
+ * and integrity SRIs, reusing the tool-packaging closure resolver.
+ *
+ * @returns the frozen closure: a `ToolPackageManifest` whose `topLevel`
+ *   pins the definition package and whose `entries` carry the concrete
+ *   version and integrity SRI of every transitive dependency.
+ */
+export async function resolveWorkflowClosure(args) {
+    if (isAssetSourceArgs(args)) {
+        return resolveSourceWorkflowClosure({
+            source: args.source,
+            reads: args.reads,
+            registryName: args.registryName,
+            registryConfig: args.registryConfig,
+            ...(args.fetchPackument !== undefined
+                ? { fetchPackument: args.fetchPackument }
+                : {}),
+        });
+    }
+    if (isAssetTarballArgs(args)) {
+        // The assetId is the source name so every walker resolution error is
+        // traceable to the exact asset; it is the sole and default source.
+        const name = args.source.assetId;
+        const assetSource = new AssetRegistrySource({
+            name,
+            assetId: args.source.assetId,
+            readBlob: args.readBlob,
+            listBlobs: args.listBlobs,
+        });
+        const resolver = createClosureResolver({
+            registries: new Map([[name, assetSource]]),
+            defaultRegistry: name,
+        });
+        return resolver.resolveClosure([parsePin(args.pin)]);
+    }
+    const registrySource = new HttpRegistrySource({
+        name: args.source.registry,
+        config: args.registryConfig,
+        ...(args.fetchPackument !== undefined
+            ? { fetchPackument: args.fetchPackument }
+            : {}),
+    });
+    const resolver = createClosureResolver({
+        registries: new Map([[registrySource.name, registrySource]]),
+        defaultRegistry: registrySource.name,
+    });
+    return resolver.resolveClosure([parsePin(args.pin)]);
+}
+/**
+ * The workspace-relative mount path a workflow definition's source asset is
+ * delivered under, keyed by asset id. Both the probe (inline delivery) and the
+ * deploy (streamed fan-out) build their `assetId -> mountPath` maps through
+ * this one helper, so the same asset lands at the same path on both paths.
+ */
+export function workflowSourceAssetMountPath(assetId) {
+    return `source-assets/${assetId}/`;
+}
+/**
+ * Build the inline asset mounts a source-ref frame delivers for an asset-sourced
+ * closure: one per distinct asset the closure's `kind:"asset"` entries name (so
+ * a multi-asset closure delivers every backing asset, not just the source), each
+ * carrying the git pack the caller resolves for that asset. `mountPath` is
+ * derived through the shared helper so probe and deploy agree on it.
+ */
+export async function buildSourceAssetMounts(closure, resolveAttachment) {
+    const assetIds = new Set();
+    for (const entry of closure.entries) {
+        if (entry.source.kind === "asset") {
+            assetIds.add(entry.source.assetId);
+        }
+    }
+    const mounts = [];
+    for (const assetId of assetIds) {
+        const attachment = await resolveAttachment(assetId);
+        mounts.push({
+            assetId,
+            mountPath: workflowSourceAssetMountPath(assetId),
+            pack: base64Encode(attachment.pack),
+            ref: attachment.ref,
+            commitSha: attachment.commitSha,
+        });
+    }
+    return mounts;
+}

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

@@ -0,0 +1,24 @@
+import { type DBExecutor, type WorkflowDefinitionSelector } from "@intx/db";
+/**
+ * The first-class `workflow_definition` a selector names, created if absent. A
+ * native workflow carries its body in the asset it points at, so this only
+ * projects a definition row -- plus its version "1" -- over that asset, keyed
+ * by the selector's wire hash, so a run can anchor on a first-class definition.
+ * A single asset backs many definitions distinguished by their wire hash, so
+ * distinct hashes over one asset yield distinct definitions.
+ * `currentVersion`/`status` are left to the table defaults; the definition
+ * carries no `modelRequirements` manifest, so it deploys as a workflow rather
+ * than launching as an instance.
+ *
+ * Idempotent and concurrency-safe: the definition insert conflicts on the
+ * unique `(assetId, wireHash)` and the version on `(definitionId, version)`, so
+ * two concurrent deploys of the same selector still yield exactly one
+ * definition and one version. The returned id is read back after the conflict
+ * -- the winner's id, not a locally-minted one -- so a losing insert anchors
+ * its version on the real row. `created` distinguishes a fresh projection from
+ * a pre-existing one for callers that report fold counts.
+ */
+export declare function ensureWorkflowDefinitionForAsset(db: DBExecutor, selector: WorkflowDefinitionSelector): Promise<{
+    definitionId: string;
+    created: boolean;
+}>;

package/dist/workflow-definition-ensure.js

@@ -0,0 +1,75 @@
+import { eq } from "drizzle-orm";
+import { resolveDefinitionIdForAsset, } from "@intx/db";
+import { asset, workflowDefinition, workflowDefinitionVersion, } from "@intx/db/schema";
+import { generateId } from "@intx/hub-common";
+/**
+ * The first-class `workflow_definition` a selector names, created if absent. A
+ * native workflow carries its body in the asset it points at, so this only
+ * projects a definition row -- plus its version "1" -- over that asset, keyed
+ * by the selector's wire hash, so a run can anchor on a first-class definition.
+ * A single asset backs many definitions distinguished by their wire hash, so
+ * distinct hashes over one asset yield distinct definitions.
+ * `currentVersion`/`status` are left to the table defaults; the definition
+ * carries no `modelRequirements` manifest, so it deploys as a workflow rather
+ * than launching as an instance.
+ *
+ * Idempotent and concurrency-safe: the definition insert conflicts on the
+ * unique `(assetId, wireHash)` and the version on `(definitionId, version)`, so
+ * two concurrent deploys of the same selector still yield exactly one
+ * definition and one version. The returned id is read back after the conflict
+ * -- the winner's id, not a locally-minted one -- so a losing insert anchors
+ * its version on the real row. `created` distinguishes a fresh projection from
+ * a pre-existing one for callers that report fold counts.
+ */
+export async function ensureWorkflowDefinitionForAsset(db, selector) {
+    const { assetId, wireHash } = selector;
+    const assetRow = await db
+        .select({
+        tenantId: asset.tenantId,
+        creatorPrincipalId: asset.creatorPrincipalId,
+        name: asset.name,
+        displayName: asset.displayName,
+    })
+        .from(asset)
+        .where(eq(asset.id, assetId))
+        .limit(1)
+        .then((rows) => rows[0]);
+    if (assetRow === undefined) {
+        throw new Error(`ensureWorkflowDefinitionForAsset: no asset found for id "${assetId}"`);
+    }
+    const inserted = await db
+        .insert(workflowDefinition)
+        .values({
+        id: generateId("workflowDefinition"),
+        tenantId: assetRow.tenantId,
+        creatorPrincipalId: assetRow.creatorPrincipalId,
+        assetId,
+        wireHash,
+        name: assetRow.name,
+        description: assetRow.displayName,
+    })
+        .onConflictDoNothing({
+        target: [workflowDefinition.assetId, workflowDefinition.wireHash],
+    })
+        .returning({ id: workflowDefinition.id });
+    const created = inserted.length > 0;
+    const insertedId = inserted[0]?.id;
+    const definitionId = insertedId ?? (await resolveDefinitionIdForAsset(db, selector));
+    if (definitionId === null || definitionId === undefined) {
+        throw new Error(`ensureWorkflowDefinitionForAsset: definition for asset "${assetId}" (wire hash "${wireHash}") missing after insert`);
+    }
+    await db
+        .insert(workflowDefinitionVersion)
+        .values({
+        id: generateId("workflowDefinitionVersion"),
+        definitionId,
+        version: "1",
+    })
+        .onConflictDoNothing({
+        target: [
+            workflowDefinitionVersion.definitionId,
+            workflowDefinitionVersion.version,
+        ],
+    });
+    return { definitionId, created };
+}

package/dist/workflow-dispatch-service.d.ts

@@ -0,0 +1,42 @@
+import type { DBExecutor, EnqueueWorkflowRunDispatchArgs, EnqueueWorkflowRunDispatchResult, EnqueueWorkflowSignalDispatchArgs, SidecarAllocationStore, WorkflowRunDispatchStore } from "@intx/db";
+import type { SidecarAllocationRouter } from "./ws/sidecar-handler.js";
+type DispatchStore = Pick<WorkflowRunDispatchStore, "acknowledge" | "claimNextPending" | "enqueue" | "enqueueSignal" | "requeueUnsettled" | "scheduleRetry" | "settle">;
+type AllocationStore = Pick<SidecarAllocationStore, "findByAnchorRunId">;
+type DispatchRouter = Pick<SidecarAllocationRouter, "sendSignalDeliverToAllocation" | "sendWorkflowRunDispatchToAllocation">;
+export type WorkflowDispatchAcknowledgement = {
+    readonly allocationId: string;
+    readonly anchorRunId: string;
+    readonly generation: number;
+    readonly messageId: string;
+};
+export type WorkflowDispatchService = {
+    enqueue(args: EnqueueWorkflowRunDispatchArgs, tx?: DBExecutor): Promise<EnqueueWorkflowRunDispatchResult>;
+    enqueueSignal(args: EnqueueWorkflowSignalDispatchArgs, tx?: DBExecutor): Promise<EnqueueWorkflowRunDispatchResult>;
+    acknowledge(args: WorkflowDispatchAcknowledgement): Promise<void>;
+    settle(anchorRunId: string, messageId: string): Promise<void>;
+    requeueForReadyAllocation(anchorRunId: string): Promise<number>;
+    reconcileNext(): Promise<boolean>;
+    reconcileUntilIdle(maxIterations?: number): Promise<number>;
+    wake(): void;
+};
+export type WorkflowDispatchServiceDeps = {
+    readonly dispatchStore: DispatchStore;
+    readonly allocationStore: AllocationStore;
+    readonly router: DispatchRouter;
+    /** Resolve the deployment anchor's durable routing address. */
+    readonly resolveAnchorAddress: (anchorRunId: string) => Promise<string | null>;
+    readonly leaseDurationMs?: number;
+    /** Bounds pending claims and unfinished deliveries across all drains. */
+    readonly maxConcurrentDispatches?: number;
+    readonly retryDelayMs?: (attempt: number) => number;
+    readonly now?: () => Date;
+    readonly createLeaseId?: () => string;
+};
+/**
+ * Drives Hub-owned workflow triggers onto provisioned sidecars. The database
+ * row is the delivery authority: websocket acceptance never deletes the raw
+ * payload, and a generation replacement requeues every row that has not been
+ * settled by the workflow-run Git claim-check.
+ */
+export declare function createWorkflowDispatchService({ dispatchStore, allocationStore, router, resolveAnchorAddress, leaseDurationMs, maxConcurrentDispatches, retryDelayMs, now, createLeaseId, }: WorkflowDispatchServiceDeps): WorkflowDispatchService;
+export {};

package/dist/workflow-dispatch-service.js

@@ -0,0 +1,209 @@
+import { getLogger } from "@intx/log";
+import { base64Encode, deriveWorkflowRunId, hexEncode } from "@intx/types";
+import { SignalDeliverFrame } from "@intx/types/sidecar";
+import { runSidecarOperation, SidecarOperationTimeoutError, } from "./sidecar-allocation/operation.js";
+const logger = getLogger(["hub", "workflow-dispatch"]);
+const DEFAULT_LEASE_DURATION_MS = 30_000;
+const DEFAULT_MAX_CONCURRENT_DISPATCHES = 8;
+function defaultRetryDelay(attempt) {
+    return Math.min(500 * 2 ** Math.min(attempt, 6), 30_000);
+}
+function randomLeaseId() {
+    return `dispatch_lease_${hexEncode(crypto.getRandomValues(new Uint8Array(16)))}`;
+}
+function targetForReadyAllocation(allocation) {
+    if (allocation.status !== "allocated" ||
+        allocation.ensureAcceptedGeneration !== allocation.generation ||
+        allocation.initializationLeaseId !== undefined ||
+        allocation.connectDeadline !== undefined) {
+        return null;
+    }
+    return {
+        allocationId: allocation.id,
+        generation: allocation.generation,
+    };
+}
+/**
+ * Drives Hub-owned workflow triggers onto provisioned sidecars. The database
+ * row is the delivery authority: websocket acceptance never deletes the raw
+ * payload, and a generation replacement requeues every row that has not been
+ * settled by the workflow-run Git claim-check.
+ */
+export function createWorkflowDispatchService({ dispatchStore, allocationStore, router, resolveAnchorAddress, leaseDurationMs = DEFAULT_LEASE_DURATION_MS, maxConcurrentDispatches = DEFAULT_MAX_CONCURRENT_DISPATCHES, retryDelayMs = defaultRetryDelay, now = () => new Date(), createLeaseId = randomLeaseId, }) {
+    if (!Number.isSafeInteger(leaseDurationMs) || leaseDurationMs <= 0) {
+        throw new Error("leaseDurationMs must be a positive integer");
+    }
+    if (!Number.isSafeInteger(maxConcurrentDispatches) ||
+        maxConcurrentDispatches <= 0) {
+        throw new Error("maxConcurrentDispatches must be a positive integer");
+    }
+    let drainPromise = null;
+    let admittedDispatches = 0;
+    const activeDispatches = new Set();
+    function retryAt(attempt) {
+        return new Date(now().getTime() + retryDelayMs(attempt));
+    }
+    async function retry(dispatch, leaseId, code, message) {
+        await dispatchStore.scheduleRetry({
+            dispatchId: dispatch.id,
+            nextAttemptAt: retryAt(dispatch.attemptCount),
+            code,
+            message,
+            expectedLeaseId: leaseId,
+            now: now(),
+        });
+    }
+    async function reconcileNext() {
+        if (admittedDispatches >= maxConcurrentDispatches)
+            return false;
+        admittedDispatches += 1;
+        let delivery;
+        let activeDispatchId;
+        try {
+            const leaseId = createLeaseId();
+            const claimStartedAt = performance.now();
+            const dispatch = await dispatchStore.claimNextPending({
+                leaseId,
+                leaseDurationMs,
+                excludedDispatchIds: [...activeDispatches],
+            });
+            if (dispatch === null)
+                return false;
+            // A concurrent claim can outlive both its exclusion snapshot and the old
+            // lease. Do not start another delivery while its original I/O is pending.
+            if (activeDispatches.has(dispatch.id))
+                return true;
+            const remaining = leaseDurationMs - (performance.now() - claimStartedAt);
+            if (remaining <= 0)
+                return true;
+            activeDispatchId = dispatch.id;
+            activeDispatches.add(dispatch.id);
+            try {
+                await runSidecarOperation("Workflow dispatch", Math.ceil(remaining), (signal) => {
+                    delivery = deliver(dispatch, leaseId, signal);
+                    return delivery;
+                });
+            }
+            catch (error) {
+                if (!(error instanceof SidecarOperationTimeoutError))
+                    throw error;
+                // The durable lease expires independently. Do not start another database
+                // write here: a stuck retry write must not occupy the freed drain either.
+                logger.warn `Dispatch ${dispatch.id} stopped at its delivery deadline`;
+            }
+            return true;
+        }
+        finally {
+            const release = () => {
+                admittedDispatches -= 1;
+                if (activeDispatchId !== undefined)
+                    activeDispatches.delete(activeDispatchId);
+            };
+            // Timeouts free the drain, but the underlying I/O retains its admission
+            // reservation and dispatch exclusion until it actually settles.
+            if (delivery === undefined)
+                release();
+            else
+                void delivery.then(release, release);
+        }
+    }
+    async function deliver(dispatch, leaseId, signal) {
+        const allocation = await allocationStore.findByAnchorRunId(dispatch.anchorRunId);
+        signal.throwIfAborted();
+        if (allocation === null) {
+            await retry(dispatch, leaseId, "allocation_missing", `No sidecar allocation exists for workflow anchor ${dispatch.anchorRunId}`);
+            return;
+        }
+        const target = targetForReadyAllocation(allocation);
+        if (target === null) {
+            await retry(dispatch, leaseId, "allocation_not_ready", `Sidecar allocation ${allocation.id} is not ready for delivery`);
+            return;
+        }
+        const agentAddress = await resolveAnchorAddress(dispatch.anchorRunId);
+        signal.throwIfAborted();
+        if (agentAddress === null) {
+            await retry(dispatch, leaseId, "anchor_address_missing", `Workflow anchor ${dispatch.anchorRunId} has no routing address`);
+            return;
+        }
+        try {
+            if (dispatch.kind === "signal") {
+                const frame = SignalDeliverFrame.assert(JSON.parse(new TextDecoder().decode(dispatch.rawMessage)));
+                await router.sendSignalDeliverToAllocation(target, {
+                    agentAddress: frame.agentAddress,
+                    runId: frame.runId,
+                    signalName: frame.signalName,
+                    signalId: frame.signalId,
+                    payload: frame.payload,
+                }, signal);
+            }
+            else {
+                // A deliverable mail dispatch always carries the sender persisted at
+                // enqueue (the workflow_run_dispatch mail-sender check enforces it).
+                // A null here means the row bypassed that invariant, so fail loudly
+                // rather than deliver with no authenticated sender or fall back to the
+                // MIME From.
+                if (dispatch.senderAddress === null) {
+                    throw new Error(`mail dispatch ${dispatch.id} has no persisted authenticated sender`);
+                }
+                await router.sendWorkflowRunDispatchToAllocation(target, agentAddress, deriveWorkflowRunId(agentAddress), dispatch.stepGrants, base64Encode(dispatch.rawMessage), dispatch.senderAddress, dispatch.messageId, signal);
+            }
+            // Keep the delivery lease until the sidecar acknowledges its durable
+            // inbox write. If that ack never arrives, lease expiry makes the same
+            // immutable payload claimable again.
+        }
+        catch (error) {
+            signal.throwIfAborted();
+            await retry(dispatch, leaseId, "dispatch_unroutable", error instanceof Error ? error.message : String(error));
+        }
+    }
+    async function reconcileUntilIdle(maxIterations = 100) {
+        let reconciled = 0;
+        while (reconciled < maxIterations && (await reconcileNext())) {
+            reconciled += 1;
+        }
+        return reconciled;
+    }
+    function wake() {
+        if (drainPromise !== null)
+            return;
+        drainPromise = Promise.resolve()
+            .then(async () => {
+            await reconcileUntilIdle();
+        })
+            .catch((error) => {
+            logger.error `Workflow dispatch reconciliation failed: ${error instanceof Error ? error.message : String(error)}`;
+        })
+            .finally(() => {
+            drainPromise = null;
+        });
+    }
+    return {
+        async enqueue(args, tx) {
+            const result = await dispatchStore.enqueue(args, tx);
+            wake();
+            return result;
+        },
+        async enqueueSignal(args, tx) {
+            const result = await dispatchStore.enqueueSignal(args, tx);
+            wake();
+            return result;
+        },
+        async acknowledge(args) {
+            await dispatchStore.acknowledge({
+                ...args,
+                now: now(),
+            });
+        },
+        async settle(anchorRunId, messageId) {
+            await dispatchStore.settle(anchorRunId, messageId, now());
+        },
+        async requeueForReadyAllocation(anchorRunId) {
+            const count = await dispatchStore.requeueUnsettled(anchorRunId);
+            wake();
+            return count;
+        },
+        reconcileNext,
+        reconcileUntilIdle,
+        wake,
+    };
+}

package/dist/workflow-dispatch-settlement.d.ts

@@ -0,0 +1,29 @@
+import type { CommittedReads } from "./repo-store/index.js";
+export type ConsumedWorkflowDispatch = {
+    readonly messageId: string;
+    readonly address: string;
+    readonly rejection?: {
+        readonly code: string;
+        readonly message: string;
+    };
+};
+export type ReceivedWorkflowSignal = {
+    readonly runId: string;
+    readonly signalId: string;
+};
+export type AcceptedWorkflowDispatch = {
+    readonly runId: string;
+    readonly messageId: string;
+    readonly kind: "mail" | "signal";
+};
+/** Enumerate dispatches durably accepted by one live or sealed run log. */
+export declare function listAcceptedWorkflowDispatches(reads: CommittedReads, runId: string, targetMessageIds?: ReadonlySet<string>): Promise<AcceptedWorkflowDispatch[]>;
+/** Enumerate durable SignalReceived ids from one live or sealed run log. */
+export declare function listReceivedWorkflowSignals(reads: CommittedReads, runId: string): Promise<ReceivedWorkflowSignal[]>;
+/**
+ * Enumerate the workflow-run claim-check's retained consumed index. The kind
+ * validator guarantees this tree shape before the ref advances; the runtime
+ * validator here keeps the Git-to-database projection fail-closed if that
+ * invariant is ever violated.
+ */
+export declare function listConsumedWorkflowDispatches(reads: CommittedReads): Promise<ConsumedWorkflowDispatch[]>;

package/dist/workflow-dispatch-settlement.js

@@ -0,0 +1,140 @@
+import { type } from "arktype";
+import { splitCombinedEventLog, WORKFLOW_RUN_EVENTS_FILE, } from "./workflow-run-event-log.js";
+import { WORKFLOW_RUN_ADDRESSES_PREFIX, WORKFLOW_RUN_CONSUMED_DIR, WORKFLOW_RUN_EVENTS_DIR, WORKFLOW_RUN_RUNS_PREFIX, } from "./workflow-run-kind.js";
+const ConsumedEnvelope = type({
+    messageId: "string",
+    address: "string",
+    "rejection?": {
+        code: "string > 0",
+        message: "string > 0",
+    },
+    "+": "ignore",
+});
+const SignalReceived = type({
+    type: "'SignalReceived'",
+    signalId: "string",
+    "+": "ignore",
+});
+const RunStarted = type({
+    type: "'RunStarted'",
+    "consumedMessageId?": "string",
+    "+": "ignore",
+});
+function projectAcceptedDispatch(raw, path) {
+    let decoded;
+    try {
+        decoded = JSON.parse(raw);
+    }
+    catch (cause) {
+        throw new Error(`workflow_dispatch_event_invalid_json: ${path}`, {
+            cause,
+        });
+    }
+    if (typeof decoded !== "object" || decoded === null || !("type" in decoded)) {
+        return null;
+    }
+    if (decoded.type === "SignalReceived") {
+        const signal = SignalReceived(decoded);
+        if (signal instanceof type.errors) {
+            throw new Error(`workflow_dispatch_signal_invalid: ${path}: ${signal.summary}`);
+        }
+        return { kind: "signal", messageId: signal.signalId };
+    }
+    if (decoded.type === "RunStarted") {
+        const started = RunStarted(decoded);
+        if (started instanceof type.errors) {
+            throw new Error(`workflow_dispatch_run_started_invalid: ${path}: ${started.summary}`);
+        }
+        return started.consumedMessageId === undefined
+            ? null
+            : { kind: "mail", messageId: started.consumedMessageId };
+    }
+    return null;
+}
+/** Enumerate dispatches durably accepted by one live or sealed run log. */
+export async function listAcceptedWorkflowDispatches(reads, runId, targetMessageIds) {
+    if (targetMessageIds?.size === 0)
+        return [];
+    const accepted = [];
+    const remaining = targetMessageIds === undefined ? undefined : new Set(targetMessageIds);
+    const accept = (dispatch) => {
+        if (dispatch === null)
+            return;
+        if (remaining !== undefined && !remaining.delete(dispatch.messageId))
+            return;
+        accepted.push({ runId, ...dispatch });
+    };
+    const runPath = `${WORKFLOW_RUN_RUNS_PREFIX}/${runId}`;
+    const children = await reads.listDir(runPath);
+    const combined = children.find((entry) => entry.type === "blob" && entry.name === WORKFLOW_RUN_EVENTS_FILE);
+    if (combined !== undefined) {
+        const raw = new TextDecoder().decode(await reads.readBlobByOid(combined.oid));
+        const lines = splitCombinedEventLog(raw);
+        for (let index = lines.length - 1; index >= 0; index -= 1) {
+            const line = lines[index];
+            if (line === undefined)
+                continue;
+            accept(projectAcceptedDispatch(line, `${runPath}/${WORKFLOW_RUN_EVENTS_FILE}:${String(index + 1)}`));
+            if (remaining?.size === 0)
+                break;
+        }
+        return accepted.reverse();
+    }
+    const eventsPath = `${runPath}/${WORKFLOW_RUN_EVENTS_DIR}`;
+    const eventEntries = (await reads.listDir(eventsPath))
+        .filter((entry) => entry.type === "blob" && entry.name.endsWith(".json"))
+        .sort((left, right) => right.name.localeCompare(left.name, undefined, {
+        numeric: true,
+    }));
+    for (const eventEntry of eventEntries) {
+        const raw = new TextDecoder().decode(await reads.readBlobByOid(eventEntry.oid));
+        accept(projectAcceptedDispatch(raw, `${eventsPath}/${eventEntry.name}`));
+        if (remaining?.size === 0)
+            break;
+    }
+    return accepted.reverse();
+}
+/** Enumerate durable SignalReceived ids from one live or sealed run log. */
+export async function listReceivedWorkflowSignals(reads, runId) {
+    return (await listAcceptedWorkflowDispatches(reads, runId))
+        .filter((dispatch) => dispatch.kind === "signal")
+        .map((dispatch) => ({ runId, signalId: dispatch.messageId }));
+}
+/**
+ * Enumerate the workflow-run claim-check's retained consumed index. The kind
+ * validator guarantees this tree shape before the ref advances; the runtime
+ * validator here keeps the Git-to-database projection fail-closed if that
+ * invariant is ever violated.
+ */
+export async function listConsumedWorkflowDispatches(reads) {
+    const consumed = [];
+    for (const addressEntry of await reads.listDir(WORKFLOW_RUN_ADDRESSES_PREFIX)) {
+        if (addressEntry.type !== "tree")
+            continue;
+        const consumedPath = `${WORKFLOW_RUN_ADDRESSES_PREFIX}/${addressEntry.name}/${WORKFLOW_RUN_CONSUMED_DIR}`;
+        for (const entry of await reads.listDir(consumedPath)) {
+            if (entry.type !== "blob" || !entry.name.endsWith(".json"))
+                continue;
+            const raw = await reads.readBlobByOid(entry.oid);
+            let decoded;
+            try {
+                decoded = JSON.parse(new TextDecoder().decode(raw));
+            }
+            catch (cause) {
+                throw new Error(`workflow_dispatch_consumed_invalid_json: ${consumedPath}/${entry.name}`, { cause });
+            }
+            const envelope = ConsumedEnvelope(decoded);
+            if (envelope instanceof type.errors) {
+                throw new Error(`workflow_dispatch_consumed_invalid: ${consumedPath}/${entry.name}: ${envelope.summary}`);
+            }
+            consumed.push({
+                messageId: envelope.messageId,
+                address: envelope.address,
+                ...(envelope.rejection !== undefined
+                    ? { rejection: envelope.rejection }
+                    : {}),
+            });
+        }
+    }
+    return consumed;
+}