@jarenjs/core 0.73.0 → 0.83.2

package/docs/SEARCH.md

@@ -0,0 +1,158 @@
+# Resident lexical search
+
+`@jarenjs/core/search` is an opt-in, dependency-free index. It compiles a
+versioned definition, owns resident postings and field statistics, and returns
+ranked string IDs. It imports no database, AI engine, worker or DOM code.
+
+```js
+import { compileLexical } from '@jarenjs/core/search';
+const lexical = compileLexical({
+  version: 1, fields: ['title', 'sku'], prefix: true, fuzzy: 0.15,
+  combineWith: 'AND', normalization: 'application-decoded-text/1',
+});
+const index = lexical.create();
+index.rebuild([{ id: 'tea', title: 'Green tea', sku: '00120' }],
+  { generation: 1, sourceRevision: 'catalog-revision-1' });
+const result = index.search('gren tea', { limit: 20 });
+index.dispose();
+```
+
+## Definition and compatibility
+
+The definition is closed: `version`, `fields`, `profile`, `prefix`, `fuzzy`,
+`combineWith`, `boost`, `normalization` and `limits`. Fields are distinct names;
+documents carry a nonempty string `id` and string fields. Missing/null fields
+index as empty text. Numbers are refused rather than silently stripping leading
+zeros. Applications decode HTML before indexing and give that policy a stable
+`normalization` identity. Changing this identity invalidates snapshots.
+
+The default profile, `minisearch-7.2.0-cold`, uses lowercase UTF-16 text,
+Unicode punctuation/separator plus CR/LF token boundaries, preserved accents,
+and BM25+ with k=1.2, b=0.7 and delta=0.5. Tabs and symbols follow the reference
+tokenizer, not a different whitespace tokenizer. Field lengths count distinct
+unprocessed tokens. Query token repetitions add their score repeatedly, while
+the final quality multiplier counts distinct query terms. Empty/punctuation-only
+queries return a complete empty result. A numeric identifier remains text, but
+prefix/fuzzy matching can deliberately include nearby identifiers; exact identifier
+lookup should use `prefix: false, fuzzy: 0` or the authoritative row lookup.
+
+Fuzzy distance is `min(6, round(queryToken.length * fuzzy))`, measured by
+Levenshtein distance over UTF-16 units. Prefix expansion wins a fuzzy overlap.
+Exact, prefix and fuzzy weights are respectively 1, 0.375 and 0.45, with the
+reference's length/distance attenuation. Field `boost` values are finite positive
+numbers. Term combination is `AND` or `OR`.
+
+Equal-score results in the cold profile preserve first matching posting order
+under the last AND term (first union occurrence for OR). Vocabulary prefix
+traversal is reverse depth-first and fuzzy traversal is forward depth-first,
+both derived deterministically from authoritative document order. An update
+reconstructs these orders from the current documents, so it agrees with a fresh
+build; this is deliberately independent of a reference engine's deleted-posting
+history. Snapshots preserve the same ties. The retained reference's JSON reload
+can change ties: this divergence is published, never silently normalized.
+The explicit `lexical-key/1` profile instead breaks score ties by string ID.
+It is a declared ordering choice, not cold-profile parity.
+
+## Results and completeness
+
+`search(text, options)` returns `state`, `hits: [{id, score}]`, `total`,
+`hasMore`, `continuation`, `generation`, `sourceRevision`, `identity` and `used`.
+`complete` certifies that the complete membership was evaluated; `limit` bounds
+the returned page, and `total` still counts every matched, filtered document.
+`budget-exhausted`, `invalidated` and `error` return no hits and `total: null`.
+They never look like complete empty searches.
+
+Options include `limit`, smaller `credits: {work, expansions, candidates}`,
+`sourceRevision`, `filter(hit)`, `compare(a,b)`, `onMatch(hit)`, `query` and
+`after`. Filtering and `onMatch` run before sorting and slicing, so counts and
+facets do not filter a truncated top-k. A custom comparator changes ordering
+only. Callbacks are trusted synchronous application code; their own CPU,
+allocations and side effects are outside engine credits. A callback that mutates
+or disposes the index invalidates the pending result before publication.
+
+A continuation identifies the final score and stable ID plus exact text,
+request identity, configuration and source revision. Supply it as `after`.
+Changed identities or missing cursor members invalidate the request. Every page
+re-evaluates the complete bounded membership; this is resident pagination, not a
+claim of indexed seek performance. Query/host layers supply `query` for the
+filter, facet and ordering identity. Never reuse it with different callbacks.
+
+## Updates and resource credits
+
+`rebuild(rows, identity)`, `update({put, remove}, identity)` and `clear(identity)`
+prepare before publishing. Failures leave the published generation intact.
+Lower generations invalidate; an equal generation with different content refuses.
+Equal content and source revision is a no-op: zero changes, unchanged generation,
+no additional postings and no tombstones. A higher source revision can publish
+unchanged indexed text, allowing a change in non-indexed authoritative fields to
+invalidate query results. Explicit generations are nonnegative safe integers.
+
+`SEARCH_LIMITS` declares finite document, source-byte, retained-index,
+temporary-byte, token/posting, vocabulary, field/token/query, candidate,
+expansion, output and work ceilings. `stats()` reports retained document,
+posting, vocabulary, source and accounted-index quantities. Accounted bytes
+are a conservative logical allocation model; they are not measurements of a
+JavaScript VM's heap or its garbage collector. Temporary reservations include
+the old published index, staged documents/postings, vocabulary construction and
+snapshot decoding. Credits are checked before publication; source/token-sized
+temporary allocations are reserved before tokenization. No deleted content is
+retained for later vacuuming.
+
+`rebuildAsync(rows, {yield, signal, onProgress, ...identity})` and
+`updateAsync(changes, request)` use the same transactional preparation, yields in bounded work batches, and fences cancellation
+and superseded requests before publication. A single document or posting reorder
+that cannot fit one batch refuses. `yield` must yield to the host's event loop
+when responsiveness is required; resolving a promise alone does not do that.
+An injected worker host additionally enforces its process/VM memory ceiling.
+One index's logical limits cannot bound another index or a caller-owned catalog.
+
+## Snapshots and ownership
+
+`snapshot()` produces a JSON string in `jaren-lexical/1`. It contains an explicit
+complete marker, exact configuration identity, source revision, generation,
+ordered derived field text and stable ordinals. A content checksum detects
+accidental corruption; it does not authenticate untrusted storage.
+`restore(string, {sourceRevision, generation?})` validates before atomic
+publication. Corruption, incompatible configuration, stale source, partial
+format and allocation limits return `rebuild-required` with a reason. Restore
+reconstructs postings through the same engine; it is not a zero-cost mmap load.
+An identical second restore reports zero changes.
+
+The authoritative source owns revision validation. An index snapshot is a
+discardable derived cache, never a second catalog. The db adapter publishes it
+atomically, and the app search resource owns an injected worker and drains it
+on disposal. `dispose()` is idempotent, clears resident references, rejects new
+work and fences unfinished builds.
+
+## Measured qualification
+
+Run `npm run benchmark:lexical` for isolated retained-reference and native
+measurements over both frozen synthetic consumers. The runner compares complete
+membership, scores, cold ties and native reload results for every labelled query.
+It reports reference reload divergence and slower native paths beside gains.
+Heap/RSS qualification belongs to the named Node host and its enforced heap
+ceiling; browser layout and real consumer relevance are separate evidence.
+
+<!--fact:lexical.measurements-->
+
+Measured on v24.19.0, linux/x64, AMD Ryzen 9 5900HX with Radeon Graphics.
+
+| Consumer / engine | Rows | Cold / warm ms | Query p95 ms | One update ms | Snapshot gzip bytes | Sampled heap / RSS high-water MiB | V8 heap ceiling MiB |
+|---|---:|---|---:|---:|---:|---|---:|
+| catalog / reference | 10000 | 130.99 / 50.10 | 11.97 | 0.45 | 370591 | 95.97 / 190.46 | 240.00 |
+| catalog / native | 10000 | 203.59 / 201.37 | 10.89 | 63.60 | 121054 | 104.08 / 208.89 | 240.00 |
+| archive-stock / reference | 75000 | 1124.97 / 578.43 | 168.33 | 0.55 | 2820312 | 559.14 / 697.04 | 752.00 |
+| archive-stock / native | 75000 | 1500.68 / 1775.38 | 98.43 | 681.98 | 920811 | 579.94 / 726.00 | 752.00 |
+
+| Consumer | Native logical index MiB | Peak update accounted MiB | Native teardown ms / remaining handles | Membership / order / score / native reload differences | Reference reload tie changes |
+|---|---:|---:|---|---|---:|
+| catalog | 24.58 | 35.37 | 0.04 / 0 | 0 / 0 / 0 / 0 | 1002 |
+| archive-stock | 186.22 | 267.03 | 0.03 / 0 | 0 / 0 / 0 / 0 | 6002 |
+
+Browser gzip: native 5606 bytes; reference 5874 bytes.
+
+Separate Node processes, identical source rows and queries, five query samples each; startup includes source generation, cold build, snapshot and warm restore. An earlier unconstrained native run exceeded the larger corpus heap and RSS ceilings; the explicit host heap settings are required for this qualification. RSS is the OS process high-water mark; heap is sampled after operations. peakHeapBytes is the V8 hard heap ceiling (a conservative bound, not an observed peak); both engines run with the same max-old-space-size derived from the frozen heap budget, reserving 64 MiB for young space and explicitly limiting each semi-space to 16 MiB. Unconstrained GC is not a bounded host. Reference indexBytes is serialized JSON; native indexBytes is conservative logical retained allocation, so those columns are not the same metric. Both retain a cold and a restored index during query qualification.
+
+Native build, reload and update costs exceed the reference; source-bound snapshots compress better. Cold tie compatibility deliberately differs from reference reload ordering. These synthetic results qualify the named bounded host, not downstream relevance or universal latency.
+
+<!--/fact-->

package/docs/VIRTUAL.md

@@ -0,0 +1,40 @@
+# Virtual geometry
+
+Import `fixedRange`, `createVirtualAxis`, `virtualIndices` and
+`logicalScrollOffset` from `@jarenjs/core/virtual`. This opt-in entry has no DOM,
+view, app, database or worker dependency.
+
+`fixedRange({count, size, viewport, offset=0, overscan=0})` returns a half-open
+`{start,end,offset,extent}`. It clamps offsets to the logical extent, does constant
+work, and returns an empty range for empty or hidden viewports. Count and overscan
+are nonnegative safe integers; size is finite and positive. Invalid geometry
+throws `RangeError`. Nonfinite offsets and viewports normalize to zero.
+
+For a fixed axis the mounted base range has at most
+`ceil(viewport / size) + 1 + 2 * overscan` rows, clamped by count. The extra row
+covers fractional alignment. `virtualIndices(range,pins,count,pinBudget)` merges
+unique valid pins and returns `budget-exhausted / pin-credits` when additional
+pins exceed their limit. It never silently truncates the requested viewport.
+
+`createVirtualAxis({count,estimateSize,maxMeasurements=256,maxBytes=32768})`
+adds sparse sizes through `measure(index,key,size)`. Keys are stable strings.
+The cache evicts oldest measurements and estimates their sizes again. Sorted
+sparse entries and prefix summaries cost O(M) memory, where M is the measurement
+credit, and rebuild only when measurements or identity mappings change. Position
+lookups search those summaries; measured range lookup searches logical positions
+without allocating or enumerating count items. Fixed ranges take the constant
+path when no measurement is retained. `stats()` reports retained measurements,
+accounted bytes and summaries; actual JS allocation overhead is measured separately.
+
+`update({count,estimateSize,indexOf})` remaps retained keys after insertion,
+deletion or reordering. An estimate change invalidates previous measurements.
+`anchor(offset,keyAt,query)` captures key plus intra-row offset and query identity.
+`restore(anchor,indexOf,query)` re-resolves the key, or uses the clamped previous
+logical position when it disappeared; a changed query starts at zero. The index
+in this transient fallback is never an entity identifier. The collection retains
+this anchor before the host mutates source order.
+
+`position`, `size`, `indexAt`, `extent`, `range`, `clear` and idempotent `dispose`
+complete the axis API. A disposed axis retains no measurements or summaries.
+`logicalScrollOffset` normalizes LTR, negative RTL, reverse RTL and default RTL
+coordinates at a DOM adapter boundary. Core does not choose a browser scroll ceiling.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/core",
   "private": false,
-  "version": "0.73.0",
+  "version": "0.83.2",
   "type": "module",
   "main": "./src/index.js",
   "types": "./dist/types/index.d.ts",
@@ -32,6 +32,10 @@
     "core"
   ],
   "exports": {
+    "./search": {
+      "types": "./dist/types/search/index.d.ts",
+      "default": "./src/search/index.js"
+    },
     ".": {
       "types": "./dist/types/index.d.ts",
       "default": "./src/index.js"
@@ -172,7 +176,23 @@
       "types": "./dist/types/convert/*.d.ts",
       "default": "./src/convert/*.js"
     },
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./virtual": {
+      "types": "./dist/types/virtual/index.d.ts",
+      "default": "./src/virtual/index.js"
+    },
+    "./range": {
+      "types": "./dist/types/range/index.d.ts",
+      "default": "./src/range/index.js"
+    },
+    "./retry": {
+      "types": "./dist/types/retry.d.ts",
+      "default": "./src/retry.js"
+    },
+    "./schedule": {
+      "types": "./dist/types/schedule.d.ts",
+      "default": "./src/schedule.js"
+    }
   },
   "scripts": {
     "build": "npm run build:types",

package/src/range/index.js

@@ -0,0 +1,125 @@
+//@ts-check
+/** Shared structural range protocol and resident-array provider. */
+import { isJsonValue } from '../object.js';
+import { resolveRuntime } from '../runtime.js';
+
+/** JSON wire byte cost. @param {any} value */
+export const rangeBytes = (value) => new TextEncoder().encode(JSON.stringify(value)).byteLength;
+/** Echo request identity. @param {any} request */
+export const rangeIdentity = (request) => Object.fromEntries(['generation', 'requestId', 'query', 'snapshot'].map((key) => [key, request[key]]));
+/** Validate finite request credits. @param {any} credits */
+export const validRangeCredits = (credits) => ['pages', 'rows', 'bytes', 'work'].every((key) => Number.isSafeInteger(credits?.[key]) && credits[key] >= 0);
+/** Validate a half-open logical range. @param {any} range */
+export const validLogicalRange = (range) => range && Number.isSafeInteger(range.start) && Number.isSafeInteger(range.end) && range.start >= 0 && range.end >= range.start;
+
+/**
+ * A resident-array provider. The immutable source copy and key index are reported separately
+ * from requested pages; virtual DOM does not make this resident source bounded by page credits.
+ * @param {any[]} initialRows @param {any} [options]
+ */
+export function createArrayRangeProvider(initialRows, options = {}) {
+  const source = options.source ?? resolveRuntime(options.runtime).uuid();
+  const query = options.query ?? source, keyOf = options.keyOf ?? ((row) => String(row.id));
+  let snapshot = options.snapshot ?? `${source}-v1`, revision = 0, disposed = false, ticket = 0, generation = -1;
+  let rows = [], sizes = [], indices = new Map(), sourceBytes = 0;
+  const pending = new Set(), observers = new Set(), cursors = new Map();
+  const maxPages = options.maxPages ?? 4, maxRows = options.maxRows ?? 256, maxBytes = options.maxBytes ?? 262144;
+  const maxInFlight = options.maxInFlight ?? 2;
+  for (const limit of [maxPages, maxRows, maxBytes, maxInFlight])
+    if (!Number.isSafeInteger(limit) || limit <= 0) throw new RangeError('Invalid provider credits');
+  function load(input) {
+    if (!Array.isArray(input) || !isJsonValue(input)) throw new TypeError('Array provider rows must be JSON');
+    const copy = structuredClone(input), index = new Map();
+    copy.forEach((row, i) => { const key = keyOf(row);
+      if (typeof key !== 'string' || index.has(key)) throw new TypeError('Array keys must be unique strings');
+      index.set(key, i); });
+    // Returned rows are copies, so callers cannot mutate the complete source snapshot.
+    rows = copy; indices = index; sizes = rows.map(rangeBytes); sourceBytes = sizes.reduce((n, size) => n + size, 2 + Math.max(0, rows.length - 1));
+  }
+  load(initialRows);
+  const capabilities = Object.freeze({ seekIndex: options.seekIndex !== false, seekKey: true, continuation: true,
+    exactTotal: options.exactTotal !== false, live: true, completeExport: true });
+  const provider = {
+    query, get snapshot() { return snapshot; }, capabilities,
+    indexOf(key) { return indices.get(key) ?? -1; },
+    stats() { return { rows: rows.length, bytes: sourceBytes, pages: cursors.size, pending: pending.size, subscriptions: observers.size }; },
+    replace(next, identity) {
+      if (disposed) throw new Error('Provider disposed');
+      if (typeof identity !== 'string' || identity === snapshot) throw new TypeError('Replacement needs a new source snapshot');
+      load(next); snapshot = identity; cursors.clear(); ticket++;
+      const event = { type: 'reset', revision: ++revision, query, snapshot };
+      for (const fn of observers) { try { fn(event); } catch { /* Subscribers cannot suppress sibling invalidations. */ } }
+    },
+    subscribe(fn) {
+      if (disposed) throw new Error('Provider disposed');
+      if (observers.size >= 8) throw new RangeError('Subscription credits');
+      observers.add(fn); return () => observers.delete(fn);
+    },
+    request(input, signal) {
+      const request = structuredClone(input), identity = rangeIdentity(request), used = { pages: 0, rows: 0, bytes: 0, work: 0 };
+      const refuse = (state, reason) => ({ ...identity, state, reason, used });
+      if (disposed) return Promise.resolve(refuse('error', 'disposed'));
+      if (signal?.aborted) return Promise.resolve(refuse('error', 'cancelled'));
+      if (pending.size >= maxInFlight) return Promise.resolve(refuse('budget-exhausted', 'in-flight'));
+      if (!Number.isSafeInteger(request.generation) || request.generation < 0 || typeof request.requestId !== 'string')
+        return Promise.resolve(refuse('error', 'invalid-identity'));
+      if (request.generation < generation) return Promise.resolve(refuse('invalidated', 'query-changed'));
+      generation = request.generation;
+      const current = ++ticket;
+      const run = async () => {
+        await Promise.resolve();
+        if (disposed) return refuse('error', 'disposed');
+        if (signal?.aborted) return refuse('error', 'cancelled');
+        if (current !== ticket || request.query !== query || request.snapshot !== snapshot) return refuse('invalidated', 'source-changed');
+        if (!validRangeCredits(request.credits)) return refuse('error', 'invalid-credits');
+        let range = request.range;
+        if (request.continuation != null) {
+          range = cursors.get(request.continuation);
+          if (!range) return refuse('invalidated', 'continuation-changed');
+        }
+        if (!validLogicalRange(range)) return refuse('error', 'invalid-range');
+        const length = range.end - range.start;
+        if (!request.continuation && range.start > 0 && !capabilities.seekIndex) return refuse('error', 'unsupported-seek');
+        if (request.credits.pages < 1 || request.credits.rows < length || request.credits.work < length || request.credits.bytes < 2
+          || length > maxRows) return refuse('budget-exhausted', 'credits');
+        const end = Math.min(range.end, rows.length), count = Math.max(0, end - range.start);
+        let bytes = 2 + Math.max(0, count - 1);
+        for (let i = range.start; i < end; i++) bytes += sizes[i];
+        used.work = count; used.pages = 1;
+        if (bytes > request.credits.bytes || bytes > maxBytes) return refuse('budget-exhausted', 'credits');
+        const items = structuredClone(rows.slice(range.start, end));
+        let continuation = null;
+        if (length && range.end < rows.length) {
+          continuation = `${snapshot}:${current}`;
+          while (cursors.size >= maxPages) cursors.delete(cursors.keys().next().value);
+          cursors.set(continuation, { start: range.end, end: range.end + length });
+        }
+        return { ...identity, state: 'ready', rows: items, keys: items.map(keyOf), continuation,
+          total: capabilities.exactTotal ? { kind: 'known', value: rows.length } : { kind: 'unknown' },
+          used: { pages: 1, rows: items.length, bytes, work: items.length } };
+      };
+      const promise = run().finally(() => pending.delete(promise)); pending.add(promise); return promise;
+    },
+    async *export(request, signal) {
+      const { pageRows = 64, pageBytes = maxBytes } = request;
+      if (!Number.isSafeInteger(pageRows) || pageRows <= 0 || pageRows > maxRows || !Number.isSafeInteger(pageBytes) || pageBytes < 2)
+        throw new RangeError('Invalid export credits');
+      const total = rows.length;
+      for (let start = 0; start < total; start += pageRows) {
+        await Promise.resolve();
+        if (disposed || signal?.aborted || request.query !== query || request.snapshot !== snapshot) throw new Error('Incomplete snapshot export');
+        const end = Math.min(total, start + pageRows);
+        let bytes = 2 + Math.max(0, end - start - 1);
+        for (let i = start; i < end; i++) bytes += sizes[i];
+        if (bytes > Math.min(maxBytes, pageBytes)) throw new RangeError('Export byte credits');
+        const items = structuredClone(rows.slice(start, end));
+        yield { state: 'ready', rows: items, keys: items.map(keyOf), query, snapshot };
+      }
+      if (disposed || signal?.aborted || request.query !== query || request.snapshot !== snapshot) throw new Error('Incomplete snapshot export');
+      yield { state: 'complete', total, query, snapshot };
+    },
+    async dispose() { disposed = true; ticket++; observers.clear(); await Promise.allSettled([...pending]);
+      cursors.clear(); rows = []; sizes = []; indices.clear(); sourceBytes = 0; },
+  };
+  return provider;
+}

package/src/retry.js

@@ -0,0 +1,80 @@
+//@ts-check
+/** Shared backoff arithmetic, abortable waits and an explicit dispatch budget. */
+
+/**
+ * Calculate a delay; strict never shortens the server's minimum wait.
+ * Compatibility policies retain the published clients' distinct jitter shapes.
+ * @param {{ policy?: 'strict' | 'ai-compat' | 'contract-compat', baseMs?: number, maxMs?: number, random?: () => number }} options
+ * @param {number} attempt - failed attempt, counted from one
+ * @param {number} [retryAfterMs]
+ * @returns {number}
+ */
+export function backoffDelay(options, attempt, retryAfterMs = undefined) {
+  const { policy = 'strict', baseMs = 500, maxMs = 8000, random = Math.random } = options;
+  const cap = Math.min(maxMs, baseMs * 2 ** (attempt - 1));
+  if (retryAfterMs !== undefined)
+    return policy === 'ai-compat' ? Math.min(maxMs, retryAfterMs) : Math.max(0, retryAfterMs);
+  if (policy === 'contract-compat') return cap + Math.floor(random() * 250);
+  return cap * (policy === 'ai-compat' ? 0.5 + 0.5 * random() : random());
+}
+
+/**
+ * Parse only the selected header dialect. HTTP accepts seconds or HTTP-date;
+ * milliseconds accepts nonnegative numbers only; none ignores the header.
+ * @param {string | null | undefined} raw
+ * @param {{ dialect?: 'http' | 'milliseconds' | 'none', now?: number }} [options]
+ * @returns {number | undefined}
+ */
+export function parseRetryAfter(raw, { dialect = 'http', now = Date.now() } = {}) {
+  if (raw == null || raw === '' || dialect === 'none') return undefined;
+  const number = Number(raw);
+  if (Number.isFinite(number) && number >= 0) return number * (dialect === 'milliseconds' ? 1 : 1000);
+  if (dialect !== 'http') return undefined;
+  const date = Date.parse(raw);
+  return Number.isNaN(date) ? undefined : Math.max(0, date - now);
+}
+
+/** @param {AbortSignal | null | undefined} signal @returns {any} */
+export function abortError(signal) {
+  if (signal?.reason !== undefined) return signal.reason;
+  const error = new Error('The operation was aborted.');
+  error.name = 'AbortError';
+  return error;
+}
+
+/** Abortable timer with listener cleanup on either settlement.
+ * @param {number} ms @param {AbortSignal} [signal] @returns {Promise<void>} */
+export function sleep(ms, signal = undefined) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) { reject(abortError(signal)); return; }
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(abortError(signal));
+    };
+    const timer = setTimeout(() => {
+      signal?.removeEventListener('abort', onAbort);
+      resolve();
+    }, ms);
+    signal?.addEventListener('abort', onAbort, { once: true });
+  });
+}
+
+/**
+ * A host-private total budget reused across SDK, workflow and job callbacks.
+ * The single-attempt transport takes a credit immediately before dispatch.
+ * @param {number} attempts
+ * @param {'safe-read' | 'provider-idempotent' | 'single-send'} [safety]
+ */
+export function createAttemptBudget(attempts, safety = 'safe-read') {
+  if (!Number.isSafeInteger(attempts) || attempts < 1
+    || !['safe-read', 'provider-idempotent', 'single-send'].includes(safety))
+    throw new TypeError('attempt budget needs positive total attempts and an explicit safety category');
+  const limit = safety === 'single-send' ? 1 : attempts;
+  let used = 0;
+  return Object.freeze({
+    safety,
+    get used() { return used; },
+    get remaining() { return limit - used; },
+    take() { if (used >= limit) return false; used++; return true; },
+  });
+}

package/src/schedule.js

@@ -0,0 +1,156 @@
+//@ts-check
+/** Bounded fair admission, with per-scope spacing and drained shutdown. */
+import { sleep as defaultSleep } from './retry.js';
+
+/**
+ * @typedef {Object} ScheduleOptions
+ * @property {number} [concurrency]
+ * @property {number} [maxQueue]
+ * @property {number} [spacingMs]
+ * @property {number} [maxScopes]
+ * @property {() => number} [now]
+ * @property {(ms: number, signal?: AbortSignal) => Promise<void>} [sleep]
+ */
+
+/**
+ * Round-robin admission among ready scopes; FIFO inside each scope. Closing
+ * stops admission immediately and waits for admitted work, including workers
+ * which ignore cancellation. A host must keep resources until close settles.
+ * @param {ScheduleOptions} [options]
+ */
+export function createScheduler(options = {}) {
+  const { concurrency = 4, maxQueue = 64, maxScopes = 256, spacingMs = 0, now = Date.now, sleep = defaultSleep } = options;
+  if (!Number.isSafeInteger(concurrency) || concurrency < 1
+    || !Number.isSafeInteger(maxQueue) || maxQueue < 1
+    || !Number.isSafeInteger(maxScopes) || maxScopes < 1
+    || !Number.isFinite(spacingMs) || spacingMs < 0
+    || typeof now !== 'function' || typeof sleep !== 'function')
+    throw new TypeError('scheduler needs finite concurrency, queue and spacing bounds and clock/sleep functions');
+  /** @type {any[]} */
+  const queue = [];
+  /** @type {Map<string, number>} */
+  const ready = new Map();
+  const turns = new Map();
+  let turn = 0;
+  let lastScope = '';
+  let active = 0;
+  let closed = false;
+  let scheduled = false;
+  /** @type {AbortController | null} */
+  let wake = null;
+  /** @type {Array<() => void>} */
+  const drained = [];
+
+  function kick() {
+    if (scheduled) return;
+    scheduled = true;
+    queueMicrotask(pump);
+  }
+
+  function pump() {
+    scheduled = false;
+    wake?.abort();
+    wake = null;
+    let at = now();
+    function prune() {
+      at = now();
+      for (let i = queue.length - 1; i >= 0; i--) {
+        const item = queue[i];
+        const reason = closed ? 'closed' : item.signal?.aborted ? 'cancelled' : item.deadline <= at ? 'deadline' : null;
+        if (reason !== null) {
+          queue.splice(i, 1);
+          item.cleanup();
+          item.reject(new Error(reason));
+        }
+      }
+    }
+    prune();
+    while (active < concurrency && queue.length) {
+      prune();
+      let index = -1;
+      let oldest = Infinity;
+      for (let i = 0; i < queue.length; i++) {
+        const item = queue[i];
+        const served = turns.get(item.scope) ?? (item.scope === lastScope ? turn : 0);
+        if ((ready.get(item.scope) ?? 0) <= at && served < oldest) { index = i; oldest = served; }
+      }
+      if (index < 0) break;
+      const [item] = queue.splice(index, 1);
+      item.cleanup();
+      lastScope = item.scope;
+      turns.set(item.scope, ++turn);
+      ready.set(item.scope, at + spacingMs);
+      active++;
+      // Invoke in this turn, so no cancellation microtask can slip between
+      // admission and the worker's own dispatch/authority check.
+      let answer;
+      try { answer = item.worker(); }
+      catch (error) { answer = Promise.reject(error); }
+      Promise.resolve(answer).then(item.resolve, item.reject).finally(() => {
+        active--;
+        kick();
+      });
+    }
+    // Spacing state for inactive scopes expires, bounding retention by the
+    // rate window and active/queued scopes rather than the lifetime of a host.
+    for (const [scope, time] of ready) if (time <= at && !queue.some((item) => item.scope === scope)) ready.delete(scope);
+    for (const scope of turns.keys()) if (!queue.some((item) => item.scope === scope)) turns.delete(scope);
+    if (queue.length) {
+      let next = Math.min(...queue.map((item) => item.deadline));
+      if (active < concurrency) next = Math.min(next, ...queue.map((item) => ready.get(item.scope) ?? at));
+      if (Number.isFinite(next)) {
+        const controller = new AbortController();
+        wake = controller;
+        Promise.resolve().then(() => sleep(Math.max(0, next - now()), controller.signal)).then(() => {
+          if (!controller.signal.aborted) kick();
+        }, (error) => {
+          if (controller.signal.aborted) return;
+          closed = true;
+          for (const item of queue.splice(0)) { item.cleanup(); item.reject(error); }
+          kick();
+        });
+      }
+    }
+    if (!active && !queue.length) for (const resolve of drained.splice(0)) resolve();
+  }
+
+  return Object.freeze({
+    /** @template T @param {() => T | Promise<T>} worker
+     * @param {{ scope?: string, signal?: AbortSignal, deadline?: number }} [context]
+     * @returns {Promise<T>} */
+    run(worker, { scope = '', signal, deadline = Infinity } = {}) {
+      if (typeof worker !== 'function' || typeof scope !== 'string' || typeof deadline !== 'number' || Number.isNaN(deadline))
+        return Promise.reject(new TypeError('scheduler needs a worker, scope and deadline'));
+      const reason = closed ? 'closed' : signal?.aborted ? 'cancelled' : deadline <= now() ? 'deadline'
+        : queue.length >= maxQueue ? 'queue-full' : null;
+      if (reason !== null) return Promise.reject(new Error(reason));
+      for (const [name, time] of ready) if (time <= now()) ready.delete(name);
+      const scopes = new Set([...ready.keys(), ...queue.map((item) => item.scope)]);
+      if (!scopes.has(scope) && scopes.size >= maxScopes) return Promise.reject(new Error('scope-limit'));
+      return new Promise((resolve, reject) => {
+        signal?.addEventListener('abort', kick, { once: true });
+        queue.push({ worker, scope, signal, deadline, resolve, reject,
+          cleanup: () => signal?.removeEventListener('abort', kick) });
+        kick();
+      });
+    },
+    /** A server observation delays all following work in its scope.
+     * @param {string} scope @param {number} delayMs */
+    observe(scope, delayMs) {
+      if (typeof scope !== 'string' || !Number.isFinite(delayMs) || delayMs < 0)
+        throw new TypeError('rate observation needs a scope and a nonnegative delay');
+      if (closed) return;
+      for (const [name, time] of ready) if (time <= now()) ready.delete(name);
+      if (!ready.has(scope) && ready.size >= maxScopes) throw new Error('scope-limit');
+      ready.set(scope, Math.max(ready.get(scope) ?? 0, now() + delayMs));
+      kick();
+    },
+    /** @returns {Promise<void>} */
+    close() {
+      closed = true;
+      kick();
+      return new Promise((resolve) => { drained.push(resolve); });
+    },
+    stats: () => ({ active, queued: queue.length, closed }),
+  });
+}