@forgezero/runtime 0.1.22 → 0.1.25

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
 
@@ -790,7 +814,7 @@ Threshold-share parsing, validation and reconstruction. This is a supported entr
 
 ```text
 import {
-  PROBE_BYTES,
+  CUSTODY_ENVELOPE_SUITE,
 } from '@forgezero/runtime/custody-share';
 ```
 
@@ -800,10 +824,10 @@ This minimal executable use imports one concrete value from this exact entry poi
 
 ```text
 import {
-  PROBE_BYTES,
+  CUSTODY_ENVELOPE_SUITE,
 } from '@forgezero/runtime/custody-share';
 
-export const selectedCapability = PROBE_BYTES;
+export const selectedCapability = CUSTODY_ENVELOPE_SUITE;
 ```
 
 <a id="forgezero-runtime-custody-crypto"></a>

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/custody-share.d.ts

@@ -1,8 +1,55 @@
 import { type CipherBox, type SealedToKey } from './custody-crypto';
+export declare const CUSTODY_ENVELOPE_VERSION: 3;
+export declare const CUSTODY_ENVELOPE_SUITE: "ml-kem-768+x25519+hkdf-sha256+aes-256-gcm+ml-dsa-65";
+export declare const CUSTODY_FACTOR_PROOF_VERSION: 1;
+export type CustodyCredentialPurpose = 'custody';
+export type CustodyCredentialLifecycle = 'pending' | 'active' | 'retired';
+export type CustodyFactor = 'ceremony_passkey' | 'recovery_phrase';
+export type CustodyEnvelopeGeneration = number;
+export type CustodyTransactionOutcome = 'completed' | 'factor_mismatch' | 'credential_mismatch' | 'replayed' | 'expired' | 'batch_mismatch' | 'seed_fingerprint_mismatch';
+export interface CustodyFactorBinding {
+    version: typeof CUSTODY_FACTOR_PROOF_VERSION;
+    realmId: string;
+    ceremonyKey: string;
+    custodianKey: string;
+    factor: CustodyFactor;
+    requestKey: string;
+    method: 'POST';
+    path: string;
+    payloadDigest: string;
+    challenge: string;
+    expiresAtSec: number;
+}
+export interface CustodyPasskeyProofV1 {
+    version: typeof CUSTODY_FACTOR_PROOF_VERSION;
+    factor: 'ceremony_passkey';
+    credentialId: string;
+    signature: string;
+}
+export interface CustodyPhraseProofV1 {
+    version: typeof CUSTODY_FACTOR_PROOF_VERSION;
+    factor: 'recovery_phrase';
+    signature: string;
+}
+export type CustodyFactorProof = CustodyPasskeyProofV1 | CustodyPhraseProofV1;
+export interface CustodyActionRequest {
+    _key: string;
+    ceremonyKey: string;
+    ownerUserKey: string;
+    operation: 'seal' | 'verify' | 'reshare' | 'unlock' | 'rotate' | 'verify_rotation';
+    allowedFactors: CustodyFactor[];
+    payloadDigest: string;
+    challenge: string;
+    status: 'open' | 'consumed' | 'expired';
+    expiresAtSec: number;
+    revision: number;
+}
 export interface SealedShare {
     shareIndex: number;
-    /** Account credential whose PRF deterministically derives this passkey key. */
+    /** Dedicated custody credential whose PRF deterministically derives this passkey key. */
     passkeyCredentialId?: string;
+    /** Base64url ceremony salt persisted with that exact custody credential. */
+    passkeyPrfSalt?: string;
     passkeyEnvelope: CipherBox;
     phraseEnvelope: CipherBox;
     /** base64 — the HKDF salt for the phrase key and the verifier. */
@@ -10,6 +57,22 @@ export interface SealedShare {
     /** hex — proves the right phrase without being able to rebuild it. */
     phraseVerifier: string;
 }
+/** New writes use this shape. V2 is retained only for bounded unlock-and-rotate migration. */
+export interface CustodyEnvelopeV3 extends SealedShare {
+    version: typeof CUSTODY_ENVELOPE_VERSION;
+    suite: typeof CUSTODY_ENVELOPE_SUITE;
+    generation: CustodyEnvelopeGeneration;
+    passkeyGeneration?: CustodyEnvelopeGeneration;
+    phraseGeneration?: CustodyEnvelopeGeneration;
+    realmId: string;
+    ceremonyKey: string;
+    custodianKey: string;
+    passkeyCredentialId: string;
+    passkeyPrfSalt: string;
+    passkeyActionPublicKey: string;
+    phraseActionPublicKey: string;
+}
+export declare function isCustodyEnvelopeV3(value: SealedShare): value is CustodyEnvelopeV3;
 type EnvelopeKind = 'passkey' | 'phrase';
 /** The x-coordinate a share was cut at — its custodian-facing share number. */
 export declare function shareIndexOf(share: Uint8Array): number;
@@ -44,12 +107,15 @@ export declare function openShareWithPhrase(sealed: SealedShare, custodianKey: s
  * ever sent.
  */
 export interface WrappingKeys {
-    /** The verified, PRF-capable account credential selected by the browser. */
+    /** The verified, PRF-capable custody credential selected by the browser. */
     passkeyCredentialId: string;
+    passkeyPrfSalt: string;
     passkeyPublicKey: string;
     phrasePublicKey: string;
     phraseSalt: string;
     phraseVerifier: string;
+    passkeyActionPublicKey: string;
+    phraseActionPublicKey: string;
 }
 /** The private half for one factor. Never leaves the machine that made it. */
 export declare function passkeyWrappingKey(custodianKey: string, passkeyPrfOutput: Uint8Array): {
@@ -65,9 +131,25 @@ export declare function phraseWrappingKey(custodianKey: string, phraseWords: str
 export declare function wrappingKeysFor(args: {
     custodianKey: string;
     passkeyCredentialId: string;
+    passkeyPrfSalt: string;
     passkeyPrfOutput: Uint8Array;
     phraseWords: string[];
 }): WrappingKeys;
+export declare function custodyFactorActionPublicKey(factor: CustodyFactor, custodianKey: string, factorMaterial: Uint8Array): string;
+/** Stable browser/API digest used to bind a custody proof to one exact payload. */
+export declare function custodyActionPayloadDigest(value: unknown): string;
+export declare function createCustodyFactorProof(args: {
+    binding: CustodyFactorBinding;
+    factorMaterial: Uint8Array;
+    credentialId?: string;
+}): CustodyFactorProof;
+export declare function createCustodyPasskeyProof(binding: CustodyFactorBinding, passkeyPrfOutput: Uint8Array, credentialId: string): CustodyPasskeyProofV1;
+export declare function createCustodyPhraseProof(binding: CustodyFactorBinding, phraseWords: string[], phraseSalt: string): CustodyPhraseProofV1;
+export declare function verifyCustodyFactorProof(args: {
+    binding: CustodyFactorBinding;
+    proof: CustodyFactorProof;
+    publicKey: string;
+}): boolean;
 /** Open something the server sealed to one of those public keys. */
 export declare function openSealedToFactor(args: {
     custodianKey: string;
@@ -76,9 +158,12 @@ export declare function openSealedToFactor(args: {
     passkeyPrfOutput?: Uint8Array;
     phraseWords?: string[];
     phraseSalt?: string;
+    aad?: string;
 }): Uint8Array;
 /** The aad the server must use when sealing to a custodian's factor key. */
 export declare const factorWrapAad: (custodianKey: string, factor: EnvelopeKind) => string;
+/** Canonical AAD for V3. Length-prefixing prevents ambiguous concatenation. */
+export declare function custodyEnvelopeV3Aad(envelope: Pick<CustodyEnvelopeV3, 'version' | 'suite' | 'realmId' | 'ceremonyKey' | 'custodianKey' | 'shareIndex' | 'passkeyCredentialId' | 'generation' | 'passkeyGeneration' | 'phraseGeneration'>, factor: EnvelopeKind): string;
 /**
  * A share plus a probe, sealed together.
  *

package/dist/custody-share.js

@@ -174,9 +174,18 @@ function phraseVerifier(words, salt) {
 }
 
 // src/custody-share.ts
+import { ml_dsa65 } from "@noble/post-quantum/ml-dsa.js";
+import { hkdf as hkdf3 } from "@noble/hashes/hkdf.js";
+import { sha256 as sha2563 } from "@noble/hashes/sha2.js";
+var CUSTODY_ENVELOPE_VERSION = 3;
+var CUSTODY_ENVELOPE_SUITE = "ml-kem-768+x25519+hkdf-sha256+aes-256-gcm+ml-dsa-65";
+var CUSTODY_FACTOR_PROOF_VERSION = 1;
 var KEY_BYTES3 = 32;
 var MIN_PRF_BYTES = 32;
 var PASSKEY_KEY_SALT = "forgezero:custodian:passkey:v1";
+function isCustodyEnvelopeV3(value) {
+  return value.version === CUSTODY_ENVELOPE_VERSION && value.suite === CUSTODY_ENVELOPE_SUITE;
+}
 var utf82 = (value) => new TextEncoder().encode(value);
 var toBase642 = (bytes) => {
   let binary = "";
@@ -283,31 +292,167 @@ function phraseWrappingKey(custodianKey, phraseWords, salt) {
 function wrappingKeysFor(args) {
   if (!args.passkeyCredentialId)
     throw new Error("custody-share: passkey credential id is required");
+  if (!/^[A-Za-z0-9_-]{43}$/.test(args.passkeyPrfSalt)) {
+    throw new Error("custody-share: ceremony passkey PRF salt is required");
+  }
   const salt = newSalt();
   const passkey = passkeyWrappingKey(args.custodianKey, args.passkeyPrfOutput);
   const phrase = phraseWrappingKey(args.custodianKey, args.phraseWords, salt);
+  const passkeyAction = custodyFactorActionKeyPair("ceremony_passkey", args.custodianKey, args.passkeyPrfOutput);
+  const phraseMaterial = phraseToKey(args.phraseWords, salt);
+  const phraseAction = custodyFactorActionKeyPair("recovery_phrase", args.custodianKey, phraseMaterial);
   try {
     return {
       passkeyCredentialId: args.passkeyCredentialId,
+      passkeyPrfSalt: args.passkeyPrfSalt,
       passkeyPublicKey: toBase642(passkey.publicKey),
       phrasePublicKey: toBase642(phrase.publicKey),
       phraseSalt: toBase642(salt),
-      phraseVerifier: phraseVerifier(args.phraseWords, salt)
+      phraseVerifier: phraseVerifier(args.phraseWords, salt),
+      passkeyActionPublicKey: toBase642(passkeyAction.publicKey),
+      phraseActionPublicKey: toBase642(phraseAction.publicKey)
     };
   } finally {
     passkey.secretKey.fill(0);
     phrase.secretKey.fill(0);
+    passkeyAction.secretKey.fill(0);
+    phraseAction.secretKey.fill(0);
+    phraseMaterial.fill(0);
+  }
+}
+var actionInfo = (factor, custodianKey) => `forgezero:custody:factor-action:ml-dsa-65:v1:${factor}:${custodianKey.length}:${custodianKey}`;
+function custodyFactorActionKeyPair(factor, custodianKey, factorMaterial) {
+  assertCustodianKey(custodianKey);
+  if (factorMaterial.length < 32)
+    throw new Error("custody-share: action factor must be at least 32 bytes");
+  const seed = hkdf3(sha2563, factorMaterial, utf82("forgezero:custody:factor-action:ml-dsa-65:v1"), utf82(actionInfo(factor, custodianKey)), 32);
+  try {
+    const pair = ml_dsa65.keygen(seed);
+    return { publicKey: Uint8Array.from(pair.publicKey), secretKey: Uint8Array.from(pair.secretKey) };
+  } finally {
+    seed.fill(0);
+  }
+}
+function custodyFactorActionPublicKey(factor, custodianKey, factorMaterial) {
+  const pair = custodyFactorActionKeyPair(factor, custodianKey, factorMaterial);
+  try {
+    return toBase642(pair.publicKey);
+  } finally {
+    pair.secretKey.fill(0);
+  }
+}
+var proofBytes = (binding) => {
+  const values = [
+    "forgezero-custody-factor-proof-v1",
+    String(binding.version),
+    binding.realmId,
+    binding.ceremonyKey,
+    binding.custodianKey,
+    binding.factor,
+    binding.requestKey,
+    binding.method,
+    binding.path,
+    binding.payloadDigest,
+    binding.challenge,
+    String(binding.expiresAtSec)
+  ];
+  return utf82(values.map((value) => `${utf82(value).length}:${value}`).join(`
+`));
+};
+function canonicalJson(value) {
+  if (value === null || typeof value === "boolean" || typeof value === "string")
+    return JSON.stringify(value);
+  if (typeof value === "number") {
+    if (!Number.isFinite(value))
+      throw new Error("custody-share: non-finite action payload number");
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value))
+    return `[${value.map(canonicalJson).join(",")}]`;
+  if (typeof value === "object") {
+    return `{${Object.entries(value).filter(([, item]) => item !== undefined).sort(([left], [right]) => left.localeCompare(right)).map(([key, item]) => `${JSON.stringify(key)}:${canonicalJson(item)}`).join(",")}}`;
+  }
+  throw new Error("custody-share: unsupported action payload value");
+}
+function custodyActionPayloadDigest(value) {
+  return Array.from(sha2563(utf82(canonicalJson(value))), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function createCustodyFactorProof(args) {
+  if (args.binding.version !== CUSTODY_FACTOR_PROOF_VERSION) {
+    throw new Error("custody-share: unsupported factor proof version");
+  }
+  const pair = custodyFactorActionKeyPair(args.binding.factor, args.binding.custodianKey, args.factorMaterial);
+  try {
+    const signature = toBase642(ml_dsa65.sign(proofBytes(args.binding), pair.secretKey));
+    return args.binding.factor === "ceremony_passkey" ? {
+      version: CUSTODY_FACTOR_PROOF_VERSION,
+      factor: "ceremony_passkey",
+      credentialId: args.credentialId ?? "",
+      signature
+    } : { version: CUSTODY_FACTOR_PROOF_VERSION, factor: "recovery_phrase", signature };
+  } finally {
+    pair.secretKey.fill(0);
+  }
+}
+function createCustodyPasskeyProof(binding, passkeyPrfOutput, credentialId) {
+  if (binding.factor !== "ceremony_passkey") {
+    throw new Error("custody-share: passkey proof requires ceremony_passkey binding");
+  }
+  return createCustodyFactorProof({
+    binding,
+    factorMaterial: passkeyPrfOutput,
+    credentialId
+  });
+}
+function createCustodyPhraseProof(binding, phraseWords, phraseSalt) {
+  if (binding.factor !== "recovery_phrase") {
+    throw new Error("custody-share: phrase proof requires recovery_phrase binding");
+  }
+  if (!validatePhrase(phraseWords))
+    throw new Error("INVALID_PHRASE");
+  const material = phraseToKey(phraseWords, fromBase642(phraseSalt));
+  try {
+    return createCustodyFactorProof({ binding, factorMaterial: material });
+  } finally {
+    material.fill(0);
+  }
+}
+function verifyCustodyFactorProof(args) {
+  try {
+    if (args.proof.version !== CUSTODY_FACTOR_PROOF_VERSION || args.proof.factor !== args.binding.factor)
+      return false;
+    const publicKey = fromBase642(args.publicKey);
+    const signature = fromBase642(args.proof.signature);
+    return publicKey.length === ml_dsa65.lengths.publicKey && signature.length === ml_dsa65.lengths.signature && ml_dsa65.verify(signature, proofBytes(args.binding), publicKey);
+  } catch {
+    return false;
   }
 }
 function openSealedToFactor(args) {
   const pair = args.factor === "passkey" ? passkeyWrappingKey(args.custodianKey, args.passkeyPrfOutput) : phraseWrappingKey(args.custodianKey, args.phraseWords, fromBase642(args.phraseSalt));
   try {
-    return openFromKey(pair.secretKey, args.box, wrapInfo(args.custodianKey, args.factor));
+    return openFromKey(pair.secretKey, args.box, args.aad ?? wrapInfo(args.custodianKey, args.factor));
   } finally {
     pair.secretKey.fill(0);
   }
 }
 var factorWrapAad = (custodianKey, factor) => wrapInfo(custodianKey, factor);
+function custodyEnvelopeV3Aad(envelope, factor) {
+  const values = [
+    "forgezero-custody-envelope-aad",
+    String(envelope.version),
+    envelope.suite,
+    envelope.realmId,
+    envelope.ceremonyKey,
+    envelope.custodianKey,
+    String(envelope.shareIndex),
+    factor,
+    factor === "passkey" ? envelope.passkeyCredentialId : "recovery_phrase",
+    String(factor === "passkey" ? envelope.passkeyGeneration ?? envelope.generation : envelope.phraseGeneration ?? envelope.generation)
+  ];
+  return values.map((value) => `${utf82(value).length}:${value}`).join(`
+`);
+}
 var PROBE_BYTES = 32;
 function joinProbeAndShare(probe, share) {
   if (probe.length !== PROBE_BYTES)
@@ -324,17 +469,20 @@ function splitProbeAndShare(opened) {
 }
 function openFactorEnvelope(args) {
   const box = args.factor === "passkey" ? args.sealed.passkeyEnvelope : args.sealed.phraseEnvelope;
+  const aad = isCustodyEnvelopeV3(args.sealed) ? custodyEnvelopeV3Aad(args.sealed, args.factor) : undefined;
   return splitProbeAndShare(openSealedToFactor({
     custodianKey: args.custodianKey,
     factor: args.factor,
     box,
     passkeyPrfOutput: args.passkeyPrfOutput,
     phraseWords: args.phraseWords,
-    phraseSalt: args.sealed.phraseSalt
+    phraseSalt: args.sealed.phraseSalt,
+    aad
   }));
 }
 export {
   wrappingKeysFor,
+  verifyCustodyFactorProof,
   splitProbeAndShare,
   shareIndexOf,
   sealShare,
@@ -345,6 +493,16 @@ export {
   openSealedToFactor,
   openFactorEnvelope,
   joinProbeAndShare,
+  isCustodyEnvelopeV3,
   factorWrapAad,
-  PROBE_BYTES
+  custodyFactorActionPublicKey,
+  custodyEnvelopeV3Aad,
+  custodyActionPayloadDigest,
+  createCustodyPhraseProof,
+  createCustodyPasskeyProof,
+  createCustodyFactorProof,
+  PROBE_BYTES,
+  CUSTODY_FACTOR_PROOF_VERSION,
+  CUSTODY_ENVELOPE_VERSION,
+  CUSTODY_ENVELOPE_SUITE
 };

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.25",
   "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"