@loomwork/worker-runtime 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+

package/NOTICE

@@ -0,0 +1,8 @@
+Loom
+Copyright 2026 Sushil Chhetri
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this project except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0

package/README.md

@@ -1,3 +1,76 @@
-# Temporary Holding Version
+# @loomwork/worker-runtime — the worker SPI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The contract for running one execution on some compute placement: `WorkerRuntime` (`allocate`, `execute`,
+`release`, optional `cancel`) and the JSON `ExecutionPackage` that crosses the boundary. A package carries
+identity and resume coordinates (`executionId`, `workflowId`, `flowId`, `input` or a `resumeEvent`),
+never code: the worker resolves the flow by id from the code it booted with and rebuilds state from the
+shared event and snapshot stores. This is infrastructure. An app does not normally import it; you read it
+when you write a worker backend or a dispatcher. A [`@loomwork/dispatcher`](../dispatcher/README.md) sits in
+front of a worker and owns retries and placement.
+
+Implementations: `LocalWorkerRuntime` ([`@loomwork/worker-runtime-local`](../worker-runtime-local/README.md),
+in-process), `RemoteWorkerRuntime` (`@loomwork/plugin-worker-remote`, HTTP to a `@loomwork/plugin-worker-server`
+endpoint) and `CloudRunWorkerRuntime` (`@loomwork/plugin-cloudrun`).
+
+```ts
+import {
+  isSupersededRefusal,
+  type ExecutionPackage,
+  type ExecutionResult,
+  type WorkerRuntime,
+} from "@loomwork/worker-runtime";
+
+// What a dispatcher does around any WorkerRuntime: lease, execute, always release.
+export async function dispatchOnce(
+  worker: WorkerRuntime,
+  pkg: ExecutionPackage
+): Promise<ExecutionResult | "superseded"> {
+  const lease = await worker.allocate({ executionId: pkg.executionId });
+  try {
+    return await worker.execute(lease, pkg);
+  } catch (err) {
+    // Another holder owns this execution: settled, not failed. Do not retry it.
+    if (isSupersededRefusal(err, pkg.executionId)) return "superseded";
+    throw err;
+  } finally {
+    await worker.release(lease);
+  }
+}
+```
+
+## Surface
+
+- **Interface.** `WorkerRuntime`, `WorkerRequest`, `WorkerLease` (`leaseId`, optional fencing token
+  `fence`, `metadata`).
+- **Payloads.** `ExecutionPackage` (a fresh start sets `input`; a resume sets `resumeEvent`; optional
+  `snapshotId`, `fromSequence`, `metadata`, `principal`), `ExecutionResult` (`status`, folded `state`,
+  `output`, `error`, `suspendedOn`, `lastSequence`) and `ExecutionOutcome`
+  (`"completed" | "suspended" | "failed"`).
+- **Superseded refusals.** `isSupersededRefusal(err, executionId)` and `ExecutionSupersededError`, its
+  wire form.
+
+## Behaviour that surprises people
+
+- **A suspend is a normal result.** `execute` runs to suspend-or-complete and returns
+  `status: "suspended"`; the caller resumes with a fresh package carrying `resumeEvent`.
+- **Superseded is not failed.** `isSupersededRefusal` is true for a lost start race, a lost or held
+  lease, a stale fence or `ExecutionSupersededError`, each only when it names this execution. A
+  dispatcher must not retry it: every attempt takes a newer fence, so a retry would fence the winner out
+  and the two would ping-pong. It transfers ownership without checking the new holder is alive, so run
+  `recoverAbandoned`, and await the outcome by id.
+- **`principal` crosses the wire as plain data.** A receiving worker should honour it only from a caller
+  it has authenticated; `runsAsSystem` marks a worker that runs principal-less packages as the kernel's
+  system identity, which a network transport refuses to expose without an authentication gate.
+- **`cancel` is best effort.** Durable cancellation settles through the shared store and does not depend
+  on this call reaching the worker.
+
+## Install
+
+Unpublished for now: inside this repo use `workspace:*`; from a sibling checkout use a `link:` override (see [AGENTS.md](../../AGENTS.md)).
+
+## See also
+
+- API reference: section "`@loomwork/worker-runtime` — the SPI" in [docs/api-reference.org](../../docs/api-reference.org).
+- Guide: [user guide, section 13: where executions run](../../docs/user-guide.md#13-where-executions-run-compute); `runWorkerRuntimeConformance` in `@loomwork/conformance` proves an implementation.
+- ADRs: [0001 dispatcher and worker runtime](../../docs/adr/0001-execution-dispatcher-and-worker-runtime.md), [0002 HTTP worker](../../docs/adr/0002-http-worker-and-remote-worker-runtime.md), [0003 Cloud Run](../../docs/adr/0003-cloud-run-worker-runtime.md), [0004 failure recovery](../../docs/adr/0004-failure-recovery.md).
+- Source: `packages/worker-runtime/src`.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export type { ExecutionOutcome, ExecutionPackage, ExecutionResult, WorkerLease, WorkerRequest, WorkerRuntime, } from "./types";
+export { ExecutionSupersededError, isSupersededRefusal } from "./superseded";
+//# 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,eAAe,EACf,WAAW,EACX,aAAa,EACb,aAAa,GACd,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,wBAAwB,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -0,0 +1,7 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSupersededRefusal = exports.ExecutionSupersededError = void 0;
+var superseded_1 = require("./superseded");
+Object.defineProperty(exports, "ExecutionSupersededError", { enumerable: true, get: function () { return superseded_1.ExecutionSupersededError; } });
+Object.defineProperty(exports, "isSupersededRefusal", { enumerable: true, get: function () { return superseded_1.isSupersededRefusal; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAQA,2CAA6E;AAApE,sHAAA,wBAAwB,OAAA;AAAE,iHAAA,mBAAmB,OAAA"}

package/dist/superseded.d.ts

@@ -0,0 +1,66 @@
+/**
+ * L20 (ADR 0004) — `execute` was refused because ANOTHER holder owns the execution. This is the
+ * portable form of that refusal: the HTTP worker answers it with
+ * `409 { code: "superseded", executionId }` and `RemoteWorkerRuntime` rethrows it as this error,
+ * so a caller on the far side of a wire can tell it apart from a transport or storage failure
+ * exactly as an in-process caller can.
+ *
+ * It is NOT a failed attempt. Every dispatch acquires a newer fence, so retrying it supersedes
+ * the holder that just won, which is then fenced out and retries in turn — the two ping-pong and
+ * each bounce re-runs the in-flight step. So a dispatcher settles it instead of retrying.
+ *
+ * What settling means: the refusal TRANSFERS ownership to the newer fence holder, and nothing
+ * here checks that holder is alive. Its liveness is covered only by its own dispatcher's policy
+ * (retries, `executeTimeoutMs`) and, past that, by `recoverAbandoned` — which a deployment MUST
+ * run to cover holders that die (a duplicate dispatcher that crashed mid-run, or one that timed
+ * out while its wedged instance kept the fence). Until then the execution may sit in `running`.
+ *
+ * The newer holder can even be this caller's own earlier attempt (an HTTP attempt that timed out
+ * but kept running): the execution then completes while `dispatch()` rejects with this error.
+ * So a caller that needs the OUTCOME should treat this error as "await by id" —
+ * `loadState` / `subscribe` on the same executionId — not as a failure of the execution.
+ */
+export declare class ExecutionSupersededError extends Error {
+    readonly executionId: string;
+    /** What the worker was refused with, when known (in-process). Absent across a wire. */
+    readonly cause?: unknown | undefined;
+    constructor(executionId: string, 
+    /** What the worker was refused with, when known (in-process). Absent across a wire. */
+    cause?: unknown | undefined);
+}
+/**
+ * L20 (ADR 0004) — does `err` mean "a newer or other holder owns `executionId`", rather than
+ * "this attempt failed"? A dispatcher MUST NOT retry or redispatch on `true`.
+ *
+ * Exactly three shapes, each REQUIRED to name `executionId` so an error about some other
+ * execution never qualifies:
+ *  - `ExecutionAlreadyExistsError` — a start lost the sequence-0 race (ADR 0103);
+ *  - `LeaseHeldError` / `LeaseLostError` (ADR 0130 D11), bare or as the `cause` of a
+ *    `StorageWriteError` (a write the lease gate refused) — a live owner holds the lease, or this
+ *    driver lost its own;
+ *  - `StaleFenceError`, bare or as the `cause` of a `StorageWriteError` — this attempt's token
+ *    was superseded by a newer `acquireFence` (a redispatch, a recovery pass, a fenced wake or a
+ *    cancel). The id check matters: a coalesced batch rejects every caller in it with ONE
+ *    writer's error (ADR 0074 L1), so a stale fence naming a different execution is that
+ *    writer's refusal and, for this one, a genuine storage failure — retryable;
+ *  - `ExecutionSupersededError` — the wire form of either.
+ *
+ * Not included: `StartLeaseHeldError` (a caller-chosen start that found a lease but NO sequence 0, a
+ * possible ghost; same reasoning) and `StartFencedOutError` (`@loomwork/workflow-runtime`) — a start refused on the fence
+ * with sequence 0 still absent. Its newer token's holder has written nothing and may be dead, so
+ * settling would lose the start outright; it stays retryable.
+ *
+ * Accepted imprecision: a coalesced batch holding writes for TWO fenced-out executions rejects
+ * both with the first one's error, so the second sees a stale fence naming another execution and
+ * retries. That retry takes a newer fence, so it can supersede the second execution's live holder
+ * and re-run its in-flight step once more; the holder it fences out then gets a refusal naming
+ * its own execution and settles. One bounded extra bounce per such batch — not a ping-pong —
+ * accepted rather than guessing which execution a batch error "really" meant.
+ *
+ * Every other error, including any other `StorageWriteError`, is `false`: a genuine failure is
+ * never swallowed. Matched by `name`, not class, because `@loomwork/worker-runtime` sits below the
+ * packages that define the first two (layering), and so a second bundled copy of any of them
+ * cannot hide a refusal — the same rule as `isStaleFence` in `@loomwork/workflow-runtime`.
+ */
+export declare function isSupersededRefusal(err: unknown, executionId: string): boolean;
+//# sourceMappingURL=superseded.d.ts.map

package/dist/superseded.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"superseded.d.ts","sourceRoot":"","sources":["../src/superseded.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,wBAAyB,SAAQ,KAAK;IAE/C,QAAQ,CAAC,WAAW,EAAE,MAAM;IAC5B,uFAAuF;IACvF,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO;gBAFf,WAAW,EAAE,MAAM;IAC5B,uFAAuF;IAC9E,KAAK,CAAC,EAAE,OAAO,YAAA;CAQ3B;AAQD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAyB9E"}

package/dist/superseded.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExecutionSupersededError = void 0;
+exports.isSupersededRefusal = isSupersededRefusal;
+/**
+ * L20 (ADR 0004) — `execute` was refused because ANOTHER holder owns the execution. This is the
+ * portable form of that refusal: the HTTP worker answers it with
+ * `409 { code: "superseded", executionId }` and `RemoteWorkerRuntime` rethrows it as this error,
+ * so a caller on the far side of a wire can tell it apart from a transport or storage failure
+ * exactly as an in-process caller can.
+ *
+ * It is NOT a failed attempt. Every dispatch acquires a newer fence, so retrying it supersedes
+ * the holder that just won, which is then fenced out and retries in turn — the two ping-pong and
+ * each bounce re-runs the in-flight step. So a dispatcher settles it instead of retrying.
+ *
+ * What settling means: the refusal TRANSFERS ownership to the newer fence holder, and nothing
+ * here checks that holder is alive. Its liveness is covered only by its own dispatcher's policy
+ * (retries, `executeTimeoutMs`) and, past that, by `recoverAbandoned` — which a deployment MUST
+ * run to cover holders that die (a duplicate dispatcher that crashed mid-run, or one that timed
+ * out while its wedged instance kept the fence). Until then the execution may sit in `running`.
+ *
+ * The newer holder can even be this caller's own earlier attempt (an HTTP attempt that timed out
+ * but kept running): the execution then completes while `dispatch()` rejects with this error.
+ * So a caller that needs the OUTCOME should treat this error as "await by id" —
+ * `loadState` / `subscribe` on the same executionId — not as a failure of the execution.
+ */
+class ExecutionSupersededError extends Error {
+    executionId;
+    cause;
+    constructor(executionId, 
+    /** What the worker was refused with, when known (in-process). Absent across a wire. */
+    cause) {
+        super(`execution "${executionId}" is owned by another holder (a lost start race or a newer fence); this dispatch was superseded, not failed — redispatching would fence that holder out. Await the execution by id (loadState/subscribe); if its holder has died, recoverAbandoned re-drives it.`);
+        this.executionId = executionId;
+        this.cause = cause;
+        this.name = "ExecutionSupersededError";
+        Object.setPrototypeOf(this, ExecutionSupersededError.prototype);
+    }
+}
+exports.ExecutionSupersededError = ExecutionSupersededError;
+function field(value, key) {
+    return value !== null && typeof value === "object"
+        ? value[key]
+        : undefined;
+}
+/**
+ * L20 (ADR 0004) — does `err` mean "a newer or other holder owns `executionId`", rather than
+ * "this attempt failed"? A dispatcher MUST NOT retry or redispatch on `true`.
+ *
+ * Exactly three shapes, each REQUIRED to name `executionId` so an error about some other
+ * execution never qualifies:
+ *  - `ExecutionAlreadyExistsError` — a start lost the sequence-0 race (ADR 0103);
+ *  - `LeaseHeldError` / `LeaseLostError` (ADR 0130 D11), bare or as the `cause` of a
+ *    `StorageWriteError` (a write the lease gate refused) — a live owner holds the lease, or this
+ *    driver lost its own;
+ *  - `StaleFenceError`, bare or as the `cause` of a `StorageWriteError` — this attempt's token
+ *    was superseded by a newer `acquireFence` (a redispatch, a recovery pass, a fenced wake or a
+ *    cancel). The id check matters: a coalesced batch rejects every caller in it with ONE
+ *    writer's error (ADR 0074 L1), so a stale fence naming a different execution is that
+ *    writer's refusal and, for this one, a genuine storage failure — retryable;
+ *  - `ExecutionSupersededError` — the wire form of either.
+ *
+ * Not included: `StartLeaseHeldError` (a caller-chosen start that found a lease but NO sequence 0, a
+ * possible ghost; same reasoning) and `StartFencedOutError` (`@loomwork/workflow-runtime`) — a start refused on the fence
+ * with sequence 0 still absent. Its newer token's holder has written nothing and may be dead, so
+ * settling would lose the start outright; it stays retryable.
+ *
+ * Accepted imprecision: a coalesced batch holding writes for TWO fenced-out executions rejects
+ * both with the first one's error, so the second sees a stale fence naming another execution and
+ * retries. That retry takes a newer fence, so it can supersede the second execution's live holder
+ * and re-run its in-flight step once more; the holder it fences out then gets a refusal naming
+ * its own execution and settles. One bounded extra bounce per such batch — not a ping-pong —
+ * accepted rather than guessing which execution a batch error "really" meant.
+ *
+ * Every other error, including any other `StorageWriteError`, is `false`: a genuine failure is
+ * never swallowed. Matched by `name`, not class, because `@loomwork/worker-runtime` sits below the
+ * packages that define the first two (layering), and so a second bundled copy of any of them
+ * cannot hide a refusal — the same rule as `isStaleFence` in `@loomwork/workflow-runtime`.
+ */
+function isSupersededRefusal(err, executionId) {
+    const name = field(err, "name");
+    if (name === "ExecutionAlreadyExistsError" ||
+        name === "ExecutionSupersededError" ||
+        name === "StaleFenceError" ||
+        // ADR 0130 D11: a driver stood down (another live owner holds the lease) or lost its lease.
+        name === "LeaseHeldError" ||
+        name === "LeaseLostError") {
+        return field(err, "executionId") === executionId;
+    }
+    if (name === "StorageWriteError") {
+        const cause = field(err, "cause");
+        // ADR 0130 D11: a write refused because the lease behind it was lost (or held by another) is the
+        // same "another holder owns it" as a stale fence, when it names this execution.
+        const causeName = field(cause, "name");
+        return ((causeName === "StaleFenceError" ||
+            causeName === "LeaseLostError" ||
+            causeName === "LeaseHeldError") &&
+            field(cause, "executionId") === executionId);
+    }
+    return false;
+}
+//# sourceMappingURL=superseded.js.map

package/dist/superseded.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"superseded.js","sourceRoot":"","sources":["../src/superseded.ts"],"names":[],"mappings":";;;AA4EA,kDAyBC;AArGD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAa,wBAAyB,SAAQ,KAAK;IAEtC;IAEA;IAHX,YACW,WAAmB;IAC5B,uFAAuF;IAC9E,KAAe;QAExB,KAAK,CACH,cAAc,WAAW,kQAAkQ,CAC5R,CAAC;QANO,gBAAW,GAAX,WAAW,CAAQ;QAEnB,UAAK,GAAL,KAAK,CAAU;QAKxB,IAAI,CAAC,IAAI,GAAG,0BAA0B,CAAC;QACvC,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,wBAAwB,CAAC,SAAS,CAAC,CAAC;IAClE,CAAC;CACF;AAZD,4DAYC;AAED,SAAS,KAAK,CAAC,KAAc,EAAE,GAAW;IACxC,OAAO,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAChD,CAAC,CAAE,KAAiC,CAAC,GAAG,CAAC;QACzC,CAAC,CAAC,SAAS,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,SAAgB,mBAAmB,CAAC,GAAY,EAAE,WAAmB;IACnE,MAAM,IAAI,GAAG,KAAK,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IAChC,IACE,IAAI,KAAK,6BAA6B;QACtC,IAAI,KAAK,0BAA0B;QACnC,IAAI,KAAK,iBAAiB;QAC1B,4FAA4F;QAC5F,IAAI,KAAK,gBAAgB;QACzB,IAAI,KAAK,gBAAgB,EACzB,CAAC;QACD,OAAO,KAAK,CAAC,GAAG,EAAE,aAAa,CAAC,KAAK,WAAW,CAAC;IACnD,CAAC;IACD,IAAI,IAAI,KAAK,mBAAmB,EAAE,CAAC;QACjC,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC;QAClC,iGAAiG;QACjG,gFAAgF;QAChF,MAAM,SAAS,GAAG,KAAK,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;QACvC,OAAO,CACL,CAAC,SAAS,KAAK,iBAAiB;YAC9B,SAAS,KAAK,gBAAgB;YAC9B,SAAS,KAAK,gBAAgB,CAAC;YACjC,KAAK,CAAC,KAAK,EAAE,aAAa,CAAC,KAAK,WAAW,CAC5C,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,122 @@
+import type { ExecutionState, SuspendCondition } from "@loomwork/core";
+/**
+ * The immutable, JSON-serializable description of ONE execution to run on a
+ * worker. It is the sole payload that crosses the placement boundary
+ * (in-process, HTTP, Cloud Run). It carries **identity + resume coordinates**,
+ * never live code: the worker resolves the flow/effects by id from the code it
+ * was booted with (`flowId`), and reconstructs state from the shared event +
+ * snapshot stores.
+ *
+ * Two shapes:
+ *  - fresh start:  `input` set, `resumeEvent` absent.
+ *  - resume:       `resumeEvent` set (e.g. an approval decision). The worker
+ *                  rebuilds from the latest snapshot + event tail and continues.
+ */
+export interface ExecutionPackage {
+    executionId: string;
+    /** Workflow/flow definition id — used to fold identity and resolve code. */
+    workflowId: string;
+    /** Registry key the worker uses to resolve the flow's runner + effects. */
+    flowId: string;
+    /** Input for a fresh start. Ignored on resume (it lives in the event log). */
+    input?: unknown;
+    /** Present ⇒ this is a resume dispatch. Delivered as the resume payload. */
+    resumeEvent?: {
+        eventType: string;
+        payload: unknown;
+        waitId?: string;
+    };
+    /** Optional resume hints (a specific snapshot / event offset to rebuild from). */
+    snapshotId?: string;
+    fromSequence?: number;
+    /** Opaque routing/telemetry metadata; never load-bearing for correctness. */
+    metadata?: Record<string, unknown>;
+    /**
+     * R3 (DISPATCHER_SPI 1.2.0) — the AUTHENTICATED principal this dispatch acts for (a
+     * `PrincipalChain`: `actor`, `tenant`, …), as JSON. A worker that fails closed on a missing
+     * principal (`security.strict`) authorizes the start/resume/query/cancel against it; a package
+     * WITHOUT one is anonymous and is refused there unless the worker was explicitly given the
+     * kernel's system identity. It crosses the wire as plain data, so a receiving worker must
+     * only honour it from a caller it has AUTHENTICATED (the worker-server does so only when its
+     * `authorize` gate is configured): whoever can post a package can otherwise name any actor.
+     * Never load-bearing for placement.
+     */
+    principal?: Record<string, unknown>;
+}
+/** Where an execution ended for this dispatch. A suspend is a normal outcome. */
+export type ExecutionOutcome = "completed" | "suspended" | "failed";
+/**
+ * What a worker returns after running an ExecutionPackage to a terminal-or-
+ * suspended state and persisting its events/snapshot. This is exactly the JSON a
+ * remote worker sends back over `POST /execute`, plus the folded terminal state
+ * so in-process callers avoid a re-read.
+ */
+export interface ExecutionResult {
+    executionId: string;
+    status: ExecutionOutcome;
+    /** Folded execution state at the stopping point (completed / suspended / failed). */
+    state: ExecutionState;
+    /** `state.variables._output` on completion; convenience mirror. */
+    output?: unknown;
+    /** `state.variables._error` on failure; convenience mirror. */
+    error?: unknown;
+    /** The condition the execution suspended on, when `status === "suspended"`. */
+    suspendedOn?: SuspendCondition;
+    /** Highest event sequence persisted for this execution. */
+    lastSequence: number;
+}
+/** A request to reserve worker capacity for one execution. */
+export interface WorkerRequest {
+    executionId: string;
+    metadata?: Record<string, unknown>;
+    /** R3 — the dispatch's principal (see {@link ExecutionPackage.principal}), so allocation is authorized as the caller. */
+    principal?: Record<string, unknown>;
+}
+/**
+ * A reservation of worker capacity. For LocalWorkerRuntime this is a trivial
+ * in-process token; for CloudRunWorkerRuntime it names the allocated instance.
+ */
+export interface WorkerLease {
+    leaseId: string;
+    /**
+     * K9.4 — the monotonic fencing token this dispatch holds (acquired from a
+     * fencing event store at allocate time). Every event the run appends carries
+     * it, so after a re-dispatch acquires a newer token, this lease's holder can
+     * no longer write — a partitioned "zombie" worker is fenced out at the store.
+     * Absent on non-fencing stores (e.g. single-node SQLite): correlation only.
+     */
+    fence?: number;
+    metadata?: Record<string, unknown>;
+}
+/**
+ * The Platform SPI. A `WorkerRuntime` abstracts *how/where* an ExecutionPackage
+ * runs. Implementations: LocalWorkerRuntime (in-process), RemoteWorkerRuntime
+ * (HTTP), CloudRunWorkerRuntime. Optional platform capabilities
+ * (secrets/identity/logging/metrics) hang off the same adapter so cloud concerns
+ * stay isolated behind the interface.
+ */
+export interface WorkerRuntime {
+    /**
+     * R3 — OPTIONAL: `true` when this worker runs principal-less packages under the kernel's
+     * SYSTEM identity (it bypasses the execution authorizer). A transport that exposes the worker
+     * to a network (the worker-server) refuses to be built around such a worker without an
+     * authentication gate, because every caller it admits would otherwise be the system.
+     */
+    readonly runsAsSystem?: boolean;
+    allocate(request: WorkerRequest): Promise<WorkerLease>;
+    execute(lease: WorkerLease, pkg: ExecutionPackage): Promise<ExecutionResult>;
+    release(lease: WorkerLease): Promise<void>;
+    /**
+     * OPTIONAL (K8.5) — best-effort cancellation of an execution this worker may
+     * be driving: aborts its in-flight effect and records the durable
+     * `EXECUTION_CANCELLED`. Returns whether a cancellation was performed here
+     * (`false` when the execution is unknown to this worker or already terminal).
+     * Delivery is best-effort by contract: the caller's durable settlement — the
+     * orchestrator's `ExecutionRuntime.cancel()` fence-then-cancel against the
+     * shared store — never depends on this call reaching the worker; this exists
+     * so a live remote effect is severed promptly instead of running to fenced
+     * rejection.
+     */
+    cancel?(executionId: string, reason?: string): Promise<boolean>;
+}
+//# 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,cAAc,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAEvE;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,UAAU,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,8EAA8E;IAC9E,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,4EAA4E;IAC5E,WAAW,CAAC,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,OAAO,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACvE,kFAAkF;IAClF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED,iFAAiF;AACjF,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG,WAAW,GAAG,QAAQ,CAAC;AAEpE;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,gBAAgB,CAAC;IACzB,qFAAqF;IACrF,KAAK,EAAE,cAAc,CAAC;IACtB,mEAAmE;IACnE,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,+DAA+D;IAC/D,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,+EAA+E;IAC/E,WAAW,CAAC,EAAE,gBAAgB,CAAC;IAC/B,2DAA2D;IAC3D,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,8DAA8D;AAC9D,MAAM,WAAW,aAAa;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,yHAAyH;IACzH,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACrC;AAED;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IACvD,OAAO,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IAC7E,OAAO,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C;;;;;;;;;;OAUG;IACH,MAAM,CAAC,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACjE"}

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@loomwork/worker-runtime",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Worker runtime SPI for Loom — the platform-agnostic contract for executing an ExecutionPackage on some compute placement (local, remote HTTP, Cloud Run)",
+  "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"
+  },
+  "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/worker-runtime"
+  },
+  "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/index.ts

@@ -0,0 +1,9 @@
+export type {
+  ExecutionOutcome,
+  ExecutionPackage,
+  ExecutionResult,
+  WorkerLease,
+  WorkerRequest,
+  WorkerRuntime,
+} from "./types";
+export { ExecutionSupersededError, isSupersededRefusal } from "./superseded";

package/src/superseded.ts

@@ -0,0 +1,102 @@
+/**
+ * L20 (ADR 0004) — `execute` was refused because ANOTHER holder owns the execution. This is the
+ * portable form of that refusal: the HTTP worker answers it with
+ * `409 { code: "superseded", executionId }` and `RemoteWorkerRuntime` rethrows it as this error,
+ * so a caller on the far side of a wire can tell it apart from a transport or storage failure
+ * exactly as an in-process caller can.
+ *
+ * It is NOT a failed attempt. Every dispatch acquires a newer fence, so retrying it supersedes
+ * the holder that just won, which is then fenced out and retries in turn — the two ping-pong and
+ * each bounce re-runs the in-flight step. So a dispatcher settles it instead of retrying.
+ *
+ * What settling means: the refusal TRANSFERS ownership to the newer fence holder, and nothing
+ * here checks that holder is alive. Its liveness is covered only by its own dispatcher's policy
+ * (retries, `executeTimeoutMs`) and, past that, by `recoverAbandoned` — which a deployment MUST
+ * run to cover holders that die (a duplicate dispatcher that crashed mid-run, or one that timed
+ * out while its wedged instance kept the fence). Until then the execution may sit in `running`.
+ *
+ * The newer holder can even be this caller's own earlier attempt (an HTTP attempt that timed out
+ * but kept running): the execution then completes while `dispatch()` rejects with this error.
+ * So a caller that needs the OUTCOME should treat this error as "await by id" —
+ * `loadState` / `subscribe` on the same executionId — not as a failure of the execution.
+ */
+export class ExecutionSupersededError extends Error {
+  constructor(
+    readonly executionId: string,
+    /** What the worker was refused with, when known (in-process). Absent across a wire. */
+    readonly cause?: unknown
+  ) {
+    super(
+      `execution "${executionId}" is owned by another holder (a lost start race or a newer fence); this dispatch was superseded, not failed — redispatching would fence that holder out. Await the execution by id (loadState/subscribe); if its holder has died, recoverAbandoned re-drives it.`
+    );
+    this.name = "ExecutionSupersededError";
+    Object.setPrototypeOf(this, ExecutionSupersededError.prototype);
+  }
+}
+
+function field(value: unknown, key: string): unknown {
+  return value !== null && typeof value === "object"
+    ? (value as Record<string, unknown>)[key]
+    : undefined;
+}
+
+/**
+ * L20 (ADR 0004) — does `err` mean "a newer or other holder owns `executionId`", rather than
+ * "this attempt failed"? A dispatcher MUST NOT retry or redispatch on `true`.
+ *
+ * Exactly three shapes, each REQUIRED to name `executionId` so an error about some other
+ * execution never qualifies:
+ *  - `ExecutionAlreadyExistsError` — a start lost the sequence-0 race (ADR 0103);
+ *  - `LeaseHeldError` / `LeaseLostError` (ADR 0130 D11), bare or as the `cause` of a
+ *    `StorageWriteError` (a write the lease gate refused) — a live owner holds the lease, or this
+ *    driver lost its own;
+ *  - `StaleFenceError`, bare or as the `cause` of a `StorageWriteError` — this attempt's token
+ *    was superseded by a newer `acquireFence` (a redispatch, a recovery pass, a fenced wake or a
+ *    cancel). The id check matters: a coalesced batch rejects every caller in it with ONE
+ *    writer's error (ADR 0074 L1), so a stale fence naming a different execution is that
+ *    writer's refusal and, for this one, a genuine storage failure — retryable;
+ *  - `ExecutionSupersededError` — the wire form of either.
+ *
+ * Not included: `StartLeaseHeldError` (a caller-chosen start that found a lease but NO sequence 0, a
+ * possible ghost; same reasoning) and `StartFencedOutError` (`@loomwork/workflow-runtime`) — a start refused on the fence
+ * with sequence 0 still absent. Its newer token's holder has written nothing and may be dead, so
+ * settling would lose the start outright; it stays retryable.
+ *
+ * Accepted imprecision: a coalesced batch holding writes for TWO fenced-out executions rejects
+ * both with the first one's error, so the second sees a stale fence naming another execution and
+ * retries. That retry takes a newer fence, so it can supersede the second execution's live holder
+ * and re-run its in-flight step once more; the holder it fences out then gets a refusal naming
+ * its own execution and settles. One bounded extra bounce per such batch — not a ping-pong —
+ * accepted rather than guessing which execution a batch error "really" meant.
+ *
+ * Every other error, including any other `StorageWriteError`, is `false`: a genuine failure is
+ * never swallowed. Matched by `name`, not class, because `@loomwork/worker-runtime` sits below the
+ * packages that define the first two (layering), and so a second bundled copy of any of them
+ * cannot hide a refusal — the same rule as `isStaleFence` in `@loomwork/workflow-runtime`.
+ */
+export function isSupersededRefusal(err: unknown, executionId: string): boolean {
+  const name = field(err, "name");
+  if (
+    name === "ExecutionAlreadyExistsError" ||
+    name === "ExecutionSupersededError" ||
+    name === "StaleFenceError" ||
+    // ADR 0130 D11: a driver stood down (another live owner holds the lease) or lost its lease.
+    name === "LeaseHeldError" ||
+    name === "LeaseLostError"
+  ) {
+    return field(err, "executionId") === executionId;
+  }
+  if (name === "StorageWriteError") {
+    const cause = field(err, "cause");
+    // ADR 0130 D11: a write refused because the lease behind it was lost (or held by another) is the
+    // same "another holder owns it" as a stale fence, when it names this execution.
+    const causeName = field(cause, "name");
+    return (
+      (causeName === "StaleFenceError" ||
+        causeName === "LeaseLostError" ||
+        causeName === "LeaseHeldError") &&
+      field(cause, "executionId") === executionId
+    );
+  }
+  return false;
+}

package/src/types.ts

@@ -0,0 +1,123 @@
+import type { ExecutionState, SuspendCondition } from "@loomwork/core";
+
+/**
+ * The immutable, JSON-serializable description of ONE execution to run on a
+ * worker. It is the sole payload that crosses the placement boundary
+ * (in-process, HTTP, Cloud Run). It carries **identity + resume coordinates**,
+ * never live code: the worker resolves the flow/effects by id from the code it
+ * was booted with (`flowId`), and reconstructs state from the shared event +
+ * snapshot stores.
+ *
+ * Two shapes:
+ *  - fresh start:  `input` set, `resumeEvent` absent.
+ *  - resume:       `resumeEvent` set (e.g. an approval decision). The worker
+ *                  rebuilds from the latest snapshot + event tail and continues.
+ */
+export interface ExecutionPackage {
+  executionId: string;
+  /** Workflow/flow definition id — used to fold identity and resolve code. */
+  workflowId: string;
+  /** Registry key the worker uses to resolve the flow's runner + effects. */
+  flowId: string;
+  /** Input for a fresh start. Ignored on resume (it lives in the event log). */
+  input?: unknown;
+  /** Present ⇒ this is a resume dispatch. Delivered as the resume payload. */
+  resumeEvent?: { eventType: string; payload: unknown; waitId?: string };
+  /** Optional resume hints (a specific snapshot / event offset to rebuild from). */
+  snapshotId?: string;
+  fromSequence?: number;
+  /** Opaque routing/telemetry metadata; never load-bearing for correctness. */
+  metadata?: Record<string, unknown>;
+  /**
+   * R3 (DISPATCHER_SPI 1.2.0) — the AUTHENTICATED principal this dispatch acts for (a
+   * `PrincipalChain`: `actor`, `tenant`, …), as JSON. A worker that fails closed on a missing
+   * principal (`security.strict`) authorizes the start/resume/query/cancel against it; a package
+   * WITHOUT one is anonymous and is refused there unless the worker was explicitly given the
+   * kernel's system identity. It crosses the wire as plain data, so a receiving worker must
+   * only honour it from a caller it has AUTHENTICATED (the worker-server does so only when its
+   * `authorize` gate is configured): whoever can post a package can otherwise name any actor.
+   * Never load-bearing for placement.
+   */
+  principal?: Record<string, unknown>;
+}
+
+/** Where an execution ended for this dispatch. A suspend is a normal outcome. */
+export type ExecutionOutcome = "completed" | "suspended" | "failed";
+
+/**
+ * What a worker returns after running an ExecutionPackage to a terminal-or-
+ * suspended state and persisting its events/snapshot. This is exactly the JSON a
+ * remote worker sends back over `POST /execute`, plus the folded terminal state
+ * so in-process callers avoid a re-read.
+ */
+export interface ExecutionResult {
+  executionId: string;
+  status: ExecutionOutcome;
+  /** Folded execution state at the stopping point (completed / suspended / failed). */
+  state: ExecutionState;
+  /** `state.variables._output` on completion; convenience mirror. */
+  output?: unknown;
+  /** `state.variables._error` on failure; convenience mirror. */
+  error?: unknown;
+  /** The condition the execution suspended on, when `status === "suspended"`. */
+  suspendedOn?: SuspendCondition;
+  /** Highest event sequence persisted for this execution. */
+  lastSequence: number;
+}
+
+/** A request to reserve worker capacity for one execution. */
+export interface WorkerRequest {
+  executionId: string;
+  metadata?: Record<string, unknown>;
+  /** R3 — the dispatch's principal (see {@link ExecutionPackage.principal}), so allocation is authorized as the caller. */
+  principal?: Record<string, unknown>;
+}
+
+/**
+ * A reservation of worker capacity. For LocalWorkerRuntime this is a trivial
+ * in-process token; for CloudRunWorkerRuntime it names the allocated instance.
+ */
+export interface WorkerLease {
+  leaseId: string;
+  /**
+   * K9.4 — the monotonic fencing token this dispatch holds (acquired from a
+   * fencing event store at allocate time). Every event the run appends carries
+   * it, so after a re-dispatch acquires a newer token, this lease's holder can
+   * no longer write — a partitioned "zombie" worker is fenced out at the store.
+   * Absent on non-fencing stores (e.g. single-node SQLite): correlation only.
+   */
+  fence?: number;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * The Platform SPI. A `WorkerRuntime` abstracts *how/where* an ExecutionPackage
+ * runs. Implementations: LocalWorkerRuntime (in-process), RemoteWorkerRuntime
+ * (HTTP), CloudRunWorkerRuntime. Optional platform capabilities
+ * (secrets/identity/logging/metrics) hang off the same adapter so cloud concerns
+ * stay isolated behind the interface.
+ */
+export interface WorkerRuntime {
+  /**
+   * R3 — OPTIONAL: `true` when this worker runs principal-less packages under the kernel's
+   * SYSTEM identity (it bypasses the execution authorizer). A transport that exposes the worker
+   * to a network (the worker-server) refuses to be built around such a worker without an
+   * authentication gate, because every caller it admits would otherwise be the system.
+   */
+  readonly runsAsSystem?: boolean;
+  allocate(request: WorkerRequest): Promise<WorkerLease>;
+  execute(lease: WorkerLease, pkg: ExecutionPackage): Promise<ExecutionResult>;
+  release(lease: WorkerLease): Promise<void>;
+  /**
+   * OPTIONAL (K8.5) — best-effort cancellation of an execution this worker may
+   * be driving: aborts its in-flight effect and records the durable
+   * `EXECUTION_CANCELLED`. Returns whether a cancellation was performed here
+   * (`false` when the execution is unknown to this worker or already terminal).
+   * Delivery is best-effort by contract: the caller's durable settlement — the
+   * orchestrator's `ExecutionRuntime.cancel()` fence-then-cancel against the
+   * shared store — never depends on this call reaching the worker; this exists
+   * so a live remote effect is severed promptly instead of running to fenced
+   * rejection.
+   */
+  cancel?(executionId: string, reason?: string): Promise<boolean>;
+}