@forgezero/runtime 0.1.22 → 0.1.24

package/README.md

@@ -7,7 +7,7 @@
 
 # Platform runtime
 
-The machinery behind a request handler — jobs, queues, an outbox, a hash-chained audit trail, mail, backups, schema validation and exact money. 31 public modules, each imported on its own.
+The machinery behind a request handler — jobs, queues, an outbox, a hash-chained audit trail, mail, backups, schema validation and exact money. 32 public modules, each imported on its own.
 
 ## Package overview
 
@@ -54,6 +54,7 @@ These are supported consumer entry points, not every internal module shipped for
 | @forgezero/runtime/slip10 | SLIP-0010 derivation for ed25519, hardened-only — BIP-32 does not work on this curve and produces halves that do not correspond. | portable | [Reference + usage](#forgezero-runtime-slip10) |
 | @forgezero/runtime/identity | Hybrid Ed25519 + ML-DSA-65 request signing. One canonical string, so the compute agent that signs inside a guest and the API that verifies cannot drift — which two implementations of it certainly would. | portable | [Reference + usage](#forgezero-runtime-identity) |
 | @forgezero/runtime/vault-runtime | Provider-neutral algorithms for non-exportable Vault runtime records: passwords, DEK/KEK operations, HMAC/JWS, Ed25519/secp256k1 and Ethereum/Solana address encoding. | portable | [Reference + usage](#forgezero-runtime-vault-runtime) |
+| @forgezero/runtime/lifecycle | Framework-neutral blue/green drain coordination with exact release fencing and separately proved HTTP, WebSocket, durable-job and schedule counters. | portable | [Reference + usage](#forgezero-runtime-lifecycle) |
 | @forgezero/runtime/schema | Validate against JSON Schema, restrict what a caller may declare, and describe a schema as a form. | portable | [Reference + usage](#forgezero-runtime-schema) |
 | @forgezero/runtime/schema/typebox | The TypeBox validator behind that interface. | portable | [Reference + usage](#forgezero-runtime-schema-typebox) |
 | @forgezero/runtime/finance/discounts | Promotions as arithmetic over integer minor units. They never stack — one winner — and a percentage rounds down, because rounding a discount up gives away a unit of currency per invoice forever. | portable | [Reference + usage](#forgezero-runtime-finance-discounts) |
@@ -149,7 +150,7 @@ Memory-only keyed work queue — awaited results, parallel across keys and stric
 
 ```text
 import {
-  QueueKeyStoppedError,
+  QueueIntakePausedError,
 } from '@forgezero/runtime/queue';
 ```
 
@@ -159,10 +160,10 @@ This minimal executable use imports one concrete value from this exact entry poi
 
 ```text
 import {
-  QueueKeyStoppedError,
+  QueueIntakePausedError,
 } from '@forgezero/runtime/queue';
 
-export const selectedCapability = QueueKeyStoppedError;
+export const selectedCapability = QueueIntakePausedError;
 ```
 
 <a id="forgezero-runtime-outbox"></a>
@@ -533,6 +534,29 @@ import {
 export const selectedCapability = DEFAULT_PASSWORD_ALPHABET;
 ```
 
+<a id="forgezero-runtime-lifecycle"></a>
+## @forgezero/runtime/lifecycle
+
+Framework-neutral blue/green drain coordination with exact release fencing and separately proved HTTP, WebSocket, durable-job and schedule counters. This is a supported entry point. Import only the named values used by the adjacent task example; the declaration file remains the complete API reference.
+
+```text
+import {
+  RUNTIME_DRAIN_BEGIN_PATH,
+} from '@forgezero/runtime/lifecycle';
+```
+
+## @forgezero/runtime/lifecycle — Use this entry point
+
+This minimal executable use imports one concrete value from this exact entry point without a wildcard or package-root detour. Keep the value or values the application actually needs; the full named inventory remains directly above it.
+
+```text
+import {
+  RUNTIME_DRAIN_BEGIN_PATH,
+} from '@forgezero/runtime/lifecycle';
+
+export const selectedCapability = RUNTIME_DRAIN_BEGIN_PATH;
+```
+
 <a id="forgezero-runtime-schema"></a>
 ## @forgezero/runtime/schema
 

package/dist/audit.js

@@ -14,6 +14,13 @@ class QueueStoppedError extends Error {
   }
 }
 
+class QueueIntakePausedError extends Error {
+  constructor() {
+    super("queue: intake is paused for a runtime handoff");
+    this.name = "QueueIntakePausedError";
+  }
+}
+
 class QueueKeyStoppedError extends Error {
   key;
   constructor(key) {
@@ -81,6 +88,7 @@ function createQueue(options = {}) {
   let sequence = 0;
   let globallyPaused = false;
   let accepting = true;
+  let intakePaused = false;
   let aborted = false;
   let completed = 0;
   let failed = 0;
@@ -161,8 +169,8 @@ function createQueue(options = {}) {
   return {
     run(key, handler, ...args) {
       const id = `q_${++sequence}`;
-      if (!accepting || stoppedKeys.has(key)) {
-        const refused = Promise.reject(accepting ? new QueueKeyStoppedError(key) : new QueueStoppedError);
+      if (!accepting || intakePaused || stoppedKeys.has(key)) {
+        const refused = Promise.reject(!accepting ? new QueueStoppedError : intakePaused ? new QueueIntakePausedError : new QueueKeyStoppedError(key));
         refused.catch(() => {
           return;
         });
@@ -242,6 +250,15 @@ function createQueue(options = {}) {
       globallyPaused = false;
       pump();
     },
+    pauseIntake() {
+      intakePaused = true;
+    },
+    resumeIntake() {
+      if (!accepting)
+        return;
+      intakePaused = false;
+      pump();
+    },
     snapshot() {
       let queued = 0;
       for (const lane of lanes.values())
@@ -252,6 +269,7 @@ function createQueue(options = {}) {
         queued,
         keys: lanes.size,
         paused: globallyPaused,
+        intakePaused,
         pausedKeys: [...paused],
         stoppedKeys: [...stoppedKeys],
         completed,

package/dist/jobs.js

@@ -14,6 +14,13 @@ class QueueStoppedError extends Error {
   }
 }
 
+class QueueIntakePausedError extends Error {
+  constructor() {
+    super("queue: intake is paused for a runtime handoff");
+    this.name = "QueueIntakePausedError";
+  }
+}
+
 class QueueKeyStoppedError extends Error {
   key;
   constructor(key) {
@@ -81,6 +88,7 @@ function createQueue(options = {}) {
   let sequence = 0;
   let globallyPaused = false;
   let accepting = true;
+  let intakePaused = false;
   let aborted = false;
   let completed = 0;
   let failed = 0;
@@ -161,8 +169,8 @@ function createQueue(options = {}) {
   return {
     run(key, handler, ...args) {
       const id = `q_${++sequence}`;
-      if (!accepting || stoppedKeys.has(key)) {
-        const refused = Promise.reject(accepting ? new QueueKeyStoppedError(key) : new QueueStoppedError);
+      if (!accepting || intakePaused || stoppedKeys.has(key)) {
+        const refused = Promise.reject(!accepting ? new QueueStoppedError : intakePaused ? new QueueIntakePausedError : new QueueKeyStoppedError(key));
         refused.catch(() => {
           return;
         });
@@ -242,6 +250,15 @@ function createQueue(options = {}) {
       globallyPaused = false;
       pump();
     },
+    pauseIntake() {
+      intakePaused = true;
+    },
+    resumeIntake() {
+      if (!accepting)
+        return;
+      intakePaused = false;
+      pump();
+    },
     snapshot() {
       let queued = 0;
       for (const lane of lanes.values())
@@ -252,6 +269,7 @@ function createQueue(options = {}) {
         queued,
         keys: lanes.size,
         paused: globallyPaused,
+        intakePaused,
         pausedKeys: [...paused],
         stoppedKeys: [...stoppedKeys],
         completed,

package/dist/lifecycle.d.ts

@@ -0,0 +1,115 @@
+/** Generic, framework-neutral runtime drain contract used by native and OCI workloads. */
+export declare const RUNTIME_DRAIN_BEGIN_PATH = "/.forgezero/runtime/drain/v1/begin";
+export declare const RUNTIME_DRAIN_STATUS_PATH = "/.forgezero/runtime/drain/v1/status";
+export interface RuntimeWorkCounters {
+    http: number;
+    websocket: number;
+    jobs: number;
+    schedules: number;
+}
+export interface RuntimeDrainDependencies {
+    /** Atomically refuse all new HTTP, WebSocket, job and schedule intake. */
+    drainRequests(): void;
+    /** Resolve only after all already-admitted HTTP and WebSocket work is closed. */
+    waitForRequests(): Promise<void>;
+    /** Stop schedule intake and wait for already-leased durable jobs. */
+    stopJobs(timeoutMs: number): Promise<void>;
+    /** A live, non-secret snapshot. Every counter must reach zero before acknowledgement. */
+    workCounters(): RuntimeWorkCounters;
+    /** Injectable monotonic wait used for the bounded deadline. */
+    sleep(ms: number): Promise<void>;
+}
+export interface RuntimeDrainRequest {
+    protocol: 'forgezero-drain/v1';
+    nonce: string;
+    sourceRevision: string;
+    targetRevision: string;
+    timeoutMs: number;
+}
+export interface RuntimeDrainStatus extends RuntimeDrainRequest {
+    status: 'draining' | 'drained' | 'failed';
+    inFlight: RuntimeWorkCounters;
+    failure?: string;
+}
+/**
+ * One process owns one controller. A second nonce cannot replace an in-flight
+ * drain, while an exact retry is idempotently acknowledged.
+ */
+export declare class RuntimeDrainController {
+    #private;
+    private readonly dependencies;
+    constructor(dependencies: RuntimeDrainDependencies);
+    begin(request: RuntimeDrainRequest): {
+        accepted: true;
+        duplicate: boolean;
+    };
+    status(nonce: string): RuntimeDrainStatus;
+}
+export interface RuntimeStateAdapter<T> {
+    protocol: string;
+    schemaVersion: number;
+    maximumBytes: number;
+    validate(value: unknown): value is T;
+    exportState(): Promise<{
+        cursor: string;
+        value: T;
+    }>;
+    importState(value: T, context: {
+        sourceRevision: string;
+        targetRevision: string;
+        cursor: string;
+        digest: `sha256:${string}`;
+    }): Promise<void>;
+}
+export interface RuntimeStateHandoffRequest {
+    protocol: string;
+    nonce: string;
+    schemaVersion: number;
+    sourceRevision: string;
+    targetRevision: string;
+    source: {
+        url: string;
+        authorization: string;
+    };
+}
+export interface RuntimeStateEnvelope<T = unknown> {
+    protocol: string;
+    schemaVersion: number;
+    sourceRevision: string;
+    targetRevision: string;
+    cursor: string;
+    digest: `sha256:${string}`;
+    value: T;
+}
+export interface RuntimeStateHandoffStatus {
+    protocol: string;
+    nonce: string;
+    schemaVersion: number;
+    sourceRevision: string;
+    targetRevision: string;
+    status: 'pending' | 'acknowledged' | 'failed';
+    cursor?: string;
+    digest?: `sha256:${string}`;
+    failure?: string;
+}
+export type RuntimeStateFetch = (input: string, init: {
+    method: 'GET';
+    headers: Readonly<Record<string, string>>;
+    signal: AbortSignal;
+}) => Promise<Response>;
+/**
+ * Bounded typed state transfer. The runtime owns schema validation and value
+ * import; the Agent sees only cursor/digest acknowledgement metadata.
+ */
+export declare class RuntimeStateHandoffController<T> {
+    #private;
+    private readonly adapter;
+    private readonly fetchState;
+    constructor(adapter: RuntimeStateAdapter<T>, fetchState?: RuntimeStateFetch);
+    exportState(sourceRevision: string, targetRevision: string): Promise<RuntimeStateEnvelope<T>>;
+    begin(request: RuntimeStateHandoffRequest, timeoutMs: number): {
+        accepted: true;
+        duplicate: boolean;
+    };
+    status(nonce: string): RuntimeStateHandoffStatus;
+}

package/dist/lifecycle.js

@@ -0,0 +1,243 @@
+var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require : typeof Proxy !== "undefined" ? new Proxy(x, {
+  get: (a, b) => (typeof require !== "undefined" ? require : a)[b]
+}) : x)(function(x) {
+  if (typeof require !== "undefined")
+    return require.apply(this, arguments);
+  throw Error('Dynamic require of "' + x + '" is not supported');
+});
+
+// src/lifecycle.ts
+var RUNTIME_DRAIN_BEGIN_PATH = "/.forgezero/runtime/drain/v1/begin";
+var RUNTIME_DRAIN_STATUS_PATH = "/.forgezero/runtime/drain/v1/status";
+var REVISION = /^[a-f0-9]{40}$/;
+var NONCE = /^[A-Za-z0-9_-]{43}$/;
+var counter = (value) => Number.isSafeInteger(value) && value >= 0;
+var validateCounters = (value) => {
+  if (![value.http, value.websocket, value.jobs, value.schedules].every(counter)) {
+    throw new Error("RUNTIME_DRAIN_COUNTERS_INVALID");
+  }
+  return { ...value };
+};
+var idle = (value) => value.http === 0 && value.websocket === 0 && value.jobs === 0 && value.schedules === 0;
+
+class RuntimeDrainController {
+  dependencies;
+  #request = null;
+  #status = "draining";
+  #failure;
+  constructor(dependencies) {
+    this.dependencies = dependencies;
+  }
+  begin(request) {
+    if (request.protocol !== "forgezero-drain/v1" || !NONCE.test(request.nonce) || !REVISION.test(request.sourceRevision) || !REVISION.test(request.targetRevision) || !Number.isSafeInteger(request.timeoutMs) || request.timeoutMs < 100 || request.timeoutMs > 600000) {
+      throw new Error("RUNTIME_DRAIN_REQUEST_INVALID");
+    }
+    if (this.#request) {
+      const duplicate = this.#request.nonce === request.nonce && this.#request.sourceRevision === request.sourceRevision && this.#request.targetRevision === request.targetRevision;
+      if (!duplicate)
+        throw new Error("RUNTIME_DRAIN_ALREADY_STARTED");
+      return { accepted: true, duplicate: true };
+    }
+    this.#request = { ...request };
+    this.#status = "draining";
+    this.dependencies.drainRequests();
+    const work = Promise.all([
+      this.dependencies.waitForRequests(),
+      this.dependencies.stopJobs(request.timeoutMs)
+    ]);
+    Promise.race([
+      work.then(() => "completed"),
+      this.dependencies.sleep(request.timeoutMs).then(() => "timeout")
+    ]).then((result) => {
+      if (result === "timeout")
+        throw new Error("RUNTIME_DRAIN_TIMEOUT");
+      if (!idle(validateCounters(this.dependencies.workCounters())))
+        throw new Error("RUNTIME_DRAIN_NOT_IDLE");
+      this.#status = "drained";
+    }).catch((cause) => {
+      this.#status = "failed";
+      this.#failure = cause instanceof Error ? cause.message.slice(0, 128) : "RUNTIME_DRAIN_FAILED";
+    });
+    return { accepted: true, duplicate: false };
+  }
+  status(nonce) {
+    if (!this.#request || !NONCE.test(nonce) || nonce !== this.#request.nonce) {
+      throw new Error("RUNTIME_DRAIN_NOT_FOUND");
+    }
+    return {
+      ...this.#request,
+      status: this.#status,
+      inFlight: validateCounters(this.dependencies.workCounters()),
+      ...this.#failure ? { failure: this.#failure } : {}
+    };
+  }
+}
+var HANDOFF_TEXT = /^[A-Za-z0-9][A-Za-z0-9_.:@/-]{0,127}$/;
+var CURSOR = /^[A-Za-z0-9][A-Za-z0-9_.:@/+\-=]{0,511}$/;
+var DIGEST = /^sha256:[a-f0-9]{64}$/;
+var AUTHORIZATION = /^Bearer [A-Za-z0-9_-]{43}$/;
+var canonicalJson = (value, seen = new Set) => {
+  if (value === null)
+    return "null";
+  if (typeof value === "string")
+    return JSON.stringify(value);
+  if (typeof value === "boolean")
+    return value ? "true" : "false";
+  if (typeof value === "number") {
+    if (!Number.isFinite(value))
+      throw new Error("RUNTIME_STATE_VALUE_INVALID");
+    return JSON.stringify(value);
+  }
+  if (typeof value !== "object" || seen.has(value))
+    throw new Error("RUNTIME_STATE_VALUE_INVALID");
+  seen.add(value);
+  try {
+    if (Array.isArray(value))
+      return `[${value.map((entry) => canonicalJson(entry, seen)).join(",")}]`;
+    const object = value;
+    const entries = Object.keys(object).sort().map((key) => {
+      if (object[key] === undefined)
+        throw new Error("RUNTIME_STATE_VALUE_INVALID");
+      return `${JSON.stringify(key)}:${canonicalJson(object[key], seen)}`;
+    });
+    return `{${entries.join(",")}}`;
+  } finally {
+    seen.delete(value);
+  }
+};
+var stateDigest = async (input) => {
+  const bytes = new TextEncoder().encode(canonicalJson(input));
+  const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", bytes));
+  return `sha256:${[...digest].map((byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+};
+var assertAdapter = (adapter) => {
+  if (!HANDOFF_TEXT.test(adapter.protocol) || !Number.isSafeInteger(adapter.schemaVersion) || adapter.schemaVersion < 1 || adapter.schemaVersion > 65535 || !Number.isSafeInteger(adapter.maximumBytes) || adapter.maximumBytes < 1 || adapter.maximumBytes > 1048576) {
+    throw new Error("RUNTIME_STATE_ADAPTER_INVALID");
+  }
+};
+var loopbackSource = (raw) => {
+  const value = new URL(raw);
+  if (value.protocol !== "http:" || value.username || value.password || value.hash || !["127.0.0.1", "[::1]", "::1", "localhost"].includes(value.hostname)) {
+    throw new Error("RUNTIME_STATE_SOURCE_INVALID");
+  }
+  return value.toString();
+};
+
+class RuntimeStateHandoffController {
+  adapter;
+  fetchState;
+  #request = null;
+  #status = null;
+  constructor(adapter, fetchState = (input, init) => fetch(input, init)) {
+    this.adapter = adapter;
+    this.fetchState = fetchState;
+    assertAdapter(adapter);
+  }
+  async exportState(sourceRevision, targetRevision) {
+    if (!REVISION.test(sourceRevision) || !REVISION.test(targetRevision))
+      throw new Error("RUNTIME_STATE_REVISION_INVALID");
+    const exported = await this.adapter.exportState();
+    if (!CURSOR.test(exported.cursor) || !this.adapter.validate(exported.value)) {
+      throw new Error("RUNTIME_STATE_EXPORT_INVALID");
+    }
+    const unsigned = {
+      protocol: this.adapter.protocol,
+      schemaVersion: this.adapter.schemaVersion,
+      sourceRevision,
+      targetRevision,
+      cursor: exported.cursor,
+      value: exported.value
+    };
+    if (new TextEncoder().encode(canonicalJson(unsigned)).byteLength > this.adapter.maximumBytes) {
+      throw new Error("RUNTIME_STATE_EXPORT_TOO_LARGE");
+    }
+    return { ...unsigned, digest: await stateDigest(unsigned) };
+  }
+  begin(request, timeoutMs) {
+    if (!NONCE.test(request.nonce) || request.protocol !== this.adapter.protocol || request.schemaVersion !== this.adapter.schemaVersion || !REVISION.test(request.sourceRevision) || !REVISION.test(request.targetRevision) || !AUTHORIZATION.test(request.source.authorization) || !Number.isSafeInteger(timeoutMs) || timeoutMs < 100 || timeoutMs > 600000) {
+      throw new Error("RUNTIME_STATE_REQUEST_INVALID");
+    }
+    const sourceUrl = loopbackSource(request.source.url);
+    if (this.#request) {
+      const duplicate = canonicalJson(this.#request) === canonicalJson(request);
+      if (!duplicate)
+        throw new Error("RUNTIME_STATE_ALREADY_STARTED");
+      return { accepted: true, duplicate: true };
+    }
+    this.#request = structuredClone(request);
+    this.#status = {
+      protocol: request.protocol,
+      nonce: request.nonce,
+      schemaVersion: request.schemaVersion,
+      sourceRevision: request.sourceRevision,
+      targetRevision: request.targetRevision,
+      status: "pending"
+    };
+    this.fetchState(sourceUrl, {
+      method: "GET",
+      headers: { Authorization: request.source.authorization },
+      signal: AbortSignal.timeout(timeoutMs)
+    }).then(async (response) => {
+      if (!response.ok)
+        throw new Error(`RUNTIME_STATE_SOURCE_HTTP_${response.status}`);
+      const length = Number(response.headers.get("content-length") ?? 0);
+      if (length > this.adapter.maximumBytes)
+        throw new Error("RUNTIME_STATE_SOURCE_TOO_LARGE");
+      const bytes = new Uint8Array(await response.arrayBuffer());
+      if (bytes.byteLength > this.adapter.maximumBytes)
+        throw new Error("RUNTIME_STATE_SOURCE_TOO_LARGE");
+      const envelope = JSON.parse(new TextDecoder().decode(bytes));
+      if (envelope.protocol !== request.protocol || envelope.schemaVersion !== request.schemaVersion || envelope.sourceRevision !== request.sourceRevision || envelope.targetRevision !== request.targetRevision || !CURSOR.test(envelope.cursor) || !DIGEST.test(envelope.digest) || !this.adapter.validate(envelope.value)) {
+        throw new Error("RUNTIME_STATE_ENVELOPE_INVALID");
+      }
+      const expected = await stateDigest({
+        protocol: envelope.protocol,
+        schemaVersion: envelope.schemaVersion,
+        sourceRevision: envelope.sourceRevision,
+        targetRevision: envelope.targetRevision,
+        cursor: envelope.cursor,
+        value: envelope.value
+      });
+      if (expected !== envelope.digest)
+        throw new Error("RUNTIME_STATE_DIGEST_MISMATCH");
+      await this.adapter.importState(envelope.value, {
+        sourceRevision: request.sourceRevision,
+        targetRevision: request.targetRevision,
+        cursor: envelope.cursor,
+        digest: envelope.digest
+      });
+      this.#status = {
+        protocol: request.protocol,
+        nonce: request.nonce,
+        schemaVersion: request.schemaVersion,
+        sourceRevision: request.sourceRevision,
+        targetRevision: request.targetRevision,
+        status: "acknowledged",
+        cursor: envelope.cursor,
+        digest: envelope.digest
+      };
+    }).catch((cause) => {
+      this.#status = {
+        protocol: request.protocol,
+        nonce: request.nonce,
+        schemaVersion: request.schemaVersion,
+        sourceRevision: request.sourceRevision,
+        targetRevision: request.targetRevision,
+        status: "failed",
+        failure: cause instanceof Error ? cause.message.slice(0, 128) : "RUNTIME_STATE_FAILED"
+      };
+    });
+    return { accepted: true, duplicate: false };
+  }
+  status(nonce) {
+    if (!this.#status || !NONCE.test(nonce) || nonce !== this.#status.nonce)
+      throw new Error("RUNTIME_STATE_NOT_FOUND");
+    return structuredClone(this.#status);
+  }
+}
+export {
+  RuntimeStateHandoffController,
+  RuntimeDrainController,
+  RUNTIME_DRAIN_STATUS_PATH,
+  RUNTIME_DRAIN_BEGIN_PATH
+};

package/dist/queue.d.ts

@@ -80,6 +80,10 @@ export interface DrainReport {
 export declare class QueueStoppedError extends Error {
     constructor();
 }
+/** A reversible handoff fence refused new work while existing work drained. */
+export declare class QueueIntakePausedError extends Error {
+    constructor();
+}
 export declare class QueueKeyStoppedError extends Error {
     readonly key: string;
     constructor(key: string);
@@ -116,6 +120,12 @@ export declare function createQueue(options?: QueueOptions): {
     /** Hold everything. New submissions are accepted and wait. */
     pause(): void;
     resume(): void;
+    /**
+     * Refuse new submissions without stopping the queue. Already accepted work
+     * continues, so `whenIdle()` is an exact reversible handoff boundary.
+     */
+    pauseIntake(): void;
+    resumeIntake(): void;
     /** How much is outstanding, for a health endpoint or a drain decision. */
     snapshot(): {
         width: number;
@@ -123,6 +133,7 @@ export declare function createQueue(options?: QueueOptions): {
         queued: number;
         keys: number;
         paused: boolean;
+        intakePaused: boolean;
         pausedKeys: string[];
         stoppedKeys: string[];
         completed: number;

package/dist/queue.js

@@ -14,6 +14,13 @@ class QueueStoppedError extends Error {
   }
 }
 
+class QueueIntakePausedError extends Error {
+  constructor() {
+    super("queue: intake is paused for a runtime handoff");
+    this.name = "QueueIntakePausedError";
+  }
+}
+
 class QueueKeyStoppedError extends Error {
   key;
   constructor(key) {
@@ -81,6 +88,7 @@ function createQueue(options = {}) {
   let sequence = 0;
   let globallyPaused = false;
   let accepting = true;
+  let intakePaused = false;
   let aborted = false;
   let completed = 0;
   let failed = 0;
@@ -161,8 +169,8 @@ function createQueue(options = {}) {
   return {
     run(key, handler, ...args) {
       const id = `q_${++sequence}`;
-      if (!accepting || stoppedKeys.has(key)) {
-        const refused = Promise.reject(accepting ? new QueueKeyStoppedError(key) : new QueueStoppedError);
+      if (!accepting || intakePaused || stoppedKeys.has(key)) {
+        const refused = Promise.reject(!accepting ? new QueueStoppedError : intakePaused ? new QueueIntakePausedError : new QueueKeyStoppedError(key));
         refused.catch(() => {
           return;
         });
@@ -242,6 +250,15 @@ function createQueue(options = {}) {
       globallyPaused = false;
       pump();
     },
+    pauseIntake() {
+      intakePaused = true;
+    },
+    resumeIntake() {
+      if (!accepting)
+        return;
+      intakePaused = false;
+      pump();
+    },
     snapshot() {
       let queued = 0;
       for (const lane of lanes.values())
@@ -252,6 +269,7 @@ function createQueue(options = {}) {
         queued,
         keys: lanes.size,
         paused: globallyPaused,
+        intakePaused,
         pausedKeys: [...paused],
         stoppedKeys: [...stoppedKeys],
         completed,
@@ -312,5 +330,6 @@ export {
   createQueue,
   TaskCancelledError,
   QueueStoppedError,
-  QueueKeyStoppedError
+  QueueKeyStoppedError,
+  QueueIntakePausedError
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgezero/runtime",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "type": "module",
   "publishConfig": {
     "access": "public",
@@ -51,6 +51,10 @@
       "types": "./dist/realtime.d.ts",
       "default": "./dist/realtime.js"
     },
+    "./lifecycle": {
+      "types": "./dist/lifecycle.d.ts",
+      "default": "./dist/lifecycle.js"
+    },
     "./calendar": {
       "types": "./dist/calendar.d.ts",
       "default": "./dist/calendar.js"