@forgezero/runtime 0.1.21 → 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
 
@@ -972,6 +996,19 @@ scheduler.pause();            // stop scheduling, let in-flight finish
 await scheduler.runNow('rotate-provider-credentials');
 ```
 
+## Deployment handoff is typed state, not copied RAM
+
+The portable lifecycle for native and containerd services is deliberately smaller than a process snapshot. First report not-ready and close new HTTP and job intake. Existing requests, streams and queue handlers drain within one deadline. Durable jobs stay in the application store with an idempotency key, expiring lease and monotonic fence, so the candidate may reclaim unfinished work without allowing the old generation to commit. An optional handoff value may carry a bounded, versioned cursor or connection coordinate after schema validation. Closures, arbitrary heap objects, sockets and Vault plaintext never cross generations; the candidate resolves the same named Vault references through its own authorized runtime boundary. This is the lifecycle ForgeZero itself must use before it is offered to tenants.
+
+```text
+old: ready=false -> close intake -> drain HTTP/streams -> drain or release fenced jobs
+new: private health -> validate handoff -> resolve named Vault refs -> accept claims
+switch: route new HTTP -> observe old deadline -> stop old or roll back
+
+durable job = payload + idempotencyKey + leaseUntil + fence
+handoff value = versioned + schema-validated + size-bounded + non-secret
+```
+
 ## Status somebody can read during an incident
 
 Last run, duration, result, error and consecutive failures per job. Without it a job that has been failing for a week looks exactly like a job that has been succeeding.

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.21",
+  "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"