@nylorun/runtime 0.15.1-beta → 0.16.0-beta

package/dist/blob/types.d.ts

@@ -0,0 +1,108 @@
+/**
+ * The `BlobStore` seam (blueprint D35, F8.1): the only way the Runtime reaches the Object
+ * store. Bytes live here; what they mean lives in Postgres, which is the commit point: an
+ * object counts only once a committed row references its key, so an orphaned upload is
+ * garbage, never data. Keys are chosen by the Runtime (fresh random ids), so the seam needs no
+ * conditional writes.
+ *
+ * Two adapters, held to one conformance suite (`test/blob/conformance.ts`):
+ * - `s3` (`./s3.ts`): the plain S3 API, against RustFS in the local stack and S3 or any S3
+ *   server elsewhere;
+ * - `fs` (`./fs.ts`): files under a directory, for embedding and tests.
+ */
+/** A body to store: bytes, a web stream, or any async iterable of chunks (a Node stream). */
+export type BlobBody = Uint8Array | ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>;
+export interface BlobPutOptions {
+    /** Stored with the object and returned by `head` and `get`. Default `application/octet-stream`. */
+    contentType?: string;
+    /**
+     * Refuse a body longer than this many bytes with `BlobTooLargeError`; nothing is stored. The
+     * body is counted as it streams, so a caller need not know its length up front.
+     */
+    maxBytes?: number;
+    signal?: AbortSignal;
+}
+export interface BlobPutResult {
+    key: string;
+    /** Bytes stored. */
+    size: number;
+    /** SHA-256 of the bytes stored, lowercase hex. */
+    sha256: string;
+}
+export interface BlobMeta {
+    key: string;
+    /** The whole object's size in bytes. */
+    size: number;
+    contentType: string;
+    lastModified: Date;
+}
+/** Bytes `start` to `end`, both inclusive, as in an HTTP `Range` header. */
+export interface BlobRange {
+    start: number;
+    /** Inclusive; past the end of the object means "to the end". Default: to the end. */
+    end?: number;
+}
+export interface BlobGetOptions {
+    /** Only these bytes. A range that starts at or past the end throws `BlobRangeError`. */
+    range?: BlobRange;
+    signal?: AbortSignal;
+}
+export interface BlobGetResult extends BlobMeta {
+    /** The bytes asked for: the whole object, or the range. Read it or cancel it. */
+    body: ReadableStream<Uint8Array>;
+    /** Present when a range was asked for: the bytes `body` holds, both inclusive. */
+    range?: {
+        start: number;
+        end: number;
+    };
+}
+/** An entry of `list`: the object's key, size and when it was last written. */
+export interface BlobListEntry {
+    key: string;
+    size: number;
+    lastModified: Date;
+}
+export interface BlobStore {
+    /** Which adapter this is, for logs and `/ready`. */
+    readonly kind: "fs" | "s3";
+    /** Store `body` at `key`, replacing what is there. Streams; counts and hashes as it goes. */
+    put(key: string, body: BlobBody, options?: BlobPutOptions): Promise<BlobPutResult>;
+    /** The object's bytes and metadata, or `undefined` when there is none at `key`. */
+    get(key: string, options?: BlobGetOptions): Promise<BlobGetResult | undefined>;
+    /** The object's metadata, or `undefined` when there is none at `key`. */
+    head(key: string): Promise<BlobMeta | undefined>;
+    /** Remove the object; removing one that is not there succeeds. */
+    delete(key: string): Promise<void>;
+    /** Every object whose key starts with `prefix`, in key order. */
+    list(prefix: string): AsyncIterable<BlobListEntry>;
+}
+/** The Object store failed or refused a request; `status` is the HTTP status when it has one. */
+export declare class BlobStoreError extends Error {
+    readonly status?: number | undefined;
+    readonly code?: string | undefined;
+    constructor(message: string, status?: number | undefined, code?: string | undefined);
+}
+/** A `put` body grew past `maxBytes`. Nothing was stored. */
+export declare class BlobTooLargeError extends Error {
+    readonly maxBytes: number;
+    constructor(maxBytes: number);
+}
+/** A `get` range starts at or past the end of the object (HTTP 416). */
+export declare class BlobRangeError extends Error {
+    readonly range: BlobRange;
+    readonly size: number;
+    constructor(range: BlobRange, size: number);
+}
+export declare const DEFAULT_CONTENT_TYPE = "application/octet-stream";
+export declare const MAX_KEY_BYTES = 1024;
+/**
+ * Keys are `/`-separated segments of `A-Z a-z 0-9 . _ -`, neither `.` nor `..`, at most 1024
+ * bytes: safe as S3 keys without encoding surprises and as relative paths for `fs`.
+ */
+export declare function assertBlobKey(key: string): void;
+/** A `list` prefix: empty, a key, or a key followed by `/` (or the start of a segment). */
+export declare function assertBlobPrefix(prefix: string): void;
+export declare function assertRange(range: BlobRange): void;
+export declare function assertMaxBytes(maxBytes: number | undefined): void;
+/** The chunks of a `BlobBody`, as `Uint8Array`s. */
+export declare function chunksOf(body: BlobBody): AsyncGenerator<Uint8Array>;

package/dist/blob/types.js

@@ -0,0 +1,85 @@
+/**
+ * The `BlobStore` seam (blueprint D35, F8.1): the only way the Runtime reaches the Object
+ * store. Bytes live here; what they mean lives in Postgres, which is the commit point: an
+ * object counts only once a committed row references its key, so an orphaned upload is
+ * garbage, never data. Keys are chosen by the Runtime (fresh random ids), so the seam needs no
+ * conditional writes.
+ *
+ * Two adapters, held to one conformance suite (`test/blob/conformance.ts`):
+ * - `s3` (`./s3.ts`): the plain S3 API, against RustFS in the local stack and S3 or any S3
+ *   server elsewhere;
+ * - `fs` (`./fs.ts`): files under a directory, for embedding and tests.
+ */
+/** The Object store failed or refused a request; `status` is the HTTP status when it has one. */
+export class BlobStoreError extends Error {
+    status;
+    code;
+    constructor(message, status, code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "BlobStoreError";
+    }
+}
+/** A `put` body grew past `maxBytes`. Nothing was stored. */
+export class BlobTooLargeError extends Error {
+    maxBytes;
+    constructor(maxBytes) {
+        super(`The body is larger than ${maxBytes} bytes`);
+        this.maxBytes = maxBytes;
+        this.name = "BlobTooLargeError";
+    }
+}
+/** A `get` range starts at or past the end of the object (HTTP 416). */
+export class BlobRangeError extends Error {
+    range;
+    size;
+    constructor(range, size) {
+        super(`Range ${range.start}-${range.end ?? ""} is outside an object of ${size} bytes`);
+        this.range = range;
+        this.size = size;
+        this.name = "BlobRangeError";
+    }
+}
+export const DEFAULT_CONTENT_TYPE = "application/octet-stream";
+export const MAX_KEY_BYTES = 1024;
+const SEGMENT = /^[A-Za-z0-9._-]+$/;
+/**
+ * Keys are `/`-separated segments of `A-Z a-z 0-9 . _ -`, neither `.` nor `..`, at most 1024
+ * bytes: safe as S3 keys without encoding surprises and as relative paths for `fs`.
+ */
+export function assertBlobKey(key) {
+    if (typeof key !== "string" || key === "" || key.length > MAX_KEY_BYTES)
+        throw new TypeError(`Blob key must be 1 to ${MAX_KEY_BYTES} characters`);
+    for (const segment of key.split("/"))
+        if (!SEGMENT.test(segment) || segment === "." || segment === "..")
+            throw new TypeError(`Blob key ${JSON.stringify(key)} must be /-separated segments of A-Z a-z 0-9 . _ -, none . or ..`);
+}
+/** A `list` prefix: empty, a key, or a key followed by `/` (or the start of a segment). */
+export function assertBlobPrefix(prefix) {
+    if (prefix === "")
+        return;
+    assertBlobKey(prefix.endsWith("/") ? prefix.slice(0, -1) : prefix);
+}
+export function assertRange(range) {
+    if (!Number.isSafeInteger(range.start) || range.start < 0)
+        throw new TypeError("Range start must be a non-negative integer");
+    if (range.end !== undefined && (!Number.isSafeInteger(range.end) || range.end < range.start))
+        throw new TypeError("Range end must be an integer no smaller than start");
+}
+export function assertMaxBytes(maxBytes) {
+    if (maxBytes !== undefined && (!Number.isSafeInteger(maxBytes) || maxBytes < 0))
+        throw new TypeError("maxBytes must be a non-negative integer");
+}
+/** The chunks of a `BlobBody`, as `Uint8Array`s. */
+export async function* chunksOf(body) {
+    if (body instanceof Uint8Array) {
+        yield body;
+        return;
+    }
+    for await (const chunk of body) {
+        if (!(chunk instanceof Uint8Array))
+            throw new TypeError("A blob body must yield Uint8Array chunks");
+        yield chunk;
+    }
+}

package/dist/core/sandbox-routes.d.ts

@@ -1,5 +1,5 @@
 import type { Action } from "@nylorun/core/contracts";
-import type { SandboxManager } from "../sandbox/manager.js";
+import type { WorkspacePort } from "../harness-api/workspace.js";
 import type { SandboxToolOutcome } from "../sandbox/tools.js";
 import { type SessionSandboxRef } from "../sandbox/share.js";
 export declare class SandboxRouteError extends Error {
@@ -16,7 +16,7 @@ export type SandboxRouteRead = {
     readonly lookup: (id: string) => SessionSandboxRef | undefined;
 };
 export type SandboxRouteDeps = {
-    readonly sandbox: SandboxManager;
+    readonly sandbox: Pick<WorkspacePort, "run">;
     /** The session (rejects when missing) and its owner chain, read in one transaction. */
     readonly session: (id: string) => Promise<SandboxRouteRead>;
     readonly getAction: (id: string) => Promise<Action | undefined>;

package/dist/core/sandbox-routes.js

@@ -3,7 +3,7 @@
  * Wired from TenantRuntime; keeps route bodies out of the hot runtime file.
  */
 import { isSandboxToolName, } from "@nylorun/core/define";
-import { capabilityForSandbox, owningSandboxSessionId, sandboxSpecOf, sandboxSpecsEqual, sessionSandboxSpec, } from "../sandbox/share.js";
+import { capabilityForSandbox, owningSandboxSessionId, sandboxSpecOf, sandboxWorkspaceOf, sandboxSpecsEqual, sessionSandboxSpec, } from "../sandbox/share.js";
 export class SandboxRouteError extends Error {
     status;
     constructor(status, message) {
@@ -36,11 +36,12 @@ function toolInput(body) {
 }
 async function runTool(deps, { session, lookup }, tool, input, signal) {
     const spec = resolveSpec(session, lookup);
-    const ownerId = owningSandboxSessionId(session, lookup);
+    const workspace = sandboxWorkspaceOf(session, lookup);
     const ref = {
-        id: ownerId,
+        id: workspace.ownerId,
         activeTurnId: session.activeTurnId,
         manifest: session.manifest,
+        ...(workspace.sandboxId === undefined ? {} : { sandboxId: workspace.sandboxId }),
     };
     return deps.sandbox.run(ref, capabilityForSandbox(spec), tool, input, signal);
 }

package/dist/execution/memory.d.ts

@@ -1,4 +1,4 @@
-import { type DurableExecution, type Wake, type WorkerHandlers } from "./types.js";
+import { type DurableExecution, type SandboxSignal, type Wake, type WorkerHandlers } from "./types.js";
 export interface MemoryExecutionOptions {
     /** Delay between sweep passes of one Tenant. Default 5000. */
     sweepIntervalMs?: number;
@@ -8,6 +8,11 @@ export interface MemoryExecutionOptions {
     maxAttempts?: number;
     /** How long a dedupe key merges repeated wakes. Default 24 hours. */
     dedupeRetentionMs?: number;
+    /**
+     * How long `stop` waits for running handlers after aborting them; the ones still running
+     * then are abandoned. Default `DEFAULT_STOP_GRACE_MS`.
+     */
+    stopGraceMs?: number;
     /** Receives handler failures that are not retried. */
     onError?: (error: unknown) => void;
 }
@@ -23,16 +28,21 @@ export declare class MemoryExecution implements DurableExecution {
     private readonly seen;
     private readonly timers;
     private readonly sweeps;
+    private readonly sandboxes;
     private readonly delayed;
     private readonly inflight;
     private readonly sweepIntervalMs;
     private readonly retryDelayMs;
     private readonly maxAttempts;
     private readonly dedupeRetentionMs;
+    private readonly stopGraceMs;
     private readonly onError;
     constructor(options?: MemoryExecutionOptions);
     wake(tenantId: string, sessionId: string, wake: Wake): Promise<void>;
     deliver(tenantId: string, actionId: string): Promise<void>;
+    sandbox(tenantId: string, sandboxId: string, signal: SandboxSignal): Promise<void>;
+    private armSandbox;
+    private runSandbox;
     timer(tenantId: string, key: string, at: Date): Promise<void>;
     armSweep(tenantId: string): Promise<void>;
     disarmSweep(tenantId: string): Promise<void>;

package/dist/execution/memory.js

@@ -1,4 +1,4 @@
-import { WAKE_REASONS, sessionKey, } from "./types.js";
+import { DEFAULT_STOP_GRACE_MS, WAKE_REASONS, sessionKey, settleWithin, } from "./types.js";
 /**
  * In-process `DurableExecution`. Not durable: wakes, timers and sweeps live in
  * memory. It keeps the seam's ordering guarantees within one process, which is
@@ -11,18 +11,21 @@ export class MemoryExecution {
     seen = new Map();
     timers = new Map();
     sweeps = new Map();
+    sandboxes = new Map();
     delayed = new Set();
     inflight = new Set();
     sweepIntervalMs;
     retryDelayMs;
     maxAttempts;
     dedupeRetentionMs;
+    stopGraceMs;
     onError;
     constructor(options = {}) {
         this.sweepIntervalMs = options.sweepIntervalMs ?? 5000;
         this.retryDelayMs = options.retryDelayMs ?? 50;
         this.maxAttempts = options.maxAttempts ?? 5;
         this.dedupeRetentionMs = options.dedupeRetentionMs ?? 24 * 60 * 60_000;
+        this.stopGraceMs = options.stopGraceMs ?? DEFAULT_STOP_GRACE_MS;
         this.onError =
             options.onError ??
                 ((error) => queueMicrotask(() => {
@@ -46,6 +49,66 @@ export class MemoryExecution {
     async deliver(tenantId, actionId) {
         this.enqueue("deliver", tenantId, actionId);
     }
+    async sandbox(tenantId, sandboxId, signal) {
+        const key = `${tenantId}\u0000${sandboxId}`;
+        let state = this.sandboxes.get(key);
+        if (!state)
+            this.sandboxes.set(key, (state = { tenantId, sandboxId, tail: Promise.resolve(), pending: [], attempts: 0, timers: new Map() }));
+        if (signal.kind === "arm")
+            this.armSandbox(state, signal.timer, signal.at);
+        else
+            this.runSandbox(state, "reconcile");
+    }
+    armSandbox(state, timer, at) {
+        const existing = state.timers.get(timer);
+        if (existing?.handle)
+            clearTimeout(existing.handle);
+        const entry = { at };
+        state.timers.set(timer, entry);
+        if (!this.handlers)
+            return;
+        entry.handle = setTimeout(() => {
+            if (state.timers.get(timer) !== entry)
+                return;
+            state.timers.delete(timer);
+            this.runSandbox(state, timer === "retry" ? "reconcile" : timer);
+        }, Math.max(0, at - Date.now()));
+    }
+    runSandbox(state, trigger) {
+        const handlers = this.handlers;
+        if (!handlers) {
+            state.pending.push(trigger);
+            return;
+        }
+        const run = state.tail.then(async () => {
+            if (!this.handlers)
+                return;
+            if (!handlers.sandbox) {
+                this.onError(new Error("WorkerHandlers.sandbox is required for sandbox reconciles"));
+                return;
+            }
+            const controller = new AbortController();
+            try {
+                const result = await handlers.sandbox(state.tenantId, state.sandboxId, trigger, controller.signal);
+                state.attempts = 0;
+                for (const item of result.arm ?? [])
+                    this.armSandbox(state, item.timer, item.at);
+                if (result.retryAfterMs !== undefined)
+                    this.armSandbox(state, "retry", Date.now() + Math.max(0, result.retryAfterMs));
+            }
+            catch (error) {
+                state.attempts += 1;
+                if (state.attempts >= this.maxAttempts) {
+                    state.attempts = 0;
+                    this.onError(error);
+                }
+                else
+                    this.armSandbox(state, "retry", Date.now() + this.retryDelayMs * 2 ** (state.attempts - 1));
+            }
+        });
+        state.tail = run.catch(() => undefined);
+        this.track(state.tail);
+    }
     async timer(tenantId, key, at) {
         const id = `${tenantId}\u0000${key}`;
         const existing = this.timers.get(id);
@@ -81,6 +144,12 @@ export class MemoryExecution {
             this.armTimer(id, timer);
         for (const [tenantId, sweep] of this.sweeps)
             this.scheduleSweep(tenantId, sweep, 0);
+        for (const state of this.sandboxes.values()) {
+            for (const [timer, entry] of state.timers)
+                this.armSandbox(state, timer, entry.at);
+            for (const trigger of state.pending.splice(0))
+                this.runSandbox(state, trigger);
+        }
     }
     async stop() {
         this.handlers = undefined;
@@ -93,10 +162,15 @@ export class MemoryExecution {
         for (const sweep of this.sweeps.values())
             if (sweep.handle)
                 clearTimeout(sweep.handle);
+        for (const state of this.sandboxes.values())
+            for (const entry of state.timers.values())
+                if (entry.handle)
+                    clearTimeout(entry.handle);
         for (const state of this.keys.values())
             state.controller?.abort();
-        while (this.inflight.size > 0)
-            await Promise.allSettled(this.inflight);
+        // Bounded: a handler that ignores its abort is abandoned and runs on unwaited. An
+        // abandoned advance's lease lapses and the next advance takes the session over (§11.4).
+        await settleWithin(this.inflight, this.stopGraceMs);
     }
     /**
      * Resolves once no advance or delivery is running or queued and no busy or

package/dist/execution/types.d.ts

@@ -37,6 +37,13 @@
  * - **Retry after `retry`.** A delivery that returns `retry` is run again for
  *   the same key after `retryAfterMs`. This is how an Action endpoint that is
  *   down or busy is retried; the handler throws only on infrastructure errors.
+ * - **One reconcile per sandbox at a time** (F7.2). `sandbox` runs
+ *   `WorkerHandlers.sandbox` for the key `<tenantId>:<sandboxId>` at least once
+ *   after a `reconcile` resolves, never overlapping another run for the key. A
+ *   run that answers `retryAfterMs` runs again after it (one pending retry per
+ *   key: a later one replaces it), and each timer it answers is armed. `arm`
+ *   sets one of the sandbox's timers (`idle`, `ttl`): setting it again replaces
+ *   the earlier time, and the run it causes is told which timer fired.
  */
 /** Why a session is woken (§12.3, "Where wakes come from"). */
 export type WakeReason = 
@@ -69,6 +76,28 @@ export type AdvanceResult = {
     status: "busy";
     retryAfterMs: number;
 };
+/** A pod sandbox's timers. */
+export type SandboxTimer = "idle" | "ttl";
+/** What `DurableExecution.sandbox` asks for: a reconcile, or a timer. */
+export type SandboxSignal = {
+    kind: "reconcile";
+} | {
+    kind: "arm";
+    timer: SandboxTimer;
+    at: number;
+};
+/** Why `WorkerHandlers.sandbox` runs. */
+export type SandboxTrigger = "reconcile" | SandboxTimer;
+/** What a sandbox reconcile asks for next. */
+export interface SandboxResult {
+    /** Run again this soon. */
+    retryAfterMs?: number;
+    /** Timers to set, at ms since the epoch. */
+    arm?: readonly {
+        timer: SandboxTimer;
+        at: number;
+    }[];
+}
 export type DeliverResult = {
     status: "done";
 }
@@ -94,6 +123,11 @@ export interface WorkerHandlers {
      * stops. Throw only on infrastructure errors. Required when `deliver` is used.
      */
     deliver?(tenantId: string, actionId: string, signal: AbortSignal): Promise<DeliverResult>;
+    /**
+     * Reconciles one pod sandbox (F7.2), serialized per sandbox. Throw only on infrastructure
+     * errors. Required when `sandbox` is used.
+     */
+    sandbox?(tenantId: string, sandboxId: string, trigger: SandboxTrigger, signal: AbortSignal): Promise<SandboxResult>;
 }
 export interface DurableExecution {
     /** At-least-once. `dedupeKey` merges repeated wakes for the same cause. */
@@ -110,13 +144,22 @@ export interface DurableExecution {
      * after the transaction that made the Action pending commits.
      */
     deliver(tenantId: string, actionId: string): Promise<void>;
+    /**
+     * A pod sandbox's reconcile, or one of its timers (F7.2): see "One reconcile per sandbox
+     * at a time". Absent where pods are not supported.
+     */
+    sandbox?(tenantId: string, sandboxId: string, signal: SandboxSignal): Promise<void>;
     /** Arms the Tenant's self-re-arming sweep. Idempotent. */
     armSweep(tenantId: string): Promise<void>;
     /** Stops re-arming the Tenant's sweep (Tenant deleted). A pass already running finishes. */
     disarmSweep(tenantId: string): Promise<void>;
     /** Starts delivering to `handlers` (serving the Worker endpoint, for Restate). */
     start(handlers: WorkerHandlers): Promise<void>;
-    /** Stops delivering, aborts running advances' signals and waits for them. */
+    /**
+     * Stops delivering, aborts running advances' signals and waits for them, up to the
+     * implementation's stop grace (`DEFAULT_STOP_GRACE_MS`). Handlers still running then are
+     * abandoned: their sessions' leases lapse and the next advance takes over (§11.4).
+     */
     stop(): Promise<void>;
     /**
      * Resolves when the backing service answers, rejects otherwise (readiness,
@@ -155,3 +198,13 @@ export declare function parseSessionKey(key: string): {
     tenantId: string;
     sessionId: string;
 };
+/**
+ * Default time `DurableExecution.stop` waits for running handlers after aborting them: the
+ * advance grace period (`DEFAULT_ADVANCE_GRACE_MS` in `tenant/worker.ts`).
+ */
+export declare const DEFAULT_STOP_GRACE_MS = 30000;
+/**
+ * Waits until `inflight` is empty (it shrinks as its promises settle and may grow meanwhile),
+ * for at most `graceMs`. Resolves to how many were still running when the grace ran out.
+ */
+export declare function settleWithin(inflight: ReadonlySet<Promise<unknown>>, graceMs: number): Promise<number>;

package/dist/execution/types.js

@@ -37,6 +37,13 @@
  * - **Retry after `retry`.** A delivery that returns `retry` is run again for
  *   the same key after `retryAfterMs`. This is how an Action endpoint that is
  *   down or busy is retried; the handler throws only on infrastructure errors.
+ * - **One reconcile per sandbox at a time** (F7.2). `sandbox` runs
+ *   `WorkerHandlers.sandbox` for the key `<tenantId>:<sandboxId>` at least once
+ *   after a `reconcile` resolves, never overlapping another run for the key. A
+ *   run that answers `retryAfterMs` runs again after it (one pending retry per
+ *   key: a later one replaces it), and each timer it answers is armed. `arm`
+ *   sets one of the sandbox's timers (`idle`, `ttl`): setting it again replaces
+ *   the earlier time, and the run it causes is told which timer fired.
  */
 export const WAKE_REASONS = [
     "message",
@@ -59,3 +66,27 @@ export function parseSessionKey(key) {
         throw new Error(`Invalid session key: ${key}`);
     return { tenantId: key.slice(0, at), sessionId: key.slice(at + 1) };
 }
+/**
+ * Default time `DurableExecution.stop` waits for running handlers after aborting them: the
+ * advance grace period (`DEFAULT_ADVANCE_GRACE_MS` in `tenant/worker.ts`).
+ */
+export const DEFAULT_STOP_GRACE_MS = 30_000;
+/**
+ * Waits until `inflight` is empty (it shrinks as its promises settle and may grow meanwhile),
+ * for at most `graceMs`. Resolves to how many were still running when the grace ran out.
+ */
+export async function settleWithin(inflight, graceMs) {
+    let timer;
+    const expired = new Promise((resolve) => {
+        timer = setTimeout(() => resolve("expired"), Math.max(0, graceMs));
+    });
+    try {
+        while (inflight.size > 0)
+            if ((await Promise.race([Promise.allSettled(inflight), expired])) === "expired")
+                break;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    return inflight.size;
+}

package/dist/gates/contract.d.ts

@@ -3,20 +3,24 @@
  * it is not in the published OpenAPI documents.
  *
  * `POST /nylorun/v1/model-calls`
- * - Headers: `Authorization: Bearer <NYLORUN_GATES_TOKEN>`, `Idempotency-Key: <effect id>`,
- *   and optionally `Nylorun-Tenant: <tenant id>`, which must then be the database's one
- *   Tenant (a call naming another is refused).
- * - Body: `ModelCallBody`, at most `MAX_MODEL_CALL_BYTES`.
+ * - Headers: `Authorization: Bearer <run token>` (F5, `tenant/run-token.ts`), `Idempotency-Key:
+ *   <effect id>`, and optionally `Nylorun-Tenant: <tenant id>`, which must then be the token's
+ *   Tenant. Core's credential (`NYLORUN_GATES_TOKEN`) is refused: only a run calls the model.
+ * - Body: `ModelCallBody`, at most `MAX_MODEL_CALL_BYTES`. It names no session, turn or agent:
+ *   the gate takes them from the token, and refuses a body that names them.
  * - `200 {outcome}` once the call has finished, whether the outcome is a candidate or a
- *   failure; nothing is sent while it runs. `401 gate_unauthorized` for a missing or wrong
- *   token, `400 invalid_request` for a malformed Tenant header or a bad body, `409
- *   gate_conflict` when a different request already runs under the same key.
+ *   failure; nothing is sent while it runs. `401 gate_unauthorized` for a missing, malformed,
+ *   expired or foreign token, `409 run_stale` when the token's lease is no longer the
+ *   session's (a cancel, a new turn, a takeover), `400 invalid_request` for a malformed Tenant
+ *   header or a bad body, `409 gate_conflict` when a different request already runs under the
+ *   same key.
  * - With an `Idempotency-Key` the call outlives its client (P1.2): a re-send with the same key
  *   and body joins it, or gets its outcome for 30 minutes. Without one, a client that goes
  *   away aborts the call.
  *
  * `POST /nylorun/v1/model-calls/{key}/cancel` (same headers): aborts the keyed call; `204`
- * whether or not it exists.
+ * whether or not it exists, `403 gate_forbidden` when it is another session's call. The token
+ * need not be live: a user cancel makes it stale, and still stops its call.
  */
 import { z } from "zod";
 import type { ModelGateOutcome } from "./model-gate.js";
@@ -26,9 +30,6 @@ export declare const TENANT_HEADER = "nylorun-tenant";
 /** Largest request body the gate reads: one `ModelCall` with its whole projected history. */
 export declare const MAX_MODEL_CALL_BYTES: number;
 export declare const ModelCallBodySchema: z.ZodObject<{
-    sessionId: z.ZodString;
-    turnId: z.ZodString;
-    agentId: z.ZodString;
     effectId: z.ZodString;
     invocationId: z.ZodString;
     call: z.ZodObject<{
@@ -37,7 +38,7 @@ export declare const ModelCallBodySchema: z.ZodObject<{
             name: z.ZodString;
         }, z.core.$loose>>;
     }, z.core.$loose>;
-}, z.core.$strip>;
+}, z.core.$strict>;
 export type ModelCallBody = z.infer<typeof ModelCallBodySchema>;
 export interface ModelCallResponse {
     readonly outcome: ModelGateOutcome;
@@ -45,7 +46,7 @@ export interface ModelCallResponse {
 /** An error answer: `{error: {code, message}}`. */
 export interface GateErrorBody {
     readonly error: {
-        readonly code: "gate_unauthorized" | "invalid_request" | "gate_conflict";
+        readonly code: "gate_unauthorized" | "gate_forbidden" | "run_stale" | "invalid_request" | "gate_conflict";
         readonly message: string;
     };
 }

package/dist/gates/contract.js

@@ -3,20 +3,24 @@
  * it is not in the published OpenAPI documents.
  *
  * `POST /nylorun/v1/model-calls`
- * - Headers: `Authorization: Bearer <NYLORUN_GATES_TOKEN>`, `Idempotency-Key: <effect id>`,
- *   and optionally `Nylorun-Tenant: <tenant id>`, which must then be the database's one
- *   Tenant (a call naming another is refused).
- * - Body: `ModelCallBody`, at most `MAX_MODEL_CALL_BYTES`.
+ * - Headers: `Authorization: Bearer <run token>` (F5, `tenant/run-token.ts`), `Idempotency-Key:
+ *   <effect id>`, and optionally `Nylorun-Tenant: <tenant id>`, which must then be the token's
+ *   Tenant. Core's credential (`NYLORUN_GATES_TOKEN`) is refused: only a run calls the model.
+ * - Body: `ModelCallBody`, at most `MAX_MODEL_CALL_BYTES`. It names no session, turn or agent:
+ *   the gate takes them from the token, and refuses a body that names them.
  * - `200 {outcome}` once the call has finished, whether the outcome is a candidate or a
- *   failure; nothing is sent while it runs. `401 gate_unauthorized` for a missing or wrong
- *   token, `400 invalid_request` for a malformed Tenant header or a bad body, `409
- *   gate_conflict` when a different request already runs under the same key.
+ *   failure; nothing is sent while it runs. `401 gate_unauthorized` for a missing, malformed,
+ *   expired or foreign token, `409 run_stale` when the token's lease is no longer the
+ *   session's (a cancel, a new turn, a takeover), `400 invalid_request` for a malformed Tenant
+ *   header or a bad body, `409 gate_conflict` when a different request already runs under the
+ *   same key.
  * - With an `Idempotency-Key` the call outlives its client (P1.2): a re-send with the same key
  *   and body joins it, or gets its outcome for 30 minutes. Without one, a client that goes
  *   away aborts the call.
  *
  * `POST /nylorun/v1/model-calls/{key}/cancel` (same headers): aborts the keyed call; `204`
- * whether or not it exists.
+ * whether or not it exists, `403 gate_forbidden` when it is another session's call. The token
+ * need not be live: a user cancel makes it stale, and still stops its call.
  */
 import { z } from "zod";
 export const MODEL_CALLS_PATH = "/nylorun/v1/model-calls";
@@ -24,10 +28,7 @@ export const MODEL_CALLS_PATH = "/nylorun/v1/model-calls";
 export const TENANT_HEADER = "nylorun-tenant";
 /** Largest request body the gate reads: one `ModelCall` with its whole projected history. */
 export const MAX_MODEL_CALL_BYTES = 32 * 1024 * 1024;
-export const ModelCallBodySchema = z.object({
-    sessionId: z.string().min(1),
-    turnId: z.string().min(1),
-    agentId: z.string().min(1),
+export const ModelCallBodySchema = z.strictObject({
     effectId: z.string().min(1),
     invocationId: z.string().min(1),
     call: z.looseObject({