@intx/hub-sessions 0.2.2 → 0.4.0

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,23 +8,38 @@ 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";
 export declare const WORKFLOW_RUN_PROCESSING_DIR = "processing";
 export declare const WORKFLOW_RUN_CONSUMED_DIR = "consumed";
+/**
+ * Per-run inbound mail-part subtree. Non-text inbound mail content
+ * (image/audio/video/document mail parts) is committed here as real
+ * files rather than inlined into the JSON event log, whose serialization
+ * boundary would corrupt binary bytes. The layout is
+ * `runs/<runId>/parts/<urlEncoded(messageId)>/<index>-<name>`: one
+ * directory per inbound message (so a long-lived run's successive turns
+ * never collide), and one file per mail part carrying its verbatim
+ * bytes. The workflow-host ingest writes the bytes and records a
+ * lightweight `{ name, contentType, ref }` reference into the run's
+ * trigger / signal payload; the step invoker reads the bytes back at
+ * `agent.send` time. Files are immutable once written, like `blobs/`.
+ */
+export declare const WORKFLOW_RUN_PARTS_DIR = "parts";
 /**
  * Filename of the per-address retention watermark blob, a direct child
  * of `addresses/<urlEncoded>/` (a file, not a directory). Carries the
@@ -42,15 +57,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 +96,69 @@ export declare const DEFAULT_CONSUMED_RETENTION_MS: number;
  * `<agentKey>` directory layer below the prefix).
  */
 export declare const WORKFLOW_RUN_AGENT_STATE_PREFIX = "agent-state";
+/**
+ * Conversational-mailbox subtree for the warm single-step agent. The
+ * substrate mailbox backing commits the agent's durable inbox under
+ * `mailbox/INBOX/` so the full message history replicates to the hub
+ * alongside the run state. The layout is:
+ *
+ *   - `mailbox/INBOX/index.json` — the mailbox index. MUTABLE: the
+ *     backing rewrites it on every flush, so it is exempt from the
+ *     retained-blob byte-equality walk the `<uid>.eml` blobs are subject
+ *     to. It must nonetheless PERSIST once it existed: dropping it drops
+ *     the whole mailbox and resets uidValidity/uidNext on the next open.
+ *   - `mailbox/INBOX/<uid>.eml` — one message per file, carrying the
+ *     raw signed message bytes. `<uid>` is a decimal integer >= 1. A
+ *     RETAINED `<uid>.eml` (present in both prior and prospective) is
+ *     opaque and IMMUTABLE: it must reappear byte-identically, exactly
+ *     like `runs/<runId>/blobs/`. A prior `<uid>.eml` may be ABSENT from
+ *     the prospective tree — that is the warm agent expunging a message.
+ *     The raw bytes are not lost: they stay reachable through the parent
+ *     commit, and a `workflow-run` repo's objects are never GC'd (its
+ *     kind is off the GC allow-list), so an expunged message survives in
+ *     history for the life of the run repo. The audit trail rests on
+ *     "these objects are never pruned", not on the live tree being
+ *     monotonic.
+ *
+ * The only entries permitted under `mailbox/` are the `INBOX/`
+ * directory; the only entries permitted under `mailbox/INBOX/` are
+ * `index.json` and `<uid>.eml` message files. Anything else fails the
+ * push.
+ */
+export declare const WORKFLOW_RUN_MAILBOX_PREFIX = "mailbox";
+export declare const WORKFLOW_RUN_MAILBOX_INBOX_DIR = "INBOX";
+export declare const WORKFLOW_RUN_MAILBOX_INDEX_FILE = "index.json";
+/**
+ * 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;
+/**
+ * Maximum byte length of a single mail part path component (the
+ * URL-encoded message segment, and each `<index>-<name>` filename).
+ * messageIds and mail part names arrive from untrusted inbound mail;
+ * an over-long RFC 5322 message-id URL-encodes past the filesystem's
+ * 255-byte component limit and would otherwise fail at disk-write time,
+ * downstream of validation. Reject it at the boundary instead.
+ */
+export declare const MAX_MAIL_PART_PATH_COMPONENT_BYTES = 255;
 /**
  * JSON envelope carried by inbox and processing entries. Keys:
  *   - `messageId`: dedup key for the inbound message.
@@ -115,6 +206,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
@@ -129,6 +224,35 @@ declare const WatermarkEnvelope: import("arktype/internal/variants/object.ts").O
 export type ClaimCheckEnvelope = typeof ClaimCheckEnvelope.infer;
 export type ConsumedEnvelope = typeof ConsumedEnvelope.infer;
 export type WatermarkEnvelope = typeof WatermarkEnvelope.infer;
+/**
+ * Terminal event discriminators mapped to the `workflow_run.status` value
+ * each settles the run into. A run whose log contains an entry with one of
+ * these `type` values must not receive any event with a strictly greater
+ * seq.
+ *
+ * This map is a hand-rolled copy of the runtime's terminal-run vocabulary
+ * (`isTerminalRunPhase` in `@intx/workflow` state-machine `state.ts`,
+ * re-exported from the state-machine index and consumed by `transition.ts`),
+ * duplicated here because `@intx/hub-sessions` must not depend on
+ * `@intx/workflow`. It is the sole authority for that vocabulary and MUST
+ * stay in sync with the canonical runtime definition:
+ * if the runtime adds or removes a terminal run phase, update this map too.
+ * Drift silently reopens the restore-time double-driver collision that
+ * `scanRunsForBoot` (below) exists to prevent.
+ */
+type TerminalRunStatus = "completed" | "failed" | "cancelled";
+/**
+ * Classify a workflow-run event type against the terminal-status vocabulary.
+ * `TERMINAL_EVENT_STATUS` is the sole authority (see above), so a type absent
+ * from it is by definition not terminal: no separate membership set is
+ * consulted and no "unmapped terminal type" case can arise.
+ */
+export declare function classifyTerminalEvent(eventType: string): {
+    terminal: true;
+    status: TerminalRunStatus;
+} | {
+    terminal: false;
+};
 export declare const workflowRunKindHandler: KindHandler;
 export declare const workflowRunAuthorize: AuthorizeFn;
 export type EnqueueInboxArgs = {
@@ -153,6 +277,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 +338,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 +380,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 +390,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 allocation-dispatch row.
+     */
+    rejection?: {
+        code: string;
+        message: string;
+    };
     /**
      * Retention horizon for the consumed dedup index, in milliseconds.
      * The commit advances the per-address watermark to
@@ -263,27 +445,52 @@ export type ReplayProcessingToInboxResult = {
     commitSha: string;
     replayedKeys: string[];
 };
+export type ScanRunsForBootResult = {
+    ownedMessageIds: Set<string>;
+    pendingSealRunIds: string[];
+};
+/**
+ * Walk `runs/` once and return the two boot-recovery inputs the supervisor's
+ * spawn needs, from a single traversal of the working tree via `getRepoDir`:
+ *
+ * - `ownedMessageIds`: the `consumedMessageId`s of NON-terminal runs -- the
+ *   messages a live run still owns. Spawn feeds this into
+ *   `replayProcessingToInbox`'s `ownedMessageIds` so a parked run's message is
+ *   not re-admitted to inbox and dispatched a second time while the run is
+ *   recovered by re-driving its durable log. Without this, the re-drive AND the
+ *   re-triggered fresh run both re-park the same awaitSignal gate on the same
+ *   runId, and the two concurrent runtime bodies race to a corrupt terminal.
+ * - `pendingSealRunIds`: runs that are terminal but still in per-event form --
+ *   an interrupted fold left them unsealed. Spawn hands these to the recovery
+ *   sweep, which re-runs the idempotent fold. A terminal event is a *proposal*:
+ *   the authoritative decision is `compactRunEvents`, which independently
+ *   re-checks the run's max-seq event and no-ops a run that is not actually
+ *   terminal, so this scan may be loose.
+ *
+ * The working tree tracks the run-event ref (`refs/heads/main`); the
+ * claim-check ref (`refs/heads/events`) cannot see it, which is why this lives
+ * at the caller rather than inside `replayProcessingToInbox`'s single-ref
+ * delta. A run whose log is sealed (combined `events.jsonl`, only permitted for
+ * a terminated run) contributes to neither set; an absent `runs/` directory
+ * yields empty results.
+ */
+export declare function scanRunsForBoot(store: RepoStore, repoId: RepoId): Promise<ScanRunsForBootResult>;
+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 run event logs under `runs/` and return the set of
- * `consumedMessageId`s belonging to NON-terminal runs -- the messages a
- * live run still owns. The caller (the supervisor's spawn-time replay)
- * feeds this into `replayProcessingToInbox`'s `ownedMessageIds` so a
- * parked run's message is not re-admitted to inbox and dispatched a
- * second time while the run is recovered by re-driving its durable log.
- * Without this, the re-drive AND the re-triggered fresh run both re-park
- * the same awaitSignal gate on the same runId, and the two concurrent
- * runtime bodies race to a corrupt terminal.
+ * 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.
  *
- * Reads the substrate's working tree via `getRepoDir`, mirroring the
- * child's `discoverInFlightRuns`. The working tree tracks the run-event
- * ref (`refs/heads/main`); the claim-check ref (`refs/heads/events`)
- * cannot see it, which is why this lives at the caller rather than inside
- * `replayProcessingToInbox`'s single-ref delta. A run whose log is sealed
- * (combined `events.json`, only permitted for a terminated run) or
- * carries a terminal event is excluded; an absent `runs/` directory
- * yields an empty set.
+ * 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 readOwnedMessageIds(store: RepoStore, repoId: RepoId): Promise<Set<string>>;
+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