@forgezero/runtime 0.1.1 → 0.1.2

package/README.md

@@ -5,7 +5,7 @@ themselves, keyed queues, a transactional outbox, a hash-chained audit trail,
 templated mail, encrypted backups, schema validation, and money that is never a
 floating-point number.
 
-Twenty-six modules. Each is its own entry point, so you install one package and
+Thirty-three public modules. Each is its own entry point, so you install one package and
 your bundler includes only what you imported.
 
 ```bash
@@ -24,7 +24,7 @@ import { createScheduler } from '@forgezero/runtime/jobs';
 
 | | |
 |---|---|
-| **Spine** | `jobs` `queue` `serial` `outbox` |
+| **Spine** | `jobs` `queue` `outbox` |
 | **Record** | `audit` `backup` `compliance` `calendar` |
 | **Identity** | `identity` `totp` `notify` `notify/templates` `schema` `schema/typebox` |
 | **Finance** | `finance/money` `finance/storage` `finance/ledger` `finance/commission` `finance/rates` `finance/transfers` `finance/tax` `finance/chain` `finance/custody` `finance/derive` `finance/venues` `finance/binance` |
@@ -32,6 +32,29 @@ import { createScheduler } from '@forgezero/runtime/jobs';
 None of it knows what your product does. You bind your own rules to these; you
 do not fork them.
 
+## One reusable async queue
+
+`queue` is deliberately memory-only: it accepts a function, returns that
+function's value through a Promise, runs one key sequentially, and runs
+different keys in parallel. Persistence and cluster ownership remain in the
+business layer that knows what a pending request means; ForgeZero uses an
+ArangoDB unique claim, while another caller may use any database or no database.
+
+```ts
+import { createQueue } from '@forgezero/runtime/queue';
+
+const queue = createQueue({ width: 8 });
+const task = queue.run('tenant-a:wallet-7', transfer, amount, destination);
+const receipt = await task.result;
+
+queue.pauseKey('tenant-a:wallet-7');
+queue.resumeKey('tenant-a:wallet-7');
+queue.stopKey('tenant-a:wallet-7'); // running finishes; pending is rejected
+queue.startKey('tenant-a:wallet-7');
+queue.cancel(task.id);               // pending task only
+await queue.stop(30_000);            // close intake and drain all work
+```
+
 ## Three things worth knowing before you use it
 
 **Money is never a number.** An amount is minor units as a `bigint` with its
@@ -81,9 +104,9 @@ node_modules/@forgezero/runtime/contracts/src/
   ColdVault.sol        M-of-N EIP-712, signatures ordered by ascending signer
 ```
 
-Full documentation: **https://forgezero.net/docs/runtime**
+Full documentation: **https://www.forgezero.net/docs/runtime**
 
 ## Licence
 
-MIT. Part of [ForgeZero](https://forgezero.net) — secrets, attested compute and
+MIT. Part of [ForgeZero](https://www.forgezero.net) — secrets, attested compute and
 deploys — and usable entirely on its own, with no ForgeZero account.

package/dist/audit.js

@@ -6,32 +6,271 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
   throw Error('Dynamic require of "' + x + '" is not supported');
 });
 
-// src/serial.ts
-function createKeyedSerial(options = {}) {
-  const maxKeys = options.maxKeys ?? 1e4;
-  const chains = new Map;
-  return {
-    run(key, work) {
-      const previous = chains.get(key) ?? Promise.resolve();
-      const next = previous.then(work, work);
-      const settled = next.then(() => {
+// src/queue.ts
+class QueueStoppedError extends Error {
+  constructor() {
+    super("queue: stopped before this task could run");
+    this.name = "QueueStoppedError";
+  }
+}
+
+class QueueKeyStoppedError extends Error {
+  key;
+  constructor(key) {
+    super(`queue: key ${key} is stopped`);
+    this.key = key;
+    this.name = "QueueKeyStoppedError";
+  }
+}
+
+class TaskCancelledError extends Error {
+  constructor() {
+    super("queue: task cancelled");
+    this.name = "TaskCancelledError";
+  }
+}
+var DEFAULT_RETRY = {
+  attempts: 1,
+  backoffMs: (attempt) => Math.min(30000, 2 ** attempt * 100)
+};
+function createQueue(options = {}) {
+  const width = options.width ?? 8;
+  const retry = { ...DEFAULT_RETRY, ...options.retry };
+  if (!Number.isSafeInteger(width) || width < 1) {
+    throw new RangeError("queue: width must be a positive integer");
+  }
+  if (!Number.isSafeInteger(retry.attempts) || retry.attempts < 1) {
+    throw new RangeError("queue: retry attempts must be a positive integer");
+  }
+  const sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const lanes = new Map;
+  const running = new Set;
+  const paused = new Set;
+  const stoppedKeys = new Set;
+  let sequence = 0;
+  let globallyPaused = false;
+  let accepting = true;
+  let aborted = false;
+  let completed = 0;
+  let failed = 0;
+  const idle = [];
+  const announceIdle = () => {
+    if (running.size > 0)
+      return;
+    for (const lane of lanes.values())
+      if (lane.length > 0)
         return;
-      }, () => {
+    while (idle.length > 0)
+      idle.shift()();
+  };
+  function pump() {
+    if (globallyPaused || aborted) {
+      announceIdle();
+      return;
+    }
+    for (const [key, lane] of lanes) {
+      if (running.size >= width)
+        break;
+      if (running.has(key) || paused.has(key) || lane.length === 0)
+        continue;
+      execute(key);
+    }
+    announceIdle();
+  }
+  async function execute(key) {
+    running.add(key);
+    try {
+      const lane = lanes.get(key);
+      const entry = lane?.[0];
+      if (entry && !globallyPaused && !paused.has(key) && !aborted) {
+        lane.shift();
+        await attempt(entry);
+      }
+    } finally {
+      running.delete(key);
+      const remaining = lanes.get(key);
+      if (remaining?.length === 0)
+        lanes.delete(key);
+      else if (remaining) {
+        lanes.delete(key);
+        lanes.set(key, remaining);
+      }
+      pump();
+    }
+  }
+  async function attempt(entry) {
+    if (entry.cancelled) {
+      entry.reject(new TaskCancelledError);
+      return;
+    }
+    for (;; ) {
+      entry.attempt += 1;
+      try {
+        const value = await entry.run();
+        completed += 1;
+        entry.resolve(value);
         return;
+      } catch (cause) {
+        if (entry.attempt >= retry.attempts || entry.cancelled || aborted) {
+          failed += 1;
+          entry.reject(cause);
+          return;
+        }
+        const delay = retry.backoffMs(entry.attempt);
+        if (!Number.isFinite(delay) || delay < 0) {
+          failed += 1;
+          entry.reject(new RangeError("queue: retry backoff must be a non-negative finite number"));
+          return;
+        }
+        await sleep(delay);
+      }
+    }
+  }
+  return {
+    run(key, handler, ...args) {
+      const id = `q_${++sequence}`;
+      if (!accepting || stoppedKeys.has(key)) {
+        const refused = Promise.reject(accepting ? new QueueKeyStoppedError(key) : new QueueStoppedError);
+        refused.catch(() => {
+          return;
+        });
+        return { id, key, result: refused };
+      }
+      let resolve;
+      let reject;
+      const result = new Promise((ok, no) => {
+        resolve = ok;
+        reject = no;
       });
-      chains.set(key, settled);
-      settled.then(() => {
-        if (chains.get(key) === settled)
-          chains.delete(key);
-      });
-      if (chains.size > maxKeys) {
-        console.warn(`[serial] ${chains.size} keys in flight, above the ${maxKeys} guideline.`);
+      const entry = {
+        id,
+        key,
+        run: async () => handler(...args),
+        resolve,
+        reject,
+        attempt: 0,
+        cancelled: false
+      };
+      const lane = lanes.get(key);
+      if (lane)
+        lane.push(entry);
+      else
+        lanes.set(key, [entry]);
+      pump();
+      return { id, key, result };
+    },
+    cancel(id) {
+      for (const [key, lane] of lanes) {
+        const index = lane.findIndex((entry2) => entry2.id === id);
+        if (index === -1)
+          continue;
+        const [entry] = lane.splice(index, 1);
+        entry.cancelled = true;
+        entry.reject(new TaskCancelledError);
+        if (lane.length === 0 && !running.has(key))
+          lanes.delete(key);
+        announceIdle();
+        return true;
+      }
+      return false;
+    },
+    pauseKey(key) {
+      paused.add(key);
+    },
+    resumeKey(key) {
+      paused.delete(key);
+      pump();
+    },
+    stopKey(key) {
+      stoppedKeys.add(key);
+      paused.delete(key);
+      const lane = lanes.get(key);
+      if (!lane)
+        return 0;
+      let removed = 0;
+      for (const entry of lane.splice(0)) {
+        removed += 1;
+        entry.cancelled = true;
+        entry.reject(new QueueKeyStoppedError(key));
+      }
+      if (!running.has(key))
+        lanes.delete(key);
+      announceIdle();
+      return removed;
+    },
+    startKey(key) {
+      const changed = stoppedKeys.delete(key);
+      pump();
+      return changed;
+    },
+    pause() {
+      globallyPaused = true;
+    },
+    resume() {
+      globallyPaused = false;
+      pump();
+    },
+    snapshot() {
+      let queued = 0;
+      for (const lane of lanes.values())
+        queued += lane.length;
+      return {
+        running: running.size,
+        queued,
+        keys: lanes.size,
+        paused: globallyPaused,
+        pausedKeys: [...paused],
+        stoppedKeys: [...stoppedKeys],
+        completed,
+        failed
+      };
+    },
+    whenIdle() {
+      if (running.size === 0 && [...lanes.values()].every((lane) => lane.length === 0)) {
+        return Promise.resolve();
       }
-      return next;
+      return new Promise((resolve) => idle.push(resolve));
     },
-    size: () => chains.size,
-    drain: async () => {
-      await Promise.allSettled([...chains.values()]);
+    async stop(deadlineMs = 30000) {
+      if (!Number.isSafeInteger(deadlineMs) || deadlineMs < 0) {
+        throw new RangeError("queue: stop deadline must be a non-negative integer");
+      }
+      accepting = false;
+      const before = { completed, failed };
+      globallyPaused = false;
+      paused.clear();
+      pump();
+      let timedOut = false;
+      let deadlineHandle;
+      const deadline = new Promise((resolve) => {
+        deadlineHandle = setTimeout(() => {
+          timedOut = true;
+          resolve();
+        }, deadlineMs);
+      });
+      await Promise.race([this.whenIdle(), deadline]);
+      if (!timedOut && deadlineHandle !== undefined)
+        clearTimeout(deadlineHandle);
+      if (timedOut)
+        aborted = true;
+      let abandoned = 0;
+      for (const lane of lanes.values()) {
+        abandoned += lane.length;
+        for (const entry of lane.splice(0))
+          entry.reject(new QueueStoppedError);
+      }
+      abandoned += running.size;
+      for (const [key, lane] of lanes) {
+        if (lane.length === 0 && !running.has(key))
+          lanes.delete(key);
+      }
+      announceIdle();
+      return {
+        completed: completed - before.completed,
+        failed: failed - before.failed,
+        abandoned,
+        timedOut
+      };
     }
   };
 }
@@ -201,8 +440,8 @@ async function verifyExport(slice, options = {}) {
 }
 function createAuditChain(options) {
   const digester = options.digester ?? hashDigester;
-  const serial = createKeyedSerial();
-  const enqueue = (realm, run) => serial.run(realm ?? "\x00platform", run);
+  const queue = createQueue();
+  const enqueue = (realm, run) => queue.run(realm ?? "\x00platform", run).result;
   return {
     append: (entry) => enqueue(entry.realm, () => appendRecord(options.store, entry, { ...options, digester })),
     verify: async (realm, fromSequence = 1, toSequence = Number.MAX_SAFE_INTEGER) => {

package/dist/jobs.d.ts

@@ -15,11 +15,12 @@
  *
  * Each has a specific answer here: reschedule after completion rather than on
  * an interval, advance only on a fully successful batch, take a fenced lock,
- * and await in-flight work on stop.
+ * and submit every run through the common awaited queue, which drains on stop.
  *
  * Zero dependencies. The lock and the cursor store are interfaces, so this runs
  * against a database, Redis, or nothing at all in a test.
  */
+import { type DrainReport } from './queue';
 /** Injected so a test does not sleep and a resumed run is reproducible. */
 export interface Clock {
     now(): number;
@@ -122,7 +123,7 @@ export declare function createScheduler(options: SchedulerOptions): {
      * leaves a record half-written — the process exits mid-transaction and the
      * next boot finds state nothing can explain.
      */
-    stop(): Promise<void>;
+    stop(deadlineMs?: number): Promise<DrainReport>;
     /** Timers stop firing; in-flight work is left to finish. */
     pause(): void;
     resume(): void;

package/dist/jobs.js

@@ -6,6 +6,275 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
   throw Error('Dynamic require of "' + x + '" is not supported');
 });
 
+// src/queue.ts
+class QueueStoppedError extends Error {
+  constructor() {
+    super("queue: stopped before this task could run");
+    this.name = "QueueStoppedError";
+  }
+}
+
+class QueueKeyStoppedError extends Error {
+  key;
+  constructor(key) {
+    super(`queue: key ${key} is stopped`);
+    this.key = key;
+    this.name = "QueueKeyStoppedError";
+  }
+}
+
+class TaskCancelledError extends Error {
+  constructor() {
+    super("queue: task cancelled");
+    this.name = "TaskCancelledError";
+  }
+}
+var DEFAULT_RETRY = {
+  attempts: 1,
+  backoffMs: (attempt) => Math.min(30000, 2 ** attempt * 100)
+};
+function createQueue(options = {}) {
+  const width = options.width ?? 8;
+  const retry = { ...DEFAULT_RETRY, ...options.retry };
+  if (!Number.isSafeInteger(width) || width < 1) {
+    throw new RangeError("queue: width must be a positive integer");
+  }
+  if (!Number.isSafeInteger(retry.attempts) || retry.attempts < 1) {
+    throw new RangeError("queue: retry attempts must be a positive integer");
+  }
+  const sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const lanes = new Map;
+  const running = new Set;
+  const paused = new Set;
+  const stoppedKeys = new Set;
+  let sequence = 0;
+  let globallyPaused = false;
+  let accepting = true;
+  let aborted = false;
+  let completed = 0;
+  let failed = 0;
+  const idle = [];
+  const announceIdle = () => {
+    if (running.size > 0)
+      return;
+    for (const lane of lanes.values())
+      if (lane.length > 0)
+        return;
+    while (idle.length > 0)
+      idle.shift()();
+  };
+  function pump() {
+    if (globallyPaused || aborted) {
+      announceIdle();
+      return;
+    }
+    for (const [key, lane] of lanes) {
+      if (running.size >= width)
+        break;
+      if (running.has(key) || paused.has(key) || lane.length === 0)
+        continue;
+      execute(key);
+    }
+    announceIdle();
+  }
+  async function execute(key) {
+    running.add(key);
+    try {
+      const lane = lanes.get(key);
+      const entry = lane?.[0];
+      if (entry && !globallyPaused && !paused.has(key) && !aborted) {
+        lane.shift();
+        await attempt(entry);
+      }
+    } finally {
+      running.delete(key);
+      const remaining = lanes.get(key);
+      if (remaining?.length === 0)
+        lanes.delete(key);
+      else if (remaining) {
+        lanes.delete(key);
+        lanes.set(key, remaining);
+      }
+      pump();
+    }
+  }
+  async function attempt(entry) {
+    if (entry.cancelled) {
+      entry.reject(new TaskCancelledError);
+      return;
+    }
+    for (;; ) {
+      entry.attempt += 1;
+      try {
+        const value = await entry.run();
+        completed += 1;
+        entry.resolve(value);
+        return;
+      } catch (cause) {
+        if (entry.attempt >= retry.attempts || entry.cancelled || aborted) {
+          failed += 1;
+          entry.reject(cause);
+          return;
+        }
+        const delay = retry.backoffMs(entry.attempt);
+        if (!Number.isFinite(delay) || delay < 0) {
+          failed += 1;
+          entry.reject(new RangeError("queue: retry backoff must be a non-negative finite number"));
+          return;
+        }
+        await sleep(delay);
+      }
+    }
+  }
+  return {
+    run(key, handler, ...args) {
+      const id = `q_${++sequence}`;
+      if (!accepting || stoppedKeys.has(key)) {
+        const refused = Promise.reject(accepting ? new QueueKeyStoppedError(key) : new QueueStoppedError);
+        refused.catch(() => {
+          return;
+        });
+        return { id, key, result: refused };
+      }
+      let resolve;
+      let reject;
+      const result = new Promise((ok, no) => {
+        resolve = ok;
+        reject = no;
+      });
+      const entry = {
+        id,
+        key,
+        run: async () => handler(...args),
+        resolve,
+        reject,
+        attempt: 0,
+        cancelled: false
+      };
+      const lane = lanes.get(key);
+      if (lane)
+        lane.push(entry);
+      else
+        lanes.set(key, [entry]);
+      pump();
+      return { id, key, result };
+    },
+    cancel(id) {
+      for (const [key, lane] of lanes) {
+        const index = lane.findIndex((entry2) => entry2.id === id);
+        if (index === -1)
+          continue;
+        const [entry] = lane.splice(index, 1);
+        entry.cancelled = true;
+        entry.reject(new TaskCancelledError);
+        if (lane.length === 0 && !running.has(key))
+          lanes.delete(key);
+        announceIdle();
+        return true;
+      }
+      return false;
+    },
+    pauseKey(key) {
+      paused.add(key);
+    },
+    resumeKey(key) {
+      paused.delete(key);
+      pump();
+    },
+    stopKey(key) {
+      stoppedKeys.add(key);
+      paused.delete(key);
+      const lane = lanes.get(key);
+      if (!lane)
+        return 0;
+      let removed = 0;
+      for (const entry of lane.splice(0)) {
+        removed += 1;
+        entry.cancelled = true;
+        entry.reject(new QueueKeyStoppedError(key));
+      }
+      if (!running.has(key))
+        lanes.delete(key);
+      announceIdle();
+      return removed;
+    },
+    startKey(key) {
+      const changed = stoppedKeys.delete(key);
+      pump();
+      return changed;
+    },
+    pause() {
+      globallyPaused = true;
+    },
+    resume() {
+      globallyPaused = false;
+      pump();
+    },
+    snapshot() {
+      let queued = 0;
+      for (const lane of lanes.values())
+        queued += lane.length;
+      return {
+        running: running.size,
+        queued,
+        keys: lanes.size,
+        paused: globallyPaused,
+        pausedKeys: [...paused],
+        stoppedKeys: [...stoppedKeys],
+        completed,
+        failed
+      };
+    },
+    whenIdle() {
+      if (running.size === 0 && [...lanes.values()].every((lane) => lane.length === 0)) {
+        return Promise.resolve();
+      }
+      return new Promise((resolve) => idle.push(resolve));
+    },
+    async stop(deadlineMs = 30000) {
+      if (!Number.isSafeInteger(deadlineMs) || deadlineMs < 0) {
+        throw new RangeError("queue: stop deadline must be a non-negative integer");
+      }
+      accepting = false;
+      const before = { completed, failed };
+      globallyPaused = false;
+      paused.clear();
+      pump();
+      let timedOut = false;
+      let deadlineHandle;
+      const deadline = new Promise((resolve) => {
+        deadlineHandle = setTimeout(() => {
+          timedOut = true;
+          resolve();
+        }, deadlineMs);
+      });
+      await Promise.race([this.whenIdle(), deadline]);
+      if (!timedOut && deadlineHandle !== undefined)
+        clearTimeout(deadlineHandle);
+      if (timedOut)
+        aborted = true;
+      let abandoned = 0;
+      for (const lane of lanes.values()) {
+        abandoned += lane.length;
+        for (const entry of lane.splice(0))
+          entry.reject(new QueueStoppedError);
+      }
+      abandoned += running.size;
+      for (const [key, lane] of lanes) {
+        if (lane.length === 0 && !running.has(key))
+          lanes.delete(key);
+      }
+      announceIdle();
+      return {
+        completed: completed - before.completed,
+        failed: failed - before.failed,
+        abandoned,
+        timedOut
+      };
+    }
+  };
+}
+
 // src/jobs.ts
 var systemClock = {
   now: () => Date.now(),
@@ -83,10 +352,13 @@ function createScheduler(options) {
     { key: job.key, label: job.label, state: "stopped", consecutiveFailures: 0, runs: 0, skippedLocked: 0 }
   ]));
   const timers = new Map;
-  const inFlight = new Map;
+  let work = createQueue({ width: Math.max(1, jobs.size) });
+  let workStopped = false;
+  let restartBlocked = false;
   let controller = new AbortController;
   let paused = false;
   let running = false;
+  const submit = (job) => work.run(job.key, execute, job).result;
   async function execute(job) {
     const report = reports.get(job.key);
     const leaseMs = job.leaseMs ?? (job.every ? everyMs(job.every) * 4 : 60000);
@@ -132,17 +404,22 @@ function createScheduler(options) {
       timers.delete(job.key);
       if (!running || paused)
         return;
-      const work = execute(job).finally(() => {
-        inFlight.delete(job.key);
-        schedule(job, everyMs(job.every));
+      submit(job).then(() => schedule(job, everyMs(job.every)), () => {
+        return;
       });
-      inFlight.set(job.key, work);
     }, delayMs));
   }
   return {
     start() {
       if (running)
         return;
+      if (restartBlocked) {
+        throw new Error("scheduler: cannot restart after an incomplete drain while abandoned work may still run");
+      }
+      if (workStopped) {
+        work = createQueue({ width: Math.max(1, jobs.size) });
+        workStopped = false;
+      }
       running = true;
       paused = false;
       controller = new AbortController;
@@ -152,15 +429,18 @@ function createScheduler(options) {
         schedule(job, job.startDelayMs ?? spreadOf(job.key, Math.min(interval, 30000)));
       }
     },
-    async stop() {
+    async stop(deadlineMs = 30000) {
       running = false;
       controller.abort();
       for (const timer of timers.values())
         clearTimeout(timer);
       timers.clear();
-      await Promise.allSettled([...inFlight.values()]);
+      const drained = await work.stop(deadlineMs);
+      workStopped = true;
+      restartBlocked = drained.timedOut;
       for (const report of reports.values())
         report.state = "stopped";
+      return drained;
     },
     pause() {
       paused = true;
@@ -185,12 +465,7 @@ function createScheduler(options) {
       const job = jobs.get(key);
       if (!job)
         throw new Error(`No job named "${key}".`);
-      const existing = inFlight.get(key);
-      if (existing)
-        await existing;
-      const work = execute(job).finally(() => inFlight.delete(key));
-      inFlight.set(key, work);
-      await work;
+      await submit(job);
       return { ...reports.get(key) };
     },
     status: () => [...reports.values()].map((report) => ({ ...report })),

package/dist/pipeline.d.ts

@@ -1,11 +1,12 @@
 /**
- * Deciding whether a push should cause a deploy, and what that deploy is.
+ * Deciding whether a push should cause a deploy.
  *
  * A webhook receiver is a public endpoint that runs commands on your machines
  * when something posts to it. Everything worth getting right is in the gap
- * between those two facts, so this module holds the decisions and none of the
- * doing: no network, no shell, no clone. What it produces is a PLAN, and
- * something else carries it out.
+ * between those two facts, so this module holds trigger verification and none
+ * of the doing: no network, no shell, no clone, and no executable plan. The
+ * agent later reads the only deployment definition from the exact checked-out
+ * commit.
  *
  * That split is not tidiness. It means the interesting cases — a forged
  * signature, a push to a branch nobody deploys, two pushes racing, a repository
@@ -21,8 +22,8 @@
  * matters when reading logs during an incident.
  */
 export declare class PipelineError extends Error {
-    readonly code: 'BAD_SIGNATURE' | 'UNSUPPORTED_PROVIDER' | 'MALFORMED_EVENT' | 'WRONG_REPOSITORY' | 'NO_SECRET';
-    constructor(code: 'BAD_SIGNATURE' | 'UNSUPPORTED_PROVIDER' | 'MALFORMED_EVENT' | 'WRONG_REPOSITORY' | 'NO_SECRET', message: string);
+    readonly code: 'BAD_SIGNATURE' | 'UNSUPPORTED_PROVIDER' | 'MALFORMED_EVENT' | 'NO_SECRET';
+    constructor(code: 'BAD_SIGNATURE' | 'UNSUPPORTED_PROVIDER' | 'MALFORMED_EVENT' | 'NO_SECRET', message: string);
 }
 export declare const GIT_PROVIDERS: readonly ["github", "gitlab", "generic"];
 export type GitProvider = (typeof GIT_PROVIDERS)[number];
@@ -73,50 +74,23 @@ export interface PushEvent {
  * failure every time somebody opened an issue.
  */
 export declare function parsePush(provider: GitProvider, body: unknown): PushEvent | null;
-export interface PipelineConfig {
+export interface DeployTrigger {
     provider: GitProvider;
     /** `owner/name`. Compared against the delivery. */
     repository: string;
     /** Only this branch deploys. One branch per pipeline, deliberately. */
     branch: string;
-    /** Where the checkout lives on the compute. */
-    workdir: string;
-    /** Shell steps, in order. Empty means clone only. */
-    steps: readonly string[];
-    cloneUrl: string;
 }
-export declare const PLAN_ACTIONS: readonly ["clone", "fetch", "checkout", "run"];
-export type PlanAction = (typeof PLAN_ACTIONS)[number];
-export interface PlanStep {
-    action: PlanAction;
-    command: string;
-    /** Shown to an operator. Never contains a credential. */
-    label: string;
-}
-/**
- * The commands that would deploy this push, in order.
- *
- * `clone` and `fetch` are both emitted, guarded on the directory existing,
- * because a runner cannot know in advance whether the first deploy has
- * happened — and branching on that in the caller means two code paths where one
- * of them is exercised once per compute, ever.
- *
- * The commit is checked out by SHA rather than by branch. A branch moves: a
- * deploy that fetched and then checked out `main` could deploy a commit that
- * arrived after the one that triggered it, so the thing tested is not the thing
- * shipped. The SHA is what the webhook said, so what deploys is what fired.
- */
-export declare function planDeploy(config: PipelineConfig, event: PushEvent): PlanStep[];
 /**
  * Should this delivery deploy at all?
  *
- * Separate from `planDeploy` so "we received it and deliberately did nothing"
- * is a first-class outcome with a reason attached. A receiver that silently
+ * "We received it and deliberately did nothing" is a first-class outcome with
+ * a reason attached. A receiver that silently
  * ignored non-matching branches would be indistinguishable from one that is
  * broken, and the first question during an incident is always whether the hook
  * arrived.
  */
-export declare function shouldDeploy(config: PipelineConfig, event: PushEvent | null): {
+export declare function shouldDeploy(config: Pick<DeployTrigger, 'repository' | 'branch'>, event: PushEvent | null): {
     deploy: boolean;
     reason: string;
 };

package/dist/pipeline.js

@@ -72,31 +72,6 @@ function parsePush(provider, body) {
     message: typeof payload.head_commit?.message === "string" ? String(payload.head_commit.message) : undefined
   };
 }
-var PLAN_ACTIONS = ["clone", "fetch", "checkout", "run"];
-function planDeploy(config, event) {
-  if (event.repository !== config.repository) {
-    throw new PipelineError("WRONG_REPOSITORY", `That delivery is for ${event.repository}, and this pipeline deploys ${config.repository}.`);
-  }
-  const dir = config.workdir;
-  return [
-    {
-      action: "clone",
-      command: `[ -d ${dir}/.git ] || git clone ${config.cloneUrl} ${dir}`,
-      label: "clone if this is the first deploy"
-    },
-    { action: "fetch", command: `git -C ${dir} fetch --prune origin`, label: "fetch" },
-    {
-      action: "checkout",
-      command: `git -C ${dir} checkout --detach ${event.commit}`,
-      label: `check out ${event.commit.slice(0, 8)}`
-    },
-    ...config.steps.map((step) => ({
-      action: "run",
-      command: `cd ${dir} && ${step}`,
-      label: step
-    }))
-  ];
-}
 function shouldDeploy(config, event) {
   if (!event)
     return { deploy: false, reason: "Not a branch push — nothing to deploy." };
@@ -113,9 +88,7 @@ export {
   webhookPath,
   verifyWebhook,
   shouldDeploy,
-  planDeploy,
   parsePush,
   PipelineError,
-  PLAN_ACTIONS,
   GIT_PROVIDERS
 };

package/dist/queue.d.ts

@@ -44,9 +44,8 @@ export interface QueueOptions {
     /** How many keys may run at once. Ordering within a key is unaffected. */
     width?: number;
     retry?: Partial<RetryPolicy>;
-    /** Injected so tests need no timers and no wall clock. */
+    /** Retry delay injection. Shutdown deadlines use a cancellable native timer. */
     sleep?: (ms: number) => Promise<void>;
-    now?: () => number;
 }
 export interface DrainReport {
     completed: number;
@@ -58,6 +57,10 @@ export interface DrainReport {
 export declare class QueueStoppedError extends Error {
     constructor();
 }
+export declare class QueueKeyStoppedError extends Error {
+    readonly key: string;
+    constructor(key: string);
+}
 export declare class TaskCancelledError extends Error {
     constructor();
 }
@@ -69,12 +72,22 @@ export declare function createQueue(options?: QueueOptions): {
      * rather than an id to poll — the previous `enqueue` returned only
      * `{ id, duplicate }` and had nowhere to put an answer.
      */
-    run<T>(key: string, handler: () => Promise<T> | T): QueueTask<T>;
+    run<Args extends unknown[], T>(key: string, handler: (...args: Args) => Promise<T> | T, ...args: Args): QueueTask<T>;
     /** Remove a task that has not started. Running work is left alone. */
     cancel(id: string): boolean;
     /** Hold one key. Work already running for it finishes. */
     pauseKey(key: string): void;
     resumeKey(key: string): void;
+    /**
+     * Close one key and reject everything for it that has not started.
+     *
+     * JavaScript cannot safely kill an arbitrary running function. The current
+     * handler is therefore allowed to finish; every pending handler is removed,
+     * and future submissions are refused until `startKey()` is explicit.
+     */
+    stopKey(key: string): number;
+    /** Re-open a key deliberately; pausing and stopping are not aliases. */
+    startKey(key: string): boolean;
     /** Hold everything. New submissions are accepted and wait. */
     pause(): void;
     resume(): void;
@@ -85,6 +98,7 @@ export declare function createQueue(options?: QueueOptions): {
         keys: number;
         paused: boolean;
         pausedKeys: string[];
+        stoppedKeys: string[];
         completed: number;
         failed: number;
     };

package/dist/queue.js

@@ -14,6 +14,15 @@ class QueueStoppedError extends Error {
   }
 }
 
+class QueueKeyStoppedError extends Error {
+  key;
+  constructor(key) {
+    super(`queue: key ${key} is stopped`);
+    this.key = key;
+    this.name = "QueueKeyStoppedError";
+  }
+}
+
 class TaskCancelledError extends Error {
   constructor() {
     super("queue: task cancelled");
@@ -25,12 +34,19 @@ var DEFAULT_RETRY = {
   backoffMs: (attempt) => Math.min(30000, 2 ** attempt * 100)
 };
 function createQueue(options = {}) {
-  const width = Math.max(1, options.width ?? 8);
+  const width = options.width ?? 8;
   const retry = { ...DEFAULT_RETRY, ...options.retry };
+  if (!Number.isSafeInteger(width) || width < 1) {
+    throw new RangeError("queue: width must be a positive integer");
+  }
+  if (!Number.isSafeInteger(retry.attempts) || retry.attempts < 1) {
+    throw new RangeError("queue: retry attempts must be a positive integer");
+  }
   const sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
   const lanes = new Map;
   const running = new Set;
   const paused = new Set;
+  const stoppedKeys = new Set;
   let sequence = 0;
   let globallyPaused = false;
   let accepting = true;
@@ -48,8 +64,10 @@ function createQueue(options = {}) {
       idle.shift()();
   };
   function pump() {
-    if (globallyPaused || aborted)
+    if (globallyPaused || aborted) {
+      announceIdle();
       return;
+    }
     for (const [key, lane] of lanes) {
       if (running.size >= width)
         break;
@@ -62,18 +80,21 @@ function createQueue(options = {}) {
   async function execute(key) {
     running.add(key);
     try {
-      for (;; ) {
-        const lane = lanes.get(key);
-        const entry = lane?.[0];
-        if (!entry || globallyPaused || paused.has(key) || aborted)
-          break;
+      const lane = lanes.get(key);
+      const entry = lane?.[0];
+      if (entry && !globallyPaused && !paused.has(key) && !aborted) {
         lane.shift();
         await attempt(entry);
       }
     } finally {
       running.delete(key);
-      if (lanes.get(key)?.length === 0)
+      const remaining = lanes.get(key);
+      if (remaining?.length === 0)
         lanes.delete(key);
+      else if (remaining) {
+        lanes.delete(key);
+        lanes.set(key, remaining);
+      }
       pump();
     }
   }
@@ -95,15 +116,21 @@ function createQueue(options = {}) {
           entry.reject(cause);
           return;
         }
-        await sleep(retry.backoffMs(entry.attempt));
+        const delay = retry.backoffMs(entry.attempt);
+        if (!Number.isFinite(delay) || delay < 0) {
+          failed += 1;
+          entry.reject(new RangeError("queue: retry backoff must be a non-negative finite number"));
+          return;
+        }
+        await sleep(delay);
       }
     }
   }
   return {
-    run(key, handler) {
+    run(key, handler, ...args) {
       const id = `q_${++sequence}`;
-      if (!accepting) {
-        const refused = Promise.reject(new QueueStoppedError);
+      if (!accepting || stoppedKeys.has(key)) {
+        const refused = Promise.reject(accepting ? new QueueKeyStoppedError(key) : new QueueStoppedError);
         refused.catch(() => {
           return;
         });
@@ -118,7 +145,7 @@ function createQueue(options = {}) {
       const entry = {
         id,
         key,
-        run: async () => handler(),
+        run: async () => handler(...args),
         resolve,
         reject,
         attempt: 0,
@@ -142,6 +169,7 @@ function createQueue(options = {}) {
         entry.reject(new TaskCancelledError);
         if (lane.length === 0 && !running.has(key))
           lanes.delete(key);
+        announceIdle();
         return true;
       }
       return false;
@@ -153,6 +181,28 @@ function createQueue(options = {}) {
       paused.delete(key);
       pump();
     },
+    stopKey(key) {
+      stoppedKeys.add(key);
+      paused.delete(key);
+      const lane = lanes.get(key);
+      if (!lane)
+        return 0;
+      let removed = 0;
+      for (const entry of lane.splice(0)) {
+        removed += 1;
+        entry.cancelled = true;
+        entry.reject(new QueueKeyStoppedError(key));
+      }
+      if (!running.has(key))
+        lanes.delete(key);
+      announceIdle();
+      return removed;
+    },
+    startKey(key) {
+      const changed = stoppedKeys.delete(key);
+      pump();
+      return changed;
+    },
     pause() {
       globallyPaused = true;
     },
@@ -170,6 +220,7 @@ function createQueue(options = {}) {
         keys: lanes.size,
         paused: globallyPaused,
         pausedKeys: [...paused],
+        stoppedKeys: [...stoppedKeys],
         completed,
         failed
       };
@@ -181,15 +232,25 @@ function createQueue(options = {}) {
       return new Promise((resolve) => idle.push(resolve));
     },
     async stop(deadlineMs = 30000) {
+      if (!Number.isSafeInteger(deadlineMs) || deadlineMs < 0) {
+        throw new RangeError("queue: stop deadline must be a non-negative integer");
+      }
       accepting = false;
       const before = { completed, failed };
+      globallyPaused = false;
+      paused.clear();
+      pump();
       let timedOut = false;
-      await Promise.race([
-        this.whenIdle(),
-        sleep(deadlineMs).then(() => {
+      let deadlineHandle;
+      const deadline = new Promise((resolve) => {
+        deadlineHandle = setTimeout(() => {
           timedOut = true;
-        })
-      ]);
+          resolve();
+        }, deadlineMs);
+      });
+      await Promise.race([this.whenIdle(), deadline]);
+      if (!timedOut && deadlineHandle !== undefined)
+        clearTimeout(deadlineHandle);
       if (timedOut)
         aborted = true;
       let abandoned = 0;
@@ -199,6 +260,11 @@ function createQueue(options = {}) {
           entry.reject(new QueueStoppedError);
       }
       abandoned += running.size;
+      for (const [key, lane] of lanes) {
+        if (lane.length === 0 && !running.has(key))
+          lanes.delete(key);
+      }
+      announceIdle();
       return {
         completed: completed - before.completed,
         failed: failed - before.failed,
@@ -211,5 +277,6 @@ function createQueue(options = {}) {
 export {
   createQueue,
   TaskCancelledError,
-  QueueStoppedError
+  QueueStoppedError,
+  QueueKeyStoppedError
 };

package/dist/snp.d.ts

@@ -17,10 +17,9 @@
  * ## What this does NOT do
  *
  * It does not verify the signature. Chaining a report to AMD's root needs the
- * VCEK certificate for that specific chip at that specific TCB, fetched from
- * AMD's KDS — a network dependency with its own failure modes, and a
- * hand-rolled ECDSA-P384 verification here would be worse than none because it
- * would produce `verified: true` for a report nobody signed.
+ * VCEK certificate for that specific chip at that specific TCB and is performed
+ * by the API's pinned KDS verifier. Keeping network trust out of this parser
+ * preserves a total byte-to-fields function.
  *
  * So `parseSnpReport` returns the signature bytes and says nothing about them.
  * The caller supplies a verifier, which is the same shape every other trust
@@ -29,8 +28,8 @@
 /** The structure is exactly this long. Anything else is not a report. */
 export declare const REPORT_BYTES = 1184;
 export declare class SnpError extends Error {
-    readonly code: 'BAD_LENGTH' | 'BAD_VERSION' | 'BAD_VMPL';
-    constructor(code: 'BAD_LENGTH' | 'BAD_VERSION' | 'BAD_VMPL', message: string);
+    readonly code: 'BAD_LENGTH' | 'BAD_VERSION' | 'BAD_VMPL' | 'BAD_SIGNATURE_ALGORITHM';
+    constructor(code: 'BAD_LENGTH' | 'BAD_VERSION' | 'BAD_VMPL' | 'BAD_SIGNATURE_ALGORITHM', message: string);
 }
 /**
  * Guest policy bits.
@@ -61,6 +60,8 @@ export interface SnpReport {
     guestSvn: number;
     policy: GuestPolicy;
     vmpl: number;
+    /** 1 is ECDSA P-384 with SHA-384. */
+    signatureAlgorithm: number;
     /** 48 bytes of hex. What the guest actually booted. */
     measurement: string;
     /** 64 bytes of hex. Whatever the guest asked the PSP to bind in — our nonce. */

package/dist/snp.js

@@ -69,19 +69,24 @@ function parseSnpReport(bytes) {
   }
   const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
   const version = view.getUint32(OFFSET.version, true);
-  if (version !== 2 && version !== 3) {
+  if (version !== 2 && version !== 3 && version !== 5) {
     throw new SnpError("BAD_VERSION", `Report version ${version} is not one this parser understands.`);
   }
   const vmpl = view.getUint32(OFFSET.vmpl, true);
   if (vmpl > 3) {
     throw new SnpError("BAD_VMPL", `VMPL ${vmpl} is outside the defined range.`);
   }
+  const signatureAlgorithm = view.getUint32(OFFSET.signatureAlgo, true);
+  if (signatureAlgorithm !== 1) {
+    throw new SnpError("BAD_SIGNATURE_ALGORITHM", `Signature algorithm ${signatureAlgorithm} is not ECDSA P-384 with SHA-384.`);
+  }
   const slice = (offset, length) => hex(bytes.subarray(offset, offset + length));
   return {
     version,
     guestSvn: view.getUint32(OFFSET.guestSvn, true),
     policy: readPolicy(view, OFFSET.policy),
     vmpl,
+    signatureAlgorithm,
     measurement: slice(OFFSET.measurement, 48),
     reportData: slice(OFFSET.reportData, 64),
     hostData: slice(OFFSET.hostData, 32),

package/package.json

@@ -1,7 +1,7 @@
 {
 	"//": "Publishing happens from an operator's machine, not CI \u2014 CLAUDE.md records that the absence of CI is deliberate. npm's `provenance` attests a tarball was built by a recognised CI provider from a named commit, so it cannot be produced here: it was set, and the first publish failed with `Automatic provenance generation not supported for provider: null`. A setting that can never be satisfied is worse than none, because it reads as a guarantee nobody is getting. Restore it the day this publishes from CI, and not before.",
 	"name": "@forgezero/runtime",
-	"version": "0.1.1",
+	"version": "0.1.2",
 	"type": "module",
 	"publishConfig": {
 		"access": "public"
@@ -59,10 +59,6 @@
 			"types": "./dist/otpauth.d.ts",
 			"default": "./dist/otpauth.js"
 		},
-		"./serial": {
-			"types": "./dist/serial.d.ts",
-			"default": "./dist/serial.js"
-		},
 		"./pipeline": {
 			"types": "./dist/pipeline.d.ts",
 			"default": "./dist/pipeline.js"
@@ -182,7 +178,7 @@
 	},
 	"scripts": {
 		"check": "tsc --noEmit",
-		"build": "bun build src/jobs.ts src/queue.ts src/serial.ts src/outbox.ts src/audit.ts src/backup.ts src/notify.ts src/notify-templates.ts src/calendar.ts src/compliance.ts src/pipeline.ts src/totp.ts src/otpauth.ts src/identity.ts src/slip10.ts src/openssh.ts src/ssh-cert.ts src/importers.ts src/snp.ts src/passkey.ts src/custody-crypto.ts src/custody-share.ts src/phrase.ts src/ssh-agent.ts src/schema.ts src/schema-typebox.ts src/finance/discounts.ts src/finance/money.ts src/finance/storage.ts src/finance/custody.ts src/finance/tax.ts src/finance/derive.ts src/finance/venues.ts src/finance/ledger.ts src/finance/rates.ts src/finance/transfers.ts src/finance/chain.ts src/finance/chain-addresses.ts src/finance/chain-deposits.ts src/finance/chain-withdrawals.ts src/finance/chain-reconcile.ts src/finance/market.ts src/finance/commission.ts --root src --outdir dist --target browser --format esm --packages external && tsc --emitDeclarationOnly --declaration --noEmit false --outDir dist",
+		"build": "bun build src/jobs.ts src/queue.ts src/outbox.ts src/audit.ts src/backup.ts src/notify.ts src/notify-templates.ts src/calendar.ts src/compliance.ts src/pipeline.ts src/totp.ts src/otpauth.ts src/identity.ts src/slip10.ts src/openssh.ts src/ssh-cert.ts src/importers.ts src/snp.ts src/passkey.ts src/custody-crypto.ts src/custody-share.ts src/phrase.ts src/ssh-agent.ts src/schema.ts src/schema-typebox.ts src/finance/discounts.ts src/finance/money.ts src/finance/storage.ts src/finance/custody.ts src/finance/tax.ts src/finance/derive.ts src/finance/venues.ts src/finance/ledger.ts src/finance/rates.ts src/finance/transfers.ts src/finance/chain.ts src/finance/chain-addresses.ts src/finance/chain-deposits.ts src/finance/chain-withdrawals.ts src/finance/chain-reconcile.ts src/finance/market.ts src/finance/commission.ts --root src --outdir dist --target browser --format esm --packages external && tsc --emitDeclarationOnly --declaration --noEmit false --outDir dist",
 		"prepublishOnly": "bun run check && bun run build"
 	},
 	"dependencies": {
@@ -241,7 +237,7 @@
 		"working-days"
 	],
 	"license": "MIT",
-	"homepage": "https://forgezero.net/docs/runtime",
+	"homepage": "https://www.forgezero.net/docs/runtime",
 	"repository": {
 		"type": "git",
 		"url": "git+https://github.com/axxra/forgezero.git",