@forgezero/runtime 0.1.3 → 0.1.5

package/dist/finance/ledger.d.ts

@@ -33,8 +33,8 @@ import { type Money } from './money';
  * must balance, so a split that loses a unit cannot be committed at all.
  */
 export declare class LedgerError extends Error {
-    readonly code: 'UNBALANCED' | 'EMPTY_TRANSACTION' | 'MIXED_ASSETS' | 'ZERO_ENTRY' | 'UNKNOWN_ACCOUNT' | 'INSUFFICIENT_AVAILABLE';
-    constructor(code: 'UNBALANCED' | 'EMPTY_TRANSACTION' | 'MIXED_ASSETS' | 'ZERO_ENTRY' | 'UNKNOWN_ACCOUNT' | 'INSUFFICIENT_AVAILABLE', message: string);
+    readonly code: 'UNBALANCED' | 'EMPTY_TRANSACTION' | 'TOO_MANY_ENTRIES' | 'MIXED_ASSETS' | 'ZERO_ENTRY' | 'UNKNOWN_ACCOUNT' | 'INSUFFICIENT_AVAILABLE';
+    constructor(code: 'UNBALANCED' | 'EMPTY_TRANSACTION' | 'TOO_MANY_ENTRIES' | 'MIXED_ASSETS' | 'ZERO_ENTRY' | 'UNKNOWN_ACCOUNT' | 'INSUFFICIENT_AVAILABLE', message: string);
 }
 /**
  * The sub-accounts every owner has.
@@ -96,6 +96,12 @@ export interface Transaction {
     atMs: number;
     memo?: string;
 }
+/**
+ * A ledger transaction is one atomic business movement, not a batch transport.
+ * Keeping the posting set small bounds both the durable document and the
+ * multikey `accountIds[*]` index entry fan-out derived from it by the API.
+ */
+export declare const MAX_LEDGER_ENTRIES = 64;
 /**
  * Every transaction sums to zero, per asset.
  *

package/dist/finance/ledger.js

@@ -168,10 +168,14 @@ function parseAccount(id) {
   return { kind, owner, bucket };
 }
 var queueKeyFor = (account) => `${account.kind}:${account.owner}`;
+var MAX_LEDGER_ENTRIES = 64;
 function assertBalanced(transaction) {
-  if (transaction.entries.length === 0) {
+  if (transaction.entries.length < 2) {
     throw new LedgerError("EMPTY_TRANSACTION", "A transaction needs at least two entries.");
   }
+  if (transaction.entries.length > MAX_LEDGER_ENTRIES) {
+    throw new LedgerError("TOO_MANY_ENTRIES", `A transaction may contain at most ${MAX_LEDGER_ENTRIES} entries; split this batch into separate transactions.`);
+  }
   const totals = new Map;
   for (const entry of transaction.entries) {
     if (entry.amount.units === 0n) {
@@ -302,6 +306,7 @@ export {
   assertAvailable,
   accountId,
   VERSION2 as VERSION,
+  MAX_LEDGER_ENTRIES,
   LedgerError,
   BUCKETS,
   ACCOUNT_KINDS

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.
  *
@@ -72,6 +86,8 @@ export interface JobContext {
     log(message: string, detail?: Record<string, unknown>): void;
 }
 export interface JobResult {
+    /** A resolved run may still report an operational failure without throwing. */
+    ok?: boolean;
     /** Anything worth showing on a status screen. Kept in the report verbatim. */
     [key: string]: unknown;
 }
@@ -80,6 +96,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 +131,8 @@ export interface JobReport {
     consecutiveFailures: number;
     runs: number;
     skippedLocked: number;
+    skippedOverlap: number;
+    nextRunAtMs?: number;
 }
 export interface SchedulerOptions {
     jobs: readonly JobSpec[];
@@ -115,6 +141,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);
@@ -380,8 +477,15 @@ function createScheduler(options) {
         log: (message, detail) => options.onLog?.(job.key, message, detail)
       });
       report.lastResult = result ?? undefined;
-      report.lastError = undefined;
-      report.consecutiveFailures = 0;
+      if (result?.ok === false) {
+        const error = new Error("job returned ok=false");
+        report.lastError = error.message;
+        report.consecutiveFailures += 1;
+        options.onError?.(job.key, error);
+      } else {
+        report.lastError = undefined;
+        report.consecutiveFailures = 0;
+      }
     } catch (error) {
       report.lastError = error instanceof Error ? error.message : String(error);
       report.consecutiveFailures += 1;
@@ -397,17 +501,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 +541,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 +549,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 +565,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 +577,7 @@ function createScheduler(options) {
       for (const report of reports.values()) {
         if (report.state !== "running")
           report.state = "paused";
+        report.nextRunAtMs = undefined;
       }
     },
     resume() {
@@ -458,7 +586,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 +611,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 +646,7 @@ var VERSION = "0.1.0";
 export {
   systemClock,
   storeLock,
+  nextWallClockAt,
   memoryLock,
   everyMs,
   defineJob,

package/dist/query.d.ts

@@ -0,0 +1,47 @@
+/** Provider-neutral, function-based typed query contracts. */
+export type QueryIssue = Readonly<{
+    path: string;
+    message: string;
+}>;
+export type QueryDecode<T> = Readonly<{
+    ok: true;
+    value: T;
+}> | Readonly<{
+    ok: false;
+    issues: readonly QueryIssue[];
+}>;
+/** Inputs may coerce wire values; outputs must validate strictly. */
+export interface QueryCodec<T> {
+    readonly schema?: unknown;
+    decode(value: unknown): QueryDecode<T>;
+    encode(value: unknown): QueryDecode<T>;
+}
+export interface QueryContract<Name extends string, Input, Output> {
+    readonly name: Name;
+    readonly input: QueryCodec<Input>;
+    readonly output: QueryCodec<Output>;
+}
+export declare class QueryContractError extends Error {
+    readonly query: string;
+    readonly phase: 'input' | 'output' | 'aborted';
+    readonly issues: readonly QueryIssue[];
+    constructor(query: string, phase: 'input' | 'output' | 'aborted', issues?: readonly QueryIssue[]);
+}
+export declare function defineQuery<const Name extends string, Input, Output>(definition: {
+    name: Name;
+    input: QueryCodec<Input>;
+    output: QueryCodec<Output>;
+}): QueryContract<Name, Input, Output>;
+export interface QueryExecution {
+    readonly signal: AbortSignal;
+}
+export interface QueryImplementation<Context, Output> {
+    execute(context: Context, input: unknown, options?: {
+        signal?: AbortSignal;
+    }): Promise<Output>;
+}
+export declare function implementQuery<Context, Name extends string, Input, Output>(contract: QueryContract<Name, Input, Output>, handler: (context: Context, input: Input, execution: QueryExecution) => Output | Promise<Output>): QueryImplementation<Context, Output> & {
+    readonly contract: typeof contract;
+};
+export type QueryInput<Q> = Q extends QueryContract<string, infer Input, unknown> ? Input : never;
+export type QueryOutput<Q> = Q extends QueryContract<string, unknown, infer Output> ? Output : never;

package/dist/query.js

@@ -0,0 +1,51 @@
+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/query.ts
+class QueryContractError extends Error {
+  query;
+  phase;
+  issues;
+  constructor(query, phase, issues = []) {
+    super(`Query ${query} failed ${phase} validation`);
+    this.query = query;
+    this.phase = phase;
+    this.issues = issues;
+    this.name = "QueryContractError";
+  }
+}
+function defineQuery(definition) {
+  if (!definition.name.trim())
+    throw new Error("A query contract requires a stable name");
+  return Object.freeze({ ...definition });
+}
+function implementQuery(contract, handler) {
+  return {
+    contract,
+    async execute(context, rawInput, options = {}) {
+      const signal = options.signal ?? new AbortController().signal;
+      if (signal.aborted)
+        throw new QueryContractError(contract.name, "aborted");
+      const decoded = contract.input.decode(rawInput);
+      if (!decoded.ok)
+        throw new QueryContractError(contract.name, "input", decoded.issues);
+      const rawOutput = await handler(context, decoded.value, { signal });
+      if (signal.aborted)
+        throw new QueryContractError(contract.name, "aborted");
+      const encoded = contract.output.encode(rawOutput);
+      if (!encoded.ok)
+        throw new QueryContractError(contract.name, "output", encoded.issues);
+      return encoded.value;
+    }
+  };
+}
+export {
+  implementQuery,
+  defineQuery,
+  QueryContractError
+};

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/dist/schema-typebox.d.ts

@@ -1,4 +1,5 @@
 import type { TSchema, Static } from '@sinclair/typebox';
+import type { QueryCodec } from './query';
 import { type SchemaValidator } from './schema';
 /**
  * TypeBox implementation of `SchemaValidator`.
@@ -20,5 +21,7 @@ export declare const typebox: SchemaValidator<TSchema>;
  * refusing to start.
  */
 export declare function parse<T extends TSchema>(schema: T, value: unknown): Static<T>;
+/** TypeBox codec for `@forgezero/runtime/query`. */
+export declare function typeboxQueryCodec<T extends TSchema>(schema: T): QueryCodec<Static<T>>;
 export { Type as T } from '@sinclair/typebox';
 export type { TSchema, Static } from '@sinclair/typebox';