@intx/workflow-host 0.2.2 → 0.3.0

package/dist/seams/scheduler.js

@@ -26,17 +26,19 @@
 //
 // The scheduler reads workflow-event blobs at the canonical layout
 // `runs/<runId>/events/<seq>.json` and writes a fresh blob at the
-// next-seq slot for each `TimerFired` commit. The blob envelope
-// carries `{ seq, type, data }` at the top level: `seq` is the
-// integer that also appears in the filename, `type` is the
-// `subscribeKind` discriminator the scheduler narrows on, and `data`
-// carries the timer payload. The workflow-run kind handler's
-// `validatePush` enforces that every event blob's body `seq` matches
-// the filename's seq, so the scheduler mints the next seq inside the
-// `writeTreePreservingPrefix` merge step and writes both into the
-// envelope and the filename.
+// next-seq slot for each `TimerFired` commit. The blob envelope is
+// FLAT -- `{ seq, type, ...eventFields }` -- matching the runtime
+// repo-store's `workflowEventToOnDisk` and the workflow-run kind
+// handler's `EventEnvelope` contract: `seq` is the integer that also
+// appears in the filename, `type` is the `subscribeKind` discriminator
+// the scheduler narrows on, and the timer fields (`timerId`, `fireAt`,
+// ...) sit alongside them, NOT under a nested `data` object. The kind
+// handler's `validatePush` enforces that every event blob's body `seq`
+// matches the filename's seq, so the scheduler mints the next seq
+// inside the `writeTreePreservingPrefix` merge step and writes both
+// into the envelope and the filename.
 import { type } from "arktype";
-import { subscribeKind } from "@intx/hub-sessions/substrate";
+import { requireEventSeq, subscribeKind, WORKFLOW_RUN_EVENTS_DIR, WORKFLOW_RUN_RUNS_PREFIX, } from "@intx/hub-sessions/substrate";
 /**
  * Substrate-shape envelope for the workflow-event blob committed to
  * `runs/<runId>/events/<seq>.json`. The validator covers the two
@@ -49,12 +51,16 @@ import { subscribeKind } from "@intx/hub-sessions/substrate";
 export const TimerEventEnvelope = type({
     seq: "number >= 0",
     type: "'TimerSet' | 'TimerFired'",
-    data: {
-        timerId: "string",
-        "fireAt?": "string",
-        "stepId?": "string | null",
-        "cron?": "string | null",
-    },
+    // FLAT on-disk shape, matching the runtime repo-store's `workflowEventToOnDisk`
+    // ({ seq, type, ...eventFields }) and the substrate's enforced `EventEnvelope`
+    // contract -- NOT a nested `data` object. The scheduler was the lone component
+    // writing/reading a nested `data` envelope; nothing else parsed it, so a
+    // deployed timer never round-tripped until this was aligned.
+    timerId: "string",
+    "fireAt?": "string",
+    "stepId?": "string | null",
+    "cron?": "string | null",
+    "+": "ignore",
 });
 export function createWorkflowHostScheduler(opts) {
     const queues = new Map();
@@ -106,21 +112,21 @@ export function createWorkflowHostScheduler(opts) {
                     break;
                 if (entry.event.type !== "TimerSet")
                     continue;
-                const fireAt = entry.event.data.fireAt;
+                const fireAt = entry.event.fireAt;
                 if (fireAt === undefined) {
-                    throw new Error(`scheduler live ingest: TimerSet in ${String(repoId.id)} run ${entry.runId} timer ${entry.event.data.timerId} missing fireAt`);
+                    throw new Error(`scheduler live ingest: TimerSet in ${String(repoId.id)} run ${entry.runId} timer ${entry.event.timerId} missing fireAt`);
                 }
                 const fireAtMs = Date.parse(fireAt);
                 if (Number.isNaN(fireAtMs)) {
-                    throw new Error(`scheduler live ingest: TimerSet in ${String(repoId.id)} run ${entry.runId} timer ${entry.event.data.timerId} fireAt unparseable: ${fireAt}`);
+                    throw new Error(`scheduler live ingest: TimerSet in ${String(repoId.id)} run ${entry.runId} timer ${entry.event.timerId} fireAt unparseable: ${fireAt}`);
                 }
-                const cron = entry.event.data.cron !== undefined && entry.event.data.cron !== null;
+                const cron = entry.event.cron !== undefined && entry.event.cron !== null;
                 if (cron && fireAtMs < opts.clock().getTime()) {
                     // Same missed-cron-tick spec as recovery: a cron TimerSet
                     // whose fireAt is in the past on arrival is dropped.
                     continue;
                 }
-                enqueue(repoId, entry.runId, entry.event.data.timerId, fireAtMs, cron);
+                enqueue(repoId, entry.runId, entry.event.timerId, fireAtMs, cron);
             }
         })();
         liveSubscriptions.push({ abort, done });
@@ -133,24 +139,24 @@ export function createWorkflowHostScheduler(opts) {
         const unfired = new Map();
         for (const e of events) {
             if (e.envelope.type === "TimerSet") {
-                const fireAt = e.envelope.data.fireAt;
+                const fireAt = e.envelope.fireAt;
                 if (fireAt === undefined) {
-                    throw new Error(`scheduler recovery: TimerSet in ${String(repoId.id)} run ${e.runId} timer ${e.envelope.data.timerId} missing fireAt`);
+                    throw new Error(`scheduler recovery: TimerSet in ${String(repoId.id)} run ${e.runId} timer ${e.envelope.timerId} missing fireAt`);
                 }
                 const fireAtMs = Date.parse(fireAt);
                 if (Number.isNaN(fireAtMs)) {
-                    throw new Error(`scheduler recovery: TimerSet in ${String(repoId.id)} run ${e.runId} timer ${e.envelope.data.timerId} fireAt unparseable: ${fireAt}`);
+                    throw new Error(`scheduler recovery: TimerSet in ${String(repoId.id)} run ${e.runId} timer ${e.envelope.timerId} fireAt unparseable: ${fireAt}`);
                 }
-                const cron = e.envelope.data.cron !== undefined && e.envelope.data.cron !== null;
-                unfired.set(`${e.runId} ${e.envelope.data.timerId}`, {
+                const cron = e.envelope.cron !== undefined && e.envelope.cron !== null;
+                unfired.set(`${e.runId} ${e.envelope.timerId}`, {
                     runId: e.runId,
-                    timerId: e.envelope.data.timerId,
+                    timerId: e.envelope.timerId,
                     fireAtMs,
                     cron,
                 });
             }
             else {
-                unfired.delete(`${e.runId} ${e.envelope.data.timerId}`);
+                unfired.delete(`${e.runId} ${e.envelope.timerId}`);
             }
         }
         const now = opts.clock().getTime();
@@ -224,14 +230,15 @@ export function createWorkflowHostScheduler(opts) {
 }
 /**
  * Read every timer-event blob across every run under the given
- * workflow-run repo. The recovery walk reads blobs from the
- * substrate's on-disk working tree directly via `enumerateEventBlobs`:
- * `subscribeKind` is a diff-shaped iterator over new commits, not a
- * "list everything at HEAD" primitive, so the startup ledger needs a
- * path-aware enumeration of the current ref tip rather than a tail
- * subscription. The substrate writes commit-then-checkout for every
- * ref-update, so the working tree is a coherent snapshot of the
- * current ref tip.
+ * workflow-run repo. Recovery reconstructs its ledger from committed
+ * state, so `enumerateEventBlobs` reads the git object store at the
+ * events ref tip via `openCommittedReads` rather than the materialized
+ * working tree, whose non-atomic post-commit checkout can lag the
+ * committed tree on a contended filesystem and hide an already-committed
+ * `TimerFired`. `subscribeKind` is a diff-shaped iterator over new
+ * commits, not a "list everything at HEAD" primitive, so the startup
+ * ledger needs this path-aware enumeration of the current ref tip rather
+ * than a tail subscription.
  */
 async function readAllEvents(opts, repoId) {
     const entries = [];
@@ -261,53 +268,36 @@ async function readAllEvents(opts, repoId) {
  * has none.
  */
 async function enumerateEventBlobs(opts, repoId) {
-    const dir = opts.repoStore.getRepoDir(repoId);
-    const fs = await import("node:fs/promises");
-    const path = await import("node:path");
-    const runsDir = path.join(dir, "runs");
+    const reads = await opts.repoStore.openCommittedReads(opts.principal, repoId, opts.ref);
+    if (reads === null)
+        return [];
     const out = [];
-    let runEntries;
-    try {
-        runEntries = await fs.readdir(runsDir);
-    }
-    catch (cause) {
-        if (isErrnoNotFound(cause))
-            return out;
-        throw cause;
-    }
-    for (const runId of runEntries) {
-        const eventsDir = path.join(runsDir, runId, "events");
-        let blobs;
-        try {
-            blobs = await fs.readdir(eventsDir);
-        }
-        catch (cause) {
-            if (isErrnoNotFound(cause))
-                continue;
-            throw cause;
-        }
+    const runEntries = await reads.listDir(WORKFLOW_RUN_RUNS_PREFIX);
+    for (const runEntry of runEntries) {
+        if (runEntry.type !== "tree")
+            continue;
+        const runId = runEntry.name;
+        const eventsDir = `${WORKFLOW_RUN_RUNS_PREFIX}/${runId}/${WORKFLOW_RUN_EVENTS_DIR}`;
+        const blobs = await reads.listDir(eventsDir);
         for (const blob of blobs) {
-            if (!/^(0|[1-9][0-9]*)\.json$/.test(blob))
+            if (blob.type !== "blob")
                 continue;
-            const raw = await fs.readFile(path.join(eventsDir, blob), "utf8");
+            // Assert a legal <seq>.json name; an illegal one under the events
+            // prefix is corruption the recovery walk must not silently drop.
+            requireEventSeq(blob.name, `${eventsDir}/${blob.name}`);
+            const raw = await reads.readBlobByOid(blob.oid);
             let parsed;
             try {
-                parsed = JSON.parse(raw);
+                parsed = JSON.parse(new TextDecoder().decode(raw));
             }
             catch (cause) {
-                throw new Error(`scheduler recovery: cannot parse ${String(repoId.id)}/${runId}/events/${blob}: ${String(cause)}`);
+                throw new Error(`scheduler recovery: cannot parse ${String(repoId.id)}/${runId}/${WORKFLOW_RUN_EVENTS_DIR}/${blob.name}: ${String(cause)}`);
             }
             out.push({ runId, payload: parsed });
         }
     }
     return out;
 }
-function isErrnoNotFound(cause) {
-    if (cause === null || typeof cause !== "object")
-        return false;
-    const code = cause.code;
-    return code === "ENOENT";
-}
 /**
  * Commit a `TimerFired` event blob to the workflow-run repo. The
  * commit goes through `writeTreePreservingPrefix` so concurrent
@@ -321,7 +311,7 @@ async function commitTimerFired(opts, runId, timerId) {
     if (owningRepoId === undefined) {
         throw new Error(`scheduler commit: cannot find deployment owning run ${runId}`);
     }
-    const prefix = `runs/${runId}/events/`;
+    const prefix = `${WORKFLOW_RUN_RUNS_PREFIX}/${runId}/${WORKFLOW_RUN_EVENTS_DIR}/`;
     await opts.repoStore.writeTreePreservingPrefix(opts.principal, owningRepoId, opts.ref, {
         preservePrefix: prefix,
         merge: async (existing) => {
@@ -329,13 +319,7 @@ async function commitTimerFired(opts, runId, timerId) {
             let alreadyFired = false;
             for (const [filepath, contents] of existing) {
                 const name = filepath.slice(prefix.length);
-                const match = /^(0|[1-9][0-9]*)\.json$/.exec(name);
-                if (match === null)
-                    continue;
-                const seqStr = match[1];
-                if (seqStr === undefined)
-                    continue;
-                const seq = Number.parseInt(seqStr, 10);
+                const seq = requireEventSeq(name, `${prefix}${name}`);
                 if (seq > maxSeq)
                     maxSeq = seq;
                 try {
@@ -360,7 +344,7 @@ async function commitTimerFired(opts, runId, timerId) {
             out[`${prefix}${String(nextSeq)}.json`] = JSON.stringify({
                 seq: nextSeq,
                 type: "TimerFired",
-                data: { timerId },
+                timerId,
             });
             return out;
         },
@@ -373,25 +357,22 @@ function isMatchingTimerFired(parsed, timerId) {
     const obj = parsed;
     if (obj.type !== "TimerFired")
         return false;
-    if (obj.data === undefined)
-        return false;
-    return obj.data.timerId === timerId;
+    return obj.timerId === timerId;
 }
 async function findOwningDeployment(opts, runId) {
     const repoIds = await opts.listActiveDeployments();
-    const fs = await import("node:fs/promises");
-    const path = await import("node:path");
     for (const repoId of repoIds) {
-        const dir = opts.repoStore.getRepoDir(repoId);
-        try {
-            await fs.access(path.join(dir, "runs", runId, "events"));
+        const reads = await opts.repoStore.openCommittedReads(opts.principal, repoId, opts.ref);
+        if (reads === null)
+            continue;
+        // The committed events subtree exists only when it holds at least
+        // one blob (git does not track empty trees), so a non-empty listing
+        // is exactly "this deployment owns the run". Reading committed state
+        // rather than the working tree keeps attribution correct when the
+        // checkout lags the object store.
+        const events = await reads.listDir(`${WORKFLOW_RUN_RUNS_PREFIX}/${runId}/${WORKFLOW_RUN_EVENTS_DIR}`);
+        if (events.length > 0)
             return repoId;
-        }
-        catch (cause) {
-            if (isErrnoNotFound(cause))
-                continue;
-            throw cause;
-        }
     }
     return undefined;
 }

package/dist/supervisor/cancel-signing.d.ts

@@ -16,8 +16,8 @@ export type CommitCancelRequestedOpts = {
     repoId: RepoId;
     /** Events ref the workflow-run repo writes to. */
     ref: string;
-    /** Deployment id used to construct the supervisor principal. */
-    deploymentId: string;
+    /** Anchor run id used to construct the supervisor principal. */
+    anchorRunId: string;
     /** Run id whose event log receives the CancelRequested entry. */
     runId: string;
     /** Cancellation origin from the Q3 map. */

package/dist/supervisor/cancel-signing.js

@@ -76,7 +76,7 @@ export async function commitCancelRequested(opts) {
     const prefix = `${RUNS_PREFIX}/${opts.runId}/${EVENTS_DIR}/`;
     const principal = {
         kind: SUPERVISOR_PRINCIPAL_KIND,
-        deploymentId: opts.deploymentId,
+        anchorRunId: opts.anchorRunId,
     };
     let resolved = null;
     const { commitSha } = await opts.substrate.writeTreePreservingPrefix(principal, opts.repoId, opts.ref, {

package/dist/supervisor/credentials.d.ts

@@ -29,24 +29,24 @@ export type CredentialsSnapshot = {
 };
 /**
  * Caller-supplied derivation of the per-step mail address from the
- * deployment id and step id. The supervisor cannot encode the
+ * run id and step id. The supervisor cannot encode the
  * deployment-domain inside library code; the wiring module supplies
  * the strategy the host owns.
  */
 export type DeriveStepAddress = (args: {
-    deploymentId: string;
+    runId: string;
     stepId: string;
 }) => string;
 /**
  * Caller-supplied override of the per-step `agent-state` repo identity
  * the supervisor reads grants from. Defaults to the
- * `<deploymentId>-<stepId>` convention (`defaultStepRepoId`); the
+ * `<runId>-<stepId>` convention (`defaultStepRepoId`); the
  * single-step launched-agent deploy supplies a derivation that returns
  * the legacy agent-state repo so the child reads grants from the same
  * repo the legacy agent identity already keys.
  */
 export type DeriveStepRepoId = (args: {
-    deploymentId: string;
+    runId: string;
     stepId: string;
 }) => RepoId;
 export type AssembleCredentialsSnapshotOpts = {
@@ -60,27 +60,27 @@ export type AssembleCredentialsSnapshotOpts = {
      * the order the workflow asset declared.
      */
     stepOrder: readonly string[];
-    /** Deployment id used in agent-state repo identity and address derivation. */
-    deploymentId: string;
+    /** Anchor run id used in agent-state repo identity and address derivation. */
+    anchorRunId: string;
     /** Per-step mail-address derivation callback. */
     deriveStepAddress: DeriveStepAddress;
     /**
      * Optional override for the `agent-state` repo's id. Callers that
-     * follow the documented convention (`<deploymentId>-<stepId>`) can
+     * follow the documented convention (`<runId>-<stepId>`) can
      * omit this; tests and bespoke layouts can supply their own.
      */
     deriveStepRepoId?: DeriveStepRepoId;
 };
 /**
- * Default mapping from `(deploymentId, stepId)` to the agent-state
- * repo id: `<deploymentId>-<stepId>`, isolating each step's grants in
+ * Default mapping from `(runId, stepId)` to the agent-state
+ * repo id: `<runId>-<stepId>`, isolating each step's grants in
  * its own repo. Applied to a one-step `stepOrder` it yields a single
  * such repo. The single-step launched-agent deploy overrides this
  * default (see `DeriveStepRepoId`) to reuse the legacy agent-state
  * repo.
  */
 export declare function defaultStepRepoId(args: {
-    deploymentId: string;
+    runId: string;
     stepId: string;
 }): RepoId;
 /**
@@ -99,3 +99,4 @@ export declare function hashGrants(grants: readonly unknown[]): Promise<string>;
  * arrives after a fresher one.
  */
 export declare function assembleCredentialsSnapshot(opts: AssembleCredentialsSnapshotOpts): Promise<CredentialsSnapshot>;
+export declare function isErrnoNotFound(cause: unknown): boolean;

package/dist/supervisor/credentials.js

@@ -20,7 +20,7 @@
 // substrate's git layout.
 //
 // Per-step address derivation (Q6.4 discovery decision):
-//   - Multi-step deployments use `<deploymentId>-<stepId>@<domain>`.
+//   - Multi-step deployments use `<runId>-<stepId>@<domain>`.
 //   - Trivial (single-step) deployments use the deployment's own
 //     mail address as the sole step's address.
 // The derivation is supplied by the caller as a `deriveStepAddress`
@@ -51,8 +51,8 @@ const StepGrantsFile = type({
     grants: "unknown[]",
 }).onUndeclaredKey("ignore");
 /**
- * Default mapping from `(deploymentId, stepId)` to the agent-state
- * repo id: `<deploymentId>-<stepId>`, isolating each step's grants in
+ * Default mapping from `(runId, stepId)` to the agent-state
+ * repo id: `<runId>-<stepId>`, isolating each step's grants in
  * its own repo. Applied to a one-step `stepOrder` it yields a single
  * such repo. The single-step launched-agent deploy overrides this
  * default (see `DeriveStepRepoId`) to reuse the legacy agent-state
@@ -61,7 +61,7 @@ const StepGrantsFile = type({
 export function defaultStepRepoId(args) {
     return {
         kind: "agent-state",
-        id: `${args.deploymentId}-${args.stepId}`,
+        id: `${args.runId}-${args.stepId}`,
     };
 }
 /**
@@ -128,12 +128,12 @@ export async function assembleCredentialsSnapshot(opts) {
     const steps = [];
     for (const stepId of opts.stepOrder) {
         const repoId = deriveRepoId({
-            deploymentId: opts.deploymentId,
+            runId: opts.anchorRunId,
             stepId,
         });
         const grants = await readStepGrants(opts, repoId);
         const address = opts.deriveStepAddress({
-            deploymentId: opts.deploymentId,
+            runId: opts.anchorRunId,
             stepId,
         });
         steps.push({
@@ -145,7 +145,7 @@ export async function assembleCredentialsSnapshot(opts) {
     }
     return { steps };
 }
-function isErrnoNotFound(cause) {
+export function isErrnoNotFound(cause) {
     if (cause === null || typeof cause !== "object")
         return false;
     const code = cause.code;

package/dist/supervisor/dispatch-attribution.js

@@ -21,7 +21,7 @@
 import { spawnSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
-import { countLooseObjects, gitBytes } from "@intx/storage-isogit";
+import { countLooseObjects, gitBytes } from "@intx/storage-isogit/node";
 const RUNS_DIR = "runs";
 const ADDRESSES_DIR = "addresses";
 const CONSUMED_DIR = "consumed";

package/dist/supervisor/drain-timeout.d.ts

@@ -16,8 +16,8 @@ export type DrainTimeoutOpts = {
     repoId: RepoId;
     /** Workflow-run repo ref the supervisor commits events to. */
     ref: string;
-    /** Deployment id baked into the supervisor's signing principal. */
-    deploymentId: string;
+    /** Anchor run id baked into the supervisor's signing principal. */
+    anchorRunId: string;
     /** Run id the drain is being escalated against. */
     runId: string;
     /**

package/dist/supervisor/drain-timeout.js

@@ -145,7 +145,7 @@ export function createDrainTimeoutAccumulator(opts) {
             substrate: opts.substrate,
             repoId: opts.repoId,
             ref: opts.ref,
-            deploymentId: opts.deploymentId,
+            anchorRunId: opts.anchorRunId,
             runId: opts.runId,
             origin,
             reason,

package/dist/supervisor/index.d.ts

@@ -1,7 +1,7 @@
-export { createWorkflowSupervisor, DEFAULT_TERMINAL_WRITE_WATCHDOG_MS, type CancelCommitInfo, type CancelRequestOpts, type DeliverSignalOpts, type DeliverSourcesOpts, type DrainOpts, type RecycleOpts, type SpawnOpts, type SpawnResult, type WorkflowSupervisor, } from "./supervisor.js";
-export { assembleCredentialsSnapshot, defaultStepRepoId, hashGrants, STEP_GRANTS_PATH, STEP_GRANTS_REF, type AssembleCredentialsSnapshotOpts, type CredentialsSnapshot, type CredentialsSnapshotStep, type DeriveStepAddress, type DeriveStepRepoId, } from "./credentials.js";
+export { createWorkflowSupervisor, type CancelCommitInfo, type CancelRequestOpts, type DeliverCredentialsOpts, type DeliverSignalOpts, type DeliverSourcesOpts, type DrainOpts, type RecycleOpts, type SpawnOpts, type SpawnResult, type WorkflowSupervisor, } from "./supervisor.js";
+export { assembleCredentialsSnapshot, isErrnoNotFound, defaultStepRepoId, hashGrants, STEP_GRANTS_PATH, STEP_GRANTS_REF, type AssembleCredentialsSnapshotOpts, type CredentialsSnapshot, type CredentialsSnapshotStep, type DeriveStepAddress, type DeriveStepRepoId, } from "./credentials.js";
 export { commitCancelRequested, SUPERVISOR_PRINCIPAL_KIND, type CommitCancelRequestedOpts, type CommitCancelRequestedResult, } from "./cancel-signing.js";
 export { createDrainTimeoutAccumulator, DEFAULT_DRAIN_TIMEOUT_MS, type DrainTimeoutAccumulator, type DrainTimeoutAccumulatorFactory, type DrainTimeoutOpts, } from "./drain-timeout.js";
 export { DEFAULT_KILL_TIMEOUT_MS } from "./child-termination.js";
 export { createRecyclePolicy, triggerRecycle, DEFAULT_POLICY_INTERVAL_MS, MAX_BUFFERED_MAIL, type ChildWiring, type RecycleAttempt, type RecycleContext, type RecycleOrigin, type RecyclePolicy, type RecyclePolicyBounds, type RecyclePolicyOpts, type TriggerRecycleOpts, } from "./recycle.js";
-export type { DeriveMailAuditRef, DispatchStructuralCounters, DispatchSubstrateLeg, DispatchTimingMark, InboxPrimitives, MailAuditRef, MailBusBindings, PrincipalSigner, SignedPayload, SubprocessHandle, SubprocessSpawner, TerminalEventSource, TerminalRunEvent, WorkflowSupervisorBindings, WorkflowSupervisorPrincipalKind, } from "./types.js";
+export type { DeriveMailAuditRef, DispatchStructuralCounters, DispatchSubstrateLeg, DispatchTimingMark, InboxPrimitives, MailAuditRef, MailBusBindings, PrincipalSigner, SignedPayload, SubprocessHandle, SubprocessSpawner, SuspensionRegistration, TerminalEventSource, TerminalRunEvent, WorkflowSupervisorBindings, WorkflowSupervisorPrincipalKind, } from "./types.js";

package/dist/supervisor/index.js

@@ -1,5 +1,5 @@
-export { createWorkflowSupervisor, DEFAULT_TERMINAL_WRITE_WATCHDOG_MS, } from "./supervisor.js";
-export { assembleCredentialsSnapshot, defaultStepRepoId, hashGrants, STEP_GRANTS_PATH, STEP_GRANTS_REF, } from "./credentials.js";
+export { createWorkflowSupervisor, } from "./supervisor.js";
+export { assembleCredentialsSnapshot, isErrnoNotFound, defaultStepRepoId, hashGrants, STEP_GRANTS_PATH, STEP_GRANTS_REF, } from "./credentials.js";
 export { commitCancelRequested, SUPERVISOR_PRINCIPAL_KIND, } from "./cancel-signing.js";
 export { createDrainTimeoutAccumulator, DEFAULT_DRAIN_TIMEOUT_MS, } from "./drain-timeout.js";
 export { DEFAULT_KILL_TIMEOUT_MS } from "./child-termination.js";

package/dist/supervisor/recycle.d.ts

@@ -18,9 +18,12 @@ export declare const DEFAULT_POLICY_INTERVAL_MS = 60000;
 /**
  * Origin tag the recycle path stamps onto its log messages so an
  * operator scanning logs can distinguish operator-initiated,
- * policy-initiated, and self-initiated recycles at a glance.
+ * policy-initiated, self-initiated, and crash-respawn origins at a
+ * glance. The `crash` origin drives the same respawn sequence after an
+ * unexpected child exit; see the six-step header note about steps 1-2
+ * degrading to no-ops for it.
  */
-export type RecycleOrigin = "operator" | "policy" | "self";
+export type RecycleOrigin = "operator" | "policy" | "self" | "crash";
 export interface RecycleAttempt {
     /** Origin the recycle was initiated from. */
     readonly origin: RecycleOrigin;

package/dist/supervisor/recycle.js

@@ -4,8 +4,9 @@
 //
 // Recycle is the supervisor's "same deploy tree, fresh process" path.
 // It tears the existing workflow-process child down and stands a new
-// one up against the SAME deploy tree (same `workflow.json`, same
-// per-step credential repos). It is STRICTLY ORTHOGONAL TO REDEPLOY:
+// one up against the SAME deploy tree (same materialized source
+// closure, same per-step credential repos). It is STRICTLY ORTHOGONAL
+// TO REDEPLOY:
 //
 //   - Recycle  = same deploy tree, fresh process.
 //   - Redeploy = new deploy tree.
@@ -20,6 +21,15 @@
 //
 // Six-step sequence (locked):
 //
+// The `drain` step and the `SubprocessHandle` handed in as `current` are
+// caller-parameterized. For the operator/policy/self recycle origins the
+// child is live: `drain` sends the real drain control mail and `kill`
+// terminates a running process. For the `crash` origin the child has
+// already exited unexpectedly, so the caller supplies a no-op `drain`
+// (there is nothing to drain) and the `kill` in step 2 lands on an
+// already-dead handle as a cheap no-op. Steps 3-6 are identical for every
+// origin.
+//
 //   1. `drain` -- send the existing drain control mail. Wait for
 //      in-flight runs to drain per each step's `drainBehavior`.
 //      `drainTimeout` escalation applies normally; the drain-timeout
@@ -153,8 +163,8 @@ export async function triggerRecycle(ctx, opts) {
     // Step 3: respawn. Fresh channelId, fresh HMAC key, fresh Ed25519
     // IPC keypair. Per-step credentials are re-read so a grants update
     // that landed since the original spawn is reflected in the new
-    // child's snapshot. The deploy tree (`workflow.json`, agents,
-    // workflow-asset repo) is UNCHANGED.
+    // child's snapshot. The deploy tree (the materialized source closure,
+    // the workflow-asset repo, the agent-state repos) is UNCHANGED.
     const channelId = generateChannelId();
     const hmacKey = generateHmacKey();
     const ipcKeypair = await (ctx.bindings.ipcKeyPairFactory ?? generateKeyPair)();
@@ -164,7 +174,7 @@ export async function triggerRecycle(ctx, opts) {
         channelId,
         hmacKey,
         hostPublicKey: ipcKeypair.publicKey,
-        deploymentId: ctx.bindings.deploymentId,
+        anchorRunId: ctx.bindings.anchorRunId,
         deploymentMailAddress: ctx.bindings.deploymentMailAddress,
         stepCount: ctx.bindings.stepCount,
         definitionHash: ctx.definitionHash,
@@ -210,7 +220,8 @@ export async function triggerRecycle(ctx, opts) {
     // the previous child's lifetime is picked up here -- the recycle
     // doubles as the supervisor's grant-refresh path. The deploy tree
     // is not consulted; this read is against the `agent-state` repos
-    // alone, whose contents are independent of `workflow.json`.
+    // alone, whose contents are independent of the materialized source
+    // closure.
     //
     // This is a substrate read that can reject -- a grants file that
     // became malformed is precisely the recycle's grant-refresh path. The
@@ -227,7 +238,7 @@ export async function triggerRecycle(ctx, opts) {
             repoStore: ctx.bindings.repoStore,
             principal: ctx.bindings.readPrincipal,
             stepOrder: ctx.stepOrder,
-            deploymentId: ctx.bindings.deploymentId,
+            anchorRunId: ctx.bindings.anchorRunId,
             deriveStepAddress: ctx.bindings.deriveStepAddress,
             ...(ctx.bindings.deriveStepRepoId !== undefined
                 ? { deriveStepRepoId: ctx.bindings.deriveStepRepoId }

package/dist/supervisor/run-event-compaction.d.ts

@@ -6,8 +6,8 @@ export type CompactRunEventsOpts = {
     repoId: RepoId;
     /** Events ref the workflow-run repo writes to. */
     ref: string;
-    /** Deployment id used to construct the supervisor principal. */
-    deploymentId: string;
+    /** Anchor run id used to construct the supervisor principal. */
+    anchorRunId: string;
     /** Run to seal. */
     runId: string;
 };
@@ -19,9 +19,9 @@ export type CompactRunEventsOpts = {
  *
  * Idempotent and terminal-only: a run already sealed (no `events/` subtree)
  * or one whose latest event is not terminal is left untouched, so the call
- * is safe to repeat. The live caller fires it once per run, right after the
- * run terminates; a bounded recovery sweep that would re-fire it to seal a
- * run whose fold a crash interrupted is not yet implemented.
+ * is safe to repeat. The live caller invokes it once per run, right after the
+ * run terminates; a bounded recovery sweep that would retry the fold for a run
+ * whose compaction a crash interrupted is not yet implemented.
  *
  * The combined file is the verbatim byte concatenation of the per-event
  * blobs in seq order (`encodeCombinedEventLog`), the exact shape the

package/dist/supervisor/run-event-compaction.js

@@ -5,7 +5,7 @@
 // and drops the per-event files. This shrinks the workflow-run repo's
 // file count -- and every per-commit cost that scales with it --
 // without losing any event. The fold writes under the substrate's
-// per-repo lock as the `supervisor` principal, whose `deploymentId`
+// per-repo lock as the `supervisor` principal, whose `anchorRunId`
 // the workflow-run kind handler checks against `repoId.id`.
 import { WORKFLOW_RUN_EVENTS_FILE, encodeCombinedEventLog, } from "@intx/hub-sessions/substrate";
 import { SUPERVISOR_PRINCIPAL_KIND } from "./cancel-signing.js";
@@ -25,9 +25,9 @@ const TERMINAL_EVENT_TYPES = new Set([
  *
  * Idempotent and terminal-only: a run already sealed (no `events/` subtree)
  * or one whose latest event is not terminal is left untouched, so the call
- * is safe to repeat. The live caller fires it once per run, right after the
- * run terminates; a bounded recovery sweep that would re-fire it to seal a
- * run whose fold a crash interrupted is not yet implemented.
+ * is safe to repeat. The live caller invokes it once per run, right after the
+ * run terminates; a bounded recovery sweep that would retry the fold for a run
+ * whose compaction a crash interrupted is not yet implemented.
  *
  * The combined file is the verbatim byte concatenation of the per-event
  * blobs in seq order (`encodeCombinedEventLog`), the exact shape the
@@ -81,7 +81,7 @@ export async function compactRunEvents(opts) {
     const combinedPath = `${RUNS_PREFIX}/${opts.runId}/${WORKFLOW_RUN_EVENTS_FILE}`;
     const principal = {
         kind: SUPERVISOR_PRINCIPAL_KIND,
-        deploymentId: opts.deploymentId,
+        anchorRunId: opts.anchorRunId,
     };
     let sealed = false;
     await opts.substrate.writeTreePreservingPrefix(principal, opts.repoId, opts.ref, {

package/dist/supervisor/spawn-env.d.ts

@@ -19,8 +19,8 @@ export interface ChildSpawnEnvParts {
     hmacKey: Uint8Array;
     /** Supervisor's Ed25519 public key for this spawn's control channel. */
     hostPublicKey: Uint8Array;
-    /** Deployment identity the supervisor manages. */
-    deploymentId: string;
+    /** Anchor run id the supervisor manages. */
+    anchorRunId: string;
     /** Mail address the deployment registered on the bus. */
     deploymentMailAddress: string;
     /** Step count of the deployed workflow (`stepOrder.length`). */

package/dist/supervisor/spawn-env.js

@@ -20,7 +20,7 @@ export function buildChildSpawnEnv(parts) {
         IPC_CHANNEL_ID: parts.channelId,
         IPC_HMAC_KEY: hexEncode(parts.hmacKey),
         HOST_PUBKEY: hexEncode(parts.hostPublicKey),
-        DEPLOYMENT_ID: parts.deploymentId,
+        DEPLOYMENT_ID: parts.anchorRunId,
         DEFINITION_HASH: parts.definitionHash,
         MAILBOX_ADDRESS: parts.deploymentMailAddress,
         STEP_COUNT: String(parts.stepCount),