@intx/hub-sessions 0.3.0 → 0.4.0

package/dist/workflow-probe-gate.js

@@ -12,11 +12,17 @@
 //   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
+//   4. Reject a projection declaring a trigger type the runtime does not
+//      implement, so a deployment that could only ever sit inert never gets
+//      approved.
+//   5. Reject a projection carrying a step the grant walk left no record for,
+//      so no deployment can schedule a step whose grants nobody approved.
+//   6. Gate the advisory grant set AND the definition's declared grant
+//      requirements against the approval policy: an operator `ApprovalSet`
+//      requires every grant the probe surfaced and every requirement it
+//      declared to be approved or the gate fails, while `approve-probed`
+//      approves exactly what the probe surfaced.
+//   7. 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
@@ -25,9 +31,12 @@
 // 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 { type } from "arktype";
 import { and, eq } from "drizzle-orm";
 import { workflowDefinitionVersion } from "@intx/db/schema";
 import { computeWireDefinitionHash } from "@intx/types/wire-definition-hash";
+import { EXECUTABLE_STEP_DESCENT, walkStepTree, } from "@intx/workflow/definition";
+import { approvalSetFromItems, inertNestedBodies, isApprovedGrantRequirement, } from "@intx/workflow-deploy";
 import { buildSourceAssetMounts, resolveWorkflowClosure, } from "./workflow-closure-resolution.js";
 import { ensureWorkflowDefinitionForAsset } from "./workflow-definition-ensure.js";
 // The version `ensureWorkflowDefinitionForAsset` projects for a fresh
@@ -73,18 +82,113 @@ export function createDbFrozenApprovalWriter(db) {
     };
 }
 function isApproveProbed(policy) {
-    return "mode" in policy;
+    return policy.kind === "approve-probed";
+}
+/**
+ * Trigger types the definition vocabulary declares but the runtime does not
+ * implement. `schedule` is reserved: no cron parser and no scheduler exist, so
+ * a schedule-triggered deployment would hash, deploy, and then never fire --
+ * no error, no log, no failed run. Admitting one at the gate is the only way a
+ * deployment reaches that state, so the gate refuses it.
+ */
+const UNIMPLEMENTED_TRIGGER_TYPES = new Set(["schedule"]);
+// A projected trigger, typed only to its discriminant. `triggers` rides the
+// wire projection as `unknown[]` on purpose (the wire envelope does not own
+// the trigger vocabulary), so the discriminant is read through a validator
+// rather than an assertion. An entry that carries no string `type` is not a
+// trigger this gate has an opinion about and is left to the deploy path.
+const ProjectedTriggerType = type({ type: "string" });
+/**
+ * The distinct unimplemented trigger types a projection declares, in first-seen
+ * order. Empty when every declared trigger has an implementation behind it.
+ */
+function collectUnimplementedTriggerTypes(triggers) {
+    const found = [];
+    for (const trigger of triggers) {
+        const parsed = ProjectedTriggerType(trigger);
+        if (parsed instanceof type.errors)
+            continue;
+        if (!UNIMPLEMENTED_TRIGGER_TYPES.has(parsed.type))
+            continue;
+        if (found.includes(parsed.type))
+            continue;
+        found.push(parsed.type);
+    }
+    return found;
+}
+const EXECUTABLE_CLOSURE_CONTEXT = "probe gate executable closure: ";
+/**
+ * Every step the deployment can execute, walked over the frozen inert
+ * projection under `EXECUTABLE_STEP_DESCENT`, each carrying the chain it was
+ * reached through and the top-level step whose grant record accounts for it.
+ *
+ * The descent is the canonical one rather than a local re-derivation on
+ * purpose. Sharing `EXECUTABLE_STEP_DESCENT` with the capability walk makes the
+ * two sides agree on ONE thing: which primitive kinds are descended into, so a
+ * newly-added container kind cannot become reachable here while staying
+ * invisible to the walk. It does NOT make the two agree about grants. This
+ * function sees only step positions; whether the walk folded the right grants
+ * into a record is not observable from the inert projection and is not checked
+ * anywhere on this path.
+ *
+ * The position each step was reached at is the walk's own `path`, for the same
+ * reason. The head of that path is the top-level step the entry descends from,
+ * which is exactly the `perStep` key the capability walk folds its grants into.
+ */
+function collectExecutableReaches(projection) {
+    const reaches = [];
+    walkStepTree({
+        tree: projection,
+        context: EXECUTABLE_CLOSURE_CONTEXT,
+        nestedTrees: (step) => inertNestedBodies(step, EXECUTABLE_STEP_DESCENT),
+        visit: ({ stepId, path }) => {
+            reaches.push({ stepId, recordStepId: path[0], reachedThrough: path });
+        },
+    });
+    return reaches;
+}
+/**
+ * Every executable step the grant-walk snapshot carries no record for.
+ *
+ * A step's approved-grant record is the snapshot entry keyed by the top-level
+ * step it descends from: the capability walk collects one record per top-level
+ * step and folds into it the grants of every step that step can run.
+ *
+ * This is a PRESENCE check and nothing more. An absent record is decisive --
+ * it leaves every step of that subtree with no approved grants at all, which
+ * is the hole this catches. A present record is not evidence the other way:
+ * nothing here opens the record to confirm it actually carries the grants the
+ * steps beneath it need. A record present but under-filled passes this check
+ * and still refuses those tool calls at run time.
+ */
+function collectStepsWithoutGrantRecord(projection, snapshot) {
+    const recordedStepIds = new Set(snapshot.perStep.map((record) => record.stepId));
+    return collectExecutableReaches(projection).filter((reach) => !recordedStepIds.has(reach.recordStepId));
+}
+function describeStepsWithoutGrantRecord(missing) {
+    const positions = missing
+        .map((missed) => `${missed.stepId} (reached through ${missed.reachedThrough.join(" > ")}; expected a grant-walk record keyed by top-level step ${missed.recordStepId})`)
+        .join("; ");
+    return `the probe's grant-walk snapshot carries no approved-grant record covering ${String(missing.length)} executable step(s): ${positions}. A step outside every record deploys with no approved grants, and its tool calls are refused at run time with nothing on the deploy path reporting it.`;
 }
 /**
  * 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
+ * Fails closed on the three 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.
+ * (tamper-evidence), every advisory grant must be operator-approved, and every
+ * declared grant requirement must be operator-approved. It also refuses a
+ * projection whose triggers include a reserved-but-unimplemented type -- not a
+ * security check, but the layer a pinned closure cannot carry a stale copy of,
+ * so it is where a workflow that could only sit inert is caught -- and one
+ * whose executable closure reaches a step the grant walk left no record for --
+ * the layer holding both halves of the probe answer at once, and a presence
+ * check on those records rather than a check that any record's contents are
+ * sufficient.
+ * 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;
@@ -101,20 +205,94 @@ export async function gateAndFreezeProbeResult(args) {
             recomputedWireHash,
         };
     }
+    // Reject a trigger type nothing implements. This runs on the projection
+    // rather than on the author's definition because `defineWorkflow` is bundled
+    // INTO the pinned workflow closure: a closure published before the authoring
+    // check carries its own frozen copy and never sees it. The projection's
+    // `triggers` are produced by the hub's live->inert projector, so this is the
+    // one trigger surface a stale closure cannot carry past. Placed after the
+    // wire-hash check so tamper-evidence still decides first -- the projection
+    // must be the one the sidecar hashed before its content is reasoned about.
+    const unimplementedTriggerTypes = collectUnimplementedTriggerTypes(probeResult.projection.triggers);
+    if (unimplementedTriggerTypes.length > 0) {
+        return {
+            ok: false,
+            reason: "unimplemented_trigger",
+            unimplementedTriggerTypes,
+        };
+    }
+    // Totality: every step the deployment can execute must have an approved-grant
+    // record behind it. The two halves of a probe answer are produced
+    // independently -- the projection by the hub's live->inert projector, the
+    // grant-walk snapshot by the sidecar's capability walk over the live
+    // definition -- and nothing until now compared them. A step the walk skipped
+    // still projects, still deploys, and is still scheduled; its tool calls are
+    // then refused for lack of any grant, and the tool runner turns that refusal
+    // into an error tool result rather than a failure, so the run completes
+    // having done none of the work. This is the check that makes that
+    // unreachable: it is total over the closure and it runs on every deploy,
+    // rather than depending on some test happening to invoke a tool from the
+    // affected step.
+    //
+    // Placed after the trigger check and before the operator-policy checks
+    // below. A deploy that trips this is a defect in the deploy path, not a
+    // decision the operator can make differently, so it must not be reported
+    // behind an unapproved-grant message an operator would act on instead.
+    //
+    // DO NOT move this assertion earlier in this package's history. The record it
+    // requires is a claim that the approval covers everything the step can run,
+    // and that claim was not kept for a step inside a loop body or a section body
+    // until the deploy and runtime producers were made total over the executable
+    // closure. Asserted before those producers, the gate would have been
+    // enforcing a guarantee the rest of the system did not honour.
+    const stepsWithoutGrantRecord = collectStepsWithoutGrantRecord(probeResult.projection, probeResult.grantWalkSnapshot);
+    if (stepsWithoutGrantRecord.length > 0) {
+        return {
+            ok: false,
+            reason: "steps_without_grant_record",
+            stepsWithoutGrantRecord,
+            message: describeStepsWithoutGrantRecord(stepsWithoutGrantRecord),
+        };
+    }
     // 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));
+        : probeResult.grants.filter((grant) => !approvals.grants.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];
+    // Gate the DECLARED grant requirements. These ride the walk snapshot rather
+    // than the flattened `grants`, and the walk never surfaces them, so the
+    // filter above cannot see them -- yet the run path materializes each one into
+    // a real grant row on the run principal, and a wildcard row reaches gates no
+    // walk-derived row can address. They therefore need the operator's decision
+    // on exactly the same terms the advertised grants do. Under `approve-probed`
+    // the probe's surface IS the approved surface, so there is nothing to gate
+    // against and the requirements ride into the approval below.
+    const declaredRequirements = probeResult.grantWalkSnapshot.grantRequirements;
+    const unapprovedGrantRequirements = isApproveProbed(approvals)
+        ? []
+        : declaredRequirements.filter((requirement) => !isApprovedGrantRequirement(approvals, requirement));
+    if (unapprovedGrantRequirements.length > 0) {
+        return {
+            ok: false,
+            reason: "grant_requirements_not_approved",
+            unapprovedGrantRequirements,
+        };
+    }
+    // Freeze: the approved surface is exactly what the workflow advertised (all
+    // of it now operator-approved), pinned to the recomputed hash. Persisting the
+    // hash is the freeze; the approved surface is returned for the deploy
+    // hand-off. The declared requirements join the walk's grant strings in that
+    // surface under both policies, so the record the hand-off and any audit read
+    // describes every kind of authority the freeze will mint.
+    const approvedGrants = [
+        ...probeResult.grants,
+        ...declaredRequirements,
+    ];
     const { definitionId } = await persist({
         assetId,
         approvedWireHash: recomputedWireHash,
@@ -125,7 +303,7 @@ export async function gateAndFreezeProbeResult(args) {
         ok: true,
         definitionId,
         approvedWireHash: recomputedWireHash,
-        approvedGrants: new Set(approvedGrants),
+        approvedSurface: approvalSetFromItems(approvedGrants),
         projection: probeResult.projection,
     };
 }
@@ -187,16 +365,13 @@ export async function installAndApproveWorkflowDefinition(args) {
         });
         assets = [];
     }
-    const { sendProbe } = args.router;
-    if (sendProbe === undefined) {
-        throw new Error("installAndApproveWorkflowDefinition: router does not support sendProbe");
-    }
-    const probeResult = await sendProbe({
+    const probeResult = await args.router.sendProbe({
         source: args.source,
         closure,
         entry: args.entry,
         ...(assets.length > 0 ? { assets } : {}),
     });
+    await args.onProbeResult?.(probeResult);
     const approval = await gateAndFreezeProbeResult({
         assetId: args.assetId,
         probeResult,

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

@@ -26,6 +26,20 @@ 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
@@ -82,6 +96,38 @@ 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
@@ -104,6 +150,15 @@ export declare function parseEventSeq(filename: string): number | null;
  * 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.
@@ -169,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 = {
@@ -310,7 +394,7 @@ export type MarkConsumedArgs = {
      * 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.
+     * an allocation-dispatch row.
      */
     rejection?: {
         code: string;
@@ -361,27 +445,36 @@ export type ReplayProcessingToInboxResult = {
     commitSha: string;
     replayedKeys: string[];
 };
+export type ScanRunsForBootResult = {
+    ownedMessageIds: Set<string>;
+    pendingSealRunIds: 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.
+ * 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.
  *
- * 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 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 readOwnedMessageIds(store: RepoStore, repoId: RepoId): Promise<Set<string>>;
+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>;