@intx/workflow-host 0.2.2

package/dist/supervisor/credentials.d.ts

@@ -0,0 +1,101 @@
+import type { Principal, RepoId, RepoStore } from "@intx/hub-sessions/substrate";
+/**
+ * Path inside each step's `agent-state` repo that carries the step's
+ * grants. The agent-state kind handler accepts state writes under the
+ * `state/` subtree; the grants snapshot rides at
+ * `state/grants.json` as a single canonical JSON document.
+ */
+export declare const STEP_GRANTS_PATH = "state/grants.json";
+/**
+ * Ref the supervisor reads each step's grants from. The agent-state
+ * kind handler defines the deploy ref under `refs/heads/deploy`; the
+ * state-bearing refs the sidecar writes to use the default
+ * `refs/heads/main` convention.
+ */
+export declare const STEP_GRANTS_REF = "refs/heads/main";
+export type CredentialsSnapshotStep = {
+    /** Workflow step id from `WorkflowDefinition.stepOrder`. */
+    stepId: string;
+    /** Mail address the step's agent presents to the bus. */
+    address: string;
+    /** Opaque `grants` array as committed in the step's repo. */
+    grants: readonly unknown[];
+    /** sha256 hex over the canonical JSON of `grants`. */
+    contentHash: string;
+};
+export type CredentialsSnapshot = {
+    /** Step-id keyed entries in `stepOrder` traversal order. */
+    steps: readonly CredentialsSnapshotStep[];
+};
+/**
+ * Caller-supplied derivation of the per-step mail address from the
+ * deployment 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;
+    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
+ * 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;
+    stepId: string;
+}) => RepoId;
+export type AssembleCredentialsSnapshotOpts = {
+    /** Substrate handle the supervisor reads from. */
+    repoStore: RepoStore;
+    /** Principal presented for each step's read. */
+    principal: Principal;
+    /**
+     * Step ids in the deployment's `stepOrder`. The trivial workflow
+     * passes a single entry; multi-step deployments pass every step in
+     * the order the workflow asset declared.
+     */
+    stepOrder: readonly string[];
+    /** Deployment id used in agent-state repo identity and address derivation. */
+    deploymentId: 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
+     * 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
+ * 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;
+    stepId: string;
+}): RepoId;
+/**
+ * Compute the per-step content hash used to pin a credentialsSnapshot
+ * push to a specific grants payload. Stable across processes because
+ * the JSON.stringify pass produces the same byte string for a given
+ * grants array.
+ */
+export declare function hashGrants(grants: readonly unknown[]): Promise<string>;
+/**
+ * Assemble the per-deployment `credentialsSnapshot` from each step's
+ * `agent-state` repo. The supervisor invokes this at spawn time and
+ * again on every `grants-updated` mail. The result rides the
+ * control IPC as a single payload; the child pins each step's grants
+ * to the supplied hash so it can ignore an out-of-order push that
+ * arrives after a fresher one.
+ */
+export declare function assembleCredentialsSnapshot(opts: AssembleCredentialsSnapshotOpts): Promise<CredentialsSnapshot>;

package/dist/supervisor/credentials.js

@@ -0,0 +1,153 @@
+// Per-step `credentialsSnapshot` assembly.
+//
+// At spawn time, the supervisor reads each workflow step's grants out
+// of its `agent-state` repo and forwards the resulting per-step
+// snapshot to the workflow-process over the control IPC. The snapshot
+// never lands on disk in the child's view and is never placed in
+// spawn-time env -- the env carries only the IPC trust anchors. The
+// child receives credentials over the authenticated control channel
+// once both halves are connected.
+//
+// Each step's snapshot is pinned to a content hash so the child can
+// detect a stale snapshot (e.g. one that arrived after a `grants-
+// updated` push the child already processed). The hash is the
+// sha256 of the canonicalized JSON serialization of the snapshot's
+// per-step `grants` array -- not the git tree SHA of the underlying
+// `agent-state` repo's `grants` ref. The substrate's tree SHA is
+// implementation-coupled to the path of the file inside the repo;
+// hashing the canonical JSON gives a stable identifier the child can
+// compare across pushes without taking a dependency on the
+// substrate's git layout.
+//
+// Per-step address derivation (Q6.4 discovery decision):
+//   - Multi-step deployments use `<deploymentId>-<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`
+// callback so the supervisor doesn't have to encode the deployment-
+// domain into the workflow-host package.
+import { type } from "arktype";
+import { hexEncode } from "@intx/types";
+/**
+ * Path inside each step's `agent-state` repo that carries the step's
+ * grants. The agent-state kind handler accepts state writes under the
+ * `state/` subtree; the grants snapshot rides at
+ * `state/grants.json` as a single canonical JSON document.
+ */
+export const STEP_GRANTS_PATH = "state/grants.json";
+/**
+ * Ref the supervisor reads each step's grants from. The agent-state
+ * kind handler defines the deploy ref under `refs/heads/deploy`; the
+ * state-bearing refs the sidecar writes to use the default
+ * `refs/heads/main` convention.
+ */
+export const STEP_GRANTS_REF = "refs/heads/main";
+/**
+ * Shape of the per-step grants file. The supervisor surfaces this
+ * untyped to the child -- the child's authorize layer narrows the
+ * inner `grants` entries against its own grant-rule validator.
+ */
+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
+ * 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 function defaultStepRepoId(args) {
+    return {
+        kind: "agent-state",
+        id: `${args.deploymentId}-${args.stepId}`,
+    };
+}
+/**
+ * Read one step's grants file from disk via the substrate's working-
+ * tree directory. The substrate documents `getRepoDir` as a pure path
+ * computation -- the sibling production adapters (`repo-store.ts`,
+ * `spawn-child.ts`) use the same working-tree-read pattern when they
+ * need synchronous access to a ref's tip without round-tripping
+ * through the git object database.
+ *
+ * A missing grants file is treated as "no grants" (empty array) so
+ * a step whose repo carries no grants file does not crash; a
+ * malformed file does crash, because the file's presence implies
+ * the deploy orchestrator intended a snapshot and a structural
+ * failure is a programming bug at the boundary.
+ */
+async function readStepGrants(opts, repoId) {
+    const fs = await import("node:fs/promises");
+    const path = await import("node:path");
+    const dir = opts.repoStore.getRepoDir(repoId);
+    const filePath = path.join(dir, STEP_GRANTS_PATH);
+    let raw;
+    try {
+        raw = await fs.readFile(filePath, "utf8");
+    }
+    catch (cause) {
+        if (isErrnoNotFound(cause))
+            return [];
+        throw cause;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (cause) {
+        throw new Error(`supervisor credentialsSnapshot: ${repoId.kind}/${repoId.id}:${STEP_GRANTS_PATH} is not valid JSON`, { cause });
+    }
+    const validated = StepGrantsFile(parsed);
+    if (validated instanceof type.errors) {
+        throw new Error(`supervisor credentialsSnapshot: ${repoId.kind}/${repoId.id}:${STEP_GRANTS_PATH} failed validation: ${validated.summary}`);
+    }
+    return validated.grants;
+}
+/**
+ * Compute the per-step content hash used to pin a credentialsSnapshot
+ * push to a specific grants payload. Stable across processes because
+ * the JSON.stringify pass produces the same byte string for a given
+ * grants array.
+ */
+export async function hashGrants(grants) {
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(JSON.stringify(grants)));
+    return hexEncode(new Uint8Array(digest));
+}
+/**
+ * Assemble the per-deployment `credentialsSnapshot` from each step's
+ * `agent-state` repo. The supervisor invokes this at spawn time and
+ * again on every `grants-updated` mail. The result rides the
+ * control IPC as a single payload; the child pins each step's grants
+ * to the supplied hash so it can ignore an out-of-order push that
+ * arrives after a fresher one.
+ */
+export async function assembleCredentialsSnapshot(opts) {
+    const deriveRepoId = opts.deriveStepRepoId ?? defaultStepRepoId;
+    const steps = [];
+    for (const stepId of opts.stepOrder) {
+        const repoId = deriveRepoId({
+            deploymentId: opts.deploymentId,
+            stepId,
+        });
+        const grants = await readStepGrants(opts, repoId);
+        const address = opts.deriveStepAddress({
+            deploymentId: opts.deploymentId,
+            stepId,
+        });
+        steps.push({
+            stepId,
+            address,
+            grants,
+            contentHash: await hashGrants(grants),
+        });
+    }
+    return { steps };
+}
+function isErrnoNotFound(cause) {
+    if (cause === null || typeof cause !== "object")
+        return false;
+    const code = cause.code;
+    return code === "ENOENT";
+}

package/dist/supervisor/dispatch-attribution.d.ts

@@ -0,0 +1,37 @@
+import type { DispatchStructuralCounters } from "./types.js";
+/**
+ * Sample the four structural counters against the workflow-run repo's
+ * on-disk working tree. Cheap filesystem reads; invoked only when the
+ * D2 observer is wired, at each leg's `"end"` mark, so the per-leg slope
+ * can be correlated with the grower that explains it.
+ */
+export declare function sampleStructuralCounters(repoDir: string): DispatchStructuralCounters;
+/**
+ * Measurement-only forced-repack toggle for the §10c A/B. When the boot
+ * edge supplies a non-zero `everyMessages`, the supervisor invokes
+ * `maybeRepack` once per dispatched message (after `markConsumed`, still
+ * under the single-writer discipline -- the dispatch loop processes one
+ * message at a time and no concurrent commit is in flight at that point),
+ * and every `everyMessages`-th message forces a `git gc`/repack of the
+ * workflow-run repo. If forcing a repack flattens the per-leg slope, the
+ * cost is loose-object/pack growth (cheap pack/gc fix); if it does not,
+ * the cost is the per-commit root-tree rewrite scaling with `runs/` +
+ * `consumed/` fan-out (run-model change). Absent toggle => never repacks.
+ */
+export type RepackToggle = {
+    everyMessages: number;
+};
+/**
+ * Force a synchronous `git gc` of the repo at `repoDir`. Synchronous
+ * (`spawnSync`) so the supervisor's single-writer invariant is trivially
+ * preserved: the dispatch loop is the sole caller and blocks here, so no
+ * `writeTreePreservingPrefix` commit can interleave with the repack.
+ * Returns the wall-clock duration in ms and whether the gc succeeded;
+ * a non-zero exit is surfaced (not swallowed) so a broken A/B run does
+ * not silently report "repack had no effect".
+ */
+export declare function forceRepack(repoDir: string): {
+    ok: boolean;
+    durationMs: number;
+    detail: string;
+};

package/dist/supervisor/dispatch-attribution.js

@@ -0,0 +1,114 @@
+// D2 per-leg substrate-attribution instrumentation (measurement-only).
+//
+// This module is the off-by-default observability + A/B surface the D2
+// latency re-attribution drives. NONE of it runs in production: the
+// supervisor only reaches these helpers when a `onDispatchTiming`
+// observer is wired (the same env-gated seam the 4.7 latency gate added)
+// and only consults the repack toggle when the boot edge supplies a
+// non-zero repack interval. With the observer unwired and the toggle
+// absent, the supervisor samples no clock, reads no directory, and forks
+// no `git gc` -- the dispatch path is byte-for-byte unchanged.
+//
+// The counters are deliberately filesystem-level reads against the
+// workflow-run repo's on-disk working tree (resolved via
+// `RepoStore.getRepoDir`, a pure path computation), NOT reaches into
+// isogit internals. That keeps the attribution honest about what it can
+// observe cheaply and avoids coupling the measurement to the storage
+// layer's private object model. `runs/` and `addresses/<addr>/consumed/`
+// fan-out is exactly the never-pruned tree growth the design (§9)
+// implicates; loose-object count + `.git` byte size are the pack-growth
+// proxies the §10c repack A/B discriminates against.
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { countLooseObjects, gitBytes } from "@intx/storage-isogit";
+const RUNS_DIR = "runs";
+const ADDRESSES_DIR = "addresses";
+const CONSUMED_DIR = "consumed";
+/**
+ * Count the immediate child entries of `dir`. Returns 0 when the
+ * directory does not exist yet (the repo's first commit has not created
+ * the subtree) -- absence is a real "fan-out is zero", not an error to
+ * surface, because the sampler runs on every leg including ones that fire
+ * before the subtree exists.
+ */
+function countEntries(dir) {
+    let entries;
+    try {
+        entries = fs.readdirSync(dir);
+    }
+    catch (cause) {
+        if (cause instanceof Error &&
+            cause.code === "ENOENT") {
+            return 0;
+        }
+        throw cause;
+    }
+    return entries.length;
+}
+/**
+ * Total entries under every `addresses/<segment>/consumed/`. The address
+ * segment is `urlEncoded(address)` on disk; rather than re-deriving the
+ * exact encoding (and risking drift from the kind handler), enumerate the
+ * address segments present and sum each one's `consumed/` fan-out. For a
+ * single warm deployment there is exactly one segment, but the sum is
+ * correct for any number.
+ */
+function countConsumed(repoDir) {
+    const addressesDir = path.join(repoDir, ADDRESSES_DIR);
+    let segments;
+    try {
+        segments = fs.readdirSync(addressesDir);
+    }
+    catch (cause) {
+        if (cause instanceof Error &&
+            cause.code === "ENOENT") {
+            return 0;
+        }
+        throw cause;
+    }
+    let total = 0;
+    for (const segment of segments) {
+        total += countEntries(path.join(addressesDir, segment, CONSUMED_DIR));
+    }
+    return total;
+}
+/**
+ * Sample the four structural counters against the workflow-run repo's
+ * on-disk working tree. Cheap filesystem reads; invoked only when the
+ * D2 observer is wired, at each leg's `"end"` mark, so the per-leg slope
+ * can be correlated with the grower that explains it.
+ */
+export function sampleStructuralCounters(repoDir) {
+    return {
+        runsFanOut: countEntries(path.join(repoDir, RUNS_DIR)),
+        consumedFanOut: countConsumed(repoDir),
+        looseObjects: countLooseObjects(repoDir),
+        gitBytes: gitBytes(repoDir),
+    };
+}
+/**
+ * Force a synchronous `git gc` of the repo at `repoDir`. Synchronous
+ * (`spawnSync`) so the supervisor's single-writer invariant is trivially
+ * preserved: the dispatch loop is the sole caller and blocks here, so no
+ * `writeTreePreservingPrefix` commit can interleave with the repack.
+ * Returns the wall-clock duration in ms and whether the gc succeeded;
+ * a non-zero exit is surfaced (not swallowed) so a broken A/B run does
+ * not silently report "repack had no effect".
+ */
+export function forceRepack(repoDir) {
+    const t0 = performance.now();
+    const result = spawnSync("git", ["-C", repoDir, "gc", "--quiet", "--prune=now"], { encoding: "utf8" });
+    const durationMs = performance.now() - t0;
+    if (result.error !== undefined) {
+        return { ok: false, durationMs, detail: result.error.message };
+    }
+    if (result.status !== 0) {
+        return {
+            ok: false,
+            durationMs,
+            detail: `git gc exited ${String(result.status)}: ${result.stderr}`,
+        };
+    }
+    return { ok: true, durationMs, detail: "" };
+}

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

@@ -0,0 +1,127 @@
+import type { PrincipalSigner, TerminalEventSource } from "./types.js";
+import type { RepoId, RepoStore as SubstrateRepoStore } from "@intx/hub-sessions/substrate";
+/**
+ * Default `drainTimeout` per deployment. Operators override this via
+ * a per-deployment policy; this value is the spec's locked default.
+ */
+export declare const DEFAULT_DRAIN_TIMEOUT_MS = 60000;
+export type DrainTimeoutOpts = {
+    /**
+     * Substrate handle through which the escalation commit lands.
+     * Reused from the supervisor's bindings -- the accumulator does
+     * not own a substrate of its own.
+     */
+    substrate: SubstrateRepoStore;
+    /** Workflow-run repo for this deployment. */
+    repoId: RepoId;
+    /** Workflow-run repo ref the supervisor commits events to. */
+    ref: string;
+    /** Deployment id baked into the supervisor's signing principal. */
+    deploymentId: string;
+    /** Run id the drain is being escalated against. */
+    runId: string;
+    /**
+     * Host-supplied per-principal signing callback the supervisor uses
+     * to mint the CancelRequested signature. The drain origin is
+     * `supervisor-drain`.
+     */
+    signAsPrincipal: PrincipalSigner;
+    /** ISO-8601 reason for the CancelRequested escalation. */
+    reason?: string;
+    /**
+     * Operator-overridable per-deployment timeout. Defaults to
+     * `DEFAULT_DRAIN_TIMEOUT_MS`.
+     */
+    drainTimeoutMs?: number;
+    /**
+     * Deterministic clock for the accumulator. Tests inject a
+     * controllable clock; production wires `() => Date.now()`.
+     */
+    now: () => number;
+    /**
+     * Scheduling primitive the accumulator uses for its tick callback.
+     * Tests inject a deterministic timer; production wires
+     * `(cb, ms) => setTimeout(cb, ms)`.
+     */
+    setTimer: (cb: () => void, ms: number) => unknown;
+    /**
+     * Disposer paired with `setTimer`. Production wires
+     * `(handle) => clearTimeout(handle as ReturnType<typeof setTimeout>)`.
+     */
+    clearTimer: (handle: unknown) => void;
+    /**
+     * Optional per-runId terminal-event source the accumulator consumes
+     * to settle early when the tracked run reaches a terminal phase
+     * before the drainTimeout fires. When absent, the accumulator falls
+     * back to timer-only settlement (the pre-binding behaviour). The
+     * supervisor wires this against its `terminalEventSource` binding;
+     * the iterator is finalised via `return()` whenever the accumulator
+     * settles (terminal, timeout, or `stop()`).
+     */
+    terminalEventSource?: TerminalEventSource;
+};
+/**
+ * Handle the supervisor holds onto so it can pause/resume ticking
+ * during step-kind transitions, and so it can stop the accumulator
+ * cleanly when the run reaches a terminal phase before the
+ * drainTimeout expires.
+ */
+export interface DrainTimeoutAccumulator {
+    /**
+     * Begin counting cancel-time. Idempotent; a second call after the
+     * accumulator has already started is a no-op so the supervisor's
+     * control loop can re-issue drain without breaking ordering.
+     */
+    start(): void;
+    /**
+     * Pause the accumulator. The supervisor calls this when its view
+     * of the workflow's in-flight steps transitions from cancel-mode
+     * to wait-mode (e.g., the last cancel-mode step completed and only
+     * `awaitSignal` steps remain). Time spent paused does not count
+     * toward the timeout.
+     */
+    pause(): void;
+    /**
+     * Resume the accumulator. Inverse of `pause`. Time elapsed since
+     * the last `start` or `resume` carries forward -- pause/resume is
+     * about wall-clock attribution, not zeroing the count.
+     */
+    resume(): void;
+    /**
+     * Stop the accumulator without escalating. Called when the run
+     * reaches a terminal phase before drainTimeout expires.
+     */
+    stop(): void;
+    /** Total accumulated cancel-time at the current moment, in ms. */
+    accumulatedMs(): number;
+    /** Whether the accumulator has already escalated. */
+    readonly escalated: boolean;
+    /**
+     * Resolves when every asynchronous resource the accumulator owns has
+     * been disposed: the escalation commit (if armed) has finished, and
+     * the per-runId terminal-event watcher (if armed) has had its
+     * iterator finalised. The supervisor awaits this in `shutdown` so a
+     * still-running watcher cannot fire a settle against a torn-down
+     * supervisor.
+     *
+     * Idempotent: calling `disposed()` multiple times returns the same
+     * promise. Resolves once `stop()` or the timer-driven escalation has
+     * run.
+     */
+    disposed(): Promise<void>;
+}
+/**
+ * Factory shape the supervisor binds against. Mirrors
+ * `createDrainTimeoutAccumulator` exactly; surfaced so tests can
+ * inject a mock factory through `WorkflowSupervisorBindings.
+ * drainTimeoutAccumulatorFactory` and observe the supervisor's
+ * drain-arming sequence without rigging a real timer host.
+ */
+export type DrainTimeoutAccumulatorFactory = (opts: DrainTimeoutOpts) => DrainTimeoutAccumulator;
+/**
+ * Construct the supervisor's drainTimeout accumulator. The returned
+ * handle is single-use: once `escalated` flips true the accumulator
+ * has committed `CancelRequested{origin: "supervisor-drain"}` and
+ * cannot tick again.
+ */
+export declare function createDrainTimeoutAccumulator(opts: DrainTimeoutOpts): DrainTimeoutAccumulator;