@forgezero/runtime 0.1.2 → 0.1.4

package/README.md

@@ -43,7 +43,9 @@ 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 });
+// Default admission is 60% of reported logical CPUs (with one reserved).
+// Use `width` for an exact ceiling, or an explicit dynamic resource policy:
+const queue = createQueue({ resources: { percent: 60, reserve: 1, max: 32 } });
 const task = queue.run('tenant-a:wallet-7', transfer, amount, destination);
 const receipt = await task.result;
 
@@ -55,6 +57,25 @@ queue.cancel(task.id);               // pending task only
 await queue.stop(30_000);            // close intake and drain all work
 ```
 
+Different async keys overlap immediately. CPU-heavy JavaScript does not become
+multi-core merely by entering a queue: put that handler in Bun/standard Workers
+and await the Worker result from the queue.
+
+Jobs accept intervals down to seconds or a local wall-clock schedule with an
+IANA timezone and weekday filter. `overlap: 'wait'` (the default) schedules the
+next run after completion; `overlap: 'skip'` keeps clock cadence and drops a tick
+when the same key is still busy. Same-key overlap is never allowed.
+
+```ts
+defineJob({
+  key: 'tenant:acme:invoice',
+  label: 'Monthly invoice preparation',
+  schedule: { timezone: 'Asia/Kolkata', time: '00:00:15', weekdays: [1] },
+  overlap: 'skip',
+  run: async ({ signal }) => generateInvoices({ signal })
+});
+```
+
 ## Three things worth knowing before you use it
 
 **Money is never a number.** An amount is minor units as a `bigint` with its

package/dist/audit.js

@@ -33,10 +33,41 @@ var DEFAULT_RETRY = {
   attempts: 1,
   backoffMs: (attempt) => Math.min(30000, 2 ** attempt * 100)
 };
+var reportedParallelism = () => {
+  const reported = globalThis.navigator?.hardwareConcurrency;
+  return Number.isSafeInteger(reported) && reported > 0 ? reported : 1;
+};
+function queueWidthFor(policy = {}) {
+  const percent = policy.percent ?? 60;
+  const reserve = policy.reserve ?? 1;
+  const min = policy.min ?? 1;
+  const max = policy.max ?? Number.MAX_SAFE_INTEGER;
+  const available = (policy.available ?? reportedParallelism)();
+  if (!Number.isFinite(percent) || percent <= 0 || percent > 100) {
+    throw new RangeError("queue: resource percent must be greater than 0 and at most 100");
+  }
+  for (const [name, value] of [["reserve", reserve], ["min", min], ["max", max]]) {
+    if (!Number.isSafeInteger(value) || value < (name === "reserve" ? 0 : 1)) {
+      throw new RangeError(`queue: resource ${name} must be ${name === "reserve" ? "a non-negative" : "a positive"} integer`);
+    }
+  }
+  if (!Number.isSafeInteger(available) || available < 1) {
+    throw new RangeError("queue: available parallelism must be a positive integer");
+  }
+  if (min > max)
+    throw new RangeError("queue: resource min cannot exceed max");
+  const usable = Math.max(1, available - reserve);
+  return Math.min(max, Math.max(min, Math.floor(usable * percent / 100)));
+}
 function createQueue(options = {}) {
-  const width = options.width ?? 8;
+  if (options.width !== undefined && options.resources !== undefined) {
+    throw new Error("queue: choose either width or resources, not both");
+  }
+  const configuredWidth = options.width;
+  const widthNow = () => configuredWidth ?? queueWidthFor(options.resources);
+  const initialWidth = widthNow();
   const retry = { ...DEFAULT_RETRY, ...options.retry };
-  if (!Number.isSafeInteger(width) || width < 1) {
+  if (!Number.isSafeInteger(initialWidth) || initialWidth < 1) {
     throw new RangeError("queue: width must be a positive integer");
   }
   if (!Number.isSafeInteger(retry.attempts) || retry.attempts < 1) {
@@ -68,6 +99,7 @@ function createQueue(options = {}) {
       announceIdle();
       return;
     }
+    const width = widthNow();
     for (const [key, lane] of lanes) {
       if (running.size >= width)
         break;
@@ -215,6 +247,7 @@ function createQueue(options = {}) {
       for (const lane of lanes.values())
         queued += lane.length;
       return {
+        width: widthNow(),
         running: running.size,
         queued,
         keys: lanes.size,

package/dist/identity.d.ts

@@ -64,6 +64,28 @@ export interface SignedEnvelope {
     edSignature: string;
     mlDsaSignature: string;
 }
+export interface ResponseRecipient {
+    publicKey: string;
+    secretKey: string;
+}
+export interface SealedResponse {
+    version: 1;
+    kemCiphertext: string;
+    nonce: string;
+    ciphertext: string;
+}
+export declare const RESPONSE_KEY_HEADER = "x-fz-response-key";
+export declare function validResponsePublicKey(value: string): boolean;
+/** One ephemeral hybrid ML-KEM-768 + X25519 recipient per request. */
+export declare function generateResponseRecipient(): ResponseRecipient;
+/** Seal one JSON response so TLS termination never sees the secret payload. */
+export declare function sealResponse<T>(recipientPublicKey: string, requestBinding: string, payload: T): Promise<SealedResponse>;
+/** Open a response only with the request's ephemeral private half and exact signature binding. */
+export declare function openResponse<T>(recipientSecretKey: string, requestBinding: string, envelope: SealedResponse): Promise<T>;
+/** One wire encoding for Agent and external API-key hybrid signatures. */
+export declare function encodeSignatureHeader(envelope: SignedEnvelope): string;
+/** Parse the common wire encoding and bind its public key id from the companion header. */
+export declare function decodeSignatureHeader(raw: string, nodeKey: string): SignedEnvelope | null;
 /**
  * The bytes that get signed.
  *
@@ -79,12 +101,14 @@ export declare function canonicalString(args: {
     timestamp: number;
     nonce: string;
     body: string | Uint8Array;
+    responseKey?: string;
 }): string;
 export declare function signRequest(keys: NodeKeyPair, nodeKey: string, args: {
     method: string;
     path: string;
     query?: string;
     body: string | Uint8Array;
+    responseKey?: string;
 }): SignedEnvelope;
 export type VerifyFailure = 'timestamp_out_of_window' | 'ed25519_invalid' | 'ml_dsa_invalid' | 'malformed';
 /** Requests older or newer than this are refused before any signature work. */
@@ -106,6 +130,7 @@ export declare function verifyRequest(args: {
     path: string;
     query?: string;
     body: string | Uint8Array;
+    responseKey?: string;
     nowSeconds?: number;
 }): {
     verified: true;

package/dist/identity.js

@@ -10,6 +10,7 @@ var __require = /* @__PURE__ */ ((x) => typeof require !== "undefined" ? require
 import { toBase64Url, fromBase64Url } from "@forgezero/access/security";
 import { ed25519 } from "@noble/curves/ed25519.js";
 import { ml_dsa65 } from "@noble/post-quantum/ml-dsa.js";
+import { ml_kem768_x25519 } from "@noble/post-quantum/hybrid.js";
 import { sha256 } from "@noble/hashes/sha2.js";
 import { hkdf } from "@noble/hashes/hkdf.js";
 var ENCODER = new TextEncoder;
@@ -41,17 +42,104 @@ function generateNodeKeys() {
     mlDsa: { publicKey: b64(mlKeys.publicKey), secretKey: b64(mlKeys.secretKey) }
   };
 }
+var RESPONSE_KEY_HEADER = "x-fz-response-key";
+function validResponsePublicKey(value) {
+  try {
+    return un64(value).length === ml_kem768_x25519.lengths.publicKey;
+  } catch {
+    return false;
+  }
+}
+function generateResponseRecipient() {
+  const pair = ml_kem768_x25519.keygen();
+  return { publicKey: b64(pair.publicKey), secretKey: b64(pair.secretKey) };
+}
+var responseKey = (sharedSecret) => hkdf(sha256, sharedSecret, undefined, ENCODER.encode("forgezero/response/ml-kem-768+x25519/v1"), 32);
+async function sealResponse(recipientPublicKey, requestBinding, payload) {
+  const { cipherText, sharedSecret } = ml_kem768_x25519.encapsulate(un64(recipientPublicKey));
+  const rawKey = responseKey(sharedSecret);
+  sharedSecret.fill(0);
+  const key = await crypto.subtle.importKey("raw", new Uint8Array(rawKey), "AES-GCM", false, ["encrypt"]);
+  rawKey.fill(0);
+  const nonce = randomBytes(12);
+  const serialized = JSON.stringify(payload);
+  if (serialized === undefined)
+    throw new Error("response: payload is not JSON serializable");
+  const plaintext = ENCODER.encode(serialized);
+  const ciphertext = await crypto.subtle.encrypt({
+    name: "AES-GCM",
+    iv: new Uint8Array(nonce),
+    additionalData: new Uint8Array(ENCODER.encode(requestBinding)),
+    tagLength: 128
+  }, key, new Uint8Array(plaintext));
+  plaintext.fill(0);
+  return {
+    version: 1,
+    kemCiphertext: b64(cipherText),
+    nonce: b64(nonce),
+    ciphertext: b64(new Uint8Array(ciphertext))
+  };
+}
+async function openResponse(recipientSecretKey, requestBinding, envelope) {
+  if (envelope?.version !== 1)
+    throw new Error("response: unsupported sealed response");
+  const sharedSecret = ml_kem768_x25519.decapsulate(un64(envelope.kemCiphertext), un64(recipientSecretKey));
+  const rawKey = responseKey(sharedSecret);
+  sharedSecret.fill(0);
+  const key = await crypto.subtle.importKey("raw", new Uint8Array(rawKey), "AES-GCM", false, ["decrypt"]);
+  rawKey.fill(0);
+  const decrypted = new Uint8Array(await crypto.subtle.decrypt({
+    name: "AES-GCM",
+    iv: new Uint8Array(un64(envelope.nonce)),
+    additionalData: new Uint8Array(ENCODER.encode(requestBinding)),
+    tagLength: 128
+  }, key, new Uint8Array(un64(envelope.ciphertext))));
+  try {
+    return JSON.parse(new TextDecoder().decode(decrypted));
+  } finally {
+    decrypted.fill(0);
+  }
+}
+var SIGNATURE_FIELDS = (envelope) => ({
+  timestamp: envelope.timestamp,
+  nonce: envelope.nonce,
+  edSignature: envelope.edSignature,
+  mlDsaSignature: envelope.mlDsaSignature
+});
+function encodeSignatureHeader(envelope) {
+  return b64(ENCODER.encode(JSON.stringify(SIGNATURE_FIELDS(envelope))));
+}
+function decodeSignatureHeader(raw, nodeKey) {
+  let parsed;
+  try {
+    parsed = JSON.parse(new TextDecoder().decode(un64(raw)));
+  } catch {
+    return null;
+  }
+  if (typeof parsed.timestamp !== "number" || !Number.isSafeInteger(parsed.timestamp) || typeof parsed.nonce !== "string" || typeof parsed.edSignature !== "string" || typeof parsed.mlDsaSignature !== "string")
+    return null;
+  return {
+    nodeKey,
+    timestamp: parsed.timestamp,
+    nonce: parsed.nonce,
+    edSignature: parsed.edSignature,
+    mlDsaSignature: parsed.mlDsaSignature
+  };
+}
 function canonicalString(args) {
   const body = typeof args.body === "string" ? ENCODER.encode(args.body) : args.body;
   const digest = Array.from(sha256(body), (byte) => byte.toString(16).padStart(2, "0")).join("");
-  return [
+  const fields = [
     args.method.toUpperCase(),
     args.path,
     args.query ?? "",
     String(args.timestamp),
     args.nonce,
     digest
-  ].join(`
+  ];
+  if (args.responseKey)
+    fields.push(args.responseKey);
+  return fields.join(`
 `);
 }
 function signRequest(keys, nodeKey, args) {
@@ -80,7 +168,8 @@ function verifyRequest(args) {
       query: args.query ?? "",
       timestamp: args.envelope.timestamp,
       nonce: args.envelope.nonce,
-      body: args.body
+      body: args.body,
+      responseKey: args.responseKey
     }));
   } catch {
     return { verified: false, reason: "malformed" };
@@ -103,9 +192,16 @@ function verifyRequest(args) {
 }
 export {
   verifyRequest,
+  validResponsePublicKey,
   signRequest,
+  sealResponse,
+  openResponse,
+  generateResponseRecipient,
   generateNodeKeys,
+  encodeSignatureHeader,
   deriveKeysFromSeed,
+  decodeSignatureHeader,
   canonicalString,
+  RESPONSE_KEY_HEADER,
   CLOCK_SKEW_SECONDS
 };

package/dist/jobs.d.ts

@@ -20,7 +20,7 @@
  * 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';
+import { type DrainReport, type QueueResourcePolicy } from './queue';
 /** Injected so a test does not sleep and a resumed run is reproducible. */
 export interface Clock {
     now(): number;
@@ -29,6 +29,20 @@ export interface Clock {
 export declare const systemClock: Clock;
 /** `30s` → 30000. Throws rather than guessing — a wrong interval is silent. */
 export declare function everyMs(interval: string | number): number;
+export interface WallClockSchedule {
+    /** IANA timezone such as `Asia/Kolkata` or `UTC`. */
+    timezone: string;
+    /** Local wall time, including optional seconds: `HH:MM` or `HH:MM:SS`. */
+    time: string;
+    /** Optional local weekdays, Sunday=0 through Saturday=6. */
+    weekdays?: readonly number[];
+}
+/**
+ * Find the next occurrence strictly after `afterMs` in the requested timezone.
+ * Intl owns daylight-saving and historical offset rules; the bounded minute
+ * scan avoids implementing a second, inevitably-wrong timezone database here.
+ */
+export declare function nextWallClockAt(schedule: WallClockSchedule, afterMs: number): number;
 /**
  * A lease, not a mutex.
  *
@@ -80,6 +94,14 @@ export interface JobSpec {
     label: string;
     /** `30s`, `5m`, or milliseconds. Omit for a job only ever run by hand. */
     every?: string | number;
+    /** Local daily/weekly schedule. Mutually exclusive with `every`. */
+    schedule?: WallClockSchedule;
+    /**
+     * `wait` schedules the next occurrence after this run settles. `skip` keeps
+     * clock time and drops a tick when the previous run is still queued/running.
+     * Neither mode overlaps the same key.
+     */
+    overlap?: 'wait' | 'skip';
     run(context: JobContext): Promise<JobResult | void>;
     /**
      * Lease length. Defaults to four intervals, so a slow run is not evicted the
@@ -107,6 +129,8 @@ export interface JobReport {
     consecutiveFailures: number;
     runs: number;
     skippedLocked: number;
+    skippedOverlap: number;
+    nextRunAtMs?: number;
 }
 export interface SchedulerOptions {
     jobs: readonly JobSpec[];
@@ -115,6 +139,10 @@ export interface SchedulerOptions {
     /** Called on every failure. Wire to telemetry; must not throw. */
     onError?: (key: string, error: unknown) => void;
     onLog?: (key: string, message: string, detail?: Record<string, unknown>) => void;
+    /** Exact lane ceiling. Mutually exclusive with `resources`. */
+    width?: number;
+    /** Dynamic resource admission for different job keys. */
+    resources?: QueueResourcePolicy;
 }
 export declare function createScheduler(options: SchedulerOptions): {
     start(): void;

package/dist/jobs.js

@@ -33,10 +33,41 @@ var DEFAULT_RETRY = {
   attempts: 1,
   backoffMs: (attempt) => Math.min(30000, 2 ** attempt * 100)
 };
+var reportedParallelism = () => {
+  const reported = globalThis.navigator?.hardwareConcurrency;
+  return Number.isSafeInteger(reported) && reported > 0 ? reported : 1;
+};
+function queueWidthFor(policy = {}) {
+  const percent = policy.percent ?? 60;
+  const reserve = policy.reserve ?? 1;
+  const min = policy.min ?? 1;
+  const max = policy.max ?? Number.MAX_SAFE_INTEGER;
+  const available = (policy.available ?? reportedParallelism)();
+  if (!Number.isFinite(percent) || percent <= 0 || percent > 100) {
+    throw new RangeError("queue: resource percent must be greater than 0 and at most 100");
+  }
+  for (const [name, value] of [["reserve", reserve], ["min", min], ["max", max]]) {
+    if (!Number.isSafeInteger(value) || value < (name === "reserve" ? 0 : 1)) {
+      throw new RangeError(`queue: resource ${name} must be ${name === "reserve" ? "a non-negative" : "a positive"} integer`);
+    }
+  }
+  if (!Number.isSafeInteger(available) || available < 1) {
+    throw new RangeError("queue: available parallelism must be a positive integer");
+  }
+  if (min > max)
+    throw new RangeError("queue: resource min cannot exceed max");
+  const usable = Math.max(1, available - reserve);
+  return Math.min(max, Math.max(min, Math.floor(usable * percent / 100)));
+}
 function createQueue(options = {}) {
-  const width = options.width ?? 8;
+  if (options.width !== undefined && options.resources !== undefined) {
+    throw new Error("queue: choose either width or resources, not both");
+  }
+  const configuredWidth = options.width;
+  const widthNow = () => configuredWidth ?? queueWidthFor(options.resources);
+  const initialWidth = widthNow();
   const retry = { ...DEFAULT_RETRY, ...options.retry };
-  if (!Number.isSafeInteger(width) || width < 1) {
+  if (!Number.isSafeInteger(initialWidth) || initialWidth < 1) {
     throw new RangeError("queue: width must be a positive integer");
   }
   if (!Number.isSafeInteger(retry.attempts) || retry.attempts < 1) {
@@ -68,6 +99,7 @@ function createQueue(options = {}) {
       announceIdle();
       return;
     }
+    const width = widthNow();
     for (const [key, lane] of lanes) {
       if (running.size >= width)
         break;
@@ -215,6 +247,7 @@ function createQueue(options = {}) {
       for (const lane of lanes.values())
         queued += lane.length;
       return {
+        width: widthNow(),
         running: running.size,
         queued,
         keys: lanes.size,
@@ -297,6 +330,53 @@ function everyMs(interval) {
     throw new Error(`"${interval}" is not an interval like 30s, 5m, 1h, 1d.`);
   return Number(match[1]) * UNITS[match[2]];
 }
+var WEEKDAY = { Sun: 0, Mon: 1, Tue: 2, Wed: 3, Thu: 4, Fri: 5, Sat: 6 };
+function wallTime(schedule) {
+  const match = /^(\d{2}):(\d{2})(?::(\d{2}))?$/.exec(schedule.time);
+  if (!match)
+    throw new Error(`"${schedule.time}" is not a wall time like 09:30 or 09:30:15.`);
+  const hour = Number(match[1]);
+  const minute = Number(match[2]);
+  const second = Number(match[3] ?? 0);
+  if (hour > 23 || minute > 59 || second > 59)
+    throw new Error(`"${schedule.time}" is not a valid wall time.`);
+  return { hour, minute, second };
+}
+function nextWallClockAt(schedule, afterMs) {
+  if (!Number.isFinite(afterMs))
+    throw new RangeError("job: schedule start must be finite");
+  const target = wallTime(schedule);
+  const weekdays = schedule.weekdays ? new Set(schedule.weekdays) : undefined;
+  if (weekdays?.size === 0 || [...weekdays ?? []].some((day) => !Number.isSafeInteger(day) || day < 0 || day > 6)) {
+    throw new Error("job: weekdays must contain Sunday=0 through Saturday=6");
+  }
+  let formatter;
+  try {
+    formatter = new Intl.DateTimeFormat("en-US", {
+      timeZone: schedule.timezone,
+      hour: "2-digit",
+      minute: "2-digit",
+      second: "2-digit",
+      weekday: "short",
+      hourCycle: "h23"
+    });
+  } catch {
+    throw new Error(`job: unknown IANA timezone "${schedule.timezone}"`);
+  }
+  const minuteFloor = Math.floor(afterMs / 60000) * 60000;
+  let candidate = minuteFloor + target.second * 1000;
+  if (candidate <= afterMs)
+    candidate += 60000;
+  for (let checked = 0;checked < 8 * 24 * 60; checked += 1, candidate += 60000) {
+    const parts = Object.fromEntries(formatter.formatToParts(candidate).map((part) => [part.type, part.value]));
+    if (Number(parts.hour) !== target.hour || Number(parts.minute) !== target.minute || Number(parts.second) !== target.second)
+      continue;
+    const weekday = WEEKDAY[parts.weekday];
+    if (!weekdays || weekdays.has(weekday))
+      return candidate;
+  }
+  throw new Error("job: no matching wall-clock occurrence was found in the next eight days");
+}
 function memoryLock(clock = systemClock) {
   const held = new Map;
   let fences = 0;
@@ -335,6 +415,10 @@ function defineJob(spec) {
     throw new Error("A job needs a key — it is the lock key and the report key.");
   if (spec.every !== undefined)
     everyMs(spec.every);
+  if (spec.every !== undefined && spec.schedule)
+    throw new Error("A job must choose either every or schedule.");
+  if (spec.schedule)
+    nextWallClockAt(spec.schedule, Date.now());
   return spec;
 }
 function spreadOf(key, ceiling) {
@@ -349,16 +433,29 @@ function createScheduler(options) {
   const jobs = new Map(options.jobs.map((job) => [job.key, job]));
   const reports = new Map(options.jobs.map((job) => [
     job.key,
-    { key: job.key, label: job.label, state: "stopped", consecutiveFailures: 0, runs: 0, skippedLocked: 0 }
+    { key: job.key, label: job.label, state: "stopped", consecutiveFailures: 0, runs: 0, skippedLocked: 0, skippedOverlap: 0 }
   ]));
   const timers = new Map;
-  let work = createQueue({ width: Math.max(1, jobs.size) });
+  const queueOptions = options.width !== undefined ? { width: options.width } : options.resources !== undefined ? { resources: options.resources } : { width: Math.max(1, jobs.size) };
+  let work = createQueue(queueOptions);
   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;
+  const outstanding = new Map;
+  const submit = async (job) => {
+    outstanding.set(job.key, (outstanding.get(job.key) ?? 0) + 1);
+    try {
+      await work.run(job.key, execute, job).result;
+    } finally {
+      const left = (outstanding.get(job.key) ?? 1) - 1;
+      if (left === 0)
+        outstanding.delete(job.key);
+      else
+        outstanding.set(job.key, left);
+    }
+  };
   async function execute(job) {
     const report = reports.get(job.key);
     const leaseMs = job.leaseMs ?? (job.every ? everyMs(job.every) * 4 : 60000);
@@ -397,17 +494,37 @@ function createScheduler(options) {
         });
     }
   }
+  function nextDelay(job) {
+    if (job.every !== undefined)
+      return everyMs(job.every);
+    if (job.schedule)
+      return Math.max(0, nextWallClockAt(job.schedule, clock.now()) - clock.now());
+    return;
+  }
   function schedule(job, delayMs) {
-    if (!running || job.every === undefined)
+    const next = delayMs ?? nextDelay(job);
+    if (!running || next === undefined)
       return;
+    reports.get(job.key).nextRunAtMs = clock.now() + next;
     timers.set(job.key, setTimeout(() => {
       timers.delete(job.key);
       if (!running || paused)
         return;
-      submit(job).then(() => schedule(job, everyMs(job.every)), () => {
+      if (job.overlap === "skip") {
+        schedule(job);
+        if ((outstanding.get(job.key) ?? 0) > 0) {
+          reports.get(job.key).skippedOverlap += 1;
+          return;
+        }
+        submit(job).catch(() => {
+          return;
+        });
+        return;
+      }
+      submit(job).then(() => schedule(job), () => {
         return;
       });
-    }, delayMs));
+    }, next));
   }
   return {
     start() {
@@ -417,7 +534,7 @@ function createScheduler(options) {
         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) });
+        work = createQueue(queueOptions);
         workStopped = false;
       }
       running = true;
@@ -425,8 +542,9 @@ function createScheduler(options) {
       controller = new AbortController;
       for (const job of jobs.values()) {
         reports.get(job.key).state = "idle";
-        const interval = job.every === undefined ? 0 : everyMs(job.every);
-        schedule(job, job.startDelayMs ?? spreadOf(job.key, Math.min(interval, 30000)));
+        const interval = job.every === undefined ? undefined : everyMs(job.every);
+        const initial = job.startDelayMs ?? (interval === undefined ? undefined : spreadOf(job.key, Math.min(interval, 30000)));
+        schedule(job, initial);
       }
     },
     async stop(deadlineMs = 30000) {
@@ -440,6 +558,8 @@ function createScheduler(options) {
       restartBlocked = drained.timedOut;
       for (const report of reports.values())
         report.state = "stopped";
+      for (const report of reports.values())
+        report.nextRunAtMs = undefined;
       return drained;
     },
     pause() {
@@ -450,6 +570,7 @@ function createScheduler(options) {
       for (const report of reports.values()) {
         if (report.state !== "running")
           report.state = "paused";
+        report.nextRunAtMs = undefined;
       }
     },
     resume() {
@@ -458,7 +579,7 @@ function createScheduler(options) {
       paused = false;
       for (const job of jobs.values()) {
         reports.get(job.key).state = "idle";
-        schedule(job, 0);
+        schedule(job, job.every !== undefined ? 0 : undefined);
       }
     },
     async runNow(key) {
@@ -483,6 +604,8 @@ function cursorJob(spec) {
     key: spec.key,
     label: spec.label,
     every: spec.every,
+    schedule: spec.schedule,
+    overlap: spec.overlap,
     leaseMs: spec.leaseMs,
     unlocked: spec.unlocked,
     startDelayMs: spec.startDelayMs,
@@ -516,6 +639,7 @@ var VERSION = "0.1.0";
 export {
   systemClock,
   storeLock,
+  nextWallClockAt,
   memoryLock,
   everyMs,
   defineJob,

package/dist/queue.d.ts

@@ -43,10 +43,33 @@ export interface RetryPolicy {
 export interface QueueOptions {
     /** How many keys may run at once. Ordering within a key is unaffected. */
     width?: number;
+    /**
+     * Resource-aware admission. Mutually exclusive with `width`.
+     *
+     * This limits concurrent KEY lanes; it does not claim that an arbitrary
+     * JavaScript closure becomes CPU-parallel. Async I/O overlaps naturally.
+     * CPU-bound handlers should use Bun/standard Workers and await them here.
+     */
+    resources?: QueueResourcePolicy;
     retry?: Partial<RetryPolicy>;
     /** Retry delay injection. Shutdown deadlines use a cancellable native timer. */
     sleep?: (ms: number) => Promise<void>;
 }
+export interface QueueResourcePolicy {
+    /** Percentage of the currently reported logical processors. Default 60. */
+    percent?: number;
+    /** Logical processors kept outside this queue. Default 1 when possible. */
+    reserve?: number;
+    /** Never admit fewer lanes than this. Default 1. */
+    min?: number;
+    /** Optional hard ceiling after percentage and reserve are applied. */
+    max?: number;
+    /**
+     * Re-read on every pump, so a container/runtime can expose a changing quota.
+     * The default uses `navigator.hardwareConcurrency` and safely falls back to 1.
+     */
+    available?: () => number;
+}
 export interface DrainReport {
     completed: number;
     failed: number;
@@ -64,6 +87,8 @@ export declare class QueueKeyStoppedError extends Error {
 export declare class TaskCancelledError extends Error {
     constructor();
 }
+/** Resolve a resource policy to a safe positive queue width. */
+export declare function queueWidthFor(policy?: QueueResourcePolicy): number;
 export declare function createQueue(options?: QueueOptions): {
     /**
      * Submit work and await its value.
@@ -93,6 +118,7 @@ export declare function createQueue(options?: QueueOptions): {
     resume(): void;
     /** How much is outstanding, for a health endpoint or a drain decision. */
     snapshot(): {
+        width: number;
         running: number;
         queued: number;
         keys: number;

package/dist/queue.js

@@ -33,10 +33,41 @@ var DEFAULT_RETRY = {
   attempts: 1,
   backoffMs: (attempt) => Math.min(30000, 2 ** attempt * 100)
 };
+var reportedParallelism = () => {
+  const reported = globalThis.navigator?.hardwareConcurrency;
+  return Number.isSafeInteger(reported) && reported > 0 ? reported : 1;
+};
+function queueWidthFor(policy = {}) {
+  const percent = policy.percent ?? 60;
+  const reserve = policy.reserve ?? 1;
+  const min = policy.min ?? 1;
+  const max = policy.max ?? Number.MAX_SAFE_INTEGER;
+  const available = (policy.available ?? reportedParallelism)();
+  if (!Number.isFinite(percent) || percent <= 0 || percent > 100) {
+    throw new RangeError("queue: resource percent must be greater than 0 and at most 100");
+  }
+  for (const [name, value] of [["reserve", reserve], ["min", min], ["max", max]]) {
+    if (!Number.isSafeInteger(value) || value < (name === "reserve" ? 0 : 1)) {
+      throw new RangeError(`queue: resource ${name} must be ${name === "reserve" ? "a non-negative" : "a positive"} integer`);
+    }
+  }
+  if (!Number.isSafeInteger(available) || available < 1) {
+    throw new RangeError("queue: available parallelism must be a positive integer");
+  }
+  if (min > max)
+    throw new RangeError("queue: resource min cannot exceed max");
+  const usable = Math.max(1, available - reserve);
+  return Math.min(max, Math.max(min, Math.floor(usable * percent / 100)));
+}
 function createQueue(options = {}) {
-  const width = options.width ?? 8;
+  if (options.width !== undefined && options.resources !== undefined) {
+    throw new Error("queue: choose either width or resources, not both");
+  }
+  const configuredWidth = options.width;
+  const widthNow = () => configuredWidth ?? queueWidthFor(options.resources);
+  const initialWidth = widthNow();
   const retry = { ...DEFAULT_RETRY, ...options.retry };
-  if (!Number.isSafeInteger(width) || width < 1) {
+  if (!Number.isSafeInteger(initialWidth) || initialWidth < 1) {
     throw new RangeError("queue: width must be a positive integer");
   }
   if (!Number.isSafeInteger(retry.attempts) || retry.attempts < 1) {
@@ -68,6 +99,7 @@ function createQueue(options = {}) {
       announceIdle();
       return;
     }
+    const width = widthNow();
     for (const [key, lane] of lanes) {
       if (running.size >= width)
         break;
@@ -215,6 +247,7 @@ function createQueue(options = {}) {
       for (const lane of lanes.values())
         queued += lane.length;
       return {
+        width: widthNow(),
         running: running.size,
         queued,
         keys: lanes.size,
@@ -275,6 +308,7 @@ function createQueue(options = {}) {
   };
 }
 export {
+  queueWidthFor,
   createQueue,
   TaskCancelledError,
   QueueStoppedError,

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.2",
+	"version": "0.1.4",
 	"type": "module",
 	"publishConfig": {
 		"access": "public"
@@ -178,6 +178,7 @@
 	},
 	"scripts": {
 		"check": "tsc --noEmit",
+		"prebuild": "rm -rf 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"
 	},
@@ -240,10 +241,10 @@
 	"homepage": "https://www.forgezero.net/docs/runtime",
 	"repository": {
 		"type": "git",
-		"url": "git+https://github.com/axxra/forgezero.git",
+		"url": "git+https://github.com/forgezero-net/packages.git",
 		"directory": "packages/runtime"
 	},
-	"bugs": "https://github.com/axxra/forgezero/issues",
+	"bugs": "https://github.com/forgezero-net/packages/issues",
 	"sideEffects": false,
 	"files": [
 		"dist",

package/dist/finance/binance.d.ts

@@ -1,27 +0,0 @@
-import { VenueError, type VenueAdapter, type MarketType, type OrderStatus } from './venues';
-export interface BinanceCredentials {
-    apiKey: string;
-    apiSecret: string;
-}
-export interface BinanceOptions {
-    credentials: BinanceCredentials;
-    /** Override for testnet, or for a test. */
-    hosts?: Partial<Record<MarketType, string>>;
-    fetch?: typeof globalThis.fetch;
-    /**
-     * How far a request may be delayed before Binance refuses it.
-     *
-     * 5s rather than the 60s maximum. A signed order that arrives a minute late
-     * is an order placed into a market that has moved, and accepting it is worse
-     * than being told to retry.
-     */
-    recvWindowMs?: number;
-    now?: () => number;
-}
-/** Binance spells `BTC/USDT` as `BTCUSDT`. Denormalised here and nowhere else. */
-export declare const binanceSymbol: (symbol: string) => string;
-/** Binance statuses → ours. An unknown one is `rejected`, never silently `accepted`. */
-export declare function toOrderStatus(status: string): OrderStatus;
-export declare function createBinanceAdapter(options: BinanceOptions): VenueAdapter;
-/** Turn a Binance error into something that names the actual cause. */
-export declare function readBinanceError(error: unknown): VenueError | undefined;

package/dist/finance/binance.js

@@ -1,452 +0,0 @@
-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/finance/money.ts
-class MoneyError extends Error {
-  code;
-  constructor(code, message) {
-    super(message);
-    this.code = code;
-    this.name = "MoneyError";
-  }
-}
-var ASSETS = [
-  { code: "USDT", decimals: 6 },
-  { code: "USDC", decimals: 6 },
-  { code: "BTC", decimals: 8 },
-  { code: "ETH", decimals: 18 },
-  { code: "BNB", decimals: 18 },
-  { code: "EUR", decimals: 2 },
-  { code: "USD", decimals: 2 }
-];
-var REGISTRY = new Map(ASSETS.map((asset) => [asset.code, asset]));
-function defineAsset(spec) {
-  if (spec.decimals < 0 || spec.decimals > 30 || !Number.isInteger(spec.decimals)) {
-    throw new MoneyError("UNKNOWN_ASSET", `${spec.code}: decimals must be an integer 0–30.`);
-  }
-  REGISTRY.set(spec.code, spec);
-}
-function assetSpec(code) {
-  const spec = REGISTRY.get(code);
-  if (!spec)
-    throw new MoneyError("UNKNOWN_ASSET", `Unknown asset "${code}". Call defineAsset first.`);
-  return spec;
-}
-var money = (units, asset) => {
-  assetSpec(asset);
-  return { units, asset };
-};
-var zero = (asset) => money(0n, asset);
-function parseAmount(value, asset) {
-  const spec = assetSpec(asset);
-  const text = value.trim();
-  if (!/^-?\d+(\.\d+)?$/.test(text)) {
-    throw new MoneyError("NOT_FINITE", `"${value}" is not a plain decimal amount.`);
-  }
-  const negative = text.startsWith("-");
-  const [whole, fraction = ""] = text.replace("-", "").split(".");
-  if (fraction.length > spec.decimals) {
-    throw new MoneyError("PRECISION_LOSS", `${asset} has ${spec.decimals} decimals; "${value}" has ${fraction.length}.`);
-  }
-  const padded = fraction.padEnd(spec.decimals, "0");
-  const units = BigInt(whole + padded);
-  return { units: negative ? -units : units, asset };
-}
-function formatAmount(amount, options = {}) {
-  const spec = assetSpec(amount.asset);
-  const negative = amount.units < 0n;
-  const digits = (negative ? -amount.units : amount.units).toString().padStart(spec.decimals + 1, "0");
-  const whole = digits.slice(0, digits.length - spec.decimals);
-  let fraction = spec.decimals === 0 ? "" : digits.slice(digits.length - spec.decimals);
-  if (options.trim && fraction)
-    fraction = fraction.replace(/0+$/, "");
-  return `${negative ? "-" : ""}${whole}${fraction ? `.${fraction}` : ""}`;
-}
-function sameAsset(a, b) {
-  if (a.asset !== b.asset) {
-    throw new MoneyError("ASSET_MISMATCH", `Cannot combine ${a.asset} and ${b.asset}.`);
-  }
-}
-function add(a, b) {
-  sameAsset(a, b);
-  return { units: a.units + b.units, asset: a.asset };
-}
-function subtract(a, b) {
-  sameAsset(a, b);
-  return { units: a.units - b.units, asset: a.asset };
-}
-var negate = (amount) => ({ units: -amount.units, asset: amount.asset });
-var abs = (amount) => ({
-  units: amount.units < 0n ? -amount.units : amount.units,
-  asset: amount.asset
-});
-var isZero = (amount) => amount.units === 0n;
-var isNegative = (amount) => amount.units < 0n;
-function compare(a, b) {
-  sameAsset(a, b);
-  return a.units < b.units ? -1 : a.units > b.units ? 1 : 0;
-}
-var equals = (a, b) => a.asset === b.asset && a.units === b.units;
-var ROUNDING = ["down", "up", "half-up"];
-function divideRounded(numerator, denominator, mode) {
-  if (denominator === 0n)
-    throw new MoneyError("DIVIDE_BY_ZERO", "Division by zero.");
-  const negative = numerator < 0n !== denominator < 0n;
-  const a = numerator < 0n ? -numerator : numerator;
-  const b = denominator < 0n ? -denominator : denominator;
-  const quotient = a / b;
-  const remainder = a % b;
-  if (remainder === 0n)
-    return negative ? -quotient : quotient;
-  let result = quotient;
-  if (mode === "up")
-    result += 1n;
-  else if (mode === "half-up" && remainder * 2n >= b)
-    result += 1n;
-  return negative ? -result : result;
-}
-function mulRate(amount, rate, mode = "down") {
-  if (!/^-?\d+(\.\d+)?$/.test(rate.trim())) {
-    throw new MoneyError("NOT_FINITE", `"${rate}" is not a plain decimal rate.`);
-  }
-  const [whole, fraction = ""] = rate.trim().replace("-", "").split(".");
-  const scale = 10n ** BigInt(fraction.length);
-  const scaled = BigInt(whole + fraction) * (rate.trim().startsWith("-") ? -1n : 1n);
-  return { units: divideRounded(amount.units * scaled, scale, mode), asset: amount.asset };
-}
-function convert(amount, to, rate, mode = "down") {
-  const from = assetSpec(amount.asset);
-  const target = assetSpec(to);
-  const asTarget = mulRate({ units: amount.units, asset: to }, rate, mode);
-  const shift = target.decimals - from.decimals;
-  if (shift === 0)
-    return asTarget;
-  if (shift > 0)
-    return { units: asTarget.units * 10n ** BigInt(shift), asset: to };
-  return { units: divideRounded(asTarget.units, 10n ** BigInt(-shift), mode), asset: to };
-}
-function allocate(amount, parts) {
-  if (parts < 1)
-    throw new MoneyError("NOT_FINITE", "Cannot allocate into fewer than one part.");
-  const each = divideRounded(amount.units, BigInt(parts), "down");
-  const allocated = Array.from({ length: parts }, () => each);
-  let remainder = amount.units - each * BigInt(parts);
-  const step = remainder < 0n ? -1n : 1n;
-  for (let index = 0;remainder !== 0n; index = (index + 1) % parts) {
-    allocated[index] += step;
-    remainder -= step;
-  }
-  return allocated.map((units) => ({ units, asset: amount.asset }));
-}
-function toStep(amount, step, mode = "down") {
-  const stepUnits = parseAmount(step, amount.asset).units;
-  if (stepUnits <= 0n)
-    throw new MoneyError("NOT_FINITE", "A step must be positive.");
-  return { units: divideRounded(amount.units, stepUnits, mode) * stepUnits, asset: amount.asset };
-}
-var VERSION = "0.1.0";
-
-// src/finance/venues.ts
-var MARKET_TYPES = ["spot", "margin", "futures"];
-var ORDER_SIDES = ["buy", "sell"];
-var ORDER_TYPES = ["market", "limit", "stop-limit"];
-var TIME_IN_FORCE = ["gtc", "ioc", "fok"];
-var VENUES = [
-  {
-    key: "binance",
-    label: "Binance",
-    markets: ["spot", "margin", "futures"],
-    rateLimit: { perMinute: 6000, counts: "weight" },
-    clientOrderIds: true,
-    note: "Publishes no AAAA records, so every endpoint is IPv4-only and the budget is per IP."
-  }
-];
-var venue = (key) => VENUES.find((entry) => entry.key === key);
-var venuesFor = (type) => VENUES.filter((entry) => entry.markets.includes(type));
-var symbolOf = (base, quote) => `${base.toUpperCase()}/${quote.toUpperCase()}`;
-function parseSymbol(symbol) {
-  const [base, quote] = symbol.toUpperCase().split("/");
-  if (!base || !quote)
-    throw new VenueError("BAD_SYMBOL", `"${symbol}" is not BASE/QUOTE.`);
-  return { base, quote };
-}
-
-class VenueError extends Error {
-  code;
-  constructor(code, message) {
-    super(message);
-    this.code = code;
-    this.name = "VenueError";
-  }
-}
-function notionalOf(request, market) {
-  const price = request.price;
-  if (!price)
-    return parseAmount("0", market.quote);
-  const quantity = Number(formatAmount(request.quantity));
-  const priceText = formatAmount(price);
-  return parseAmount((quantity * Number(priceText)).toFixed(0) === "NaN" ? "0" : String(quantity * Number(priceText)), market.quote);
-}
-function validateOrder(request, market) {
-  const spec = venue(request.venue);
-  if (!spec)
-    throw new VenueError("UNKNOWN_VENUE", `Unknown venue "${request.venue}".`);
-  if (!spec.markets.includes(request.type)) {
-    throw new VenueError("MARKET_UNSUPPORTED", `${spec.label} does not offer ${request.type}.`);
-  }
-  if (market.venue !== request.venue || market.type !== request.type || market.symbol !== request.symbol) {
-    throw new VenueError("UNKNOWN_MARKET", "The market does not describe this order.");
-  }
-  if (request.orderType !== "market" && !request.price) {
-    throw new VenueError("PRICE_REQUIRED", `A ${request.orderType} order needs a price.`);
-  }
-  const snapped = toStep(request.quantity, market.lotStep);
-  if (compare(snapped, request.quantity) !== 0) {
-    throw new VenueError("LOT_STEP", `Quantity ${formatAmount(request.quantity, { trim: true })} is not a multiple of ${market.lotStep}.`);
-  }
-  if (request.price) {
-    const onTick = toStep(request.price, market.tickStep);
-    if (compare(onTick, request.price) !== 0) {
-      throw new VenueError("TICK_STEP", `Price ${formatAmount(request.price, { trim: true })} is not a multiple of ${market.tickStep}.`);
-    }
-    const notional = notionalOf(request, market);
-    if (compare(notional, parseAmount(market.minNotional, market.quote)) < 0) {
-      throw new VenueError("MIN_NOTIONAL", `Order is worth ${formatAmount(notional, { trim: true })} ${market.quote}; the minimum is ${market.minNotional}.`);
-    }
-  }
-  if (request.leverage !== undefined) {
-    if (request.type === "spot" || market.maxLeverage === undefined) {
-      throw new VenueError("LEVERAGE_UNSUPPORTED", `${request.type} markets have no leverage.`);
-    }
-    if (request.leverage < 1 || request.leverage > market.maxLeverage) {
-      throw new VenueError("LEVERAGE_TOO_HIGH", `Leverage ${request.leverage}× exceeds the ${market.maxLeverage}× maximum on this market.`);
-    }
-  }
-}
-async function submitOrder(adapter, request, market) {
-  validateOrder(request, market);
-  return adapter.placeOrder(request, market);
-}
-var VERSION2 = "0.1.0";
-
-// src/finance/binance.ts
-import { createHttpClient, binanceWeight } from "@forgezero/providers/http";
-var BUDGET_HOST = "binance";
-var DEFAULT_HOSTS = {
-  spot: "https://api.binance.com",
-  margin: "https://api.binance.com",
-  futures: "https://fapi.binance.com"
-};
-var binanceSymbol = (symbol) => {
-  const { base, quote } = parseSymbol(symbol);
-  return `${base}${quote}`;
-};
-var PATHS = {
-  spot: {
-    order: "/api/v3/order",
-    openOrders: "/api/v3/openOrders",
-    account: "/api/v3/account",
-    exchangeInfo: "/api/v3/exchangeInfo"
-  },
-  margin: {
-    order: "/sapi/v1/margin/order",
-    openOrders: "/sapi/v1/margin/openOrders",
-    account: "/sapi/v1/margin/account",
-    exchangeInfo: "/api/v3/exchangeInfo"
-  },
-  futures: {
-    order: "/fapi/v1/order",
-    openOrders: "/fapi/v1/openOrders",
-    account: "/fapi/v2/account",
-    exchangeInfo: "/fapi/v1/exchangeInfo"
-  }
-};
-function toOrderStatus(status) {
-  switch (status) {
-    case "NEW":
-    case "PENDING_NEW":
-      return "accepted";
-    case "PARTIALLY_FILLED":
-      return "partial";
-    case "FILLED":
-      return "filled";
-    case "CANCELED":
-    case "PENDING_CANCEL":
-    case "EXPIRED":
-    case "EXPIRED_IN_MATCH":
-      return "cancelled";
-    default:
-      return "rejected";
-  }
-}
-var SIDE = { buy: "BUY", sell: "SELL" };
-var TYPE = { market: "MARKET", limit: "LIMIT", "stop-limit": "STOP_LOSS_LIMIT" };
-async function sign(secret, query) {
-  const key = await crypto.subtle.importKey("raw", new TextEncoder().encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
-  const mac = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(query));
-  return [...new Uint8Array(mac)].map((byte) => byte.toString(16).padStart(2, "0")).join("");
-}
-function createBinanceAdapter(options) {
-  const hosts = { ...DEFAULT_HOSTS, ...options.hosts };
-  const recvWindow = options.recvWindowMs ?? 5000;
-  const now = options.now ?? Date.now;
-  const clients = new Map;
-  const clientFor = (type) => {
-    const base = hosts[type];
-    const existing = clients.get(base);
-    if (existing)
-      return existing;
-    const client = createHttpClient({
-      baseUrl: base,
-      fetch: options.fetch,
-      costOf: binanceWeight,
-      budget: { host: BUDGET_HOST, limit: 6000, windowMs: 60000, defaultCost: 1, headroom: 0.9 }
-    });
-    clients.set(base, client);
-    return client;
-  };
-  async function signed(args) {
-    const entries = Object.entries(args.params).filter(([, value]) => value !== undefined);
-    const base = new URLSearchParams(entries.map(([name, value]) => [name, String(value)])).toString();
-    const withTiming = `${base}${base ? "&" : ""}recvWindow=${recvWindow}&timestamp=${now()}`;
-    const signature = await sign(options.credentials.apiSecret, withTiming);
-    const response = await clientFor(args.type).call({
-      path: `${args.path}?${withTiming}&signature=${signature}`,
-      method: args.method,
-      weight: args.weight,
-      headers: { "X-MBX-APIKEY": options.credentials.apiKey }
-    });
-    return response.body;
-  }
-  return {
-    venue: "binance",
-    symbolFor: (symbol) => binanceSymbol(symbol),
-    async markets(type) {
-      const info = await clientFor(type).call({ path: PATHS[type].exchangeInfo, weight: 20 });
-      return (info.body.symbols ?? []).filter((entry) => entry.status === "TRADING").map((entry) => {
-        const filter = (name) => entry.filters.find((candidate) => candidate.filterType === name);
-        return {
-          venue: "binance",
-          type,
-          symbol: `${entry.baseAsset}/${entry.quoteAsset}`,
-          base: entry.baseAsset,
-          quote: entry.quoteAsset,
-          lotStep: filter("LOT_SIZE")?.stepSize ?? "0.00000001",
-          tickStep: filter("PRICE_FILTER")?.tickSize ?? "0.00000001",
-          minNotional: filter("NOTIONAL")?.minNotional ?? filter("MIN_NOTIONAL")?.minNotional ?? "0",
-          ...type === "spot" ? {} : { maxLeverage: 125 }
-        };
-      });
-    },
-    async placeOrder(request, market) {
-      if (request.type === "futures" && request.leverage) {
-        await signed({
-          type: "futures",
-          path: "/fapi/v1/leverage",
-          method: "POST",
-          params: { symbol: binanceSymbol(request.symbol), leverage: request.leverage }
-        });
-      }
-      const raw = await signed({
-        type: request.type,
-        path: PATHS[request.type].order,
-        method: "POST",
-        weight: 1,
-        params: {
-          symbol: binanceSymbol(request.symbol),
-          side: SIDE[request.side],
-          type: TYPE[request.orderType],
-          quantity: formatAmount(request.quantity, { trim: true }),
-          price: request.price ? formatAmount(request.price, { trim: true }) : undefined,
-          stopPrice: request.stopPrice ? formatAmount(request.stopPrice, { trim: true }) : undefined,
-          timeInForce: request.orderType === "market" ? undefined : (request.timeInForce ?? "gtc").toUpperCase(),
-          newClientOrderId: request.clientOrderId,
-          ...request.type === "margin" ? { sideEffectType: "NO_SIDE_EFFECT" } : {},
-          ...request.dryRun ? { test: "true" } : {}
-        }
-      });
-      return readOrder(raw, market);
-    },
-    async cancelOrder(args) {
-      await signed({
-        type: args.type,
-        path: PATHS[args.type].order,
-        method: "DELETE",
-        params: { symbol: binanceSymbol(args.symbol), orderId: args.venueOrderId }
-      });
-    },
-    async openOrders(args) {
-      const raw = await signed({
-        type: args.type,
-        path: PATHS[args.type].openOrders,
-        method: "GET",
-        weight: args.symbol ? 3 : 40,
-        params: { symbol: args.symbol ? binanceSymbol(args.symbol) : undefined }
-      });
-      return (raw ?? []).map((entry) => readOrder(entry, undefined));
-    },
-    async balances(type) {
-      const raw = await signed({ type, path: PATHS[type].account, method: "GET", weight: 10, params: {} });
-      const rows = raw.balances ?? raw.userAssets ?? (raw.assets ?? []).map((entry) => ({ asset: entry.asset, free: entry.availableBalance }));
-      return rows.filter((entry) => Number(entry.free) > 0).map((entry) => {
-        try {
-          return parseAmount(entry.free, entry.asset);
-        } catch {
-          return null;
-        }
-      }).filter((amount) => amount !== null);
-    }
-  };
-}
-function readOrder(raw, market) {
-  const asset = market?.base ?? "BTC";
-  const executed = String(raw.executedQty ?? raw.origQty ?? "0");
-  let filledQuantity;
-  try {
-    filledQuantity = parseAmount(executed, asset);
-  } catch {
-    filledQuantity = zero(asset);
-  }
-  const quoteFilled = Number(raw.cummulativeQuoteQty ?? 0);
-  const filled = Number(executed);
-  return {
-    venueOrderId: String(raw.orderId ?? ""),
-    clientOrderId: raw.clientOrderId ? String(raw.clientOrderId) : undefined,
-    status: toOrderStatus(String(raw.status ?? "NEW")),
-    filledQuantity,
-    ...market && filled > 0 && quoteFilled > 0 ? {
-      averagePrice: (() => {
-        try {
-          return parseAmount((quoteFilled / filled).toFixed(assetSpec(market.quote).decimals), market.quote);
-        } catch {
-          return;
-        }
-      })()
-    } : {},
-    raw
-  };
-}
-function readBinanceError(error) {
-  const body = error.body;
-  if (!body?.code)
-    return;
-  const known = {
-    [-1013]: ["MIN_NOTIONAL", "The order is below the venue minimum, or off its lot or tick step."],
-    [-2010]: ["MIN_NOTIONAL", "Rejected: insufficient balance, or below the minimum."],
-    [-1111]: ["LOT_STEP", "More decimal places than this market accepts."],
-    [-1121]: ["UNKNOWN_MARKET", "That symbol is not traded on this venue."]
-  };
-  const match = known[body.code];
-  return match ? new VenueError(match[0], `${match[1]} (${body.msg})`) : undefined;
-}
-export {
-  toOrderStatus,
-  readBinanceError,
-  createBinanceAdapter,
-  binanceSymbol
-};

package/dist/serial.d.ts

@@ -1,54 +0,0 @@
-/**
- * Run work for one key strictly in order, and give the caller the result back.
- *
- * ## Why this is not `@forgezero/runtime/queue`
- *
- * The queue is for work that happens LATER: it persists a message, hands it to
- * a handler, retries, dead-letters. It is the right answer when the caller does
- * not need the outcome — a deposit credit, a webhook, a scan.
- *
- * This is for work that happens NOW and whose result the caller returns. A
- * request writing a ledger posting has to answer with the posting; enqueuing it
- * would mean replying "accepted" to something the caller needs to have
- * happened. Two different problems, and using the queue for this one would mean
- * inventing a way to wait for a message — which is a worse version of this file.
- *
- * It was written twice before it was written once: the audit chain needed it to
- * keep sequence numbers gapless, and accounts needed it to stop two credits
- * interleaving. Two copies of a concurrency primitive is two chances to get it
- * wrong, so it lives here.
- *
- * ## What it does NOT give you
- *
- * Ordering within ONE process. Two API nodes each hold their own chain, so a
- * durable guarantee still needs a unique index on whatever must not happen
- * twice. This makes the common case cheap and correct; the index makes every
- * case correct. Anything relying on this alone across a cluster is relying on
- * there being one node, which stops being true without warning.
- */
-export interface SerialOptions {
-    /**
-     * Keys to keep chains for.
-     *
-     * A chain per key is a promise per key, and a process serving a million
-     * accounts would hold a million of them forever. Idle chains are dropped once
-     * settled, so the map holds only keys with work in flight.
-     */
-    maxKeys?: number;
-}
-export declare function createKeyedSerial(options?: SerialOptions): {
-    /**
-     * Run `work` after everything already queued for this key.
-     *
-     * A rejection does NOT poison the chain: the tail is always replaced with a
-     * settled promise, so one transient failure cannot take every subsequent
-     * call for that key with it — which is how a single database blip becomes a
-     * permanently stuck account.
-     */
-    run<T>(key: string, work: () => Promise<T>): Promise<T>;
-    /** How many keys have work in flight. For a health endpoint. */
-    size: () => number;
-    /** Wait for everything currently queued. Tests, and a graceful shutdown. */
-    drain: () => Promise<void>;
-};
-export type KeyedSerial = ReturnType<typeof createKeyedSerial>;

package/dist/serial.js

@@ -1,40 +0,0 @@
-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/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(() => {
-        return;
-      }, () => {
-        return;
-      });
-      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.`);
-      }
-      return next;
-    },
-    size: () => chains.size,
-    drain: async () => {
-      await Promise.allSettled([...chains.values()]);
-    }
-  };
-}
-export {
-  createKeyedSerial
-};