@intx/hub-sessions 0.2.2 → 0.3.0

package/dist/workflow-probe-gate.d.ts

@@ -0,0 +1,214 @@
+import type { DBExecutor } from "@intx/db";
+import type { GrantWalkSnapshot } from "@intx/types";
+import type { PackumentFetcher, RegistryConfig } from "@intx/tool-packaging";
+import type { WorkflowProjectionDefinition } from "@intx/types/sidecar";
+import type { ToolPackageManifest } from "@intx/types/tool-packages";
+import type { WorkflowDefinitionAssetSource, WorkflowDefinitionRegistrySource } from "@intx/types/workflow-sources";
+import type { ApprovalSet } from "@intx/workflow-deploy";
+import { type ResolveAssetAttachmentFn } from "./workflow-closure-resolution.js";
+import type { SourceTreeReads } from "./workflow-source-closure.js";
+import type { SidecarRouter, WorkflowProbeResult } from "./ws/sidecar-handler.js";
+/**
+ * The frozen record an approval writes: the definition's asset selector, the
+ * approved wire hash (the freeze anchor), the approved grant set, and the
+ * grant-walk snapshot the run path materializes grants from. The grant set is a
+ * deterministic projection of the content the hash addresses and rides the
+ * deploy hand-off in memory; the snapshot is persisted onto the version row so a
+ * run derives its grants from the frozen walk without re-reading and re-walking
+ * the workflow's `workflow.json`.
+ */
+export type FrozenApproval = {
+    readonly assetId: string;
+    readonly approvedWireHash: string;
+    readonly approvedGrants: readonly string[];
+    readonly grantSnapshot: GrantWalkSnapshot;
+};
+/**
+ * Persists a frozen approval and returns the definition it was recorded
+ * against. Bound to a `DBExecutor` in production via
+ * `createDbFrozenApprovalWriter`; a test double records the call.
+ */
+export type PersistFrozenApprovalFn = (approval: FrozenApproval) => Promise<{
+    definitionId: string;
+}>;
+/**
+ * The outcome of gating and freezing a probe result. `ok: true` is the frozen
+ * approval the deploy hand-off consumes. The `ok: false` arms name the two
+ * fail-closed paths: a shipped hash that does not match the hub recompute
+ * (tamper-evidence), and advisory grants the operator did not approve.
+ */
+export type ProbeGateResult = {
+    readonly ok: true;
+    readonly definitionId: string;
+    readonly approvedWireHash: string;
+    readonly approvedGrants: ReadonlySet<string>;
+    /**
+     * The inert wire projection the freeze hashed. Rides the ok-arm so the
+     * deploy hand-off carries the exact content the frozen hash addresses,
+     * never a re-projection of a registry that may have moved since approval.
+     */
+    readonly projection: WorkflowProjectionDefinition;
+} | {
+    readonly ok: false;
+    readonly reason: "wire_hash_mismatch";
+    readonly shippedWireHash: string;
+    readonly recomputedWireHash: string;
+} | {
+    readonly ok: false;
+    readonly reason: "grants_not_approved";
+    readonly unapprovedGrants: readonly string[];
+};
+/**
+ * Build the production persistence step of the freeze. Records identity through
+ * the selector-keyed ensure helper (a definition keyed by `(assetId,
+ * wireHash)`) and writes the approved wire hash and the grant-walk snapshot onto
+ * that definition's version row in one transaction. The grant SET is not written
+ * to a version-row column -- the approved wire hash already pins the content the
+ * grants project from -- so it travels with the returned frozen approval; the
+ * snapshot is written because the run path reads it back to materialize grants.
+ */
+export declare function createDbFrozenApprovalWriter(db: DBExecutor): PersistFrozenApprovalFn;
+/**
+ * Approve exactly the grant surface the probe reports, without a pre-walked
+ * operator `ApprovalSet` to gate against. Under this mode the gate skips the
+ * per-grant membership check and freezes exactly what the probe advertised.
+ *
+ * This is the code-sourced analogue of the live-authored self-approve: the hub
+ * has no live definition to pre-walk, so the probe's advertised grants ARE the
+ * declared surface. It does NOT relax tamper-evidence -- the wire-hash check
+ * still runs and can still fail closed.
+ */
+export type ApproveProbedGrants = {
+    readonly mode: "approve-probed";
+};
+/**
+ * How the gate turns the probe's advisory grant set into an approved set.
+ * Either an explicit operator `ApprovalSet` -- every advertised grant must
+ * appear in it or the gate fails closed -- or `approve-probed`, which approves
+ * exactly the surface the probe reported.
+ */
+export type ProbeApprovalPolicy = ApprovalSet | ApproveProbedGrants;
+export type GateAndFreezeArgs = {
+    /** The `workflow`-kind asset the frozen definition projects over. */
+    readonly assetId: string;
+    /** The sidecar's inert probe answer: projection, advisory grants, shipped hash. */
+    readonly probeResult: WorkflowProbeResult;
+    /**
+     * The approval policy. An `ApprovalSet` gates the advisory set against the
+     * operator-approved grant-shape strings; `approve-probed` approves exactly
+     * the surface the probe reported.
+     */
+    readonly approvals: ProbeApprovalPolicy;
+    /** Persistence step for the freeze; `createDbFrozenApprovalWriter` in production. */
+    readonly persist: PersistFrozenApprovalFn;
+};
+/**
+ * Gate a probe result and, on approval, freeze it. Operates purely over the
+ * inert projection and grant set -- no author code runs here and the capability
+ * walk is never re-run.
+ *
+ * Fails closed on the two security-load-bearing checks before it writes
+ * anything: the recomputed wire hash must match the hash the sidecar shipped
+ * (tamper-evidence), and every advisory grant must be operator-approved. Only
+ * then does it freeze the recomputed hash onto the version row and return the
+ * approved grant set.
+ */
+export declare function gateAndFreezeProbeResult(args: GateAndFreezeArgs): Promise<ProbeGateResult>;
+type InstallAndApproveCommonArgs = {
+    /** The `interchange.workflow` entry-module path the sidecar evaluates to project the definition. */
+    readonly entry: string;
+    /** The `workflow`-kind asset the frozen definition projects over. */
+    readonly assetId: string;
+    /**
+     * The approval policy threaded to the gate: an operator `ApprovalSet` to gate
+     * the advisory set against, or `approve-probed` to approve exactly the
+     * surface the probe reports.
+     */
+    readonly approvals: ProbeApprovalPolicy;
+    /** The sidecar router carrying the probe transport. */
+    readonly router: Pick<SidecarRouter, "sendProbe">;
+    /** Executor the freeze writes through. */
+    readonly db: DBExecutor;
+};
+/** Install a definition published to an npm registry. */
+export type InstallAndApproveRegistryArgs = InstallAndApproveCommonArgs & {
+    readonly source: WorkflowDefinitionRegistrySource;
+    /** A `name@range` spec for the workflow definition package. */
+    readonly pin: string;
+    /** URL and credentials for the registry `source` names. */
+    readonly registryConfig: RegistryConfig;
+    /** Test seam for packument fetches, threaded to closure resolution. Omitted in production. */
+    readonly fetchPackument?: PackumentFetcher;
+};
+/**
+ * Install a definition published as a tarball inside a hub `package-registry`
+ * asset. The caller mints the asset-read closures (`readBlob`/`listBlobs`) and
+ * `resolveAttachment`; this glue never imports the asset service, so hub-service
+ * ownership stays at the caller.
+ */
+export type InstallAndApproveAssetTarballArgs = InstallAndApproveCommonArgs & {
+    readonly source: WorkflowDefinitionAssetSource;
+    /** A `name@range` spec for the workflow definition package. */
+    readonly pin: string;
+    /** Reads a blob at `path` from the asset the definition is sourced from. */
+    readonly readBlob: (path: string) => Promise<Uint8Array>;
+    /** Lists the blob names directly under `dir` in that asset. */
+    readonly listBlobs: (dir: string) => Promise<string[]>;
+    /** Resolves each asset the closure references to the pack the probe delivers. */
+    readonly resolveAttachment: ResolveAssetAttachmentFn;
+};
+/**
+ * Install a definition whose package lives as a git subtree of a hub asset at a
+ * pinned commit. The caller binds a `SourceTreeReads` to that commit and
+ * supplies the npm `registryConfig` for the external deps; there is no
+ * `name@range` pin (the member is selected from `source.package.packageName`).
+ * `resolveAttachment` delivers the same git pack the tarball arm does, so the
+ * sidecar checks the subtree out of it.
+ */
+export type InstallAndApproveAssetSourceArgs = InstallAndApproveCommonArgs & {
+    readonly source: WorkflowDefinitionAssetSource;
+    /** Git-tree reads pinned to `source.package.commitSha`. */
+    readonly reads: SourceTreeReads;
+    /**
+     * The registry name external deps are stamped with in the frozen closure.
+     * Must be a name the sidecar's registry map is keyed by (its npm registry).
+     */
+    readonly registryName: string;
+    /** URL and credentials for the npm registry external deps resolve against. */
+    readonly registryConfig: RegistryConfig;
+    /** Test seam for packument fetches, threaded to closure resolution. Omitted in production. */
+    readonly fetchPackument?: PackumentFetcher;
+    /** Resolves each asset the closure references to the pack the probe delivers. */
+    readonly resolveAttachment: ResolveAssetAttachmentFn;
+};
+export type InstallAndApproveArgs = InstallAndApproveRegistryArgs | InstallAndApproveAssetTarballArgs | InstallAndApproveAssetSourceArgs;
+/**
+ * The frozen hand-off `installAndApproveWorkflowDefinition` produces. It carries
+ * the gate outcome plus the two values the source-ref deploy frame needs and
+ * must NOT recompute at deploy: the inert `projection` the freeze hashed and the
+ * frozen dependency `closure` the pin resolved to. Re-resolving either at deploy
+ * would reintroduce the non-determinism the freeze eliminates -- a registry that
+ * moved between approve and deploy would pin different bytes and project
+ * differently, failing the child re-verify -- so both ride from approve verbatim.
+ */
+export type InstallAndApproveResult = {
+    readonly approval: ProbeGateResult;
+    readonly projection: WorkflowProjectionDefinition;
+    readonly closure: ToolPackageManifest;
+};
+/**
+ * The install/approve orchestration entrypoint the end-to-end flow drives:
+ * resolve the frozen closure, probe the sidecar, then gate and freeze the
+ * result. This is production glue, not test-only wiring.
+ *
+ * The operator-approval decision is an input (`approvals`): the caller supplies
+ * either the `ApprovalSet` the operator approved, which the gate holds the
+ * advisory set to, or `approve-probed` to approve exactly the surface the probe
+ * reports.
+ *
+ * Returns the gate outcome alongside the inert projection and the frozen
+ * closure so the deploy hand-off consumes them verbatim rather than re-probing
+ * or re-resolving.
+ */
+export declare function installAndApproveWorkflowDefinition(args: InstallAndApproveArgs): Promise<InstallAndApproveResult>;
+export {};

package/dist/workflow-probe-gate.js

@@ -0,0 +1,207 @@
+// Hub-side install/approve orchestration and gate for a code-sourced workflow
+// definition.
+//
+// This is the production glue that turns a code-sourced workflow install into
+// an approved, frozen definition WITHOUT executing any author code on the hub.
+// Everything here operates over the inert projection and grant set the sidecar
+// returns from a probe:
+//
+//   1. Resolve the frozen dependency closure for the definition's pin.
+//   2. Probe the sidecar for the definition's inert needs-surface projection,
+//      its advisory grant set, and the content hash the sidecar shipped.
+//   3. RECOMPUTE the wire hash over the RECEIVED projection as tamper-evidence:
+//      a shipped hash that differs from the hub recompute is rejected, fail
+//      closed, no coercion.
+//   4. Gate the advisory grant set against the approval policy: an operator
+//      `ApprovalSet` requires every grant the probe surfaced to be approved or
+//      the gate fails, while `approve-probed` approves exactly what the probe
+//      surfaced.
+//   5. Freeze the approved wire hash onto the definition version row, keyed by
+//      the definition's selector, and return the frozen approved grant set.
+//
+// The frozen approved set is the single source of truth for the definition's
+// grants: the deploy path materializes deploy grants as a SUBSET of it (never a
+// fresh walk), so a workflow can never acquire at deploy or run time a grant it
+// did not have frozen at approval. The wire hash is that freeze's anchor -- the
+// grant set is a deterministic projection of the exact content the hash
+// addresses, so pinning the hash pins the set.
+import { and, eq } from "drizzle-orm";
+import { workflowDefinitionVersion } from "@intx/db/schema";
+import { computeWireDefinitionHash } from "@intx/types/wire-definition-hash";
+import { buildSourceAssetMounts, resolveWorkflowClosure, } from "./workflow-closure-resolution.js";
+import { ensureWorkflowDefinitionForAsset } from "./workflow-definition-ensure.js";
+// The version `ensureWorkflowDefinitionForAsset` projects for a fresh
+// definition, and therefore the row the approval freeze targets. Kept in step
+// with the ensure helper: if that helper ever projects a different initial
+// version, this must follow.
+const FROZEN_VERSION = "1";
+/**
+ * Build the production persistence step of the freeze. Records identity through
+ * the selector-keyed ensure helper (a definition keyed by `(assetId,
+ * wireHash)`) and writes the approved wire hash and the grant-walk snapshot onto
+ * that definition's version row in one transaction. The grant SET is not written
+ * to a version-row column -- the approved wire hash already pins the content the
+ * grants project from -- so it travels with the returned frozen approval; the
+ * snapshot is written because the run path reads it back to materialize grants.
+ */
+export function createDbFrozenApprovalWriter(db) {
+    return async ({ assetId, approvedWireHash, grantSnapshot }) => {
+        // Ensure-then-stamp is one freeze: a crash between the two would persist a
+        // version row with a NULL `approvedWireHash`, which the schema treats as
+        // the legitimate "not yet approved" state -- indistinguishable from an
+        // un-approved definition. Wrap both writes in one transaction so the freeze
+        // is all-or-nothing.
+        return db.transaction(async (tx) => {
+            const { definitionId } = await ensureWorkflowDefinitionForAsset(tx, {
+                assetId,
+                wireHash: approvedWireHash,
+            });
+            // `FROZEN_VERSION` is hand-coupled to the version the ensure helper
+            // projects; if that coupling ever drifts, the update would silently stamp
+            // zero rows and no hash would persist. Assert exactly one row so a drift
+            // fails loud instead of open.
+            const stamped = await tx
+                .update(workflowDefinitionVersion)
+                .set({ approvedWireHash, grantSnapshot })
+                .where(and(eq(workflowDefinitionVersion.definitionId, definitionId), eq(workflowDefinitionVersion.version, FROZEN_VERSION)))
+                .returning({ id: workflowDefinitionVersion.id });
+            if (stamped.length !== 1) {
+                throw new Error(`createDbFrozenApprovalWriter: expected to stamp exactly one ${FROZEN_VERSION} version row for definition ${definitionId}, but updated ${String(stamped.length)}`);
+            }
+            return { definitionId };
+        });
+    };
+}
+function isApproveProbed(policy) {
+    return "mode" in policy;
+}
+/**
+ * Gate a probe result and, on approval, freeze it. Operates purely over the
+ * inert projection and grant set -- no author code runs here and the capability
+ * walk is never re-run.
+ *
+ * Fails closed on the two security-load-bearing checks before it writes
+ * anything: the recomputed wire hash must match the hash the sidecar shipped
+ * (tamper-evidence), and every advisory grant must be operator-approved. Only
+ * then does it freeze the recomputed hash onto the version row and return the
+ * approved grant set.
+ */
+export async function gateAndFreezeProbeResult(args) {
+    const { assetId, probeResult, approvals, persist } = args;
+    // Tamper-evidence: recompute over the RECEIVED projection and compare to the
+    // shipped hash. A mismatch means the projection the hub is approving is not
+    // the one the sidecar hashed, so reject rather than freeze a hash that does
+    // not describe the approved content.
+    const recomputedWireHash = await computeWireDefinitionHash(probeResult.projection);
+    if (recomputedWireHash !== probeResult.wireHash) {
+        return {
+            ok: false,
+            reason: "wire_hash_mismatch",
+            shippedWireHash: probeResult.wireHash,
+            recomputedWireHash,
+        };
+    }
+    // Gate the advisory grant set. Under an `ApprovalSet` every grant the probe
+    // surfaced must appear in the operator's approved set; any miss fails the
+    // gate closed. Under `approve-probed` there is no set to gate against -- the
+    // probe's surface IS the approved set -- so nothing is ever unapproved.
+    const unapprovedGrants = isApproveProbed(approvals)
+        ? []
+        : probeResult.grants.filter((grant) => !approvals.has(grant));
+    if (unapprovedGrants.length > 0) {
+        return { ok: false, reason: "grants_not_approved", unapprovedGrants };
+    }
+    // Freeze: the approved set is exactly what the workflow advertised (all of it
+    // now operator-approved), pinned to the recomputed hash. Persisting the hash
+    // is the freeze; the grant set is returned for the deploy hand-off.
+    const approvedGrants = [...probeResult.grants];
+    const { definitionId } = await persist({
+        assetId,
+        approvedWireHash: recomputedWireHash,
+        approvedGrants,
+        grantSnapshot: probeResult.grantWalkSnapshot,
+    });
+    return {
+        ok: true,
+        definitionId,
+        approvedWireHash: recomputedWireHash,
+        approvedGrants: new Set(approvedGrants),
+        projection: probeResult.projection,
+    };
+}
+// 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 isAssetSourceInstallArgs(args) {
+    return (args.source.kind === "asset" && args.source.package.format === "source");
+}
+function isAssetTarballInstallArgs(args) {
+    return (args.source.kind === "asset" && args.source.package.format === "tarball");
+}
+/**
+ * The install/approve orchestration entrypoint the end-to-end flow drives:
+ * resolve the frozen closure, probe the sidecar, then gate and freeze the
+ * result. This is production glue, not test-only wiring.
+ *
+ * The operator-approval decision is an input (`approvals`): the caller supplies
+ * either the `ApprovalSet` the operator approved, which the gate holds the
+ * advisory set to, or `approve-probed` to approve exactly the surface the probe
+ * reports.
+ *
+ * Returns the gate outcome alongside the inert projection and the frozen
+ * closure so the deploy hand-off consumes them verbatim rather than re-probing
+ * or re-resolving.
+ */
+export async function installAndApproveWorkflowDefinition(args) {
+    let closure;
+    let assets;
+    if (isAssetSourceInstallArgs(args)) {
+        closure = await resolveWorkflowClosure({
+            source: args.source,
+            reads: args.reads,
+            registryName: args.registryName,
+            registryConfig: args.registryConfig,
+            ...(args.fetchPackument !== undefined
+                ? { fetchPackument: args.fetchPackument }
+                : {}),
+        });
+        assets = await buildSourceAssetMounts(closure, args.resolveAttachment);
+    }
+    else if (isAssetTarballInstallArgs(args)) {
+        closure = await resolveWorkflowClosure({
+            source: args.source,
+            pin: args.pin,
+            readBlob: args.readBlob,
+            listBlobs: args.listBlobs,
+        });
+        assets = await buildSourceAssetMounts(closure, args.resolveAttachment);
+    }
+    else {
+        closure = await resolveWorkflowClosure({
+            source: args.source,
+            pin: args.pin,
+            registryConfig: args.registryConfig,
+            ...(args.fetchPackument !== undefined
+                ? { fetchPackument: args.fetchPackument }
+                : {}),
+        });
+        assets = [];
+    }
+    const { sendProbe } = args.router;
+    if (sendProbe === undefined) {
+        throw new Error("installAndApproveWorkflowDefinition: router does not support sendProbe");
+    }
+    const probeResult = await sendProbe({
+        source: args.source,
+        closure,
+        entry: args.entry,
+        ...(assets.length > 0 ? { assets } : {}),
+    });
+    const approval = await gateAndFreezeProbeResult({
+        assetId: args.assetId,
+        probeResult,
+        approvals: args.approvals,
+        persist: createDbFrozenApprovalWriter(args.db),
+    });
+    return { approval, projection: probeResult.projection, closure };
+}

package/dist/workflow-run-kind.d.ts

@@ -1,4 +1,4 @@
-import { type AuthorizeFn, type KindHandler, type Principal, type RepoId, type RepoStore } from "./repo-store/index.js";
+import { type AuthorizeFn, type CommittedReads, type KindHandler, type Principal, type RepoId, type RepoStore } from "./repo-store/index.js";
 export type WorkflowRunHubPrincipal = {
     readonly kind: "hub";
 };
@@ -8,18 +8,19 @@ export type WorkflowRunSidecarPrincipal = {
 };
 export type WorkflowRunWorkflowProcessPrincipal = {
     readonly kind: "workflow-process";
-    readonly deploymentId: string;
+    readonly anchorRunId: string;
     readonly runId?: string;
 };
 export type WorkflowRunSupervisorPrincipal = {
     readonly kind: "supervisor";
-    readonly deploymentId: string;
+    readonly anchorRunId: string;
 };
 export type WorkflowRunPrincipal = WorkflowRunHubPrincipal | WorkflowRunSidecarPrincipal | WorkflowRunWorkflowProcessPrincipal | WorkflowRunSupervisorPrincipal;
 export declare const WORKFLOW_RUN_GITIGNORE_PATH = ".gitignore";
 export declare const WORKFLOW_RUN_RUNS_PREFIX = "runs";
 export declare const WORKFLOW_RUN_EVENTS_DIR = "events";
 export declare const WORKFLOW_RUN_BLOBS_DIR = "blobs";
+export declare const WORKFLOW_RUN_GRANTS_FILE = "grants.json";
 export declare const WORKFLOW_RUN_ADDRESSES_PREFIX = "addresses";
 export declare const WORKFLOW_RUN_CONTROL_PREFIX = "control";
 export declare const WORKFLOW_RUN_INBOX_DIR = "inbox";
@@ -42,15 +43,28 @@ export declare const WORKFLOW_RUN_WATERMARK_FILE = "watermark.json";
  * deduped by a retained consumed entry, short enough that `consumed/`
  * reaches a bounded steady state of one day's message volume.
  *
- * INVARIANT (operator-owned): the horizon must be >= the longest
- * window in which the same `messageId` could legitimately be
- * re-submitted and still must be caught as a duplicate. There is no
- * automatic internal mail redelivery in the system today, so this is
- * the external re-submission window. If an at-least-once redelivery
- * source is ever added, the horizon must be >= its maximum redelivery
- * window or dedup breaks; a breach surfaces LOUDLY (a too-late
- * re-submission carrying an old `receivedAt` is refused at enqueue,
- * not silently reprocessed) rather than as silent double-processing.
+ * INVARIANT (operator-owned): the horizon must be >= the longest window in
+ * which the same `messageId` could legitimately be re-submitted and still must
+ * be caught as a duplicate. The hub now redelivers un-acked inbound mail
+ * (connected-window retry and reconnect-redelivery), so an at-least-once
+ * internal source DOES exist -- but the dedup guarantee against it does not
+ * rest on window arithmetic. It rests on a STRUCTURAL fact: `enqueueInbox` is
+ * only ever called with a freshly stamped `receivedAt` (a redelivery
+ * re-enters `onMailMessage` and re-stamps `Date.now()`, never carrying the
+ * original), and the watermark only ever advances to at most
+ * `consumedAt - retentionHorizonMs`, which is <= now, so a fresh `receivedAt`
+ * always sits a full horizon above the watermark and can never be stale-
+ * refused. A redelivery instead hits the `consumed/`/`processing/`/`inbox/`
+ * dedup index and is deduped there. The sole path that carries an original
+ * (old) `receivedAt` back into the queue is `replayProcessingToInbox`, which
+ * writes straight to `inbox/` and bypasses the stale gate entirely. So
+ * `claim_check_stale_enqueue` is unreachable via redelivery today. If any
+ * redelivery source is ever changed to carry the ORIGINAL `receivedAt` into
+ * `enqueueInbox`, stale becomes reachable, the horizon must then be >= that
+ * source's maximum redelivery window, and `StaleInboxEnqueueError`'s
+ * withhold-not-ack handling becomes load-bearing; a breach surfaces LOUDLY (an
+ * old-`receivedAt` re-submission is refused at enqueue) rather than as silent
+ * double-processing.
  */
 export declare const DEFAULT_CONSUMED_RETENTION_MS: number;
 /**
@@ -68,6 +82,28 @@ export declare const DEFAULT_CONSUMED_RETENTION_MS: number;
  * `<agentKey>` directory layer below the prefix).
  */
 export declare const WORKFLOW_RUN_AGENT_STATE_PREFIX = "agent-state";
+/**
+ * Parse the seq from a per-event log filename `<seq>.json` under
+ * `runs/<runId>/events/`. Returns the non-negative integer seq, or
+ * `null` when the name is not a legal per-event filename. This is the
+ * one place the filename shape is defined; every reader of the event log
+ * narrows names through it rather than re-encoding the regex. Callers
+ * decide what an illegal name means -- a foreign entry to skip, or a
+ * substrate-invariant violation to surface -- since `validatePush` is
+ * the authority that keeps illegal names from landing in the first place.
+ */
+export declare function parseEventSeq(filename: string): number | null;
+/**
+ * Narrow a per-event filename to its seq, throwing when it is illegal.
+ * A reader that enumerates the committed event log to act on its entries
+ * uses this rather than `parseEventSeq`: `validatePush` is the authority
+ * that keeps an illegal name from ever landing under
+ * `runs/<runId>/events/`, so a name that reaches a reader is corruption,
+ * and silently skipping it would drop an event from processing. `context`
+ * is the repo-root-relative blob path, surfaced in the error so the
+ * offending entry is identifiable.
+ */
+export declare function requireEventSeq(filename: string, context: string): number;
 /**
  * JSON envelope carried by inbox and processing entries. Keys:
  *   - `messageId`: dedup key for the inbound message.
@@ -115,6 +151,10 @@ declare const ConsumedEnvelope: import("arktype/internal/variants/object.ts").Ob
         store: string;
         path: string;
     };
+    rejection?: {
+        code: string;
+        message: string;
+    };
 }, {}>;
 /**
  * JSON envelope carried by the per-address `watermark.json` blob. The
@@ -153,6 +193,54 @@ export type EnqueueInboxResult = {
     inboxKey: string;
     envelope: ClaimCheckEnvelope;
 };
+/**
+ * Which already-present state an `enqueueInbox` call found the messageId
+ * in. Every value is POSITIVE evidence the message's bytes are durably on
+ * disk (inbox/processing) or were already consumed -- so a caller gating a
+ * receipt on the enqueue may safely acknowledge on any of them.
+ */
+export type EnqueueAlreadyPresentReason = "duplicate" | "already_inbox" | "processing" | "consumed";
+/**
+ * Outcome of an `enqueueInbox` call. Modeled as a value (not an exception)
+ * precisely because the return/throw boundary is the ack/withhold boundary
+ * for a caller gating a durable-receipt ack: a returned outcome is safe to
+ * acknowledge (the bytes are on disk -- freshly written or already present),
+ * a throw is not (the write could not complete or its disposition cannot be
+ * decided). `enqueued` is the only outcome that added a new inbox entry, so
+ * it is the only one a dispatch-driving caller wakes its loop on.
+ */
+export type EnqueueInboxOutcome = ({
+    outcome: "enqueued";
+} & EnqueueInboxResult) | {
+    outcome: "already-present";
+    reason: EnqueueAlreadyPresentReason;
+};
+/**
+ * Thrown by `enqueueInbox` when the inbound's `receivedAt` is strictly below
+ * the address's retention watermark. This is refusal under UNCERTAINTY, not
+ * proof of prior receipt: the consumed dedup entry that would rule out a
+ * duplicate may have been pruned, so the substrate can no longer tell a
+ * duplicate from a never-processed message and refuses rather than risk
+ * reprocessing. A caller gating a durable-receipt ack MUST NOT acknowledge on
+ * this -- acking an "I cannot tell" would terminally drop a message that was
+ * never written. It is its own type (not a generic Error) so that a caller,
+ * and monitoring, can surface it as a distinct loud signal rather than
+ * blending it into ordinary I/O-failure noise.
+ *
+ * Structurally unreachable on the mail-inbound path today: `enqueueInbox` is
+ * only ever called with a freshly stamped `receivedAt` (a redelivery
+ * re-stamps `Date.now()` rather than carrying the original), and the watermark
+ * only ever advances to at most `consumedAt - retentionHorizonMs <= now`, so a
+ * fresh `receivedAt` sits a full horizon above it. The sole path that carries
+ * an original (old) `receivedAt` back into the queue is
+ * `replayProcessingToInbox`, which writes straight to `inbox/` and bypasses
+ * this gate entirely. If any redelivery source is ever changed to carry the
+ * original `receivedAt` into `enqueueInbox`, this becomes reachable and its
+ * withhold-not-ack handling becomes load-bearing.
+ */
+export declare class StaleInboxEnqueueError extends Error {
+    constructor(message: string);
+}
 /**
  * Append a new inbox entry for `address`. The merge callback reads
  * the address subtree under the per-repo lock, augments the inbox
@@ -166,7 +254,7 @@ export type EnqueueInboxResult = {
  * invariant here also catches the concurrent-enqueue race that the
  * per-repo lock alone cannot surface.
  */
-export declare function enqueueInbox(store: RepoStore, principal: Principal, repoId: RepoId, args: EnqueueInboxArgs): Promise<EnqueueInboxResult>;
+export declare function enqueueInbox(store: RepoStore, principal: Principal, repoId: RepoId, args: EnqueueInboxArgs): Promise<EnqueueInboxOutcome>;
 export type DequeueToProcessingResult = {
     commitSha: string;
     key: string;
@@ -208,7 +296,7 @@ export type ReadProcessingEntryResult = {
  * committed -- which is exactly when the supervisor forwards
  * `trigger.fired` -- observes the processing entry. Reading the working tree (rather than walking the
  * committed git tree) matches the workflow-process child's sibling
- * reads of `workflow.json` and `runs/<runId>/events/`. Because the
+ * read of `runs/<runId>/events/`. Because the
  * read issues no commit it cannot race the supervisor's `markConsumed`
  * write; it returns a point-in-time snapshot of the directory.
  */
@@ -218,6 +306,16 @@ export type MarkConsumedArgs = {
     messageId: string;
     runId: string;
     consumedAt: number;
+    /**
+     * Present when the supervisor deliberately refused the message instead of
+     * delivering it to the run. The consumed entry remains the durable dedup
+     * record, while Hub projection uses this detail to fail (rather than settle)
+     * an exclusive-dispatch row.
+     */
+    rejection?: {
+        code: string;
+        message: string;
+    };
     /**
      * Retention horizon for the consumed dedup index, in milliseconds.
      * The commit advances the per-address watermark to
@@ -284,6 +382,22 @@ export type ReplayProcessingToInboxResult = {
  * yields an empty set.
  */
 export declare function readOwnedMessageIds(store: RepoStore, repoId: RepoId): Promise<Set<string>>;
+export type WorkflowRunLifecycle = "absent" | "live" | "terminal";
+/** Read one run's lifecycle from a committed workflow-run tree. */
+export declare function readCommittedWorkflowRunLifecycle(reads: CommittedReads | null, runId: string): Promise<WorkflowRunLifecycle>;
+/**
+ * Read the durable lifecycle of one run from the workflow-run working tree.
+ * `grants.json` alone is still an absent run: grants are staged before the
+ * first trigger, while the first event is the durable proof that the run was
+ * fired. A sealed event log is terminal by the kind handler's compaction
+ * invariant.
+ *
+ * The supervisor uses this when in-memory cohort membership is empty. That
+ * happens both for a genuinely new deployment and briefly during recovery,
+ * so treating both states as "fire" would start a second driver for a live
+ * log or reuse a terminal run.
+ */
+export declare function readWorkflowRunLifecycle(store: RepoStore, repoId: RepoId, runId: string): Promise<WorkflowRunLifecycle>;
 export type ReplayProcessingToInboxOpts = {
     /**
      * MessageIds whose run is still LIVE (non-terminal) and therefore owns