@loomwork/dispatcher 0.0.0-stage → 0.1.0

package/dist/SupervisingDispatcher.d.ts

@@ -0,0 +1,57 @@
+import { type ExecutionPackage, type ExecutionResult } from "@loomwork/worker-runtime";
+import type { DispatchMetadata, DispatcherHealth, ExecutionDispatcher } from "./types";
+export interface CircuitPolicy {
+    /** Consecutive dispatch failures before the circuit opens. */
+    threshold: number;
+    /** How long the circuit stays open before a half-open trial, in ms. */
+    cooldownMs: number;
+    /** Circuit key for a package. Default: `pkg.flowId` (per-flow breaker). */
+    key?: (pkg: ExecutionPackage) => string;
+}
+export interface SupervisionPolicy {
+    /** Restart a *throwing* dispatch up to N extra times (default 0). A returned
+     *  "failed" result is a normal outcome, not a restartable error — and neither is a
+     *  refusal because another holder owns the execution ({@link isSupersededRefusal},
+     *  L20): it is rethrown at once, without a restart and without counting against the
+     *  circuit, because restarting it would fence out the holder that won. */
+    maxRestarts?: number;
+    /** Base backoff between restarts, in ms (default 0). */
+    backoffMs?: number;
+    /** Exponential growth factor for the backoff (default 2). */
+    backoffFactor?: number;
+    /** Optional circuit breaker — fail fast when a target is consistently down. */
+    circuit?: CircuitPolicy;
+}
+export declare class CircuitOpenError extends Error {
+    readonly key: string;
+    constructor(key: string);
+}
+export interface SupervisingDispatcherOptions {
+    policy?: SupervisionPolicy;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}
+/**
+ * Fault supervision (Loom 2.0 K4). A composite {@link ExecutionDispatcher} that wraps
+ * a child with an explicit restart/backoff policy and a per-key **circuit breaker**:
+ * after `threshold` consecutive dispatch failures the circuit opens and further
+ * dispatches fail fast (CircuitOpenError) until a `cooldownMs` half-open trial — so a
+ * flaky model/tool/worker is not hammered. Promotes the runtime's ad-hoc
+ * retry/redispatch into a named supervision seam; composes over LocalDispatcher /
+ * PlacementDispatcher unchanged.
+ */
+export declare class SupervisingDispatcher implements ExecutionDispatcher {
+    private readonly child;
+    private readonly circuits;
+    private readonly policy;
+    private readonly now;
+    private readonly sleep;
+    constructor(child: ExecutionDispatcher, options?: SupervisingDispatcherOptions);
+    dispatch(pkg: ExecutionPackage, meta?: DispatchMetadata): Promise<ExecutionResult>;
+    cancel(executionId: string): Promise<void>;
+    health(): Promise<DispatcherHealth>;
+    private guardCircuit;
+    private recordSuccess;
+    private recordFailure;
+}
+//# sourceMappingURL=SupervisingDispatcher.d.ts.map

package/dist/SupervisingDispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SupervisingDispatcher.d.ts","sourceRoot":"","sources":["../src/SupervisingDispatcher.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,eAAe,EAErB,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAEvF,MAAM,WAAW,aAAa;IAC5B,8DAA8D;IAC9D,SAAS,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,UAAU,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,gBAAgB,KAAK,MAAM,CAAC;CACzC;AAED,MAAM,WAAW,iBAAiB;IAChC;;;;8EAI0E;IAC1E,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,wDAAwD;IACxD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;gBACT,GAAG,EAAE,MAAM;CAKxB;AAOD,MAAM,WAAW,4BAA4B;IAC3C,MAAM,CAAC,EAAE,iBAAiB,CAAC;IAC3B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACvC;AAED;;;;;;;;GAQG;AACH,qBAAa,qBAAsB,YAAW,mBAAmB;IAO7D,OAAO,CAAC,QAAQ,CAAC,KAAK;IANxB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA8B;IACvD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoB;IAC3C,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IACnC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgC;gBAGnC,KAAK,EAAE,mBAAmB,EAC3C,OAAO,GAAE,4BAAiC;IAOtC,QAAQ,CAAC,GAAG,EAAE,gBAAgB,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC;IA8BlF,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI1C,MAAM,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAczC,OAAO,CAAC,YAAY;IAYpB,OAAO,CAAC,aAAa;IAcrB,OAAO,CAAC,aAAa;CAUtB"}

package/dist/SupervisingDispatcher.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SupervisingDispatcher = exports.CircuitOpenError = void 0;
+const worker_runtime_1 = require("@loomwork/worker-runtime");
+class CircuitOpenError extends Error {
+    key;
+    constructor(key) {
+        super(`Circuit open for "${key}" — failing fast`);
+        this.name = "CircuitOpenError";
+        this.key = key;
+    }
+}
+exports.CircuitOpenError = CircuitOpenError;
+/**
+ * Fault supervision (Loom 2.0 K4). A composite {@link ExecutionDispatcher} that wraps
+ * a child with an explicit restart/backoff policy and a per-key **circuit breaker**:
+ * after `threshold` consecutive dispatch failures the circuit opens and further
+ * dispatches fail fast (CircuitOpenError) until a `cooldownMs` half-open trial — so a
+ * flaky model/tool/worker is not hammered. Promotes the runtime's ad-hoc
+ * retry/redispatch into a named supervision seam; composes over LocalDispatcher /
+ * PlacementDispatcher unchanged.
+ */
+class SupervisingDispatcher {
+    child;
+    circuits = new Map();
+    policy;
+    now;
+    sleep;
+    constructor(child, options = {}) {
+        this.child = child;
+        this.policy = options.policy ?? {};
+        this.now = options.now ?? (() => Date.now());
+        this.sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    }
+    async dispatch(pkg, meta) {
+        const key = this.policy.circuit?.key?.(pkg) ?? pkg.flowId;
+        this.guardCircuit(key); // throws CircuitOpenError if open within cooldown
+        const maxRestarts = Math.max(0, this.policy.maxRestarts ?? 0);
+        const base = this.policy.backoffMs ?? 0;
+        const factor = this.policy.backoffFactor ?? 2;
+        let lastErr;
+        for (let attempt = 0; attempt <= maxRestarts; attempt++) {
+            try {
+                const result = await this.child.dispatch(pkg, meta);
+                this.recordSuccess(key);
+                return result;
+            }
+            catch (err) {
+                // L20 — superseded, not failed: not restartable, and not the target's fault. But an
+                // EARLIER restart of this dispatch that failed genuinely still counts against the
+                // circuit — the refusal ends the dispatch, it does not erase what preceded it.
+                if ((0, worker_runtime_1.isSupersededRefusal)(err, pkg.executionId)) {
+                    if (attempt > 0)
+                        this.recordFailure(key);
+                    throw err;
+                }
+                lastErr = err;
+                if (attempt < maxRestarts)
+                    await this.sleep(base * factor ** attempt);
+            }
+        }
+        this.recordFailure(key);
+        throw lastErr;
+    }
+    async cancel(executionId) {
+        return this.child.cancel(executionId);
+    }
+    async health() {
+        const h = await this.child.health();
+        const open = [...this.circuits.entries()]
+            .filter(([, c]) => c.openedAt !== null)
+            .map(([k]) => k);
+        return {
+            healthy: h.healthy && open.length === 0,
+            inFlight: h.inFlight,
+            ...(open.length > 0
+                ? { detail: `circuits-open: ${open.join(",")}` }
+                : h.detail !== undefined && { detail: h.detail }),
+        };
+    }
+    guardCircuit(key) {
+        const c = this.circuits.get(key);
+        if (c === undefined || c.openedAt === null)
+            return;
+        const cooldown = this.policy.circuit?.cooldownMs ?? 0;
+        if (this.now() - c.openedAt < cooldown) {
+            throw new CircuitOpenError(key);
+        }
+        // Cooldown elapsed → half-open: allow one trial. Keep the failure count so a
+        // fresh failure re-opens immediately; a success resets it.
+        c.openedAt = null;
+    }
+    recordSuccess(key) {
+        // DELETE rather than reset. A circuit with `failures: 0, openedAt: null` is
+        // indistinguishable from an absent one everywhere it is read — `guardCircuit`
+        // returns on either, `recordFailure` defaults to exactly that shape, and
+        // `health()` counts only open circuits — so dropping it is observationally
+        // identical and bounds the map to circuits actually accumulating failures.
+        //
+        // Without this the map only grows. The default key is `flowId` (bounded by
+        // deployed flows), but `policy.circuit.key` receives the whole ExecutionPackage,
+        // so keying per tenant — or per execution, which reads as natural — turned a
+        // supervisor into a leak for the lifetime of the process.
+        this.circuits.delete(key);
+    }
+    recordFailure(key) {
+        const circuit = this.policy.circuit;
+        if (circuit === undefined)
+            return;
+        const c = this.circuits.get(key) ?? { failures: 0, openedAt: null };
+        c.failures += 1;
+        if (c.failures >= circuit.threshold) {
+            c.openedAt = this.now();
+        }
+        this.circuits.set(key, c);
+    }
+}
+exports.SupervisingDispatcher = SupervisingDispatcher;
+//# sourceMappingURL=SupervisingDispatcher.js.map

package/dist/SupervisingDispatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SupervisingDispatcher.js","sourceRoot":"","sources":["../src/SupervisingDispatcher.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export type { DispatchMetadata, DispatcherHealth, ExecutionDispatcher, PlacementPolicy, } from "./types";
+export { DISPATCHER_SPI_VERSION } from "./types";
+export { LocalDispatcher, type LocalDispatcherOptions } from "./LocalDispatcher";
+export { PlacementDispatcher, type PlacementDispatcherOptions, } from "./PlacementDispatcher";
+export { dispatchMetadataFromPolicy, defaultPlacementPolicy } from "./placement";
+export { SupervisingDispatcher, CircuitOpenError, type SupervisionPolicy, type CircuitPolicy, type SupervisingDispatcherOptions, } from "./SupervisingDispatcher";
+export type { ExecutionOutcome, ExecutionPackage, ExecutionResult, } from "@loomwork/worker-runtime";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,gBAAgB,EAChB,gBAAgB,EAChB,mBAAmB,EACnB,eAAe,GAChB,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,sBAAsB,EAAE,MAAM,SAAS,CAAC;AACjD,OAAO,EAAE,eAAe,EAAE,KAAK,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AACjF,OAAO,EACL,mBAAmB,EACnB,KAAK,0BAA0B,GAChC,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,0BAA0B,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AACjF,OAAO,EACL,qBAAqB,EACrB,gBAAgB,EAChB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,4BAA4B,GAClC,MAAM,yBAAyB,CAAC;AAGjC,YAAY,EACV,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,GAChB,MAAM,0BAA0B,CAAC"}

package/dist/index.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CircuitOpenError = exports.SupervisingDispatcher = exports.defaultPlacementPolicy = exports.dispatchMetadataFromPolicy = exports.PlacementDispatcher = exports.LocalDispatcher = exports.DISPATCHER_SPI_VERSION = void 0;
+var types_1 = require("./types");
+Object.defineProperty(exports, "DISPATCHER_SPI_VERSION", { enumerable: true, get: function () { return types_1.DISPATCHER_SPI_VERSION; } });
+var LocalDispatcher_1 = require("./LocalDispatcher");
+Object.defineProperty(exports, "LocalDispatcher", { enumerable: true, get: function () { return LocalDispatcher_1.LocalDispatcher; } });
+var PlacementDispatcher_1 = require("./PlacementDispatcher");
+Object.defineProperty(exports, "PlacementDispatcher", { enumerable: true, get: function () { return PlacementDispatcher_1.PlacementDispatcher; } });
+var placement_1 = require("./placement");
+Object.defineProperty(exports, "dispatchMetadataFromPolicy", { enumerable: true, get: function () { return placement_1.dispatchMetadataFromPolicy; } });
+Object.defineProperty(exports, "defaultPlacementPolicy", { enumerable: true, get: function () { return placement_1.defaultPlacementPolicy; } });
+var SupervisingDispatcher_1 = require("./SupervisingDispatcher");
+Object.defineProperty(exports, "SupervisingDispatcher", { enumerable: true, get: function () { return SupervisingDispatcher_1.SupervisingDispatcher; } });
+Object.defineProperty(exports, "CircuitOpenError", { enumerable: true, get: function () { return SupervisingDispatcher_1.CircuitOpenError; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAMA,iCAAiD;AAAxC,+GAAA,sBAAsB,OAAA;AAC/B,qDAAiF;AAAxE,kHAAA,eAAe,OAAA;AACxB,6DAG+B;AAF7B,0HAAA,mBAAmB,OAAA;AAGrB,yCAAiF;AAAxE,uHAAA,0BAA0B,OAAA;AAAE,mHAAA,sBAAsB,OAAA;AAC3D,iEAMiC;AAL/B,8HAAA,qBAAqB,OAAA;AACrB,yHAAA,gBAAgB,OAAA"}

package/dist/placement.d.ts

@@ -0,0 +1,5 @@
+import type { ExecutionPolicy } from "@loomwork/core";
+import type { DispatchMetadata, PlacementPolicy } from "./types";
+export declare function dispatchMetadataFromPolicy(policy: ExecutionPolicy): DispatchMetadata;
+export declare function defaultPlacementPolicy(defaultTarget: string): PlacementPolicy;
+//# sourceMappingURL=placement.d.ts.map

package/dist/placement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"placement.d.ts","sourceRoot":"","sources":["../src/placement.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAMjE,wBAAgB,0BAA0B,CAAC,MAAM,EAAE,eAAe,GAAG,gBAAgB,CAQpF;AAKD,wBAAgB,sBAAsB,CAAC,aAAa,EAAE,MAAM,GAAG,eAAe,CAK7E"}

package/dist/placement.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dispatchMetadataFromPolicy = dispatchMetadataFromPolicy;
+exports.defaultPlacementPolicy = defaultPlacementPolicy;
+// Map the out-of-core ExecutionPolicy (the Loom 2.0 PCB sidecar) onto the advisory
+// DispatchMetadata the compute layer already understands. This is the seam by which
+// a flow's declared placement/priority/resources drive WHERE it runs — without the
+// kernel ever depending on the compute layer (P10).
+function dispatchMetadataFromPolicy(policy) {
+    return {
+        ...(policy.computeTarget !== undefined && { target: policy.computeTarget }),
+        ...(policy.priority !== undefined && { priority: policy.priority }),
+        ...(policy.affinity !== undefined && { lane: policy.affinity }),
+        ...(policy.resources?.cpu !== undefined && { estimatedCpu: policy.resources.cpu }),
+        ...(policy.resources?.memoryMb !== undefined && { estimatedMemory: policy.resources.memoryMb }),
+    };
+}
+// Default placement: honour an explicit `meta.target` when it names a registered
+// target, otherwise fall through to the dispatcher's default. Deterministic and
+// dependency-free — the advisory plane never affects correctness (P10), only WHERE.
+function defaultPlacementPolicy(defaultTarget) {
+    return (_pkg, meta, targets) => {
+        if (meta?.target !== undefined && targets.includes(meta.target))
+            return meta.target;
+        return defaultTarget;
+    };
+}
+//# sourceMappingURL=placement.js.map

package/dist/placement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"placement.js","sourceRoot":"","sources":["../src/placement.ts"],"names":[],"mappings":";;AAOA,gEAQC;AAKD,wDAKC;AAtBD,mFAAmF;AACnF,oFAAoF;AACpF,mFAAmF;AACnF,oDAAoD;AACpD,SAAgB,0BAA0B,CAAC,MAAuB;IAChE,OAAO;QACL,GAAG,CAAC,MAAM,CAAC,aAAa,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,aAAa,EAAE,CAAC;QAC3E,GAAG,CAAC,MAAM,CAAC,QAAQ,KAAK,SAAS,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC;QACnE,GAAG,CAAC,MAAM,CAAC,QAAQ,KAAK,SAAS,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC;QAC/D,GAAG,CAAC,MAAM,CAAC,SAAS,EAAE,GAAG,KAAK,SAAS,IAAI,EAAE,YAAY,EAAE,MAAM,CAAC,SAAS,CAAC,GAAG,EAAE,CAAC;QAClF,GAAG,CAAC,MAAM,CAAC,SAAS,EAAE,QAAQ,KAAK,SAAS,IAAI,EAAE,eAAe,EAAE,MAAM,CAAC,SAAS,CAAC,QAAQ,EAAE,CAAC;KAChG,CAAC;AACJ,CAAC;AAED,iFAAiF;AACjF,gFAAgF;AAChF,oFAAoF;AACpF,SAAgB,sBAAsB,CAAC,aAAqB;IAC1D,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE;QAC7B,IAAI,IAAI,EAAE,MAAM,KAAK,SAAS,IAAI,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC;YAAE,OAAO,IAAI,CAAC,MAAM,CAAC;QACpF,OAAO,aAAa,CAAC;IACvB,CAAC,CAAC;AACJ,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,69 @@
+import type { ExecutionPackage, ExecutionResult } from "@loomwork/worker-runtime";
+/**
+ * SPI version for the {@link ExecutionDispatcher} contract (ADR 0033). Pinned by
+ * `runExecutionDispatcherConformance` in `@loomwork/testing`.
+ *
+ * 1.1.0 (L20, ADR 0004 amendment) — a dispatcher MUST NOT retry or redispatch when the worker
+ * was refused because another holder owns the execution (`isSupersededRefusal` from
+ * `@loomwork/worker-runtime`); it settles the dispatch with that refusal. MINOR: no method changed,
+ * a non-retrying dispatcher already conforms, and the kit case runs only when the caller opts in
+ * with `overWorker`, so no 1.0 dispatcher newly fails the kit.
+ *
+ * 1.2.0 (R3, ADR 0111) — `ExecutionPackage.principal` and `WorkerRequest.principal` (both
+ * optional JSON) carry the authenticated caller across the dispatch seam, and `WorkerRuntime`
+ * gains the optional `runsAsSystem` marker. MINOR: every field is optional, a dispatcher that
+ * forwards the package whole (all four first-party ones do) already conforms, and a worker that
+ * ignores `principal` behaves as before.
+ */
+export declare const DISPATCHER_SPI_VERSION = "1.2.0";
+/**
+ * Placement hints the scheduler/orchestrator attaches to a dispatch. The
+ * Dispatcher maps these to a concrete placement decision (e.g. Cloud Run CPU/
+ * memory in Step 3). Everything is optional and advisory — correctness never
+ * depends on it.
+ */
+export interface DispatchMetadata {
+    lane?: string;
+    priority?: number;
+    estimatedCpu?: number;
+    estimatedMemory?: number;
+    estimatedDuration?: number;
+    /**
+     * Named compute placement target (e.g. "local" | "cloudrun"). Advisory: a
+     * {@link PlacementDispatcher} routes to the matching target, falling back to its
+     * default when absent/unknown. Derived from `ExecutionPolicy.computeTarget` (M4).
+     */
+    target?: string;
+}
+/**
+ * Chooses which named target handles a dispatch. Pure and synchronous so placement
+ * is deterministic and cheap. Given the package, its advisory metadata, and the set
+ * of registered target names, return the chosen name (a PlacementDispatcher falls
+ * back to its default if the returned name is not registered).
+ */
+export type PlacementPolicy = (pkg: ExecutionPackage, meta: DispatchMetadata | undefined, targets: readonly string[]) => string;
+/** A snapshot of dispatcher liveness for health checks / observability. */
+export interface DispatcherHealth {
+    healthy: boolean;
+    inFlight: number;
+    detail?: string;
+}
+/**
+ * Separates execution *placement* from execution *scheduling*. The scheduler
+ * decides WHAT runs; the Dispatcher decides WHERE, and owns worker allocation,
+ * result collection, retries and (from Step 4) timeout + failure redispatch. It
+ * talks only to a {@link WorkerRuntime} — never to a specific cloud.
+ */
+export interface ExecutionDispatcher {
+    /**
+     * Run `pkg` to suspend-or-complete. MAY retry a failed attempt; MUST NOT retry or redispatch a
+     * superseded refusal (`isSupersededRefusal`, 1.1.0) — it rejects with that refusal instead.
+     * Such a rejection is not the execution's failure: another holder owns it, possibly this
+     * caller's own earlier timed-out attempt. A caller that needs the outcome awaits it by id
+     * (`loadState` / `subscribe`); a holder that has died is re-driven by `recoverAbandoned`.
+     */
+    dispatch(pkg: ExecutionPackage, meta?: DispatchMetadata): Promise<ExecutionResult>;
+    cancel(executionId: string): Promise<void>;
+    health(): Promise<DispatcherHealth>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,0BAA0B,CAAC;AAElF;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,sBAAsB,UAAU,CAAC;AAE9C;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG,CAC5B,GAAG,EAAE,gBAAgB,EACrB,IAAI,EAAE,gBAAgB,GAAG,SAAS,EAClC,OAAO,EAAE,SAAS,MAAM,EAAE,KACvB,MAAM,CAAC;AAEZ,2EAA2E;AAC3E,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;;;;OAMG;IACH,QAAQ,CAAC,GAAG,EAAE,gBAAgB,EAAE,IAAI,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IACnF,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,MAAM,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAAC;CACrC"}

package/dist/types.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DISPATCHER_SPI_VERSION = void 0;
+/**
+ * SPI version for the {@link ExecutionDispatcher} contract (ADR 0033). Pinned by
+ * `runExecutionDispatcherConformance` in `@loomwork/testing`.
+ *
+ * 1.1.0 (L20, ADR 0004 amendment) — a dispatcher MUST NOT retry or redispatch when the worker
+ * was refused because another holder owns the execution (`isSupersededRefusal` from
+ * `@loomwork/worker-runtime`); it settles the dispatch with that refusal. MINOR: no method changed,
+ * a non-retrying dispatcher already conforms, and the kit case runs only when the caller opts in
+ * with `overWorker`, so no 1.0 dispatcher newly fails the kit.
+ *
+ * 1.2.0 (R3, ADR 0111) — `ExecutionPackage.principal` and `WorkerRequest.principal` (both
+ * optional JSON) carry the authenticated caller across the dispatch seam, and `WorkerRuntime`
+ * gains the optional `runsAsSystem` marker. MINOR: every field is optional, a dispatcher that
+ * forwards the package whole (all four first-party ones do) already conforms, and a worker that
+ * ignores `principal` behaves as before.
+ */
+exports.DISPATCHER_SPI_VERSION = "1.2.0";
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";;;AAEA;;;;;;;;;;;;;;;GAeG;AACU,QAAA,sBAAsB,GAAG,OAAO,CAAC"}

package/package.json

@@ -1,6 +1,56 @@
 {
   "name": "@loomwork/dispatcher",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Execution dispatcher for Loom — decides WHERE an execution runs and owns worker allocation, retries, timeout and result collection, sitting between the orchestrator and a WorkerRuntime",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@loomwork/core": "^0.1.0",
+    "@loomwork/worker-runtime": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.8"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chhetrisushil/loom.git",
+    "directory": "packages/dispatcher"
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/__tests__",
+    "!src/**/__fixtures__",
+    "!src/**/__snapshots__",
+    "!src/**/__golden__",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "tag": "next"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsc --build",
+    "dev": "tsc --build --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "typecheck:tests": "tsc -p tsconfig.test.json"
+  }
 }

package/src/LocalDispatcher.ts

@@ -0,0 +1,141 @@
+import {
+  type ExecutionPackage,
+  type ExecutionResult,
+  type WorkerLease,
+  type WorkerRuntime,
+  isSupersededRefusal,
+} from "@loomwork/worker-runtime";
+import type { DispatchMetadata, DispatcherHealth, ExecutionDispatcher } from "./types";
+
+export interface LocalDispatcherOptions {
+  /**
+   * How many times to attempt a dispatch before giving up. An attempt fails when
+   * the worker throws (transport/allocation error or a crashed instance) or when
+   * it exceeds {@link LocalDispatcherOptions.executeTimeoutMs} — NOT when the flow
+   * returns a "failed" result, which is a normal terminal outcome. Default 1.
+   *
+   * NOR when the worker was refused because another holder owns the execution — a lost
+   * start race or a fenced-out attempt ({@link isSupersededRefusal}, L20). That refusal is
+   * rethrown at once, never retried: `allocate` fences every attempt, so a retry would
+   * supersede the holder that won, and the two would ping-pong, re-running the in-flight
+   * step on every bounce. Declining it keeps ADR 0004's bound — the one interrupted step
+   * runs at most twice — whatever this is set to.
+   *
+   * Redispatch is safe: the worker is idempotent (it inspects durable state and
+   * resumes a crashed execution from its latest snapshot rather than restarting),
+   * so a retry continues where the failed attempt left off without re-running
+   * completed steps.
+   */
+  maxAttempts?: number;
+  /**
+   * Per-attempt deadline. A worker that hangs (a wedged/lost Cloud Run instance)
+   * is treated as a failed attempt and redispatched. Omit to wait indefinitely.
+   */
+  executeTimeoutMs?: number;
+}
+
+class DispatchTimeoutError extends Error {}
+
+/**
+ * The default Dispatcher. It wraps a single {@link WorkerRuntime} — allocate a
+ * lease, execute the package, release the lease — and exposes the placement seam
+ * without any cloud awareness. Swapping the worker (Local → Remote → CloudRun)
+ * is the only change needed to move execution off-box; callers see the same
+ * {@link ExecutionResult} contract.
+ */
+export class LocalDispatcher implements ExecutionDispatcher {
+  private inFlight = 0;
+  private readonly maxAttempts: number;
+  private readonly executeTimeoutMs: number | undefined;
+  private readonly leases = new Map<string, WorkerLease>();
+  private readonly cancelled = new Set<string>();
+
+  constructor(
+    private readonly worker: WorkerRuntime,
+    options: LocalDispatcherOptions = {}
+  ) {
+    this.maxAttempts = Math.max(1, options.maxAttempts ?? 1);
+    this.executeTimeoutMs = options.executeTimeoutMs;
+  }
+
+  async dispatch(pkg: ExecutionPackage, meta?: DispatchMetadata): Promise<ExecutionResult> {
+    this.cancelled.delete(pkg.executionId);
+    this.inFlight++;
+    try {
+      let lastErr: unknown;
+      for (let attempt = 1; attempt <= this.maxAttempts; attempt++) {
+        const lease = await this.worker.allocate({
+          executionId: pkg.executionId,
+          ...(meta !== undefined && { metadata: meta as Record<string, unknown> }),
+          ...(pkg.principal !== undefined && { principal: pkg.principal }),
+        });
+        this.leases.set(pkg.executionId, lease);
+        try {
+          const run = this.worker.execute(lease, pkg);
+          return await (this.executeTimeoutMs
+            ? withTimeout(run, this.executeTimeoutMs, pkg.executionId)
+            : run);
+        } catch (err) {
+          // L20 — superseded, not failed: someone else is driving this execution now.
+          if (isSupersededRefusal(err, pkg.executionId)) throw err;
+          lastErr = err;
+        } finally {
+          this.leases.delete(pkg.executionId);
+          await this.worker.release(lease);
+        }
+        // A cancel during this attempt aborts it; DON'T redispatch a cancelled execution
+        // (that would re-run what the caller just cancelled). Also stops the flag leaking.
+        if (this.cancelled.has(pkg.executionId)) break;
+      }
+      throw lastErr;
+    } finally {
+      this.inFlight--;
+      this.cancelled.delete(pkg.executionId);
+    }
+  }
+
+  /**
+   * Best-effort cancellation. Releases any lease held for the execution, and
+   * (K8.5) forwards the kill to the worker when it supports mid-flight
+   * interruption — in-process this aborts the in-flight effect and records the
+   * durable EXECUTION_CANCELLED; over HTTP it reaches the remote worker's
+   * `POST /cancel`. Delivery stays best-effort: durable settlement belongs to
+   * the store-side cancel (fence-then-cancel), never to this call landing.
+   */
+  async cancel(executionId: string): Promise<void> {
+    const lease = this.leases.get(executionId);
+    if (lease) {
+      // Only flag as cancelled when a dispatch is actually in flight (a lease is held) —
+      // the flag exists solely to stop that dispatch's retry loop, and gating it here keeps
+      // `cancelled` bounded (it's cleared in dispatch's finally). A cancel with no in-flight
+      // dispatch has nothing to short-circuit.
+      this.cancelled.add(executionId);
+      this.leases.delete(executionId);
+      await this.worker.release(lease);
+    }
+    await this.worker.cancel?.(executionId);
+  }
+
+  async health(): Promise<DispatcherHealth> {
+    return { healthy: true, inFlight: this.inFlight };
+  }
+}
+
+function withTimeout<T>(p: Promise<T>, ms: number, executionId: string): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const timer = setTimeout(
+      () => reject(new DispatchTimeoutError(`dispatch timed out after ${ms}ms for ${executionId}`)),
+      ms
+    );
+    p.then(
+      (v) => {
+        clearTimeout(timer);
+        resolve(v);
+      },
+      (err: unknown) => {
+        clearTimeout(timer);
+        reject(err as Error);
+      }
+    );
+  });
+}