@intx/hub-sessions 0.1.2 → 0.3.0

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

@@ -0,0 +1,440 @@
+import { type AuthorizeFn, type CommittedReads, type KindHandler, type Principal, type RepoId, type RepoStore } from "./repo-store/index.js";
+export type WorkflowRunHubPrincipal = {
+    readonly kind: "hub";
+};
+export type WorkflowRunSidecarPrincipal = {
+    readonly kind: "sidecar";
+    readonly agentId: string;
+};
+export type WorkflowRunWorkflowProcessPrincipal = {
+    readonly kind: "workflow-process";
+    readonly anchorRunId: string;
+    readonly runId?: string;
+};
+export type WorkflowRunSupervisorPrincipal = {
+    readonly kind: "supervisor";
+    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";
+/**
+ * Filename of the per-address retention watermark blob, a direct child
+ * of `addresses/<urlEncoded>/` (a file, not a directory). Carries the
+ * monotonic `receivedAt`-horizon below which consumed entries may be
+ * pruned and at-or-below which inbound enqueues are refused as stale.
+ */
+export declare const WORKFLOW_RUN_WATERMARK_FILE = "watermark.json";
+/**
+ * Default retention horizon for the consumed dedup index, in
+ * milliseconds. The boot edge resolves the operator's
+ * `CONSUMED_RETENTION_MS` config to a concrete value and threads it
+ * into `markConsumed`; this default applies only when no operator
+ * value is supplied. 24 hours is the conservative default: long enough
+ * that a duplicate from a retrying upstream within a day is still
+ * 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. 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;
+/**
+ * Per-agent durable conversation-state subtree (design §3c). A
+ * long-lived single-step agent's multi-turn conversation context is
+ * committed under `agent-state/<agentKey>/...` so it survives child
+ * respawn: on respawn the rebuilt warm agent reads its prior
+ * conversation back from here before the resumed run replays.
+ *
+ * Unlike `runs/` (append-only events, immutable blobs) this subtree is
+ * MUTABLE: each run boundary overwrites the agent's conversation
+ * snapshot with the latest turns. It is therefore exempt from the
+ * append-only / deletion-direction walks `runs/` is subject to; the
+ * only push-time constraint is segment shape (a single round-trip-safe
+ * `<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.
+ *   - `receivedAt`: epoch-ms timestamp the reactor accepted the
+ *     message; sortable FIFO key prefix.
+ *   - `address`: decoded canonical address (not URL-encoded).
+ *   - `mailAuditRef`: pointer to the raw mail bytes in the mail-audit
+ *     store. For the in-process single-agent path a separate
+ *     `MailAuditStore` holds the authoritative bytes and this ref joins
+ *     onto it.
+ *   - `rawMessage`: base64 of the inbound mail's raw MIME bytes,
+ *     inlined so the workflow-process child can read its step input by
+ *     messageId at `trigger.fired` time. The supervisor is the sole
+ *     mail owner under the unified-execution host (§3a); it has no
+ *     separate durable byte store the child can read, so the bytes ride
+ *     the claim-check envelope itself. Present whenever the supervisor
+ *     enqueued the entry; omitted by callers that only stamp the audit
+ *     ref. The bytes survive the inbox→processing transition verbatim
+ *     (the dequeue copies the entry bytes), so a `trigger.fired` for a
+ *     processing entry can always recover the input.
+ */
+declare const ClaimCheckEnvelope: import("arktype/internal/variants/object.ts").ObjectType<{
+    messageId: string;
+    receivedAt: number;
+    address: string;
+    mailAuditRef: {
+        store: string;
+        path: string;
+    };
+    rawMessage?: string;
+}, {}>;
+/**
+ * JSON envelope carried by consumed entries. The consumed entry is the
+ * canonical dedup index keyed by messageId; the envelope preserves
+ * the originating receivedAt for audit and carries the runId that
+ * consumed the message.
+ */
+declare const ConsumedEnvelope: import("arktype/internal/variants/object.ts").ObjectType<{
+    messageId: string;
+    receivedAt: number;
+    address: string;
+    runId: string;
+    consumedAt: number;
+    mailAuditRef: {
+        store: string;
+        path: string;
+    };
+    rejection?: {
+        code: string;
+        message: string;
+    };
+}, {}>;
+/**
+ * JSON envelope carried by the per-address `watermark.json` blob. The
+ * `watermark` is a `receivedAt` horizon (epoch ms): the oldest
+ * `receivedAt` a consumed entry may still retain. It only ever
+ * advances. A retention prune drops consumed entries strictly below
+ * it; `enqueueInbox` refuses any inbound strictly below it.
+ */
+declare const WatermarkEnvelope: import("arktype/internal/variants/object.ts").ObjectType<{
+    watermark: number;
+}, {}>;
+export type ClaimCheckEnvelope = typeof ClaimCheckEnvelope.infer;
+export type ConsumedEnvelope = typeof ConsumedEnvelope.infer;
+export type WatermarkEnvelope = typeof WatermarkEnvelope.infer;
+export declare const workflowRunKindHandler: KindHandler;
+export declare const workflowRunAuthorize: AuthorizeFn;
+export type EnqueueInboxArgs = {
+    address: string;
+    messageId: string;
+    receivedAt: number;
+    mailAuditRef: {
+        store: string;
+        path: string;
+    };
+    /**
+     * Base64 of the inbound mail's raw MIME bytes. Inlined on the
+     * claim-check envelope so the workflow-process child can recover its
+     * step input by messageId at `trigger.fired` time (§3a -- the
+     * supervisor is the sole mail owner and has no separate durable byte
+     * store the child reads). Omit to stamp only the audit ref.
+     */
+    rawMessage?: string;
+};
+export type EnqueueInboxResult = {
+    commitSha: string;
+    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
+ * with the new entry, and returns the full set of address files. The
+ * substrate replaces the address subtree wholesale.
+ *
+ * Rejects if a same-messageId entry already exists in any queue
+ * state at the address — including a prior inbox entry at a
+ * different `receivedAt`. The caller is expected to consult the
+ * dedup index (consumed/) before calling, but enforcing the
+ * 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<EnqueueInboxOutcome>;
+export type DequeueToProcessingResult = {
+    commitSha: string;
+    key: string;
+    envelope: ClaimCheckEnvelope;
+} | null;
+/**
+ * Move the FIFO-first inbox entry for `address` to processing.
+ * Returns `null` when the inbox is empty so the caller can
+ * distinguish "nothing to do" from "operation failed".
+ *
+ * FIFO is keyed on the parsed numeric `receivedAt` prefix of the
+ * inbox filename, with a lexicographic messageId tiebreak. The
+ * substrate does NOT rely on uniform digit widths — sorting raw
+ * filenames would put `"100-…"` ahead of `"99-…"` since `'1' < '9'`,
+ * which violates the FIFO invariant.
+ */
+export declare function dequeueToProcessing(store: RepoStore, principal: Principal, repoId: RepoId, address: string): Promise<DequeueToProcessingResult>;
+export type ReadProcessingEntryResult = {
+    envelope: ClaimCheckEnvelope;
+} | null;
+/**
+ * Read the processing-queue entry for `messageId` at `address` without
+ * mutating the tree. Returns the decoded claim-check envelope (carrying
+ * `mailAuditRef` and, when the enqueuer inlined them, the base64
+ * `rawMessage` bytes) or `null` when no processing entry exists for the
+ * messageId.
+ *
+ * This is the read half of mailbox ownership (§3a): the supervisor's
+ * dispatch loop moves an inbox entry to processing and forwards a
+ * `trigger.fired{messageId}` to the workflow-process child; the child
+ * calls this to recover the inbound message bytes that become its step
+ * input.
+ *
+ * The read is a flat working-tree read of
+ * `addresses/<seg>/processing/`. The substrate materializes each
+ * claim-check commit's touched paths into the repo's working tree (the
+ * delta write removes each deleted path and writes each put after
+ * validation passes), so a read issued after `dequeueToProcessing`
+ * 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
+ * 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.
+ */
+export declare function readProcessingEntry(store: RepoStore, _principal: Principal, repoId: RepoId, address: string, messageId: string): Promise<ReadProcessingEntryResult>;
+export type MarkConsumedArgs = {
+    address: string;
+    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
+     * `consumedAt - retentionHorizonMs` (never backward, never past the
+     * entry being written) and prunes consumed entries below it. The
+     * boot edge resolves the operator's `CONSUMED_RETENTION_MS` config
+     * to a concrete value and threads it here. Omit to apply
+     * `DEFAULT_CONSUMED_RETENTION_MS` (24h).
+     */
+    retentionHorizonMs?: number;
+};
+export type MarkConsumedResult = {
+    commitSha: string;
+    envelope: ConsumedEnvelope;
+    /** Watermark the commit advanced to (epoch-ms `receivedAt` horizon). */
+    watermark: number;
+    /** messageIds whose consumed entries this commit pruned. */
+    prunedMessageIds: string[];
+};
+/**
+ * Atomically remove the processing entry for `messageId` at `address`,
+ * write the canonical `consumed/<messageId>.json` dedup index entry,
+ * advance the per-address retention watermark, and prune consumed
+ * entries the watermark has passed. The caller is expected to have
+ * called `dequeueToProcessing` for this messageId; calling
+ * `markConsumed` without a matching processing entry throws.
+ *
+ * The consumed envelope preserves the original `receivedAt` and
+ * `mailAuditRef` from the processing entry so the dedup index doubles
+ * as an audit record.
+ *
+ * Retention (the bounded-`consumed/` contract): the watermark advances
+ * to `max(priorWatermark, min(consumedAt - retentionHorizonMs,
+ * thisEntry.receivedAt))` -- monotonic, and never past the entry being
+ * written so the new entry is always retained. Every consumed entry
+ * whose `receivedAt` is strictly below the new watermark is dropped
+ * (the oldest age-ordered tail). `consumed/` therefore reaches a
+ * bounded steady state of roughly one horizon's worth of entries
+ * instead of growing one entry per message forever.
+ */
+export declare function markConsumed(store: RepoStore, principal: Principal, repoId: RepoId, args: MarkConsumedArgs): Promise<MarkConsumedResult>;
+export type ReplayProcessingToInboxResult = {
+    commitSha: string;
+    replayedKeys: string[];
+};
+/**
+ * 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.
+ *
+ * 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.
+ */
+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
+     * its inbound message: recovery re-drives that run against the durable
+     * log, so re-admitting the message to `inbox/` would dispatch a SECOND
+     * run for it, colliding with the re-drive on the shared runId. Entries
+     * in this set are left in `processing/` untouched; the run's eventual
+     * `markConsumed` clears them. The caller computes this by reading the
+     * run event logs, which live on a DIFFERENT ref (`refs/heads/main`)
+     * than the claim-check subtree this operation commits to
+     * (`refs/heads/events`). Empty/absent means replay every processing
+     * entry (the pre-existing behaviour: recover all orphans).
+     */
+    ownedMessageIds?: ReadonlySet<string>;
+};
+/**
+ * Recovery path: move every processing entry at `address` back to
+ * inbox preserving the original `<receivedAt>-<messageId>` filename
+ * key so FIFO ordering survives a workflow-process crash. Returns
+ * the set of keys that were moved; when nothing was in processing
+ * the returned `replayedKeys` is empty (and the commit is a no-op
+ * rewrite of the same tree).
+ *
+ * The replay is atomic across all processing entries — a partial
+ * replay that left some entries in processing would corrupt the
+ * FIFO discipline (the next dequeue would pull the wrong entry).
+ *
+ * Watermark carve-out (load-bearing — do NOT "tighten" this): the
+ * replay deliberately does NOT apply the `receivedAt < watermark`
+ * stale-reject that `enqueueInbox` applies. A `processing/` entry was
+ * already dequeued past the dedup index, so re-admitting it to
+ * `inbox/` even when its `receivedAt` has fallen below an advanced
+ * watermark is correct — the message is a legitimately in-flight one
+ * recovered after a crash, not a fresh inbound that could be a
+ * duplicate. Applying the stale-reject here would silently LOSE that
+ * message. The watermark only ever gates fresh inbound at the enqueue
+ * boundary; the recovery replay is exempt by design.
+ */
+export declare function replayProcessingToInbox(store: RepoStore, principal: Principal, repoId: RepoId, address: string, opts?: ReplayProcessingToInboxOpts): Promise<ReplayProcessingToInboxResult>;
+export {};