@jarenjs/linq 0.73.0 → 0.83.2

package/src/db/receipts.js

@@ -0,0 +1,151 @@
+//@ts-check
+/** Business receipts and independent fenced leases over application-owned tables. */
+import { canonicalizeJson } from '@jarenjs/json/canonical';
+import { resolveRuntime } from '@jarenjs/core/runtime';
+import { mappedRecords, recordTransaction, copyRecord, refuseRecord } from './records.js';
+
+const fields = ['tenant', 'environment', 'aggregate', 'op', 'key', 'hashVersion', 'hash'];
+/** @param {any} identity */
+function identityOf(identity) {
+  if (!identity || fields.some((name) => typeof identity[name] !== 'string' || !identity[name] || identity[name].length > 4096))
+    throw new TypeError('command identity needs bounded tenant/environment/aggregate/op/key/hashVersion/hash strings');
+  return Object.fromEntries(fields.map((name) => [name, identity[name]]));
+}
+const idOf = (identity) => canonicalizeJson(fields.slice(0, 5).map((name) => identity[name]));
+const matches = (record, identity) => canonicalizeJson(record.identity) === canonicalizeJson(identity);
+const zero = Object.freeze({ changes: 0, writes: 0, revisions: 0 });
+
+/**
+ * No TTL applies to business receipts. The optional lease table is recoverable
+ * execution authority only. The callback receives the exact transaction client
+ * so domain changes and outbox enqueues commit with the validated outcome.
+ * @param {any} client
+ * @param {{ receipts: any, leases?: any, runtime?: any }} options
+ */
+export function createDbReceipts(client, options) {
+  const receipts = mappedRecords(client, options?.receipts);
+  const leases = options.leases === undefined ? null : mappedRecords(client, options.leases);
+  if (leases?.name === receipts.name) throw new TypeError('receipts and leases must use distinct collections');
+  const runtime = resolveRuntime(options.runtime);
+  const inside = (fn) => recordTransaction(client, fn);
+  const replay = (record, identity) => {
+    if (!matches(record, identity)) return { state: 'refused', reason: 'identity-mismatch', ...zero };
+    return { state: 'replay', historic: true, receipt: copyRecord(record), ...zero };
+  };
+  const checkLease = async (tx, id, lease) => {
+    const current = leases && await leases.get(tx, id);
+    if (!current || current.token !== lease?.token || current.expiresAt <= runtime.now()) throw refuseRecord('stale command lease');
+    return current;
+  };
+  return Object.freeze({
+    /** Authorize before calling: this low-level repository is a trusted host capability.
+     * @param {any} identity */
+    lookup(identity) {
+      const normalized = identityOf(identity);
+      return inside(async (tx) => {
+        const record = await receipts.get(tx, idOf(normalized));
+        return record ? replay(record, normalized) : { state: 'absent', ...zero };
+      });
+    },
+    /** @param {any} identity @param {(tx: any) => Promise<{ outcome: any, references?: any[] }>} work
+     * @param {{ lease?: any }} [context] */
+    execute(identity, work, context = {}) {
+      const normalized = identityOf(identity), id = idOf(normalized);
+      return inside(async (tx) => {
+        const prior = await receipts.get(tx, id);
+        if (prior) return replay(prior, normalized);
+        if (context.lease !== undefined) {
+          const claimed = await checkLease(tx, id, context.lease);
+          if (!matches(claimed, normalized)) throw refuseRecord('command lease identity mismatch');
+        }
+        else if (leases && await leases.get(tx, id)) return { state: 'refused', reason: 'lease-required', ...zero };
+        const result = copyRecord(await work(tx));
+        const record = { id, identity: normalized, outcome: result.outcome, references: result.references ?? [],
+          createdAt: runtime.now(), revision: 1, compacted: false };
+        await receipts.put(tx, record, true);
+        if (context.lease !== undefined) {
+          await checkLease(tx, id, context.lease);
+          await leases.delete(tx, id);
+        }
+        return { state: 'committed', historic: false, receipt: record, changes: 1, writes: 1, revisions: 1 };
+      });
+    },
+    /** Claim/reclaim only absent receipts; lease expiry never overrides history.
+     * @param {any} identity @param {{ leaseMs: number }} options */
+    claim(identity, { leaseMs }) {
+      if (!leases || !Number.isSafeInteger(leaseMs) || leaseMs < 1) throw new TypeError('claim needs a lease collection and positive leaseMs');
+      const normalized = identityOf(identity), id = idOf(normalized);
+      return inside(async (tx) => {
+        const receipt = await receipts.get(tx, id);
+        if (receipt) return replay(receipt, normalized);
+        const prior = await leases.get(tx, id);
+        if (prior && !matches(prior, normalized)) return { state: 'refused', reason: 'identity-mismatch', ...zero };
+        if (prior && prior.expiresAt > runtime.now()) return { state: 'in-progress', ...zero };
+        const lease = { id, identity: normalized, token: runtime.uuid(), generation: (prior?.generation ?? 0) + 1,
+          expiresAt: runtime.now() + leaseMs };
+        await leases.put(tx, lease);
+        return { state: 'claimed', lease };
+      });
+    },
+    /** Release one failed attempt; a receipt is never removed.
+     * @param {any} identity @param {any} lease */
+    release(identity, lease) {
+      const id = idOf(identityOf(identity));
+      return inside(async (tx) => { await checkLease(tx, id, lease); await leases.delete(tx, id); return { changes: 1, writes: 1, revisions: 0 }; });
+    },
+    /** Sweep a bounded, caller-selected batch of lease identities, never receipts.
+     * @param {any[]} identities */
+    sweep(identities) {
+      if (!leases || !Array.isArray(identities) || identities.length > 1000) throw new TypeError('sweep needs leases and at most 1000 identities');
+      const ids = [...new Set(identities.map((identity) => idOf(identityOf(identity))))];
+      return inside(async (tx) => {
+        let changes = 0;
+        for (const id of ids) {
+          const lease = await leases.get(tx, id);
+          if (lease && lease.expiresAt <= runtime.now()) { await leases.delete(tx, id); changes++; }
+        }
+        return { changes, writes: changes, revisions: 0 };
+      });
+    },
+    /** Import explicit immutable outcomes; a preexisting receipt always wins.
+     * No expiring claim is interpreted as a business outcome.
+     * @param {any[]} records */
+    migrate(records) {
+      if (!Array.isArray(records) || records.length > 1000) throw new TypeError('migration is bounded to 1000 explicit receipts');
+      const batch = records.map((record) => {
+        const identity = identityOf(record.identity);
+        if (!Object.hasOwn(record, 'outcome') || !Array.isArray(record.references)) throw refuseRecord('migration needs an outcome and stable references');
+        return copyRecord({ ...record, id: idOf(identity), identity, revision: 1, compacted: false });
+      });
+      return inside(async (tx) => {
+        let changes = 0;
+        for (const record of batch) {
+          const prior = await receipts.get(tx, record.id);
+          if (prior) {
+            if (!matches(prior, record.identity) || canonicalizeJson(prior.outcome) !== canonicalizeJson(record.outcome)
+              || canonicalizeJson(prior.references) !== canonicalizeJson(record.references)) throw refuseRecord('receipt migration collision');
+            continue;
+          }
+          await receipts.put(tx, record, true); changes++;
+        }
+        return { changes, writes: changes, revisions: changes };
+      });
+    },
+    /** Compaction may remove only auxiliary data; identity/outcome/references stay.
+     * @param {any} identity @param {{ retainReplay: true, retainReferences: true, actor: string, reason: string }} policy */
+    compact(identity, policy) {
+      if (policy?.retainReplay !== true || policy?.retainReferences !== true || !policy.actor || !policy.reason)
+        throw refuseRecord('erasure refused: explicit retention and actor/reason are required');
+      const normalized = identityOf(identity), id = idOf(normalized);
+      return inside(async (tx) => {
+        const record = await receipts.get(tx, id);
+        if (!record || !matches(record, normalized)) throw refuseRecord('receipt compaction identity mismatch');
+        if (record.compacted) return zero;
+        const { auxiliary: _discarded, ...retained } = record;
+        await receipts.put(tx, { ...retained, compacted: true, revision: record.revision + 1,
+          retention: { actor: policy.actor, reason: policy.reason } });
+        return { changes: 1, writes: 1, revisions: 1 };
+      });
+    },
+  });
+}

package/src/db/records.js

@@ -0,0 +1,61 @@
+//@ts-check
+/** Structural record mapping shared by durable adapters; the store owns transactions. */
+import { canonicalizeJson } from '@jarenjs/json/canonical';
+import { isThenable } from '@jarenjs/core/function';
+import { LinqRuntimeError } from '../errors.js';
+
+/** @param {any} value */
+export const copyRecord = (value) => JSON.parse(canonicalizeJson(value));
+/** @param {string} reason */
+export const refuseRecord = (reason) => new LinqRuntimeError('JL2009', reason);
+/** @param {any} client @param {Function} fn */
+export const recordTransaction = (client, fn) => typeof client.close === 'function'
+  ? client.transaction(fn, { mode: 'immediate' }) : client.transaction(fn);
+
+/** Map canonical records to declared application fields without inferring a schema.
+ * @param {any} client @param {string | { collection?: string, entity?: string, key?: Function, read: Function, write: Function }} mapping */
+export function mappedRecords(client, mapping) {
+  const spec = typeof mapping === 'string' ? { collection: mapping, read: copyRecord, write: copyRecord } : mapping;
+  const entity = spec?.entity !== undefined;
+  const owner = entity ? 'entities' : 'collections';
+  const name = entity ? spec.entity : spec?.collection;
+  if (!client || typeof client.transaction !== 'function' || !spec || !Object.hasOwn(client[owner] ?? {}, name)
+    || (entity && spec.collection !== undefined) || (spec.key !== undefined && typeof spec.key !== 'function')
+    || typeof spec.read !== 'function' || typeof spec.write !== 'function')
+    throw new TypeError('record mapping needs a declared collection or entity and synchronous read/write functions');
+  const convert = (fn, value) => {
+    const result = fn(copyRecord(value));
+    if (isThenable(result)) throw new TypeError('record mappings must be synchronous');
+    return copyRecord(result);
+  };
+  const keyOf = (id) => spec.key === undefined ? id : convert(spec.key, id);
+  return Object.freeze({
+    name: `${owner}/${name}`,
+    async get(tx, id) {
+      const value = await tx[owner][name].get(keyOf(id));
+      if (value === undefined) return undefined;
+      const record = convert(spec.read, value);
+      if (record.id !== id) throw refuseRecord('record mapping changed identity');
+      return record;
+    },
+    async put(tx, record, insert = false) {
+      const stored = convert(spec.write, record);
+      if (canonicalizeJson(convert(spec.read, stored)) !== canonicalizeJson(record))
+        throw refuseRecord('record mapping is not lossless');
+      const target = tx[owner][name], key = keyOf(record.id);
+      if (entity) {
+        if (insert || await target.get(key) === undefined) await target.create(stored);
+        else await target.update(key, stored);
+        const persisted = await target.get(key);
+        if (persisted === undefined || canonicalizeJson(convert(spec.read, persisted)) !== canonicalizeJson(record))
+          throw refuseRecord('record mapping changed the physical key or stored value');
+      }
+      else {
+        const written = await (insert ? target.insert(stored) : target.put(stored, key));
+        if (canonicalizeJson(written) !== canonicalizeJson(key)) throw refuseRecord('record mapping changed the physical key');
+      }
+      return key;
+    },
+    delete: (tx, id) => tx[owner][name].delete(keyOf(id)),
+  });
+}

package/src/db/runs.js

@@ -0,0 +1,164 @@
+//@ts-check
+/** Existing domain run identities and bounded event pages over mapped application tables. */
+import { canonicalizeJson } from '@jarenjs/json/canonical';
+import { mappedRecords, recordTransaction, copyRecord, refuseRecord } from './records.js';
+
+const zero = Object.freeze({ changes: 0, writes: 0, revisions: 0 });
+/**
+ * Checkpoints remain the existing workflow's format. Status mapping and public
+ * summaries are application policy; events never contain the checkpoint input,
+ * provider credentials, live resources or raw exceptions.
+ * @param {any} client
+ * @param {{ runs: any, events: any, statuses?: Record<string, string>,
+ * summary?: (snapshot: any) => any, canReset?: (tx: any, record: any) => any,
+ * maxPage?: number, maxBytes?: number }} options
+ */
+export function createDbRunStore(client, options) {
+  const runs = mappedRecords(client, options?.runs), events = mappedRecords(client, options?.events);
+  if (runs.name === events.name) throw new TypeError('runs and events must be distinct collections');
+  const { maxPage = 128, maxBytes = 262144 } = options;
+  for (const limit of [maxPage, maxBytes]) if (!Number.isSafeInteger(limit) || limit < 1) throw new TypeError('run observation limits must be positive finite integers');
+  const statuses = { running: 'running', waiting: 'waiting', done: 'done', failed: 'failed', cancelled: 'cancelled', ...options.statuses };
+  if (Object.values(statuses).some((value) => typeof value !== 'string' || !value)) throw new TypeError('status mapping values must be nonempty strings');
+  const summary = options.summary ?? ((snapshot) => ({ status: snapshot.status, generation: snapshot.generation }));
+  const inside = (fn) => recordTransaction(client, fn);
+  const bytes = (value) => new TextEncoder().encode(canonicalizeJson(value)).byteLength;
+  const bounded = (page) => {
+    if (bytes(page) > maxBytes) throw refuseRecord('run page exceeds byte budget');
+    return page;
+  };
+  const eventId = (id, revision) => canonicalizeJson([id, revision]);
+  const requireRun = async (tx, id) => {
+    const record = await runs.get(tx, id);
+    if (!record || !Number.isSafeInteger(record.revision) || record.revision < 0) throw refuseRecord('unknown or malformed domain run');
+    return record;
+  };
+  const guard = async (tx, record, lease) => {
+    if (record.jobId !== lease?.jobId) throw refuseRecord('foreign run job');
+    await tx.jobs.assertLease(lease);
+  };
+  const same = (record, identity) => record.workflow === identity.workflow && record.schemaVersion === identity.schemaVersion && record.jobId === identity.jobId;
+  const write = async (tx, record) => {
+    if (!Number.isSafeInteger(record.revision + 1)) throw refuseRecord('run revision exhausted');
+    record.revision++;
+    const event = { id: eventId(record.id, record.revision), runId: record.id, revision: record.revision,
+      status: record.status, summary: record.summary, cancelRequested: record.cancelRequested };
+    if (bytes({ state: 'page', events: [event], cursor: record.revision, revision: record.revision, more: false, status: record.status, summary: record.summary }) > maxBytes) throw refuseRecord('public run summary exceeds byte budget');
+    await runs.put(tx, record);
+    await events.put(tx, event, true);
+    return { record, changes: 1, writes: 2, revisions: 1 };
+  };
+  return Object.freeze({
+    /** Attach without renaming or re-enqueueing an existing domain run.
+     * @param {{ id: string, jobId: string, workflow: string, schemaVersion: string }} identity @param {any} lease */
+    attach(identity, lease) {
+      const frozen = copyRecord(identity);
+      if (['id', 'jobId', 'workflow', 'schemaVersion'].some((name) => typeof frozen[name] !== 'string' || !frozen[name])) throw new TypeError('run identity needs id/jobId/workflow/schemaVersion');
+      return inside(async (tx) => {
+        if (frozen.jobId !== lease?.jobId) throw refuseRecord('foreign run job');
+        await tx.jobs.assertLease(lease);
+        const prior = await runs.get(tx, frozen.id);
+        if (prior) {
+          if (!same(prior, frozen)) throw refuseRecord('incompatible run workflow or schema identity');
+          return { record: prior, ...zero };
+        }
+        return write(tx, { ...frozen, revision: 0, status: statuses.running, summary: null, checkpoint: null, cancelRequested: false });
+      });
+    },
+    /** Verify provenance before exposing any old checkpoint to the engine.
+     * @param {string} id @param {any} identity @param {any} lease */
+    load(id, identity, lease) {
+      return inside(async (tx) => {
+        const record = await requireRun(tx, id);
+        await guard(tx, record, lease);
+        if (!same(record, identity)) throw refuseRecord('incompatible run workflow or schema identity');
+        if (record.cancelRequested) throw refuseRecord('run cancellation stops admission');
+        return record.checkpoint;
+      });
+    },
+    /** Existing workflow CAS, mapped status/event and checkpoint co-commit.
+     * @param {string} id @param {any} snapshot @param {number} expectedGeneration @param {any} lease */
+    save(id, snapshot, expectedGeneration, lease) {
+      const checkpoint = copyRecord(snapshot);
+      return inside(async (tx) => {
+        const record = await requireRun(tx, id);
+        await guard(tx, record, lease);
+        if (record.cancelRequested) throw refuseRecord('run cancellation stops admission');
+        if ((record.checkpoint?.generation ?? 0) !== expectedGeneration) return false;
+        if (checkpoint.runId !== id || checkpoint.generation !== expectedGeneration + 1 || !Object.hasOwn(statuses, checkpoint.status))
+          throw refuseRecord('checkpoint run, generation or status mismatch');
+        record.checkpoint = checkpoint;
+        record.status = statuses[checkpoint.status];
+        record.summary = copyRecord(summary(checkpoint));
+        await write(tx, record);
+        return true;
+      });
+    },
+    /** Trusted read: public authorization belongs to the contract handler.
+     * @param {string} id */
+    get: (id) => inside((tx) => requireRun(tx, id)),
+    /** Bounded revision cursor. Missing history explicitly requires a fresh summary.
+     * @param {string} id @param {{ after?: number, limit?: number }} [options] */
+    page(id, { after = 0, limit = maxPage } = {}) {
+      if (!Number.isSafeInteger(after) || after < 0 || !Number.isSafeInteger(limit) || limit < 1 || limit > maxPage) throw new TypeError('run page needs a revision cursor and bounded limit');
+      return inside(async (tx) => {
+        const record = await requireRun(tx, id);
+        if (after > record.revision) throw refuseRecord('future run cursor');
+        const page = [], end = Math.min(record.revision, after + limit);
+        const envelope = { state: 'page', events: page, cursor: after, revision: record.revision, more: true, status: record.status, summary: record.summary };
+        for (let revision = after + 1; revision <= end; revision++) {
+          const event = await events.get(tx, eventId(id, revision));
+          if (!event) return bounded({ state: 'reset-required', cursor: record.revision, revision: record.revision, events: [], summary: record.summary, status: record.status });
+          if (event.runId !== id || event.revision !== revision) throw refuseRecord('run event identity mismatch');
+          if (bytes({ ...envelope, cursor: revision, events: [...page, event] }) > maxBytes) break;
+          page.push(event);
+        }
+        const cursor = page.at(-1)?.revision ?? after;
+        if (cursor === after && cursor < record.revision) throw refuseRecord('run page exceeds byte budget');
+        return bounded({ state: 'page', events: page, cursor, revision: record.revision, more: cursor < record.revision,
+          status: record.status, summary: record.summary });
+      });
+    },
+    /** Current authority is required in the caller's command; revision rejects stale intent.
+     * @param {string} id @param {number} expectedRevision @param {{ actor: string, reason: string }} evidence */
+    requestCancel(id, expectedRevision, evidence) {
+      if (!evidence?.actor || !evidence.reason) throw refuseRecord('cancellation needs actor and reason');
+      const proof = copyRecord(evidence);
+      return inside(async (tx) => {
+        const record = await requireRun(tx, id);
+        if (record.cancelRequested) return { record, ...zero };
+        if (record.revision !== expectedRevision) throw refuseRecord('stale cancellation revision');
+        if (record.status === statuses.done) throw refuseRecord('completed run cannot be cancelled');
+        record.cancelRequested = true; record.cancellation = proof;
+        return write(tx, record);
+      });
+    },
+    /** Called after workers drain and before resources close.
+     * @param {string} id @param {'cancelled' | 'failed'} state @param {any} lease */
+    finish(id, state, lease) {
+      if (!['cancelled', 'failed'].includes(state)) throw new TypeError('finish state must be cancelled or failed');
+      return inside(async (tx) => {
+        const record = await requireRun(tx, id);
+        await guard(tx, record, lease);
+        if (record.status === statuses[state]) return { record, ...zero };
+        record.status = statuses[state]; record.summary = { status: state };
+        return write(tx, record);
+      });
+    },
+    /** Reset touches only this run checkpoint, never receipts/effects. Host safety
+     * must consult authoritative history in this transaction; default is refusal.
+     * @param {string} id @param {number} expectedRevision @param {any} evidence @param {any} lease */
+    reset(id, expectedRevision, evidence, lease) {
+      if (!evidence?.actor || !evidence.reason || typeof options.canReset !== 'function') throw refuseRecord('reset needs explicit actor/reason and a transactional safety policy');
+      return inside(async (tx) => {
+        const record = await requireRun(tx, id);
+        await guard(tx, record, lease);
+        if (record.revision !== expectedRevision || ![statuses.cancelled, statuses.failed, statuses.waiting].includes(record.status)) throw refuseRecord('reset needs an inactive current revision');
+        if (await options.canReset(tx, copyRecord(record)) !== true) throw refuseRecord('receipt or unresolved effect prevents reset');
+        record.checkpoint = null; record.cancelRequested = false; record.status = statuses.running;
+        record.summary = { status: 'reset' }; record.reset = copyRecord(evidence);
+        return write(tx, record);
+      });
+    },
+  });
+}

package/src/db/search.js

@@ -0,0 +1,86 @@
+//@ts-check
+/** Structural lexical ranges reuse the shared resident range implementation. */
+import { createArrayRangeProvider, rangeBytes, rangeIdentity } from '@jarenjs/core/range';
+import { canonicalizeJson } from '@jarenjs/json/canonical';
+
+/**
+ * Materialize only a credited, complete lexical membership. The source retains
+ * authoritative rows; this adapter owns one bounded range copy and its cursors.
+ * @param {any} source @param {string} text @param {any} [spec] @param {any} [options]
+ * @returns {Promise<any>}
+ */
+export async function createLexicalRangeProvider(source, text, spec = {}, options = {}) {
+  const maxMatches = options.maxMatches ?? 1000, maxSourceBytes = options.maxSourceBytes ?? 1024 * 1024;
+  if (!Number.isSafeInteger(maxMatches) || maxMatches < 1 || !Number.isSafeInteger(maxSourceBytes) || maxSourceBytes < 2)
+    throw new TypeError('Invalid lexical range credits');
+  if (spec.after !== undefined || spec.limit !== undefined) throw new TypeError('Lexical ranges own continuation and result limits');
+  spec = structuredClone(spec);
+  const query = options.query ?? canonicalizeJson({ text, spec, source: options.source ?? null });
+  let disposed = false, dirty = false, epoch = 0, provider = null, refreshing = null;
+  const observers = new Set();
+  const unsubscribe = source.subscribe((event) => {
+    dirty = true; epoch++;
+    for (const observer of observers) { try { observer({ ...event, query, type: 'reset', revision: epoch, snapshot: source.sourceRevision }); }
+      catch { /* Subscribers cannot suppress a sibling's reset. */ } }
+  });
+  const refresh = async () => {
+    if (disposed) throw new Error('Lexical range disposed');
+    if (refreshing) return refreshing;
+    refreshing = (async () => {
+      const result = await source.search(text, { ...spec, limit: maxMatches });
+      if (disposed) throw new Error('Lexical range disposed');
+      if (result.state !== 'complete' || result.hasMore || result.hits.length !== result.total)
+        throw new RangeError(`Lexical range requires complete membership: ${result.reason ?? 'match-credits'}`);
+      const rows = [], snapshot = result.sourceRevision;
+      let bytes = 2;
+      for (const hit of result.hits) {
+        const row = source.row(hit.id, snapshot); bytes += rangeBytes(row) + (rows.length ? 1 : 0);
+        if (bytes > maxSourceBytes) throw new RangeError('Lexical range source byte credits');
+        rows.push(row);
+      }
+      if (provider === null) provider = createArrayRangeProvider(rows, { ...options, query, snapshot });
+      else if (provider.snapshot !== snapshot) provider.replace(rows, snapshot);
+      dirty = false; return { state: 'complete', sourceRevision: snapshot, rows: rows.length, bytes };
+    })().finally(() => { refreshing = null; });
+    return refreshing;
+  };
+  try { await refresh(); }
+  catch (error) { unsubscribe(); throw error; }
+  return {
+    query, get snapshot() { return provider.snapshot; }, capabilities: provider.capabilities, refresh,
+    indexOf: (key) => provider.indexOf(key),
+    subscribe(fn) {
+      if (disposed || typeof fn !== 'function') throw new TypeError('Invalid lexical range subscriber');
+      if (observers.size >= 8) throw new RangeError('Lexical range subscription credits');
+      observers.add(fn); return () => observers.delete(fn);
+    },
+    async request(request, signal) {
+      const refusal = (state, reason) => ({ ...rangeIdentity(request), state, reason, used: { pages: 0, rows: 0, bytes: 0, work: 0 } });
+      if (disposed) return refusal('error', 'disposed');
+      if (signal?.aborted) return refusal('error', 'cancelled');
+      const current = epoch;
+      const ready = await source.refresh();
+      if (disposed) return refusal('error', 'disposed');
+      if (signal?.aborted) return refusal('error', 'cancelled');
+      if (ready.state !== 'complete') return refusal(ready.state === 'budget-exhausted' ? ready.state : 'error', ready.reason);
+      if (dirty || current !== epoch || source.sourceRevision !== provider.snapshot) return refusal('invalidated', 'source-changed');
+      return provider.request(request, signal);
+    },
+    async *export(request, signal) {
+      const ready = await source.refresh();
+      if (ready.state !== 'complete' || dirty || disposed || source.sourceRevision !== provider.snapshot) throw new Error('Incomplete lexical snapshot export');
+      for await (const page of provider.export(request, signal)) {
+        const current = await source.refresh();
+        if (current.state !== 'complete' || dirty || disposed || source.sourceRevision !== provider.snapshot)
+          throw new Error('Incomplete lexical snapshot export');
+        yield page;
+      }
+    },
+    stats: () => ({ ...provider.stats(), refreshing: refreshing ? 1 : 0, subscriptions: observers.size, dirty }),
+    async dispose() {
+      disposed = true; unsubscribe(); observers.clear();
+      await Promise.allSettled([refreshing]); await provider.dispose();
+      if (options.disposeSource) await source.dispose();
+    },
+  };
+}

package/src/errors.js

@@ -15,7 +15,8 @@ import { CodedError } from '@jarenjs/core/errors';
  * this package can raise, proven in sync with QUERY-PEN.md §9's
  * normative table by a test.
  */
-export const LINQ_CODES = Object.freeze({
+// Freezing an unexported literal has no observable effect when the table is unused.
+export const LINQ_CODES = /* @__PURE__ */ Object.freeze({
   JL0001: 'from() received neither an iterable nor a provider',
   JL0002: 'an expression proxy escaped its capture callback',
   JL0003: 'ofType/cast need an injected compileTypeTest',
@@ -38,6 +39,7 @@ export const LINQ_CODES = Object.freeze({
   JL2006: 'a provider answered an element terminal with something other than one array',
   JL2007: 'a ledger settlement named a ref that settles no started record',
   JL2008: 'a federated fetch reached its row or byte budget',
+  JL2009: 'a durable mapped record violated identity, retention or fencing',
 });
 
 /**

package/src/expression.js

@@ -307,8 +307,7 @@ function shiftArgs(record, amount, unit) {
 function literalSpec(spec, method) {
   if (!isPlainJson(spec) || spec === null || typeof spec !== 'object' || Array.isArray(spec)) {
     throw new LinqBuildError('JL0005',
-      `${method}() takes a plain literal spec object; it is read once when the query`
-      + ' compiles, so it cannot be an expression or carry a captured value');
+      `${method}() takes a plain literal spec object, not an expression or captured value`);
   }
   return spec;
 }
@@ -336,6 +335,10 @@ const METHODS = {
   // §8.7 strings
   startsWith: binary('$starts-with'), endsWith: binary('$ends-with'),
   contains: binary('$contains'), matches: binary('$match'),
+  lexical(record, provider, spec = {}) {
+    if (typeof provider !== 'string' || !provider) throw new LinqBuildError('JL0005', 'Lexical name');
+    return makeExpr({ $lexical: [provider, record.doc, literalSpec(spec, 'lexical')] }, record.epoch, false);
+  },
   upper: unary('$upper'), lower: unary('$lower'),
   length: unary('$string-length'),
   concat: binary('$concat'),