@ayepi/work 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,1167 @@
+import { BoundedDoerOptions, Doer, Doer as Doer$1, DoerTaskOptions, UnlimitedDoerOptions, ageDoer, balancedDoer, priorityDoer, unlimitedDoer } from "@ayepi/core/doer";
+import { MaybePromise } from "@ayepi/core";
+
+//#region src/internal.d.ts
+
+/** The signature of a `logWith`-style context wrapper (`@ayepi/log`'s `logWith`). */
+type LogWith = <R>(add: object, inner: () => R) => R;
+/** The default {@link LogWith}: runs `inner` with no added context. */
+
+/** A monotonic-ish clock injection point (`() => Date.now()` by default). */
+type Clock = () => number;
+//#endregion
+//#region src/json.d.ts
+/**
+ * # JSON codec
+ *
+ * Work inputs, outputs, and group results cross the wire as strings. A plain
+ * `JSON.stringify` silently drops `undefined`, throws on `BigInt`, and flattens
+ * `Date`/`Map`/`Set` into useless shapes. {@link defaultCodec} round-trips all of
+ * them with a tagged-wrapper replacer/reviver, and you can supply your own
+ * {@link JsonCodec} (globally or per work type) for custom classes.
+ *
+ * @module
+ */
+/**
+ * A bidirectional JSON serializer. The default round-trips `Date`, `BigInt`, `Map`,
+ * `Set`, `undefined`, and `Error`; replace it to support custom types.
+ */
+interface JsonCodec {
+  /** Serialize a value to a string. */
+  stringify(value: unknown): string;
+  /** Parse a string back to a value. */
+  parse(text: string): unknown;
+}
+/**
+ * The default {@link JsonCodec}. Tags values JSON can't represent natively so they
+ * survive a `stringify` → `parse` round-trip:
+ *
+ * | Value       | Encoded as                          |
+ * |-------------|-------------------------------------|
+ * | `undefined` | `{ $ayepi:'undefined' }`            |
+ * | `bigint`    | `{ $ayepi:'BigInt', value:'123' }`  |
+ * | `Date`      | `{ $ayepi:'Date', value:<iso> }`    |
+ * | `Map`       | `{ $ayepi:'Map', value:[[k,v]…] }`  |
+ * | `Set`       | `{ $ayepi:'Set', value:[…] }`       |
+ * | `Error`     | `{ $ayepi:'Error', value:{name,message,stack} }` |
+ */
+declare const defaultCodec: JsonCodec;
+//#endregion
+//#region src/ports.d.ts
+/**
+ * # Ports
+ *
+ * The three pluggable seams every backend slots into. `@ayepi/work` ships an
+ * in-memory implementation of all three ({@link memoryQueue}/{@link memoryPubSub}/
+ * {@link memoryStore}); a distributed deployment swaps in Redis/SQS/etc. behind the
+ * same interfaces with no engine changes.
+ *
+ * All durations are **milliseconds**.
+ *
+ * - {@link Queue} — the durable work log: push bodies, lease a batch, heartbeat the
+ *   lease, ack/fail/dead-letter. At-least-once with a visibility timeout, so a dead
+ *   worker's in-flight item is redelivered.
+ * - {@link PubSub} — best-effort cross-instance fanout (identical shape to
+ *   `@ayepi/core`'s `Broker`): used to wake distributed waiters and nudge gates.
+ * - {@link Store} — get/set with TTL plus a compare-and-set primitive
+ *   ({@link Store.setIfNotExists}) that backs every idempotency/lease concern.
+ *
+ * @module
+ */
+/** Options for {@link Queue.push}. */
+interface PushOptions {
+  /** Delay before the item first becomes visible (retry backoff, scheduled work). */
+  readonly delay?: number;
+  /**
+   * Idempotency key. If a backend supports it, pushing a second body with the same
+   * key while the first is still pending is a no-op — used for at-least-once-safe
+   * fan-out (dependency payloads, retries). Best-effort; not all backends dedupe.
+   */
+  readonly dedupeKey?: string;
+}
+/**
+ * A unit of work leased from a {@link Queue}. `handle` is the backend-specific token
+ * (a memory lease token, an SQS receipt handle, a Redis lease id, …) — pass the same
+ * object back to {@link Queue.heartbeat}/{@link Queue.ack}/{@link Queue.fail}.
+ */
+interface PulledWork {
+  /** The opaque message body (a JSON-encoded work envelope). */
+  readonly body: string;
+  /** Backend-specific lease/receipt handle — round-tripped to heartbeat/ack/fail. */
+  readonly handle: unknown;
+  /** Delivery attempt for this body, starting at 1 (increments on redelivery). */
+  readonly attempt: number;
+}
+/**
+ * The durable work log. At-least-once delivery with a visibility timeout: a popped
+ * item is invisible to other workers until its lease elapses; a worker keeps the
+ * lease alive with {@link heartbeat} and removes the item with {@link ack}. A worker
+ * that dies without acking lets the lease expire, and the item is redelivered.
+ */
+interface Queue {
+  /** Append a body to the log (optionally delayed/deduped). */
+  push(body: string, opts?: PushOptions): void | Promise<void>;
+  /**
+   * Lease up to `max` currently-visible items, hiding each for `visibility` ms.
+   * Returns fewer (or none) when the queue is short. Reclaims items whose lease
+   * expired (redelivery) before leasing fresh ones.
+   */
+  pop(max: number, visibility: number): PulledWork[] | Promise<PulledWork[]>;
+  /** Extend a leased item's visibility by `visibility` ms (called on a heartbeat). */
+  heartbeat(pulled: PulledWork, visibility: number): void | Promise<void>;
+  /** Permanently remove a leased item (it completed). A stale lease must not ack. */
+  ack(pulled: PulledWork): void | Promise<void>;
+  /** Return a leased item to the queue, visible again after `delay` ms (a retry). */
+  fail(pulled: PulledWork, delay?: number): void | Promise<void>;
+  /** Move a body to a dead-letter sink after exhausting retries (optional). */
+  deadLetter?(body: string, error: string): void | Promise<void>;
+}
+/**
+ * Best-effort cross-instance message fanout. Identical in shape to `@ayepi/core`'s
+ * `Broker`: publish an opaque string, subscribe to every published string.
+ */
+interface PubSub {
+  /** Publish an opaque message to every subscriber across all instances. */
+  publish(message: string): void | Promise<void>;
+  /**
+   * Register a listener for published messages.
+   * @returns an unsubscribe function that detaches the listener.
+   */
+  subscribe(listener: (message: string) => void): () => void;
+}
+/**
+ * A small key/value store with TTL and one compare-and-set primitive.
+ * {@link setIfNotExists} is the single atom every distributed claim is built on:
+ * dependency fire-once, scheduler tick lease, group-handled claim, waiter registry.
+ */
+interface Store {
+  /** Read a value, or `undefined` if absent/expired. */
+  get(key: string): string | undefined | Promise<string | undefined>;
+  /** Write a value, optionally expiring after `ttl` ms. */
+  set(key: string, value: string, ttl?: number): void | Promise<void>;
+  /** Delete a key (optional). */
+  delete?(key: string): void | Promise<void>;
+  /**
+   * Set **only if absent**. Returns `true` when this caller won the slot, `false` when
+   * the key already held a (non-expired) value. The atomic claim every
+   * idempotency/lease concern relies on.
+   */
+  setIfNotExists(key: string, value: string, ttl?: number): boolean | Promise<boolean>;
+  /**
+   * Atomically add `by` (may be negative) to an integer key and return the new value.
+   * Backs the group open-work counter. Optional: when absent the engine falls back to
+   * a (non-atomic) get+set, which is only safe on a single-process backend.
+   */
+  increment?(key: string, by: number, ttl?: number): number | Promise<number>;
+}
+/** The three ports a backend provides together. */
+interface Backend {
+  readonly queue: Queue;
+  readonly pubsub: PubSub;
+  readonly store: Store;
+}
+//#endregion
+//#region ../core/dist/stats.d.ts
+//#region src/stats.d.ts
+/**
+ * # Stats — a tiny, runtime-agnostic metrics primitive
+ *
+ * A dependency-free way to track named, typed measurements and hand them to whatever the
+ * end user already runs — a periodic log, StatsD, Prometheus. Three metric kinds cover
+ * the field:
+ *
+ * - **counter** — a monotonic tally (`inc`): requests served, jobs failed.
+ * - **gauge** — a value that moves both ways (`set`/`add`/`max`): in-flight count, a peak.
+ * - **summary** — a distribution of observations (`observe`): always count/total/min/max/avg,
+ *   and — when buckets/quantiles are configured — histogram buckets + approximate
+ *   percentiles (p50/p95/p99). Histogram-backed, so it's deterministic and bounded-memory.
+ *
+ * Every metric carries metadata (`name`, `kind`, `description`, `unit`) and is **labelled**
+ * (e.g. `{ type: 'email' }`), so one name spans many series. {@link createMetrics} is the
+ * registry: create handles, snapshot every series as a flat {@link StatValue} list, and
+ * {@link Metrics.subscribe} to **coalesced** change notifications (a burst of mutations
+ * yields one batched callback). {@link formatPrometheus} renders a snapshot as Prometheus
+ * text exposition.
+ *
+ * ```ts
+ * import { createMetrics, formatPrometheus } from '@ayepi/core'
+ *
+ * const m = createMetrics({ quantiles: [0.5, 0.95, 0.99] })
+ * m.counter('jobs_done', { type: 'email' }).inc()
+ * m.summary('job_ms', { type: 'email' }, { unit: 'ms' }).observe(42)
+ *
+ * setInterval(() => console.log(formatPrometheus(m.list())), 15_000) // scrape/log loop
+ * ```
+ *
+ * @module
+ */
+/** The three metric shapes. */
+type StatKind = 'counter' | 'gauge' | 'summary';
+/** A metric's label set (a series within a metric family). Values are strings, order-insensitive. */
+type Labels = Readonly<Record<string, string>>;
+/** Static metadata describing a metric family (shared across its label series). */
+interface StatMeta {
+  /** The metric name (the family key). */
+  readonly name: string;
+  /** Which kind of metric this is. */
+  readonly kind: StatKind;
+  /** Human-readable description (exported as Prometheus `# HELP`). */
+  readonly description?: string;
+  /** Unit of measure, e.g. `'ms'`, `'bytes'`, `'count'` (informational). */
+  readonly unit?: string;
+}
+/** One histogram bucket: the cumulative count of observations `<= le` (`le` = upper bound, `Infinity` for the overflow). */
+interface StatBucket {
+  readonly le: number;
+  readonly count: number;
+}
+/** A summary's distribution snapshot. `quantiles`/`buckets` are present only when configured. */
+interface StatSummary {
+  /** Number of observations. */
+  readonly count: number;
+  /** Sum of all observations. */
+  readonly total: number;
+  /** Smallest observation (0 when none). */
+  readonly min: number;
+  /** Largest observation (0 when none). */
+  readonly max: number;
+  /** Mean (0 when none). */
+  readonly avg: number;
+  /** Approximate quantiles by probability key, e.g. `{ '0.95': 180 }` — when `quantiles` were configured. */
+  readonly quantiles?: Readonly<Record<string, number>>;
+  /** Cumulative histogram buckets — when buckets were configured. */
+  readonly buckets?: readonly StatBucket[];
+}
+/** A point-in-time snapshot of a single metric series (one name + label set). */
+interface StatValue {
+  /** The owning family's metadata. */
+  readonly meta: StatMeta;
+  /** This series' labels. */
+  readonly labels: Labels;
+  /** Counter/gauge value; for a summary, its observation `count` (full detail in {@link summary}). */
+  readonly value: number;
+  /** Present iff `meta.kind === 'summary'`. */
+  readonly summary?: StatSummary;
+}
+/** A monotonic tally. */
+interface Counter {
+  /** Add `by` (default 1). */
+  inc(by?: number): void;
+  /** Current total. */
+  value(): number;
+}
+/** A value that moves up and down. */
+interface Gauge {
+  /** Replace the value. */
+  set(v: number): void;
+  /** Add `by` (may be negative). */
+  add(by: number): void;
+  /** Raise to `v` if larger (a running high-water mark). */
+  max(v: number): void;
+  /** Current value. */
+  value(): number;
+}
+/** A distribution of observations. */
+interface Summary {
+  /** Record one observation. */
+  observe(v: number): void;
+  /** Current distribution snapshot. */
+  snapshot(): StatSummary;
+}
+/** Options for {@link createMetrics}. */
+interface MetricsOptions {
+  /**
+   * Probabilities (0–1) to estimate for every summary, e.g. `[0.5, 0.95, 0.99]`. Enables
+   * histogram bucketing (default {@link DEFAULT_BUCKETS} unless `buckets` is given) and fills
+   * {@link StatSummary.quantiles}. Omit for count/total/min/max/avg only (no per-observation cost).
+   */
+  readonly quantiles?: readonly number[];
+  /** Histogram bucket upper bounds for summaries (ascending). Defaults to {@link DEFAULT_BUCKETS} when `quantiles` is set. */
+  readonly buckets?: readonly number[];
+  /**
+   * Schedules the coalesced flush of change notifications. Default batches via `queueMicrotask`
+   * (one callback per synchronous burst). Inject `(fn) => fn()` for synchronous delivery, or a
+   * manual collector in tests.
+   */
+  readonly schedule?: (flush: () => void) => void;
+}
+/** The metrics registry returned by {@link createMetrics}. */
+interface Metrics {
+  /** Get-or-create a {@link Counter} series. */
+  counter(name: string, labels?: Labels, meta?: Omit<StatMeta, 'name' | 'kind'>): Counter;
+  /** Get-or-create a {@link Gauge} series. */
+  gauge(name: string, labels?: Labels, meta?: Omit<StatMeta, 'name' | 'kind'>): Gauge;
+  /** Get-or-create a {@link Summary} series. */
+  summary(name: string, labels?: Labels, meta?: Omit<StatMeta, 'name' | 'kind'>): Summary;
+  /** Snapshot every series as a flat list (one {@link StatValue} per name + label set). */
+  list(): StatValue[];
+  /** Snapshot one series, or `undefined` if it was never created. */
+  get(name: string, labels?: Labels): StatValue | undefined;
+  /** Subscribe to **coalesced** change notifications; the listener gets the batch of changed series. Returns an unsubscribe fn. */
+  subscribe(listener: (changed: readonly StatValue[]) => void): () => void;
+}
+/** Default histogram bucket upper bounds (ms-oriented), used when `quantiles` is set without explicit `buckets`. */
+declare const DEFAULT_BUCKETS: readonly number[];
+/** Create a metrics registry. */
+declare function createMetrics(opts?: MetricsOptions): Metrics;
+/**
+ * Render a {@link Metrics.list} snapshot as Prometheus text exposition format. Counters and gauges
+ * map directly; summaries are emitted as **histograms** (`_bucket`/`_count`/`_sum`) when buckets are
+ * present, else as bare `_count`/`_sum`. Names are sanitized to valid Prometheus identifiers.
+ */
+declare function formatPrometheus(stats: readonly StatValue[]): string;
+//#endregion
+//#endregion
+//#region ../core/dist/types.d.ts
+/** A value that may be returned either synchronously or as a `Promise`. */
+type MaybePromise$1<T> = T | Promise<T>;
+/**
+ * The empty object type. Used as the identity element when merging contributed
+ * shapes (middleware context, path params, etc.) so an absent contribution adds
+ * nothing rather than widening the result.
+ */
+//#endregion
+//#region ../core/dist/retry.d.ts
+//#region src/retry.d.ts
+
+/**
+ * Throw this from a {@link retry} operation to **stop retrying immediately**: the remaining
+ * attempts (and their backoff) are skipped, `onError` fires once, and `retry` then re-throws the
+ * abort's `cause` (or returns `errorResult` if one was configured). Use it for a permanent failure
+ * a retry can't fix — a 4xx, a validation error, a missing resource.
+ *
+ * ```ts
+ * await retry(async () => {
+ *   const res = await fetch(url);
+ *   if (res.status === 404) throw new RetryAbort(new Error('not found')); // don't retry a 404
+ *   if (!res.ok) throw new Error(`http ${res.status}`);                   // transient → retried
+ *   return res.json();
+ * });
+ * ```
+ */
+declare class RetryAbort extends Error {
+  constructor(cause?: unknown, message?: string);
+}
+/** Live state passed to the operation and to the {@link RetryOptions} hooks. */
+interface RetryState {
+  /** When the first attempt started (epoch ms). */
+  readonly startAt: number;
+  /** Current attempt number (1-based). */
+  readonly attempt: number;
+  /** Total attempts allowed. */
+  readonly attempts: number;
+  /** When the current attempt started (epoch ms). */
+  readonly lastAttemptAt: number;
+  /** The most recent error (undefined before any failure). */
+  readonly lastError?: unknown;
+}
+/** Options for {@link retry}. Every numeric field has a default (see {@link DEFAULT_RETRY_OPTIONS}). */
+interface RetryOptions<R = unknown> {
+  /** Total attempts including the first (default 3). */
+  attempts?: number;
+  /** First-retry delay in ms (default 1000). */
+  base?: number;
+  /** Multiplier applied per attempt (default 2). */
+  factor?: number;
+  /** Delay cap in ms (default 30000). */
+  max?: number;
+  /** Jitter fraction in `[0,1]`: each delay is scaled down by up to this much (default 0.5). */
+  jitter?: number;
+  /** If every attempt fails, resolve with this value instead of throwing. */
+  errorResult?: R;
+  /**
+   * Decide what to do with a thrown error: return `false` to **stop** retrying (abort), or a number
+   * of **milliseconds to wait at least** before the next attempt — a floor under the normal backoff
+   * (e.g. honor a `Retry-After`; `0` = just use the backoff). May be async. Default:
+   * `(err) => (err instanceof RetryAbort ? false : 0)` — overriding it **replaces** that check
+   * (e.g. `on: (e) => (e.status === 404 ? false : 0)` aborts on a 404 with no `RetryAbort` wrapper).
+   * To keep retrying through a `RetryAbort`, override it (e.g. `on: () => 0`).
+   */
+  on?: (err: unknown) => MaybePromise$1<number | false>;
+  /** Called after a successful attempt. */
+  onSuccess?: (result: R, state: RetryState) => void;
+  /** Called after a failed attempt that will be retried, before backing off. */
+  onRetry?: (error: unknown, state: RetryState) => void;
+  /** Called when all attempts are exhausted, before throwing or returning `errorResult`. */
+  onError?: (error: unknown, state: RetryState) => void;
+  /** Sleep implementation (ms) — injectable for tests (default an unref'd timer). */
+  sleep?: (ms: number) => Promise<void>;
+  /** Randomness for jitter (default `Math.random`). */
+  random?: () => number;
+  /** Clock (default `Date.now`). */
+  now?: () => number;
+}
+/** The built-in defaults — the floor under {@link setDefaultRetryOptions} and per-call options. */
+declare const DEFAULT_RETRY_OPTIONS: Required<Pick<RetryOptions, 'attempts' | 'base' | 'factor' | 'max' | 'jitter'>>;
+/** Set process-wide default {@link RetryOptions} (merged over previous overrides). Per-call options still win. */
+declare function setDefaultRetryOptions(options: RetryOptions): void;
+/** The effective global defaults ({@link DEFAULT_RETRY_OPTIONS} plus any {@link setDefaultRetryOptions} overrides). */
+declare function getDefaultRetryOptions(): RetryOptions;
+/**
+ * Backoff delay for retry `attempt` (1 = the first retry):
+ * `min(base · factor^(attempt-1), max) · (1 − jitter · random())`.
+ */
+declare function backoff(attempt: number, opts?: Pick<RetryOptions, 'base' | 'factor' | 'max' | 'jitter'>, random?: () => number): number;
+/**
+ * Run `fn`, retrying on rejection with exponential backoff + jitter up to `attempts`
+ * times. Resolves with the first success; on exhaustion it returns `errorResult` if one
+ * was provided, otherwise re-throws the last error.
+ */
+declare function retry<R>(fn: (state: RetryState) => Promise<R>, options?: RetryOptions<R>): Promise<R>;
+//#endregion
+//#endregion
+//#region src/types.d.ts
+/**
+ * A queueable, type-carrying unit of work produced by a {@link WorkBuilder}. Its `id`
+ * is assigned at build time (so you can reference it before queueing — e.g. to depend
+ * on it). `__out` is a phantom: it never exists at runtime, it only threads the output
+ * type through `enqueue`.
+ */
+interface Work<Name extends string = string, O = unknown> {
+  /** Stable id, assigned when the instance is built. */
+  readonly id: string;
+  /** The work type name (the registry key). */
+  readonly type: Name;
+  /** The (already type-checked) input payload. */
+  readonly input: unknown;
+  /** Phantom output-type carrier — never present at runtime. */
+  readonly __out: O;
+}
+/** The execution context handed to a {@link WorkHandler}. */
+interface WorkContext {
+  /** This work item's id. */
+  readonly id: string;
+  /** The group id shared by this item and everything it queues. */
+  readonly groupId: string;
+  /** Delivery attempt (1 = first try; higher after a retry). */
+  readonly attempt: number;
+  /** Queue child work **into the same group**; returns the child id(s). */
+  queue(work: Work, options?: WorkInstanceOptions): string;
+  queue(works: readonly Work[], options?: WorkInstanceOptions): string[];
+  /** Set the group's result (last-writer-wins) — what a top-level `await enqueue(...)` resolves to. */
+  setResult(result: unknown): void;
+  /** Read the current {@link WorkState} of other work items (for dependency-style coordination). */
+  states(ids: readonly string[]): Promise<(WorkState | undefined)[]>;
+  /** Win a one-time distributed claim for `key` (returns `true` once across the fleet). */
+  claim(key: string): Promise<boolean>;
+}
+/** A work handler: maps typed input (+ context) to typed output. */
+type WorkHandler<I, O> = (input: I, ctx: WorkContext) => O | Promise<O>;
+/**
+ * Per-instance options resolved at enqueue time and **serialized with the instance**.
+ * Provided at queue time, as per-type constants, or computed by {@link WorkOptions.options}.
+ */
+interface WorkInstanceOptions {
+  /** Delay before the item becomes runnable (ms). Sets `startAt = queueAt + delay`. */
+  readonly delay?: number;
+  /**
+   * Absolute time the item should become runnable (epoch ms) — an alternative to {@link delay}
+   * (`delay = runAt - now`, wins over `delay`). Works for arbitrarily-far times even on backends
+   * that cap a single delay (e.g. SQS's 15-min `DelaySeconds`): the engine re-defers early arrivals
+   * until `runAt`. See also the handler-thrown `WorkDelayError`.
+   */
+  readonly runAt?: number;
+  /** Retry policy override for this item (`@ayepi/core`'s {@link RetryOptions}; callbacks apply to `skipQueue` work). */
+  readonly retry?: RetryOptions;
+  /** Scheduling priority (higher runs first) — consumed by the {@link Doer}. */
+  readonly priority?: number;
+  /** Fairness group label — consumed by `balancedDoer`. */
+  readonly group?: string;
+  /** Skip the durable queue and run this item directly via the doer (in-process; see {@link WorkOptions.skipQueue}). */
+  readonly skipQueue?: boolean;
+}
+/** Batch execution config for a work type (see {@link defineBatchWork}). */
+interface BatchConfig<I, O> {
+  /** Flush when this many items are buffered. */
+  readonly size: number;
+  /** Flush a partial batch this long after the first item is buffered (ms). */
+  readonly maxWait: number;
+  /** Execute a whole batch at once; return one output per input, in the same order. */
+  readonly run: (inputs: I[]) => O[] | Promise<O[]>;
+}
+/**
+ * What a handler failure should do — the return of an {@link WorkOptions.onFailure} /
+ * {@link WorkSystemOptions.onFailure} classifier. Lets you treat, say, an API rate-limit (429) as
+ * "come back later" instead of a retry that burns the attempt budget and eventually dead-letters.
+ */
+type FailureDecision = /** Re-enqueue with backoff, advancing `attempt` (dead-letters once exhausted) — the default if no classifier matches. */
+'retry'
+/** Dead-letter the item now; no further attempts (a permanent failure). */ | 'abort'
+/** Re-enqueue after `delay` ms **without** advancing `attempt` — a reschedule, e.g. honor a rate-limit's `Retry-After`. */ | {
+  readonly delay: number;
+}
+/** Re-enqueue to run at an absolute time (epoch ms) **without** advancing `attempt`. */ | {
+  readonly runAt: number;
+};
+/** Context passed to an {@link WorkOptions.onFailure} classifier. */
+interface WorkFailureInfo {
+  readonly id: string;
+  readonly type: string;
+  /** The delivery attempt that just failed (1-based). */
+  readonly attempt: number;
+  /** Total attempts allowed for this item. */
+  readonly attempts: number;
+}
+/** Classify a handler error into a {@link FailureDecision}; `void` (the default) means retry/dead-letter by attempt count. */
+type FailureClassifier = (err: unknown, info: WorkFailureInfo) => MaybePromise<FailureDecision | void>;
+/** Per-work-type options passed to {@link defineWork}. */
+interface WorkOptions<I> {
+  /** Default retry policy for this type (overridden per-instance by {@link WorkInstanceOptions.retry}). */
+  readonly retry?: RetryOptions;
+  /** Default scheduling priority for this type. */
+  readonly priority?: number;
+  /** Default fairness group for this type. */
+  readonly group?: string;
+  /** Dedicated doer for this type (defaults to the work system's doer) — caps this type's concurrency. */
+  readonly doer?: Doer$1;
+  /**
+   * Dedicated {@link Queue} for this type (defaults to the work system's queue). Several types can
+   * share one `Queue` instance; the engine polls **every** distinct queue each tick, so grouping
+   * types onto separate queues isolates a flooding type — it can't starve types on another queue.
+   * Compose with a per-type {@link doer} to also cap its concurrency.
+   */
+  readonly queue?: Queue;
+  /** Compute per-instance {@link WorkInstanceOptions} from the input (overridden by queue-time options). */
+  readonly options?: (input: I) => WorkInstanceOptions;
+  /** Per-type JSON codec (defaults to the system's global codec). */
+  readonly codec?: JsonCodec;
+  /** Per-type lifecycle hook (fired alongside the global {@link WorkSystemOptions.onEvent}). */
+  readonly onEvent?: (event: WorkEvent) => void;
+  /**
+   * Classify a handler failure for this type into a {@link FailureDecision} — `'abort'` (dead-letter
+   * now), a `{ delay }`/`{ runAt }` reschedule (re-queue without counting a retry, e.g. a rate limit),
+   * or `'retry'`/nothing for the default. Overrides {@link WorkSystemOptions.onFailure}. (A handler can
+   * also decide directly by throwing `RetryAbort` → dead-letter, or `WorkDelayError` → reschedule.)
+   */
+  readonly onFailure?: FailureClassifier;
+  /** Derive `logWith` context from this type's input (merged over the global hook). */
+  readonly logContext?: (input: I) => object;
+  /**
+   * Run this type **without the durable queue** — straight to the doer, in-process.
+   * Retries, grouping, priority, events, and results still work; there is no queue,
+   * store, or heartbeat (so no cross-instance durability). Per-instance
+   * {@link WorkInstanceOptions.skipQueue} overrides this.
+   */
+  readonly skipQueue?: boolean;
+}
+/** The full definition behind a {@link WorkBuilder}. */
+interface WorkDefinition<I, O> {
+  readonly name: string;
+  readonly handler: WorkHandler<I, O>;
+  readonly options: WorkOptions<I>;
+  /** Present for batched work types (see {@link defineBatchWork}). */
+  readonly batch?: BatchConfig<I, O>;
+}
+/**
+ * A callable work builder. Invoke it with the work's input to mint a queueable
+ * {@link Work} (with a fresh id); it also exposes its `type` and underlying `def`.
+ */
+interface WorkBuilder<Name extends string, I, O> {
+  /** Build a type-checked, queueable instance from this work's input. */
+  (input: I): Work<Name, O>;
+  /** The work type name. */
+  readonly type: Name;
+  /** The underlying definition (handler + options). */
+  readonly def: WorkDefinition<I, O>;
+}
+/** The loose base every {@link WorkBuilder} satisfies regardless of its input type. */
+type AnyWorkBuilder = WorkBuilder<string, never, unknown>;
+/**
+ * Define a work type. Returns a {@link WorkBuilder} — a function that builds queueable
+ * instances — typed by its input `I` and output `O`.
+ */
+declare function defineWork<Name extends string, I, O>(name: Name, handler: WorkHandler<I, O>, opts?: WorkOptions<I>): WorkBuilder<Name, I, O>;
+/**
+ * Define a **batched** work type. Items still enqueue, retry, prioritize, and join
+ * groups individually, but execute together via {@link BatchConfig.run} once `size`
+ * accumulate or `maxWait` ms elapse — so each `.result()` resolves to its aligned
+ * output. The per-type {@link WorkOptions.doer} governs how many *batches* run at once.
+ */
+declare function defineBatchWork<Name extends string, I, O>(name: Name, config: BatchConfig<I, O> & WorkOptions<I>): WorkBuilder<Name, I, O>;
+/** The input type a builder accepts. */
+type InputOf<B> = B extends ((input: infer I) => unknown) ? I : never;
+/** The output type a builder's instances carry. */
+type OutputOf<B> = B extends ((...args: never[]) => Work<string, infer O>) ? O : never;
+/** The name of a builder. */
+type NameOf<B> = B extends {
+  readonly type: infer N extends string;
+} ? N : never;
+/** The output type carried by a {@link Work}. */
+type OutputOfWork<W> = W extends Work<string, infer O> ? O : unknown;
+/** Drop `void`/`undefined` from a union (work that returns "nothing"). */
+type NonVoidUnion<U> = Exclude<U, void | undefined>;
+/** The union of every registered work name. */
+type RegistryNames<Defs extends readonly AnyWorkBuilder[]> = NameOf<Defs[number]>;
+/** The builder in the registry with name `K`. */
+type BuilderForName<Defs extends readonly AnyWorkBuilder[], K extends string> = Extract<Defs[number], {
+  readonly type: K;
+}>;
+/** The input type of the registry's work named `K`. */
+type InputForName<Defs extends readonly AnyWorkBuilder[], K extends string> = InputOf<BuilderForName<Defs, K>>;
+/** The output type of the registry's work named `K`. */
+type OutputForName<Defs extends readonly AnyWorkBuilder[], K extends string> = OutputOf<BuilderForName<Defs, K>>;
+/**
+ * The group's final result type: the union of every registered work's non-void
+ * output. The value a top-level `await enqueue(...)` resolves to.
+ */
+type GroupResult<Defs extends readonly AnyWorkBuilder[]> = NonVoidUnion<OutputOf<Defs[number]>>;
+/**
+ * The thenable returned by `enqueue`. **Awaiting it resolves to the group result**
+ * ({@link GroupResult}); use {@link result} for this item's own output and
+ * {@link group} for the explicit group form.
+ */
+interface WorkHandle<Self, Group> extends PromiseLike<Group> {
+  /** This work item's id. */
+  readonly id: string;
+  /** The group id (this item plus everything queued under it). */
+  readonly groupId: string;
+  /** Resolve to **this item's** own output. */
+  result(): Promise<Self>;
+  /** Resolve to the **group's** final result (same as awaiting the handle). */
+  group(): Promise<Group>;
+}
+/** Lifecycle status of a single work item. */
+type WorkStatus = 'pending' | 'running' | 'success' | 'failed' | 'dead';
+/** A snapshot of one work item's state. */
+interface WorkState {
+  readonly id: string;
+  readonly type: string;
+  readonly status: WorkStatus;
+  readonly attempt: number;
+  readonly result?: unknown;
+  readonly error?: string;
+  /** When the item was enqueued (epoch ms). */
+  readonly queueAt: number;
+  /** Scheduled earliest start (epoch ms) — `queueAt + delay`. */
+  readonly startAt: number;
+  /** When execution actually began (epoch ms), if it has. */
+  readonly runAt?: number;
+  /** When the item reached a terminal state (epoch ms), if it has. */
+  readonly endAt?: number;
+  /** Scheduling priority. */
+  readonly priority?: number;
+  /** Fairness group label. */
+  readonly group?: string;
+}
+/** A unit of work currently held by this instance (polled and accepted, not skipped). */
+interface ActiveWork {
+  readonly id: string;
+  readonly type: string;
+  readonly groupId: string;
+  /** `'pending'` = accepted into the doer, awaiting a slot; `'running'` = executing. */
+  readonly status: 'pending' | 'running';
+  readonly attempt: number;
+  readonly priority: number;
+  readonly group?: string;
+  readonly queueAt: number;
+  readonly startAt: number;
+  /** When execution began, if it has. */
+  readonly runAt?: number;
+}
+/**
+ * A lifecycle event delivered to {@link WorkSystemOptions.onEvent}. `'failed'` covers
+ * both a retry (`willRetry: true`) and the terminal dead-letter (`willRetry: false`);
+ * `'deferred'` is a reschedule (a handler threw `WorkDelayError`) — it does **not** advance the
+ * attempt count. (An item put back merely because it arrived before its `startAt` is silent.)
+ */
+type WorkEvent = {
+  readonly kind: 'queued';
+  readonly id: string;
+  readonly type: string;
+  readonly groupId: string;
+  readonly at: number;
+} | {
+  readonly kind: 'started';
+  readonly id: string;
+  readonly type: string;
+  readonly groupId: string;
+  readonly attempt: number;
+  readonly at: number;
+} | {
+  readonly kind: 'deferred';
+  readonly id: string;
+  readonly type: string;
+  readonly groupId: string;
+  readonly runAt: number;
+  readonly at: number;
+} | {
+  readonly kind: 'succeeded';
+  readonly id: string;
+  readonly type: string;
+  readonly groupId: string;
+  readonly attempt: number;
+  readonly result: unknown;
+  readonly at: number;
+} | {
+  readonly kind: 'failed';
+  readonly id: string;
+  readonly type: string;
+  readonly groupId: string;
+  readonly attempt: number;
+  readonly error: string;
+  readonly willRetry: boolean;
+  readonly at: number;
+} | {
+  readonly kind: 'group-done';
+  readonly groupId: string;
+  readonly result: unknown;
+  readonly at: number;
+};
+/** What {@link WorkSystemOptions.accept} receives to decide whether *this* instance should run an item. */
+interface WorkAcceptInfo {
+  readonly id: string;
+  readonly type: string;
+  readonly groupId: string;
+  readonly attempt: number;
+  readonly input: unknown;
+}
+/**
+ * What a {@link WorkSystemOptions.backpressure} hook receives each poll: a live per-type
+ * {@link WorkStats} snapshot and the total in-flight count. Lets the hook adapt the pause to
+ * observed throughput/latency (see the bundled `adaptiveDelay` helper). The hook may still take
+ * no arguments — the context is optional.
+ */
+interface BackpressureContext {
+  /** The live metrics registry — read per-type counters/gauges/summaries (same as {@link WorkSystem.metrics}). */
+  readonly metrics: Metrics;
+  /** Total items this instance is currently holding (polled + accepted, across all types). */
+  readonly active: number;
+}
+/** Passed to {@link WorkSystemOptions.unhandledWorkGroup} when a group finishes with no waiter. */
+interface UnhandledWorkGroupInfo {
+  readonly groupId: string;
+  readonly lastResult: unknown;
+  readonly states: readonly WorkState[];
+}
+/** When a dependency fires. JSON-serializable so it runs on any instance. */
+type DependencyCondition = /** Every watched item reached a terminal state (success, failed, or dead). */
+'all-done'
+/** Every watched item succeeded. */ | 'all-success'
+/** At least `count` watched items reached the given state (`'done'` default). */ | {
+  readonly count: number;
+  readonly of?: 'done' | 'success';
+};
+/** A recurring schedule: a cron expression **or** a next-time function, plus what to run. */
+interface ScheduleConfig {
+  /** Unique schedule name (also the distributed firing-lease key). */
+  readonly name: string;
+  /** A 5-field cron expression (`min hour dom mon dow`). Mutually exclusive with {@link next}. */
+  readonly cron?: string;
+  /** Compute the next fire time from `now` (epoch ms) — return ms/`Date`, or void to stop. */
+  readonly next?: (now: number) => number | Date | void;
+  /** Produce the work instance to enqueue on each fire (or enqueue yourself and return void). */
+  readonly run: () => Work | void;
+}
+/** Options for `createWork`. Every field has a sensible default; `createWork()` works zero-config. */
+interface WorkSystemOptions {
+  /** The durable queue port (default: bundled {@link memoryQueue}). */
+  readonly queue?: Backend['queue'];
+  /** The cross-instance pub/sub port (default: bundled {@link memoryPubSub}). */
+  readonly pubsub?: Backend['pubsub'];
+  /** The key/value store port (default: bundled {@link memoryStore}). */
+  readonly store?: Backend['store'];
+  /** Default retry policy for this system, over `@ayepi/core`'s global defaults (per-type/instance `retry` override). */
+  readonly retry?: RetryOptions;
+  /**
+   * Resilience wrapper for the engine's **load-bearing** port writes (state/result/group store
+   * writes, queue push/ack). When set, each such call is retried with these options so a transient
+   * queue/store blip is absorbed before it reaches the engine's commit/queue handling; on exhaustion
+   * the error surfaces as usual (a commit error is reported via {@link onError}, never re-runs the
+   * handler). Off by default — best for backends without their own retry; the bundled Redis/SQS
+   * backends already retry per call, so this is an additional engine-level safety net.
+   */
+  readonly portRetry?: Omit<RetryOptions, 'errorResult'>;
+  /** Global doer governing concurrency + ordering (default {@link unlimitedDoer}). Per-type `doer` overrides. */
+  readonly doer?: Doer$1;
+  /** Queue poll interval when idle (ms, default 1000). */
+  readonly pollInterval?: number;
+  /**
+   * Dynamic backpressure, checked before **every** poll. Return a number of **milliseconds to
+   * pause** before taking any work — even when doers have free slots — or `0`/nothing to proceed
+   * (the default). The loop sleeps the returned time, then checks again, so it's re-polled until it
+   * returns `0`. Use it to stop pulling work while an external resource is saturated (a database at
+   * capacity, a downstream API rate-limited, a memory ceiling). May be async. A throwing
+   * `backpressure` is reported via {@link onError} (`'queue'`) and the loop backs off `pollInterval`.
+   * Prefer a modest interval (it also bounds how long `stop()` waits for the loop to exit).
+   *
+   * The hook receives a {@link BackpressureContext} (a live {@link WorkStats} snapshot + the
+   * in-flight count) so the pause can adapt to observed throughput/latency — pass the bundled
+   * `adaptiveDelay()` helper, or read `ctx.stats` yourself. (Taking no arguments is still valid.)
+   */
+  readonly backpressure?: (ctx: BackpressureContext) => MaybePromise<number | void>;
+  /** Lease/visibility timeout for a pulled item (ms, default 30000). */
+  readonly visibility?: number;
+  /** Heartbeat interval extending the lease (ms, default `visibility / 3`). */
+  readonly heartbeat?: number;
+  /** Key namespace for every store/queue key (default `'work:'`). */
+  readonly prefix?: string;
+  /** Global JSON codec (per-type `codec` overrides win). */
+  readonly codec?: JsonCodec;
+  /** Wrap each handler in a context scope (e.g. `@ayepi/log`'s `logWith`). */
+  readonly logWith?: LogWith;
+  /** Global hook: derive `logWith` context from every work's input + type. */
+  readonly logContext?: (input: unknown, type: string) => object;
+  /** Global lifecycle hook — fired for queued/started/succeeded/failed/group-done (never throws into the engine). */
+  readonly onEvent?: (event: WorkEvent) => void;
+  /**
+   * Observe a **non-critical** engine error that was swallowed to keep work flowing — so it
+   * can't be mistaken for a handler failure. `phase` is `'commit'` (recording a result that
+   * the handler **already produced** — the store/queue-ack/pub-sub after success; reported,
+   * **never retried**) or `'queue'` (a poll/routing error in the worker loop; the loop sleeps
+   * and continues). A handler's own error is **not** routed here — it retries/dead-letters as
+   * usual. Off by default; it must not throw — if it does, the throw is ignored.
+   */
+  readonly onError?: (err: unknown, phase: 'commit' | 'queue') => void;
+  /**
+   * Default classifier for handler failures (a per-type {@link WorkOptions.onFailure} overrides it):
+   * map an error to `'abort'` (dead-letter now), a `{ delay }`/`{ runAt }` reschedule (re-queue
+   * without burning a retry — e.g. a rate limit), or `'retry'`/nothing for the normal attempt-counted
+   * behavior. A throwing classifier is reported and falls back to the default.
+   */
+  readonly onFailure?: FailureClassifier;
+  /**
+   * A readable dead-letter {@link Queue} to **redrive** from. When the normal queue(s) are idle
+   * (a poll round pulled nothing) and there is free capacity, the loop transfers up to
+   * {@link redriveCount} bodies from here back onto their type's queue as **fresh** work
+   * (`attempt` reset to 1, full retry budget) and acks them off the DLQ. Use it to automatically
+   * reprocess dead-lettered items once a downstream recovers. Point it at the same sink your
+   * queue's `deadLetter` writes to (an unparseable body is dropped). Off by default.
+   */
+  readonly dlq?: Queue;
+  /** Max messages to redrive from {@link dlq} per idle poll (default 10; `0` disables redrive). */
+  readonly redriveCount?: number;
+  /**
+   * Instance affinity. Return `false` to decline an item on this instance (it is
+   * deferred for another to pick up) — lets you shard work types across a fleet.
+   */
+  readonly accept?: (info: WorkAcceptInfo) => boolean;
+  /** Called once when a group finishes with a result but nobody was waiting for it. */
+  readonly unhandledWorkGroup?: (info: UnhandledWorkGroupInfo) => void;
+  /**
+   * The {@link Metrics} registry the engine records per-type stats into (default: a fresh
+   * `createMetrics()`). Provide one to enable summary **quantiles** (`createMetrics({ quantiles:
+   * [0.5, 0.95, 0.99] })`), share a registry across several systems, or subscribe to changes.
+   * Exposed back as {@link WorkSystem.metrics}.
+   */
+  readonly metrics?: Metrics;
+  /** Start the worker loop immediately (default true). */
+  readonly autoStart?: boolean;
+  /** Clock injection for tests (default `Date.now`). */
+  readonly now?: Clock;
+  /** Randomness injection for backoff jitter (default `Math.random`). */
+  readonly random?: () => number;
+}
+/** The work system returned by `createWork`. */
+interface WorkSystem<Defs extends readonly AnyWorkBuilder[]> {
+  /** Enqueue a built instance; await the handle for the group result, `.result()` for its own. */
+  enqueue<W extends Work>(work: W, options?: WorkInstanceOptions): WorkHandle<OutputOfWork<W>, GroupResult<Defs>>;
+  /** Enqueue by registered name with a type-checked input. */
+  enqueue<K extends RegistryNames<Defs>>(name: K, input: InputForName<Defs, K>, options?: WorkInstanceOptions): WorkHandle<OutputForName<Defs, K>, GroupResult<Defs>>;
+  /** Register a recurring schedule; returns a cancel function. */
+  schedule(config: ScheduleConfig): () => void;
+  /** Start the worker + scheduler loops (idempotent). */
+  start(): void;
+  /** Stop the loops and flush in-flight heartbeats (idempotent). */
+  stop(): Promise<void>;
+  /** Snapshot of known work states (best-effort). */
+  list(): Promise<WorkState[]>;
+  /** Work currently held by this instance — polled and accepted (will not be skipped). */
+  active(): ActiveWork[];
+  /**
+   * A flat snapshot of every per-type metric series (counters/gauges/summaries), labelled by work
+   * `type` — a convenience for `metrics.list()`. Pass to `formatPrometheus`, or read individual
+   * series via {@link metrics}. See `@ayepi/core`'s {@link StatValue}.
+   */
+  stats(): StatValue[];
+  /**
+   * The live {@link Metrics} registry the engine records into — `list()` / `get(name, { type })` /
+   * `subscribe()` for change notifications. Bring your own via {@link WorkSystemOptions.metrics}
+   * (e.g. to enable quantiles or share one registry across systems).
+   */
+  readonly metrics: Metrics;
+  /** The underlying ports (queue/pubsub/store) — useful in tests and for sharing a backend. */
+  readonly backend: Backend;
+}
+//#endregion
+//#region src/engine.d.ts
+/**
+ * Create a work system. Zero-config (`createWork()`) uses the bundled in-memory backend
+ * and an {@link unlimitedDoer}; pass `work: [...] as const` for a typed registry, a
+ * `doer` to govern concurrency, and/or `queue`/`pubsub`/`store` to go distributed.
+ */
+declare function createWork<const Defs extends readonly AnyWorkBuilder[]>(opts?: WorkSystemOptions & {
+  work?: Defs;
+}): WorkSystem<Defs>;
+//#endregion
+//#region src/errors.d.ts
+/**
+ * # Work errors
+ *
+ * {@link WorkDelayError} — throw it from a handler to **defer** the item to a later time
+ * instead of completing or failing it. It is a **reschedule, not a retry**: the attempt count
+ * is unchanged, so a handler can defer indefinitely (e.g. "the upstream isn't ready, try me in
+ * 5 minutes"). The item is re-enqueued to run at the resolved time; a far-future time is honored
+ * even on backends that cap a single delay (the engine re-defers early arrivals).
+ *
+ * @module
+ */
+/** When a {@link WorkDelayError} wants the work to run: an absolute time, a relative delay, or both. */
+interface WorkDelaySpec {
+  /** Absolute time to run at (epoch ms). Wins over {@link delay}. */
+  readonly runAt?: number;
+  /** Relative delay from now (ms). `runAt` is computed as `now + delay`. */
+  readonly delay?: number;
+}
+/**
+ * Throw from a work handler to **defer** the item to a future time (a reschedule, not a failure).
+ *
+ * ```ts
+ * defineWork('poll', async (input, ctx) => {
+ *   if (!(await upstreamReady())) throw new WorkDelayError({ delay: 5 * 60_000 }); // retry in 5 min, attempt unchanged
+ *   return doWork(input);
+ * });
+ * ```
+ */
+declare class WorkDelayError extends Error {
+  /** When the item should next run. */
+  readonly when: WorkDelaySpec;
+  constructor(/** When the item should next run. */
+  when: WorkDelaySpec, message?: string);
+}
+//#endregion
+//#region src/stats.d.ts
+/** Metric names (dotted; `formatPrometheus` sanitizes the dots to underscores). Exported so consumers can reference series by name. */
+declare const WORK_METRICS: {
+  readonly queued: "work.queued";
+  readonly started: "work.started";
+  readonly succeeded: "work.succeeded";
+  readonly failed: "work.failed";
+  readonly retried: "work.retried";
+  readonly deferred: "work.deferred";
+  readonly rescheduled: "work.rescheduled";
+  readonly active: "work.active";
+  readonly pending: "work.pending";
+  readonly running: "work.running";
+  readonly peak: "work.peak_active";
+  readonly lastQueued: "work.last_queued_at";
+  readonly lastStarted: "work.last_started_at";
+  readonly lastSucceeded: "work.last_succeeded_at";
+  readonly lastFailed: "work.last_failed_at";
+  readonly waitTime: "work.wait_time";
+  readonly totalTime: "work.total_time";
+  readonly successTime: "work.success_time";
+  readonly errorTime: "work.error_time";
+  readonly delayTime: "work.delay_time";
+  readonly rescheduleTime: "work.reschedule_time";
+  readonly attempts: "work.attempts";
+};
+/** The recorder the engine feeds; all durations are **milliseconds**, timestamps epoch ms. */
+//#endregion
+//#region src/adaptive.d.ts
+/** Options for {@link adaptiveDelay}. All times are **milliseconds**. */
+interface AdaptiveDelayOptions {
+  /** Restrict the failure-rate calculation to these work types (default: every type in the snapshot). */
+  readonly types?: readonly string[];
+  /** Backoff triggers when an interval's `failed / (succeeded + failed)` exceeds this (default `0` — any failure). */
+  readonly maxFailRate?: number;
+  /** Pause floor returned while healthy (default `0` — no pause when all is well). */
+  readonly min?: number;
+  /** Pause ceiling — the backoff never grows past this (default `30000`). */
+  readonly max?: number;
+  /** The first non-zero pause when backoff starts (default `100`). */
+  readonly base?: number;
+  /** Multiplier applied to the current pause on each unhealthy interval (default `2`). */
+  readonly factor?: number;
+  /** Amount subtracted from the pause on each healthy interval (default `base`). */
+  readonly step?: number;
+}
+/** A stateful backpressure function: feed it the per-poll {@link BackpressureContext}, it returns the pause (ms). */
+type AdaptiveDelay = (ctx: BackpressureContext) => number;
+/**
+ * Build an {@link AdaptiveDelay} controller for {@link WorkSystemOptions.backpressure}. It holds a
+ * little state (the current pause + the last cumulative counts) across calls, so create **one** per
+ * work system. Watching a subset of `types` lets one system protect a specific downstream.
+ */
+declare function adaptiveDelay(opts?: AdaptiveDelayOptions): AdaptiveDelay;
+//#endregion
+//#region src/memory.d.ts
+/** Options shared by the in-memory ports (mainly the injectable clock). */
+interface MemoryOptions {
+  /** Clock injection for deterministic tests (default `Date.now`). */
+  readonly now?: Clock;
+}
+/**
+ * The minimal **synchronous** filesystem surface the file-backed {@link memoryQueue} uses.
+ * `node:fs` satisfies it (the default); tests inject their own. Writes are synchronous so the
+ * queue's own synchronous operations stay synchronous.
+ */
+interface QueueFsLike {
+  /** Read a file's contents, or `undefined` when it doesn't exist. */
+  readFile(path: string): string | undefined;
+  /** Write (overwrite) a file. */
+  writeFile(path: string, data: string): void;
+  /** Rename a file (used for an atomic temp → target swap). */
+  rename(from: string, to: string): void;
+  /** Ensure a directory exists (recursive; called once before the first write). */
+  mkdir(path: string): void;
+}
+/**
+ * In-process {@link PubSub} (the `localBroker` shape). Share one instance across
+ * engines to fan a publish out to every "pod".
+ */
+declare function memoryPubSub(): PubSub;
+/**
+ * In-memory {@link Store} with lazy TTL expiry and an atomic {@link Store.setIfNotExists}.
+ * The compare-and-set every distributed claim relies on.
+ */
+declare function memoryStore(opts?: MemoryOptions): Store;
+/** Dead-lettered bodies, exposed for inspection in tests via {@link MemoryQueue.dead}. */
+interface DeadLettered {
+  readonly body: string;
+  readonly error: string;
+}
+/** A {@link Queue} plus the in-memory extras tests reach for (its operations are synchronous). */
+interface MemoryQueue extends Queue {
+  /** Lease up to `max` visible items (synchronous — reclaims expired leases first). */
+  pop(max: number, visibility: number): PulledWork[];
+  /** Items currently moved to the dead-letter sink. */
+  readonly dead: readonly DeadLettered[];
+  /** Count of items still in the queue (leased or visible). */
+  size(): number;
+}
+/** File-persistence options for {@link memoryQueue} — single-process durability. */
+interface MemoryQueuePersistence {
+  /**
+   * Persist the queue (pending items + dead-letter sink) to this file so work survives a
+   * process restart. Writes are atomic (a temp file is renamed over the target) and happen
+   * after every mutation. On startup the file is reloaded. Omit for a pure in-memory queue.
+   */
+  readonly file?: string;
+  /** Injected filesystem (default synchronous `node:fs`). For tests, or a custom backing store. */
+  readonly fs?: QueueFsLike;
+  /**
+   * Observe a (best-effort) persistence error — a load that found a corrupt file, or a failed
+   * write. Persistence never throws into the engine: the in-memory state stays authoritative
+   * for the running process and the failure is reported here. Off by default; must not throw.
+   */
+  readonly onError?: (err: unknown) => void;
+}
+/** Options for {@link memoryQueue}: the shared clock plus optional file {@link MemoryQueuePersistence}. */
+interface MemoryQueueOptions extends MemoryOptions, MemoryQueuePersistence {}
+/**
+ * In-memory {@link Queue} with visibility-timeout leasing. `pop` first **reclaims**
+ * items whose lease expired (a dead worker → redelivery, `attempt++`), then leases
+ * fresh visible items. `ack`/`heartbeat`/`fail` are token-gated, so a stale worker
+ * whose lease already lapsed cannot ack work another worker now owns.
+ *
+ * Pass `file` to make it **durable**: state is reloaded on construction and rewritten
+ * atomically after every mutation. A heartbeat is *not* persisted (lease expiry is
+ * reset on reload anyway), so steady-state heartbeating doesn't touch the disk.
+ */
+declare function memoryQueue(opts?: MemoryQueueOptions): MemoryQueue;
+/** Options for {@link memoryBackend}: the shared clock plus optional queue file persistence. */
+interface MemoryBackendOptions extends MemoryOptions {
+  /**
+   * File-persistence for the bundled queue (the store and pub/sub stay purely in-memory).
+   * Pass `{ file: '…' }` to make pending work survive a process restart.
+   */
+  readonly queue?: MemoryQueuePersistence;
+}
+/**
+ * The three in-memory ports together, sharing one clock. The default backend when
+ * `createWork()` is called with no ports.
+ *
+ * @example A two-pod test on one shared backend:
+ * ```ts
+ * const backend = memoryBackend()
+ * const podA = createWork({ ...backend, work: [add] })
+ * const podB = createWork({ ...backend, work: [add] })
+ * ```
+ *
+ * @example A single durable process — pending work survives a restart:
+ * ```ts
+ * const backend = memoryBackend({ queue: { file: './work-queue.json' } })
+ * const work = createWork({ ...backend, work: [add] })
+ * ```
+ */
+declare function memoryBackend(opts?: MemoryBackendOptions): Backend;
+//#endregion
+//#region src/dependency.d.ts
+/** The built-in work type name for a dependency. */
+declare const DEPENDENCY_TYPE = "@work/dependency";
+/** A dependent serialized into a dependency's input (a minimal {@link Work}). */
+
+/** Options for {@link dependency}. */
+interface DependencyOptions {
+  /** Works (or their ids) to wait on. */
+  readonly on: readonly (string | Work)[];
+  /** Works to queue, into the same group, once satisfied. */
+  readonly queue: readonly Work[];
+  /** When to fire (default `'all-success'`). */
+  readonly config?: DependencyCondition;
+  /** Re-check interval (ms, default 1000). */
+  readonly poll?: number;
+  /** Give up (dead-letter) after this long (ms). */
+  readonly timeout?: number;
+}
+/**
+ * Evaluate a {@link DependencyCondition} against the watched items' states. A missing
+ * state counts as "not yet done". Pure and JSON-driven, so every instance agrees.
+ */
+declare function conditionMet(condition: DependencyCondition, states: readonly (WorkState | undefined)[]): boolean;
+/**
+ * Build a dependency: when the works it waits `on` satisfy `config`, it queues its
+ * `queue` dependents (once). Enqueue it like any work.
+ */
+declare function dependency(opts: DependencyOptions): Work<typeof DEPENDENCY_TYPE, void>;
+/**
+ * The non-blocking handler for {@link DEPENDENCY_TYPE}: check once, then fire or
+ * re-queue. Registered automatically by every work system. Remembers terminal statuses
+ * (`resolved`) so it neither re-reads settled works nor treats an evicted state as a
+ * failure.
+ */
+//#endregion
+//#region src/schedule.d.ts
+/** A parsed cron expression: a matching set per field. */
+interface CronFields {
+  readonly minute: Set<number>;
+  readonly hour: Set<number>;
+  readonly dom: Set<number>;
+  readonly month: Set<number>;
+  readonly dow: Set<number>;
+  /** Whether dom / dow were restricted (not `*`) — drives the OR semantics. */
+  readonly domRestricted: boolean;
+  readonly dowRestricted: boolean;
+}
+/** Parse a 5-field cron expression (`min hour dom mon dow`). */
+declare function parseCron(expr: string): CronFields;
+/**
+ * The next epoch-ms strictly after `fromMs` that matches `expr`, or `undefined` if
+ * none within ~a year. Minute-granular (cron's resolution).
+ */
+declare function nextAfter(expr: string, fromMs: number): number | undefined;
+/** Engine-supplied dependencies for {@link startSchedule}. */
+
+//#endregion
+//#region src/index.d.ts
+/** The default (registry-less) work system. Most apps call {@link createWork} with their own registry instead. */
+declare const work: WorkSystem<readonly AnyWorkBuilder[]>;
+/** Enqueue on the default system (instance form). */
+declare const enqueue: {
+  <W extends Work>(work: W, options?: WorkInstanceOptions): WorkHandle<OutputOfWork<W>, unknown>;
+  <K extends string>(name: K, input: InputOf<Extract<AnyWorkBuilder, {
+    readonly type: K;
+  }>>, options?: WorkInstanceOptions): WorkHandle<OutputOf<Extract<AnyWorkBuilder, {
+    readonly type: K;
+  }>>, unknown>;
+};
+/** Register a recurring schedule on the default system. */
+declare const schedule: (config: ScheduleConfig) => () => void;
+/** Start the default system's worker loop. */
+declare const start: () => void;
+/** Stop the default system. */
+declare const stop: () => Promise<void>;
+/** Snapshot the default system's known work states. */
+declare const list: () => Promise<WorkState[]>;
+//#endregion
+export { type ActiveWork, type AdaptiveDelay, type AdaptiveDelayOptions, type AnyWorkBuilder, type Backend, type BackpressureContext, type BatchConfig, type BoundedDoerOptions, type BuilderForName, type Counter, DEFAULT_BUCKETS, DEFAULT_RETRY_OPTIONS, DEPENDENCY_TYPE, type DeadLettered, type DependencyCondition, type DependencyOptions, type Doer, type DoerTaskOptions, type FailureClassifier, type FailureDecision, type Gauge, type GroupResult, type InputForName, type InputOf, type JsonCodec, type Labels, type MemoryBackendOptions, type MemoryOptions, type MemoryQueue, type MemoryQueueOptions, type MemoryQueuePersistence, type Metrics, type MetricsOptions, type NameOf, type NonVoidUnion, type OutputForName, type OutputOf, type OutputOfWork, type PubSub, type PulledWork, type PushOptions, type Queue, type QueueFsLike, type RegistryNames, RetryAbort, type RetryOptions, type RetryState, type ScheduleConfig, type StatBucket, type StatKind, type StatMeta, type StatSummary, type StatValue, type Store, type Summary, type UnhandledWorkGroupInfo, type UnlimitedDoerOptions, WORK_METRICS, type Work, type WorkAcceptInfo, type WorkBuilder, type WorkContext, type WorkDefinition, WorkDelayError, type WorkDelaySpec, type WorkEvent, type WorkFailureInfo, type WorkHandle, type WorkHandler, type WorkInstanceOptions, type WorkOptions, type WorkState, type WorkStatus, type WorkSystem, type WorkSystemOptions, adaptiveDelay, ageDoer, backoff, balancedDoer, conditionMet, createMetrics, createWork, defaultCodec, defineBatchWork, defineWork, dependency, enqueue, formatPrometheus, getDefaultRetryOptions, list, memoryBackend, memoryPubSub, memoryQueue, memoryStore, nextAfter, parseCron, priorityDoer, retry, schedule, setDefaultRetryOptions, start, stop, unlimitedDoer, work };