@jarenjs/linq 0.73.0 → 0.83.2

package/src/db/effects.js

@@ -0,0 +1,148 @@
+//@ts-check
+/** Durable external intent/evidence in mapped tables, fenced by the existing job engine. */
+import { canonicalizeJson } from '@jarenjs/json/canonical';
+import { mappedRecords, recordTransaction, copyRecord, refuseRecord } from './records.js';
+
+const zero = Object.freeze({ changes: 0, writes: 0, revisions: 0 });
+const terminal = (state) => state === 'confirmed' || state === 'rejected';
+/**
+ * Preparation/outbox and each settlement commit locally. Remote delivery never
+ * runs inside this adapter. Intent is permanent until evidence resolves it.
+ * @param {any} client @param {{ operations: any, maxLegs?: number, maxBytes?: number }} options
+ */
+export function createDbEffectStore(client, options) {
+  const records = mappedRecords(client, options?.operations);
+  const { maxLegs = 64, maxBytes = 262144 } = options;
+  for (const limit of [maxLegs, maxBytes]) if (!Number.isSafeInteger(limit) || limit < 1) throw new TypeError('effect limits must be finite positive integers');
+  const inside = (fn) => recordTransaction(client, fn);
+  const requireRecord = async (tx, id) => {
+    const record = await records.get(tx, id);
+    if (!record) throw refuseRecord('unknown external operation');
+    return record;
+  };
+  const guard = async (tx, record, revision, lease) => {
+    if (record.revision !== revision || lease?.jobId !== record.plan.jobId) throw refuseRecord('stale operation revision or foreign job');
+    await tx.jobs.assertLease(lease);
+  };
+  const legOf = (record, id) => {
+    const leg = record.legs.find((value) => value.id === id);
+    if (!leg) throw refuseRecord('unknown operation leg');
+    return leg;
+  };
+  const write = async (tx, record) => {
+    record.revision++;
+    await records.put(tx, record);
+    return { record, changes: 1, writes: 1, revisions: 1 };
+  };
+  return Object.freeze({
+    /** Caller authorization must establish review/compensation authority before preparation.
+     * @param {any} plan @param {(tx: any) => any} [prepare] */
+    prepare(plan, prepare) {
+      const frozen = copyRecord(plan);
+      if (['id', 'jobId', 'kind', 'actor', 'reason', 'hashVersion'].some((name) => typeof frozen[name] !== 'string' || !frozen[name])
+        || !Array.isArray(frozen.legs) || !frozen.legs.length || frozen.legs.length > maxLegs
+        || new Set(frozen.legs.map((leg) => leg.id)).size !== frozen.legs.length
+        || frozen.legs.some((leg) => typeof leg.id !== 'string' || !leg.id
+          || !['single-send', 'provider-idempotent'].includes(leg.request?.safety)
+          || !Number.isSafeInteger(leg.maxAttempts) || leg.maxAttempts < 1 || leg.maxAttempts > 100
+          || (leg.request.safety === 'single-send' && leg.maxAttempts !== 1)
+          || (leg.request.safety === 'provider-idempotent' && !leg.request.idempotencyKey))
+        || (frozen.compensationOf !== undefined && frozen.compensationAuthorized !== true)
+        || new TextEncoder().encode(canonicalizeJson(frozen)).byteLength > maxBytes)
+        throw new TypeError('effect preparation needs bounded reviewed legs, replay safety, attempt budgets and explicit compensation authority');
+      const fingerprint = canonicalizeJson(frozen);
+      return inside(async (tx) => {
+        const prior = await records.get(tx, frozen.id);
+        if (prior) {
+          if (prior.fingerprint !== fingerprint) throw refuseRecord('reviewed operation payload changed');
+          return { record: prior, ...zero };
+        }
+        if (await tx.jobs.get(frozen.jobId) !== undefined) throw refuseRecord('operation job identity already belongs to another enqueue');
+        if (prepare) await prepare(tx);
+        const record = { id: frozen.id, plan: frozen, fingerprint, revision: 1,
+          legs: frozen.legs.map((leg) => ({ id: leg.id, state: 'prepared', attempts: 0, evidence: null, intent: null })), decisions: [] };
+        await records.put(tx, record, true);
+        await tx.jobs.enqueue(frozen.kind, { operationId: frozen.id }, { id: frozen.jobId });
+        return { record, changes: 1, writes: 1, revisions: 1 };
+      });
+    },
+    /** @param {string} id */
+    get: (id) => inside((tx) => requireRecord(tx, id)),
+    /** Persist sending before dispatch. A stale worker cannot start another send.
+     * @param {string} id @param {string} legId @param {number} revision @param {any} lease */
+    begin(id, legId, revision, lease) {
+      return inside(async (tx) => {
+        const record = await requireRecord(tx, id);
+        await guard(tx, record, revision, lease);
+        const leg = legOf(record, legId), plan = record.plan.legs.find((value) => value.id === legId);
+        if (leg.state !== 'prepared' && leg.state !== 'retry-approved') return { state: leg.state, record, ...zero };
+        if (leg.attempts >= plan.maxAttempts) return { state: 'exhausted', record, ...zero };
+        leg.state = 'sending';
+        leg.attempts++;
+        leg.intent = { generation: lease.generation, attempt: leg.attempts };
+        return { state: 'sending', ...(await write(tx, record)) };
+      });
+    },
+    /** Only the active attempt may persist transport evidence.
+     * @param {string} id @param {string} legId @param {number} revision @param {any} lease @param {any} outcome */
+    settle(id, legId, revision, lease, outcome) {
+      const observation = copyRecord(outcome);
+      if (!['confirmed', 'rejected', 'unresolved'].includes(observation.state)
+        || !Object.hasOwn(observation, 'evidence') || new TextEncoder().encode(canonicalizeJson(observation)).byteLength > maxBytes)
+        throw refuseRecord('external settlement needs bounded confirmed/rejected/unresolved evidence');
+      return inside(async (tx) => {
+        const record = await requireRecord(tx, id);
+        await guard(tx, record, revision, lease);
+        const leg = legOf(record, legId);
+        if (leg.state !== 'sending' || leg.intent.generation !== lease.generation) throw refuseRecord('no sending intent for this attempt');
+        leg.state = observation.state;
+        leg.evidence = observation.evidence;
+        return write(tx, record);
+      });
+    },
+    /** Lost workers leave uncertainty, never proof of non-application.
+     * @param {string} id @param {number} revision @param {any} lease */
+    recover(id, revision, lease) {
+      return inside(async (tx) => {
+        const record = await requireRecord(tx, id);
+        await guard(tx, record, revision, lease);
+        let changed = false;
+        for (const leg of record.legs) if (leg.state === 'sending') { leg.state = 'unresolved'; changed = true; }
+        return changed ? write(tx, record) : { record, ...zero };
+      });
+    },
+    /** Explicit read-back or operator decisions; absence is evidence only under
+     * the declared authoritative non-application guarantee. Idempotent retries
+     * retain the reviewed request/key and the original durable attempt budget.
+     * @param {string} id @param {string} legId @param {number} revision @param {any} lease @param {any} decision */
+    reconcile(id, legId, revision, lease, decision) {
+      const proof = copyRecord(decision);
+      if (['id', 'actor', 'reason'].some((key) => typeof proof[key] !== 'string' || !proof[key])
+        || !['confirm', 'reject', 'retry'].includes(proof.action) || !Object.hasOwn(proof, 'evidence')) throw refuseRecord('reconciliation needs actor/reason and evidence');
+      return inside(async (tx) => {
+        const record = await requireRecord(tx, id);
+        if (lease?.jobId !== record.plan.jobId) throw refuseRecord('foreign reconciliation job');
+        await tx.jobs.assertLease(lease);
+        const entry = { ...proof, legId };
+        const prior = record.decisions.find((value) => value.id === proof.id);
+        if (prior) {
+          if (canonicalizeJson(prior) !== canonicalizeJson(entry)) throw refuseRecord('reconciliation decision collision');
+          return { record, ...zero };
+        }
+        await guard(tx, record, revision, lease);
+        const leg = legOf(record, legId), plan = record.plan.legs.find((value) => value.id === legId);
+        if (terminal(leg.state) || !['sending', 'unresolved'].includes(leg.state)) throw refuseRecord('only unresolved intent can be reconciled');
+        if (proof.action === 'retry' && (plan.request.safety !== 'provider-idempotent' && proof.guarantee !== 'authoritative-non-application'))
+          throw refuseRecord('absence is not proof of non-application');
+        // Single-send remains single-send: an authoritative negative result can
+        // be recorded as rejected, followed by a separately reviewed operation.
+        if (proof.action === 'retry' && leg.attempts >= plan.maxAttempts) throw refuseRecord('durable attempt budget exhausted');
+        if (record.decisions.length >= 128 || new TextEncoder().encode(canonicalizeJson(entry)).byteLength > maxBytes) throw refuseRecord('reconciliation evidence limit');
+        leg.state = proof.action === 'confirm' ? 'confirmed' : proof.action === 'reject' ? 'rejected' : 'retry-approved';
+        leg.evidence = proof.evidence;
+        record.decisions.push(entry);
+        return write(tx, record);
+      });
+    },
+  });
+}

package/src/db/handle.js

@@ -18,6 +18,7 @@ import { fromAsync, AsyncSequence } from '../async.js';
 import { Graph } from './include.js';
 import { requireMembership } from './membership.js';
 import { registerLive } from './live.js';
+import { createDbRangeProvider } from './range.js';
 
 /** The chain surface, read once from the class: every public operator
  * and terminal, `explain` set aside for its overload. */
@@ -59,6 +60,7 @@ export function createEntityHandle(store, name) {
   // the graph with nothing included: the root clauses, the keyset and
   // the page over the rows alone
   members.graph = () => new Graph(set, name);
+  members.range = (spec, options) => createDbRangeProvider(store, name, spec, options);
   members.link = (own, member, target) => {
     requireMembership(set.relations, name, member, 'link');
     set.link(own, member, target);

package/src/db/index.js

@@ -22,4 +22,10 @@
 
 export { open, defaultValidator } from './open.js';
 export { createDbLedger } from './ledger.js';
+export { createDbIngestionStore } from './ingest.js';
+export { createDbRangeProvider } from './range.js';
+export { createLexicalRangeProvider } from './search.js';
 export { defineReplication } from './replication.js';
+export { createDbReceipts } from './receipts.js';
+export { createDbEffectStore } from './effects.js';
+export { createDbRunStore } from './runs.js';

package/src/db/ingest.js

@@ -0,0 +1,153 @@
+//@ts-check
+/** Atomic page/checkpoint staging and complete-generation publication. */
+import { canonicalizeJson } from '@jarenjs/json/canonical';
+import { isThenable } from '@jarenjs/core/function';
+
+const copy = (value) => JSON.parse(canonicalizeJson(value));
+const key = (...parts) => canonicalizeJson(parts);
+
+/**
+ * Adapt application-declared collections under the client's transaction owner.
+ * Reconcile is a synchronous pure policy; network I/O belongs outside this
+ * adapter. No table, schema, credentials or provider field policy is inferred.
+ * @param {any} client
+ * @param {{ staging: string, checkpoints: string, publications: string, facts?: string,
+ * reconcile?: (existing: any, incoming: any, evidence: any) => any }} options
+ */
+export function createDbIngestionStore(client, options) {
+  if (!client || typeof client.transaction !== 'function' || !client.collections || !options)
+    throw new TypeError('ingestion store needs a client and declared collection names');
+  const names = ['staging', 'checkpoints', 'publications', ...(options.facts ? ['facts'] : [])];
+  if (new Set(names.map((name) => options[name])).size !== names.length
+    || names.some((name) => typeof options[name] !== 'string' || !Object.hasOwn(client.collections, options[name])))
+    throw new TypeError('ingestion collections must be distinct declared collections');
+  if (options.reconcile !== undefined && typeof options.reconcile !== 'function') throw new TypeError('reconcile must be a pure function');
+  const reconcile = options.reconcile ?? ((_existing, incoming) => incoming);
+  const inside = (fn) => typeof client.close === 'function' ? client.transaction(fn, { mode: 'immediate' }) : client.transaction(fn);
+  const fingerprint = (plan) => key(plan.source, plan.version, plan.partitions, plan.input, plan.policyRevision, plan.consistency);
+  const checkpointId = (plan) => key(plan.source, plan.generation);
+  const publications = (tx) => tx.collections[options.publications];
+  const checkpoints = (tx) => tx.collections[options.checkpoints];
+  const zero = { changes: 0, writes: 0, revisions: 0 };
+  const matching = async (tx, plan) => {
+    const checkpoint = await checkpoints(tx).get(checkpointId(plan));
+    if (!checkpoint || checkpoint.fingerprint !== fingerprint(plan)) throw new TypeError('ingestion checkpoint does not match the plan');
+    return checkpoint;
+  };
+  return Object.freeze({
+    /** @param {any} plan */
+    begin(plan) {
+      return inside(async (tx) => {
+        const published = await publications(tx).get(plan.source);
+        if (published?.fingerprint === fingerprint(plan)) return { state: 'unchanged', ...zero, manifest: published };
+        const id = checkpointId(plan);
+        const existing = await checkpoints(tx).get(id);
+        if (existing) {
+          if (existing.fingerprint !== fingerprint(plan)) return { state: 'refused', reason: 'generation-mismatch' };
+          if (existing.status !== 'staging') return { state: 'refused', reason: existing.status };
+          return { state: 'staging', checkpoint: existing, ...zero };
+        }
+        const checkpoint = { id, fingerprint: fingerprint(plan), source: plan.source, generation: plan.generation,
+          version: plan.version, expectedPublication: published?.generation ?? null, status: 'staging',
+          partitions: plan.partitions.map((partition) => ({ id: partition, cursor: null, complete: false, pages: [] })),
+          pages: 0, rows: 0, bytes: 0 };
+        await checkpoints(tx).insert(checkpoint);
+        return { state: 'staging', checkpoint, ...zero };
+      });
+    },
+    /** Page bytes and its continuation/completion evidence commit together.
+     * @param {any} plan @param {string} partition @param {any} page */
+    stage(plan, partition, page) {
+      return inside(async (tx) => {
+        const checkpoint = await matching(tx, plan);
+        if (checkpoint.status !== 'staging') return { state: 'refused', reason: checkpoint.status };
+        const part = checkpoint.partitions.find((p) => p.id === partition);
+        if (!part) return { state: 'refused', reason: 'unknown-partition' };
+        const id = key(plan.source, plan.generation, partition, page.cursor);
+        const staging = tx.collections[options.staging];
+        const existing = await staging.get(id);
+        const record = copy({ id, partition, generation: plan.generation, source: plan.source, page });
+        if (existing) {
+          if (canonicalizeJson(existing) !== canonicalizeJson(record)) return { state: 'refused', reason: 'page-conflict' };
+          return { state: 'staged', checkpoint, ...zero };
+        }
+        if (part.complete || canonicalizeJson(part.cursor) !== canonicalizeJson(page.cursor)) return { state: 'refused', reason: 'stale-cursor' };
+        await staging.insert(record);
+        part.pages.push(id);
+        part.cursor = page.continuation;
+        part.complete = page.complete === true && page.reason === null && page.version === plan.version;
+        checkpoint.pages++;
+        checkpoint.rows += page.rows.length;
+        checkpoint.bytes += page.bytes;
+        if (page.reason !== null) checkpoint.status = 'incomplete';
+        if (page.version !== plan.version) checkpoint.status = 'source-changed';
+        await checkpoints(tx).put(checkpoint, checkpoint.id);
+        return { state: 'staged', checkpoint, ...zero };
+      });
+    },
+    /** Preserve partial observations but fence the generation from publication.
+     * @param {any} plan @param {string} reason */
+    invalidate(plan, reason) {
+      return inside(async (tx) => {
+        const checkpoint = await matching(tx, plan);
+        if (checkpoint.status === 'published' || checkpoint.status === reason) return;
+        await checkpoints(tx).put({ ...checkpoint, status: reason }, checkpoint.id);
+      });
+    },
+    /** Completion evidence, effective facts and the pointer share one commit.
+     * @param {any} plan @param {any} evidence @param {{ signal?: AbortSignal }} [context] */
+    publish(plan, evidence, context = {}) {
+      return inside(async (tx) => {
+        if (context.signal?.aborted) return { state: 'refused', reason: 'cancelled' };
+        const checkpoint = await matching(tx, plan);
+        const published = await publications(tx).get(plan.source);
+        if (published?.fingerprint === fingerprint(plan)) return { state: 'unchanged', ...zero, manifest: published };
+        if (checkpoint.status !== 'staging' || checkpoint.partitions.some((part) => !part.complete)) return { state: 'refused', reason: 'incomplete' };
+        if ((published?.generation ?? null) !== checkpoint.expectedPublication) return { state: 'refused', reason: 'publication-conflict' };
+        if (!evidence || evidence.version !== plan.version || evidence.consistency !== plan.consistency)
+          return { state: 'refused', reason: 'source-changed' };
+        let changes = 0;
+        const seen = new Set();
+        for (const part of checkpoint.partitions) for (const id of part.pages) {
+          const record = await tx.collections[options.staging].get(id);
+          if (!record || record.page.version !== plan.version || record.page.reason !== null) throw new TypeError('publication lacks page evidence');
+          for (let i = 0; i < record.page.rows.length; i++) {
+            const providerId = record.page.ids[i];
+            const factId = key(plan.source, part.id, providerId);
+            if (seen.has(factId)) throw new TypeError('publication has duplicate source identities');
+            seen.add(factId);
+            if (!options.facts) continue;
+            const facts = tx.collections[options.facts];
+            const prior = await facts.get(factId);
+            const value = reconcile(prior?.value ?? null, copy(record.page.rows[i]), { source: plan.source, partition: part.id, providerId, version: plan.version });
+            if (isThenable(value)) throw new TypeError('reconcile must be synchronous; network I/O cannot hold a page transaction');
+            if (context.signal?.aborted) throw new TypeError('publication cancelled');
+            if (prior && canonicalizeJson(prior.value) === canonicalizeJson(value)) continue;
+            await facts.put({ id: factId, source: plan.source, partition: part.id, providerId,
+              value: copy(value), revision: (prior?.revision ?? 0) + 1 }, factId);
+            changes++;
+          }
+        }
+        const manifest = { id: plan.source, source: plan.source, generation: plan.generation, version: plan.version,
+          fingerprint: fingerprint(plan), partitions: copy(checkpoint.partitions), evidence: copy(evidence),
+          pages: checkpoint.pages, rows: checkpoint.rows, bytes: checkpoint.bytes };
+        if (context.signal?.aborted) throw new TypeError('publication cancelled');
+        await publications(tx).put(manifest, plan.source);
+        await checkpoints(tx).put({ ...checkpoint, status: 'published' }, checkpoint.id);
+        if (context.signal?.aborted) throw new TypeError('publication cancelled');
+        return { state: 'published', changes, writes: changes, revisions: changes, manifest };
+      });
+    },
+    /** @param {string} source */
+    current: (source) => client.collections[options.publications].get(source),
+    /** @param {any} plan */
+    inspect(plan) {
+      return inside(async (tx) => {
+        const checkpoint = await matching(tx, plan);
+        const observations = [];
+        for (const part of checkpoint.partitions) for (const id of part.pages) observations.push(await tx.collections[options.staging].get(id));
+        return { checkpoint, observations };
+      });
+    },
+  });
+}

package/src/db/open.js

@@ -91,6 +91,9 @@ export async function open(model, options) {
     const inner = {
       store: tx,
       capabilities: tx.capabilities,
+      sql: tx.sql,
+      jobs: tx.jobs,
+      sync: tx.sync,
       ...handlesOf(tx),
       transaction: (fn) => tx.transaction((nested) => fn(transactionClient(nested))),
       // the named-savepoint group (MODEL-FORMAT §5.2), forwarded as it

package/src/db/range.js

@@ -0,0 +1,261 @@
+//@ts-check
+/** Structural ranges over the store's cursors, keyset pages and committed capture. */
+import { canonicalizeJson } from '@jarenjs/json/canonical';
+import { resolveRuntime } from '@jarenjs/core/runtime';
+import { deepFreeze } from '@jarenjs/core/object';
+
+/** Open a bounded source. Resident mode obtains a complete, bounded source
+ * snapshot before offering index seeks or an exact total. Sequential mode
+ * admits only first pages and continuations through the store's keyset pager.
+ * @param {any} store @param {string} entity @param {any} [spec]
+ * @param {any} [options] @returns {Promise<any>} */
+export async function createDbRangeProvider(store, entity, spec = {}, options = {}) {
+  spec = structuredClone(spec);
+  const keys = options.keys?.slice();
+  if (!Array.isArray(keys) || !keys.length || keys.some((key) => typeof key !== 'string') || new Set(keys).size !== keys.length)
+    throw new TypeError('range provider needs distinct logical key members');
+  if (spec.take !== undefined || spec.skip !== undefined || spec.after !== undefined || spec.include !== undefined)
+    throw new TypeError('range provider owns the window and serves root rows');
+  const bounds = { rows: options.maxRows ?? 256, bytes: options.maxBytes ?? 262144,
+    pages: options.maxPages ?? 4, inFlight: options.maxInFlight ?? 2, subscriptions: options.maxSubscriptions ?? 8 };
+  if (!Object.values(bounds).every((n) => Number.isSafeInteger(n) && n > 0 && n < Number.MAX_SAFE_INTEGER))
+    throw new TypeError('range provider bounds must be finite positive safe integers');
+  const resident = options.resident === true;
+  const profile = options.profile === undefined ? undefined : structuredClone(options.profile);
+  const host = resolveRuntime(options.runtime);
+  const source = options.source ?? host.uuid();
+  const query = options.query ?? canonicalizeJson({ source, entity, spec, keys,
+    schema: options.schemaVersion ?? null, profile: profile ?? null });
+  if (typeof source !== 'string' || !source || typeof query !== 'string' || !query)
+    throw new TypeError('range source and query identities must be nonempty strings');
+  const encoder = new TextEncoder();
+  const bytesOf = (value) => encoder.encode(JSON.stringify(value)).byteLength;
+  const keyOf = (row) => {
+    const values = keys.map((key) => row[key]);
+    if (values.some((value) => typeof value !== 'string' && !(typeof value === 'number' && Number.isFinite(value))))
+      throw new TypeError('a range row must carry every stable key member');
+    return keys.length === 1 ? String(values[0]) : canonicalizeJson(values);
+  };
+  let revision = 1;
+  let dataVersion;
+  let disposed = false;
+  let generation = -1;
+  let ticket = 0;
+  let rows = null;
+  let residentBytes = 0;
+  const continuations = new Map();
+  const pending = new Map();
+  const exports = new Set();
+  const observers = new Set();
+  const stats = { sourceReads: 0, sourceRows: 0, sourceBytes: 0 };
+  const snapshot = () => `${source}-v${revision}`;
+  const invalidate = (reason) => {
+    revision++;
+    rows = null; residentBytes = 0; continuations.clear();
+    const event = Object.freeze({ type: 'reset', reason, query, snapshot: snapshot(), revision,
+      capture: 'committed-store-records; external changes detected on request' });
+    for (const observer of observers) {
+      try { observer(event); }
+      catch { /* A subscriber cannot suppress a sibling's source reset. */ }
+    }
+  };
+  const unsubscribe = store.observe((record) => {
+    if (!disposed && record.collections.includes(entity)) invalidate('source-changed');
+  });
+  const checkVersion = async (over) => {
+    const current = await over.dataVersion();
+    if (dataVersion !== undefined && current !== dataVersion) invalidate('external-source-changed');
+    dataVersion = current;
+  };
+  const readPage = async (over, pageOptions, used) => {
+    stats.sourceReads++;
+    const record = (work) => {
+      if (work === undefined) return;
+      stats.sourceRows += work.rows; stats.sourceBytes += work.bytes;
+      if (used !== undefined) used.work += work.rows;
+    };
+    try {
+      const page = await over.entity(entity).page(spec, {
+        ...pageOptions, lookahead: false, profile,
+      });
+      record(page.work);
+      return page;
+    }
+    catch (error) { record(error?.work); throw error; }
+  };
+  const loadResident = async (over, signal, used) => {
+    const page = await readPage(over, { limit: bounds.rows + 1, maxBytes: bounds.bytes, signal }, used);
+    const loaded = page.items;
+    const bytes = bytesOf(loaded);
+    if (page.hasMore !== false || loaded.length > bounds.rows || bytes > bounds.bytes) {
+      throw new RangeError('range source exceeds resident credits');
+    }
+    const identities = loaded.map(keyOf);
+    if (new Set(identities).size !== identities.length) throw new TypeError('range keys must be unique');
+    loaded.forEach(deepFreeze);
+    rows = loaded; residentBytes = bytes;
+  };
+  try {
+    await store.transaction(async (tx) => {
+      await checkVersion(tx);
+      if (resident) await loadResident(tx);
+    });
+  }
+  catch (error) { unsubscribe(); throw error; }
+
+  const capabilities = Object.freeze({ seekIndex: resident && options.seekIndex !== false, seekKey: false,
+    continuation: true, live: true, exactTotal: resident && options.exactTotal !== false, completeExport: resident });
+  const provider = {
+    capabilities,
+    get query() { return query; },
+    get snapshot() { return snapshot(); },
+    stats: () => ({ ...stats, pending: pending.size, pages: continuations.size,
+      rows: rows?.length ?? 0, bytes: residentBytes, subscriptions: observers.size, exports: exports.size, disposed }),
+    subscribe(observer) {
+      if (disposed) throw new Error('range provider is disposed');
+      if (typeof observer !== 'function') throw new TypeError('range subscriber must be callable');
+      if (observers.size >= bounds.subscriptions) throw new RangeError('range subscription bound reached');
+      observers.add(observer);
+      return () => observers.delete(observer);
+    },
+    request(request, signal) {
+      request = structuredClone(request);
+      const identity = Object.fromEntries(['generation', 'requestId', 'query', 'snapshot'].map((key) => [key, request?.[key]]));
+      const used = { pages: 0, rows: 0, bytes: 0, work: 0 };
+      const refuse = (state, reason) => ({ ...identity, state, reason, used: { ...used } });
+      if (disposed) return Promise.resolve(refuse('error', 'disposed'));
+      if (signal?.aborted) return Promise.resolve(refuse('error', 'cancelled'));
+      if (!Number.isSafeInteger(request?.generation) || request.generation < 0 || typeof request.requestId !== 'string')
+        return Promise.resolve(refuse('error', 'invalid-identity'));
+      if (request.query !== query || request.generation < generation) return Promise.resolve(refuse('invalidated', 'query-changed'));
+      if (pending.size >= bounds.inFlight) return Promise.resolve(refuse('budget-exhausted', 'in-flight'));
+      generation = request.generation;
+      const currentTicket = ++ticket;
+      const controller = new AbortController();
+      const abort = () => controller.abort(signal.reason);
+      signal?.addEventListener('abort', abort, { once: true });
+      const run = async () => {
+        await Promise.resolve();
+        if (disposed) return refuse('error', 'disposed');
+        if (controller.signal.aborted) return refuse('error', 'cancelled');
+        const credits = request.credits;
+        if (!['pages', 'rows', 'bytes', 'work'].every((key) => Number.isSafeInteger(credits?.[key]) && credits[key] >= 0))
+          return refuse('error', 'invalid-credits');
+        let start;
+        let limit;
+        let after;
+        if (request.continuation != null) {
+          const cursor = continuations.get(request.continuation);
+          if (!cursor || cursor.snapshot !== request.snapshot || cursor.query !== request.query)
+            return refuse('invalidated', 'continuation-changed');
+          start = cursor.end; limit = cursor.limit; after = cursor.after;
+        }
+        else {
+          const range = request.range;
+          if (!range || !Number.isSafeInteger(range.start) || !Number.isSafeInteger(range.end) || range.start < 0 || range.end < range.start)
+            return refuse('error', 'invalid-range');
+          start = range.start; limit = range.end - range.start;
+          if (start > 0 && !capabilities.seekIndex) return refuse('error', 'unsupported-seek');
+        }
+        if (credits.pages < 1 || credits.rows < limit || credits.work < limit || credits.bytes < 2
+          || limit > bounds.rows || credits.bytes > Number.MAX_SAFE_INTEGER)
+          return refuse('budget-exhausted', 'credits');
+        try {
+          let page;
+          const wantedRevision = revision;
+          const result = await store.transaction(async (tx) => {
+            await checkVersion(tx);
+            if (request.snapshot !== snapshot()) return null;
+            if (resident && rows === null) {
+              // A reset rebuilds the whole bounded source. Admission reserves
+              // its maximum root pulls separately from the requested slice.
+              if (credits.work - limit < bounds.rows + 1) throw new RangeError('resident refresh exceeds work credits');
+              await loadResident(tx, controller.signal, used);
+            }
+            if (resident) {
+              const result = rows.slice(start, start + limit);
+              used.work += result.length;
+              return result;
+            }
+            if (limit === 0) return [];
+            // The store counts row payloads; a range also owes array brackets
+            // and commas. Reserve their maximum before any row is pulled.
+            const maxBytes = Math.min(credits.bytes, bounds.bytes) - limit - 1;
+            if (maxBytes < 1) throw new RangeError('range array exceeds byte credits');
+            page = await readPage(tx, { limit, after, maxBytes, signal: controller.signal }, used);
+            return page.items;
+          }, { signal: controller.signal });
+          if (disposed) return refuse('error', 'disposed');
+          if (controller.signal.aborted) return refuse('error', 'cancelled');
+          if (currentTicket !== ticket || request.generation !== generation) return refuse('invalidated', 'superseded');
+          if (result === null || wantedRevision !== revision || request.snapshot !== snapshot()) return refuse('invalidated', 'snapshot-changed');
+          used.pages = 1;
+          const bytes = bytesOf(result);
+          if (bytes > Math.min(credits.bytes, bounds.bytes)) return refuse('budget-exhausted', 'bytes');
+          result.forEach(deepFreeze);
+          const resultKeys = result.map(keyOf);
+          if (new Set(resultKeys).size !== resultKeys.length) return refuse('error', 'duplicate-key');
+          used.rows = result.length; used.bytes = bytes;
+          let continuation = null;
+          const more = resident ? start + result.length < rows.length : page?.hasMore !== false && result.length > 0;
+          if (more) {
+            continuation = host.uuid();
+            if (continuations.size >= bounds.pages) continuations.delete(continuations.keys().next().value);
+            continuations.set(continuation, { query, snapshot: snapshot(), end: start + result.length, limit, after: page?.continuation });
+          }
+          return { ...identity, state: 'ready', rows: result, keys: resultKeys, used,
+            continuation, total: capabilities.exactTotal ? { kind: 'known', value: rows.length } : { kind: 'unknown' } };
+        }
+        catch (error) {
+          return refuse(disposed ? 'error' : controller.signal.aborted ? 'error'
+            : error instanceof RangeError || ['JD2007', 'JD2073', 'JD2074', 'JD2076'].includes(error?.code) ? 'budget-exhausted' : 'error',
+          disposed ? 'disposed' : controller.signal.aborted ? 'cancelled' : error?.code ?? error.message);
+        }
+      };
+      const promise = run().finally(() => { pending.delete(controller); signal?.removeEventListener('abort', abort); });
+      pending.set(controller, promise);
+      return promise;
+    },
+    export(request, signal) {
+      if (disposed) throw new Error('disposed');
+      if (exports.size >= bounds.inFlight) throw new RangeError('Export credits');
+      const pageRows = request.pageRows ?? 64, pageBytes = request.pageBytes ?? bounds.bytes;
+      if (!resident) throw new Error('unsupported-export');
+      if (!Number.isSafeInteger(pageRows) || pageRows <= 0 || pageRows > bounds.rows
+        || !Number.isSafeInteger(pageBytes) || pageBytes < 2) throw new RangeError('Invalid export credits');
+      const iterator = (async function* () {
+        try {
+          // Verify external changes before certifying the bounded resident source epoch.
+          await store.transaction(checkVersion);
+          if (!rows) throw new Error('Snapshot must be reloaded before export');
+          const total = rows.length;
+          for (let start = 0; start < total; start += pageRows) {
+            if (disposed || signal?.aborted || request.query !== query || request.snapshot !== snapshot() || !rows)
+              throw new Error('Incomplete snapshot export');
+            const items = rows.slice(start, start + pageRows);
+            if (bytesOf(items) > Math.min(pageBytes, bounds.bytes)) throw new RangeError('Export byte credits');
+            yield { state: 'ready', rows: items, keys: items.map(keyOf), query, snapshot: request.snapshot };
+          }
+          await store.transaction(checkVersion);
+          if (disposed || signal?.aborted || request.query !== query || request.snapshot !== snapshot() || !rows)
+            throw new Error('Incomplete snapshot export');
+          yield { state: 'complete', total, query, snapshot: request.snapshot };
+        }
+        finally { exports.delete(iterator); }
+      })();
+      exports.add(iterator);
+      return iterator;
+    },
+    async dispose() {
+      if (!disposed) {
+        disposed = true; unsubscribe(); observers.clear();
+        for (const controller of pending.keys()) controller.abort();
+      }
+      await Promise.allSettled([...pending.values()]);
+      await Promise.allSettled([...exports].map((iterator) => iterator.return()));
+      exports.clear();
+      continuations.clear(); rows = null; residentBytes = 0;
+    },
+  };
+  return Object.freeze(provider);
+}