@jarenjs/linq 0.75.0 → 0.83.3

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);
+}

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)),
+  });
+}