@jarenjs/linq 0.49.2 → 0.66.1

package/src/db/handle.js

@@ -0,0 +1,89 @@
+//@ts-check
+/**
+ * @file The handles the client fronts the store with. An entity handle
+ * is the store's entity set — every member of it, the provider members
+ * included, so `fromAsync(handle)` still binds through its root and two
+ * handles of one client still share a scope — plus the chain start
+ * (every `AsyncSequence` operator and terminal, delegated to
+ * `fromAsync(set)`: nothing is duplicated, every read is the chain and
+ * pushes down), `include` (the graph builder that EMITS the store's
+ * `load` spec), `link`/`unlink` (checked against the relation table
+ * before the store records them) and `live`. A collection handle is the
+ * collection with the same chain start and `live`. `explain()` without
+ * a document explains the empty chain; with one it is the store's
+ * explanation of that document.
+ */
+
+import { fromAsync, AsyncSequence } from '../async.js';
+import { Graph } from './include.js';
+import { requireMembership } from './membership.js';
+import { registerLive } from './live.js';
+
+/** The chain surface, read once from the class: every public operator
+ * and terminal, `explain` set aside for its overload. */
+const CHAIN_MEMBERS = Object.getOwnPropertyNames(AsyncSequence.prototype)
+  .filter((name) => name !== 'constructor' && name !== 'explain');
+const CHAIN_SYMBOLS = Object.getOwnPropertySymbols(AsyncSequence.prototype);
+
+/**
+ * Give a handle the chain start over a provider: each member is
+ * `fromAsync(provider)`'s, so the handle and the chain are one surface.
+ * @param {any} provider - the store's handle (a collection or an entity set)
+ * @param {Record<string | symbol, any>} members - the handle being built
+ */
+function chainStart(provider, members) {
+  for (const name of CHAIN_MEMBERS) {
+    members[name] = (...args) => fromAsync(provider)[name](...args);
+  }
+  for (const symbol of CHAIN_SYMBOLS) {
+    members[symbol] = () => fromAsync(provider)[symbol]();
+  }
+  const explainDocument = provider.explain;
+  members.explain = (document, options) => (document === undefined
+    ? fromAsync(provider).explain()
+    : explainDocument(document, options));
+}
+
+/**
+ * The handle over one entity set.
+ * @param {any} store - the opened store
+ * @param {string} name - the entity
+ * @returns {any}
+ */
+export function createEntityHandle(store, name) {
+  const set = store.entity(name);
+  /** @type {Record<string | symbol, any>} */
+  const members = { ...set };
+  chainStart(set, members);
+  members.include = (pick, spec) => new Graph(set, name).include(pick, spec);
+  // the graph with nothing included: the root clauses, the keyset and
+  // the page over the rows alone
+  members.graph = () => new Graph(set, name);
+  members.link = (own, member, target) => {
+    requireMembership(set.relations, name, member, 'link');
+    set.link(own, member, target);
+  };
+  members.unlink = (own, member, target) => {
+    requireMembership(set.relations, name, member, 'unlink');
+    set.unlink(own, member, target);
+  };
+  members.live = (source = fromAsync(set), options = undefined) =>
+    registerLive(store.live, source, options);
+  return Object.freeze(members);
+}
+
+/**
+ * The handle over one collection.
+ * @param {any} store - the opened store
+ * @param {string} name - the collection
+ * @returns {any}
+ */
+export function createCollectionHandle(store, name) {
+  const collection = store.collection(name);
+  /** @type {Record<string | symbol, any>} */
+  const members = { ...collection };
+  chainStart(collection, members);
+  members.live = (source = fromAsync(collection), options = undefined) =>
+    registerLive(collection.live, source, options);
+  return Object.freeze(members);
+}

package/src/db/include.js

@@ -0,0 +1,351 @@
+//@ts-check
+/**
+ * @file The graph builder: `include(pick, spec)` and the root clauses
+ * accumulate a `load` specification (MODEL-FORMAT §10.4, §10.5) — the
+ * client EMITS the spec the store already runs and runs nothing itself.
+ * The relation member is captured to its NAME; every callback is
+ * captured to a query expression over `$it` through the chain's own
+ * recording proxy — with no parameters, since a load clause binds no
+ * externals — and `toArray()` is `load(spec)`, `explain()` is
+ * `explainLoad(spec)`: the one-statement guarantee is the store's. A
+ * spec is plain JSON in a fixed member order (`where, orderBy, take,
+ * skip, after, maxDepth, include` at the root; `where, orderBy, take,
+ * skip, count, maxRows, maxBytes, include` in an include — a keyset
+ * cursor paginates the root alone), so one graph is one document;
+ * `toJSON()` is that document, as a pen's is. `cursor()` is
+ * `loadCursor(spec)`: one root graph per pull.
+ */
+
+import { deepFreeze, setObjectMember } from '@jarenjs/core/object';
+
+import { captureExpression } from '../expression.js';
+import { LinqBuildError } from '../errors.js';
+import { requireJson, describeValue } from '../json-boundary.js';
+
+const NO_PARAMS = new Set();
+const ROOT_KEYS = ['where', 'orderBy', 'take', 'skip', 'after', 'maxDepth', 'include'];
+const INCLUDE_KEYS = ['where', 'orderBy', 'take', 'skip', 'count', 'maxRows', 'maxBytes', 'include'];
+/** A member path over the row: the shorthand or the bracketed spelling. */
+const MEMBER_PATH = /^\$it(?:\.([A-Za-z_$][\w$]*)|\['((?:[^'\\]|\\.)*)'\])$/;
+
+/**
+ * Capture one callback over the row bound as `it`.
+ * @param {any} fn
+ * @param {string} what - for the message
+ * @returns {any} the query expression
+ */
+function captureOver(fn, what) {
+  if (typeof fn !== 'function') {
+    throw new LinqBuildError('JL0101', `${what} takes a callback over the row, got ${describeValue(fn)}`);
+  }
+  return captureExpression(fn, ['it'], NO_PARAMS);
+}
+
+/**
+ * The relation entry a member names, or the refusal naming the table.
+ * @param {Record<string, any>} relations
+ * @param {string} entityName
+ * @param {string} member
+ * @param {string} what
+ * @returns {{ member: string, entry: any }}
+ */
+function requireRelation(relations, entityName, member, what) {
+  const entry = relations[member];
+  if (entry === undefined) {
+    const declared = Object.keys(relations);
+    throw new LinqBuildError('JL0107',
+      `'${member}' is not a relation member of '${entityName}' — ${what} loads a declared relation`
+      + (declared.length === 0 ? `, and '${entityName}' declares none`
+        : ` (${declared.map((name) => `'${name}'`).join(', ')})`));
+  }
+  return { member, entry };
+}
+
+/**
+ * The relation member a pick names: `(u) => u.posts` — or `u.get('posts')`
+ * for a name that collides with a method — captured to `$it.posts` and
+ * looked up in the relation table.
+ * @param {any} pick
+ * @param {Record<string, any>} relations
+ * @param {string} entityName
+ * @returns {{ member: string, entry: any }}
+ */
+function pickMember(pick, relations, entityName) {
+  const captured = captureOver(pick, 'include()');
+  const match = typeof captured === 'string' ? MEMBER_PATH.exec(captured) : null;
+  if (match === null) {
+    throw new LinqBuildError('JL0107',
+      `include() picks one relation member of '${entityName}' by name ((u) => u.posts); got `
+      + (typeof captured === 'string' ? captured : 'an operator result'));
+  }
+  const member = match[1] ?? match[2].replace(/\\(.)/g, '$1');
+  return requireRelation(relations, entityName, member, 'include()');
+}
+
+/**
+ * One `$orderby` term: a bare key for a plain ascending order, else the
+ * `{ $key, $dir, $empty, $collation }` spec — as the chain spells it.
+ * @param {any} key - the key callback
+ * @param {boolean} desc
+ * @param {{ empty?: string, collation?: string } | undefined} options
+ * @param {string} what
+ * @returns {any}
+ */
+function orderTerm(key, desc, options, what) {
+  const expression = captureOver(key, what);
+  const spec = { $key: expression };
+  if (desc) spec.$dir = 'desc';
+  if (options !== undefined && options !== null) {
+    if (options.empty !== undefined) spec.$empty = requireJson(options.empty, `${what} empty`);
+    if (options.collation !== undefined) spec.$collation = requireJson(options.collation, `${what} collation`);
+  }
+  return Object.keys(spec).length === 1 ? expression : spec;
+}
+
+/**
+ * An include spec's `orderBy`: a key callback, `{ key, desc?, empty?,
+ * collation? }`, or an array of either.
+ * @param {any} orderBy
+ * @param {string} what
+ * @returns {any}
+ */
+function lowerOrder(orderBy, what) {
+  const one = (term, at) => {
+    if (typeof term === 'function') return orderTerm(term, false, undefined, at);
+    if (term !== null && typeof term === 'object' && !Array.isArray(term) && typeof term.key === 'function') {
+      return orderTerm(term.key, term.desc === true, term, at);
+    }
+    throw new LinqBuildError('JL0101',
+      `${at} takes a key callback ((p) => p.stars) or { key, desc?, empty?, collation? }, got ${describeValue(term)}`);
+  };
+  return Array.isArray(orderBy) ? orderBy.map((term, i) => one(term, `${what}[${i}]`)) : one(orderBy, what);
+}
+
+/**
+ * Lower one include: `true` (or nothing) includes the rows; an object
+ * carries the clauses the store's `load` reads, each callback captured,
+ * nested includes resolved against the TARGET's relation table.
+ * @param {any} spec
+ * @param {string} entityName - the target entity
+ * @param {(name: string) => Record<string, any> | undefined} relationsOf
+ * @param {string[]} path
+ * @returns {any}
+ */
+function lowerInclude(spec, entityName, relationsOf, path) {
+  if (spec === undefined || spec === true) return true;
+  const at = path.join('.');
+  if (spec === null || typeof spec !== 'object' || Array.isArray(spec)) {
+    // the member list is DERIVED from the same constant the check below
+    // reads: typed out, it named `after` — a member that check refuses —
+    // and a reader who believed the first message met the second
+    throw new LinqBuildError('JL0101',
+      `the include spec at ${at} is true or `
+      + `{ ${INCLUDE_KEYS.map((key) => `${key}?`).join(', ')} }, got ${describeValue(spec)}`);
+  }
+  for (const key of Object.keys(spec)) {
+    if (!INCLUDE_KEYS.includes(key)) {
+      throw new LinqBuildError('JL0101',
+        `the include spec at ${at} does not take '${key}' — the members are ${INCLUDE_KEYS.join(', ')}`
+        + (key === 'after' ? '; a keyset cursor paginates the root: after() on the graph' : ''));
+    }
+  }
+  const out = {};
+  if (spec.where !== undefined) out.where = captureOver(spec.where, `${at} where`);
+  if (spec.orderBy !== undefined) out.orderBy = lowerOrder(spec.orderBy, `${at} orderBy`);
+  for (const key of ['take', 'skip']) {
+    if (spec[key] !== undefined) out[key] = requireJson(spec[key], `${at} ${key}`);
+  }
+  if (spec.count !== undefined) {
+    if (spec.count !== true) throw new LinqBuildError('JL0101', `the include spec at ${at}: count takes true`);
+    out.count = true;
+  }
+  for (const key of ['maxRows', 'maxBytes']) {
+    // the per-root bound (MODEL-FORMAT §10.4); `Infinity` is the spelled
+    // unbounded case, and its JSON form is `null`
+    if (spec[key] === undefined) continue;
+    out[key] = spec[key] === Infinity ? null : requireJson(spec[key], `${at} ${key}`);
+  }
+  if (spec.include !== undefined) out.include = lowerIncludes(spec.include, entityName, relationsOf, path);
+  return out;
+}
+
+/**
+ * A nested include record — member → `true` | spec — over the target's
+ * relation table.
+ * @param {any} includes
+ * @param {string} entityName
+ * @param {(name: string) => Record<string, any> | undefined} relationsOf
+ * @param {string[]} path
+ * @returns {Record<string, any>}
+ */
+function lowerIncludes(includes, entityName, relationsOf, path) {
+  if (includes === null || typeof includes !== 'object' || Array.isArray(includes)) {
+    throw new LinqBuildError('JL0101',
+      `include at ${path.join('.')} is a record of relation members, got ${describeValue(includes)}`);
+  }
+  const relations = relationsOf(entityName) ?? {};
+  const out = {};
+  for (const member of Object.keys(includes)) {
+    const { entry } = requireRelation(relations, entityName, member, 'a nested include');
+    setObjectMember(out, member, lowerInclude(includes[member], entry.to, relationsOf, [...path, member]));
+  }
+  return out;
+}
+
+/** The graph over one entity set: an immutable builder of a `load` spec. */
+export class Graph {
+  #set;
+  #entity;
+  #spec;
+  #tracking;
+
+  /**
+   * @param {any} set - the store's entity set
+   * @param {string} entity - its name
+   * @param {Record<string, any>} [spec] - the spec so far (`orderBy` as a list)
+   * @param {boolean} [tracking] - whether `toArray()` registers snapshots
+   */
+  constructor(set, entity, spec = {}, tracking = true) {
+    this.#set = set;
+    this.#entity = entity;
+    this.#spec = spec;
+    this.#tracking = tracking;
+  }
+
+  /** @param {Record<string, any>} patch */
+  #with(patch) {
+    return new Graph(this.#set, this.#entity, { ...this.#spec, ...patch }, this.#tracking);
+  }
+
+  /** The other roots' tables, where a nested include finds its target's. */
+  #relationsOf() {
+    const scoped = this.#set.scope?.relations;
+    return (name) => (scoped !== null && typeof scoped === 'object' ? scoped[name] : undefined);
+  }
+
+  /**
+   * Include one relation member, with an optional spec over its rows.
+   * @param {(u: any) => any} pick - `(u) => u.posts`
+   * @param {any} [spec] - `{ where?, orderBy?, take?, skip?, after?, count?, include? }`
+   * @returns {Graph}
+   */
+  include(pick, spec) {
+    const { member, entry } = pickMember(pick, this.#set.relations, this.#entity);
+    const lowered = lowerInclude(spec, entry.to, this.#relationsOf(), [member]);
+    const include = { ...(this.#spec.include ?? {}) };
+    setObjectMember(include, member, lowered);
+    return this.#with({ include });
+  }
+
+  /** Filter the root rows; consecutive calls conjoin. @param {(it: any) => any} predicate */
+  where(predicate) {
+    const expression = captureOver(predicate, 'where()');
+    const previous = this.#spec.where;
+    if (previous === undefined) return this.#with({ where: expression });
+    const conjoined = previous !== null && typeof previous === 'object'
+      && Object.keys(previous).length === 1 && Array.isArray(previous.$and)
+      ? [...previous.$and, expression] : [previous, expression];
+    return this.#with({ where: { $and: conjoined } });
+  }
+
+  /** @param {(it: any) => any} key @param {{ empty?: string, collation?: string }} [options] */
+  orderBy(key, options) {
+    return this.#with({ orderBy: [orderTerm(key, false, options, 'orderBy()')] });
+  }
+
+  /** @param {(it: any) => any} key @param {{ empty?: string, collation?: string }} [options] */
+  orderByDescending(key, options) {
+    return this.#with({ orderBy: [orderTerm(key, true, options, 'orderByDescending()')] });
+  }
+
+  /** @param {(it: any) => any} key @param {{ empty?: string, collation?: string }} [options] */
+  thenBy(key, options) {
+    return this.#then(orderTerm(key, false, options, 'thenBy()'), 'thenBy');
+  }
+
+  /** @param {(it: any) => any} key @param {{ empty?: string, collation?: string }} [options] */
+  thenByDescending(key, options) {
+    return this.#then(orderTerm(key, true, options, 'thenByDescending()'), 'thenByDescending');
+  }
+
+  /** @param {any} term @param {string} what */
+  #then(term, what) {
+    if (this.#spec.orderBy === undefined) {
+      throw new LinqBuildError('JL0005',
+        `${what}() extends an orderBy()/orderByDescending() — none precedes it`);
+    }
+    return this.#with({ orderBy: [...this.#spec.orderBy, term] });
+  }
+
+  /** @param {number} count */
+  take(count) { return this.#with({ take: requireJson(count, 'take()') }); }
+
+  /** @param {number} count */
+  skip(count) { return this.#with({ skip: requireJson(count, 'skip()') }); }
+
+  /** The keyset continuation (§10.5): the `{ order, keys, key }` value a
+   * page emitted — a bare unique-column value is the single-column form.
+   * @param {any} cursor */
+  after(cursor) { return this.#with({ after: requireJson(cursor, 'after()') }); }
+
+  /** The include depth bound (§10.4). @param {number} depth */
+  maxDepth(depth) { return this.#with({ maxDepth: requireJson(depth, 'maxDepth()') }); }
+
+  /** The same graph, loaded without registering snapshots. */
+  asNoTracking() {
+    return new Graph(this.#set, this.#entity, this.#spec, false);
+  }
+
+  /** The document, as every pen answers it: the emitted spec. */
+  toJSON() {
+    return this.toSpec();
+  }
+
+  /** The emitted `load` spec: plain frozen JSON, a snapshot. */
+  toSpec() {
+    const out = {};
+    for (const key of ROOT_KEYS) {
+      const value = this.#spec[key];
+      if (value === undefined) continue;
+      out[key] = key === 'orderBy' && value.length === 1 ? value[0] : value;
+    }
+    return deepFreeze(structuredClone(out));
+  }
+
+  /** `load(spec)` — the store's one statement. */
+  toArray() {
+    const spec = this.toSpec();
+    return this.#tracking ? this.#set.load(spec) : this.#set.asNoTracking().load(spec);
+  }
+
+  /**
+   * `loadCursor(spec, options)` — the store's graph cursor: one root
+   * graph per pull, its includes attached and bounded, from the same one
+   * statement; `return()` releases it. Untracked unless `tracking: true`
+   * is spelled per call — a snapshot per yielded root is a unit of work
+   * that grows with the result.
+   * @param {{ signal?: AbortSignal, tracking?: boolean }} [options]
+   */
+  cursor(options) {
+    return this.#set.loadCursor(this.toSpec(), options);
+  }
+
+  /**
+   * `page(spec, options)` — the store's bounded page over the composite
+   * keyset (§10.5): `{ items, continuation, hasMore, snapshot }`, never
+   * more than `limit` roots or `maxBytes` serialised bytes, the
+   * continuation unsigned and structural. Untracked unless `tracking:
+   * true`.
+   * @param {{ limit?: number, after?: any, maxBytes?: number,
+   *   consistency?: 'live' | 'snapshot', signal?: AbortSignal,
+   *   tracking?: boolean }} [options]
+   */
+  page(options) {
+    return this.#set.page(this.toSpec(), options);
+  }
+
+  /** `explainLoad(spec)` — the SQL, the includes, the pagination strategy. */
+  explain() {
+    return this.#set.explainLoad(this.toSpec());
+  }
+}

package/src/db/index.js

@@ -0,0 +1,24 @@
+//@ts-check
+/**
+ * @file `@jarenjs/linq/db` — the store's front door. `open(model,
+ * options)` returns a client typed from the model pen whose entity
+ * handles chain (`client.entities.Post.where(…)` is `fromAsync(handle)
+ * .where(…)`, so every read is the chain's document and pushes down),
+ * load graphs from an EMITTED `load` spec (`include`), track and save
+ * changes, link and unlink many-to-many members and maintain live
+ * results — over exactly one runtime edge: this subpath imports
+ * `@jarenjs/db`, `@jarenjs/validate` and `@jarenjs/formats`, declared as
+ * optional peers; no other subpath of the package does, and the store
+ * never imports this package (the edge suite in the tests holds both).
+ * The store stays the engine: the client adds no storage semantics and
+ * duplicates no algorithm — `include` emits the spec the store runs,
+ * membership is the store's own `link`/`unlink`, `live` is the store's
+ * registration — and every read is one an `explain()` can name.
+ * `createDbLedger` is the contract ledger over a declared collection of
+ * the client's store, through that same surface: the durable idempotency
+ * ledger a host was left to write, with no edge from `@jarenjs/contract`
+ * to a store (DB-CLIENT.md §2.6).
+ */
+
+export { open, defaultValidator } from './open.js';
+export { createDbLedger } from './ledger.js';

package/src/db/ledger.js

@@ -0,0 +1,195 @@
+//@ts-check
+/**
+ * @file `createDbLedger(client, options)`: the contract ledger
+ * (`@jarenjs/contract` docs/CONTRACT-FORMAT.md §8) over a declared
+ * collection of the client's store — every claim state, the persisted
+ * generation fence, expiry, `sweep` — through the client's collection
+ * and transaction surface alone. Nothing here imports the contract
+ * package or a driver: the ledger SHAPE is structural (the
+ * `claim`/`commit`/`fail`/`lookup` the http binding calls), the record
+ * is exactly `idempotencyLedgerModel`'s, and the id is the same
+ * versioned JSON tuple the memory ledger spells. A root client claims
+ * inside `transaction(…, { mode: 'immediate' })` — one writer, so two
+ * processes never both hold `new`; a transaction client claims and
+ * settles inside the transaction it was handed, which is the ledger a
+ * lifecycle settlement lease carries: a domain write and the settlement
+ * then commit together or not at all.
+ */
+
+import { resolveRuntime } from '@jarenjs/core/runtime';
+
+import { LinqRuntimeError } from '../errors.js';
+
+/** One day, the default retention of a key — the memory ledger's. */
+const DEFAULT_TTL_MS = 86_400_000;
+
+/** The collection `idempotencyLedgerModel` declares. */
+const DEFAULT_COLLECTION = 'ledger';
+
+/**
+ * The id of one `(op, scope, key)` tuple — the version `1`, a colon, the
+ * JSON array of the three: the spelling `@jarenjs/contract/ledger`'s
+ * `ledgerId` writes, so a store's records and a memory ledger's agree.
+ * A record written under the legacy `"<op>|<scope>|<key>"` spelling is
+ * matched by no claim again; it expires by its own `expiresAt` (`sweep`)
+ * or a host rewrites it once (DB-CLIENT.md §2.6).
+ * @param {string} op
+ * @param {string} scope
+ * @param {string} key
+ * @returns {string}
+ */
+function ledgerId(op, scope, key) {
+  return `1:${JSON.stringify([op, scope, key])}`;
+}
+
+/**
+ * @typedef {Object} DbLedgerOptions
+ * @property {string} [collection] - the declared collection, `'ledger'` by default
+ * @property {number} [ttlMs] - the retention of a key, 86,400,000 ms by default
+ * @property {Partial<import('@jarenjs/core/runtime').Runtime>} [runtime] -
+ *   the host's runtime record: its `now` is the clock, its `uuid` mints
+ *   every generation
+ * @property {() => number} [now] - the clock; wins over the runtime's
+ */
+
+/**
+ * @param {unknown} ref
+ * @param {string} reason
+ * @returns {LinqRuntimeError}
+ */
+function stale(ref, reason) {
+  const r = /** @type {any} */ (ref);
+  const named = r !== null && typeof r === 'object' && typeof r.id === 'string' ? r.id : 'a ref this ledger did not issue';
+  return new LinqRuntimeError('JL2007', `${named} settles no started record: ${reason}`);
+}
+
+/**
+ * The durable ledger over a client's declared collection.
+ * @param {any} client - a `@jarenjs/linq/db` client: the root one, or
+ *   the one a transaction callback received
+ * @param {DbLedgerOptions} [options]
+ * @returns {{ claim: (claim: { op: string, scope: string, key: string, hash: string, now?: number }) => Promise<any>,
+ *   commit: (ref: unknown, response: unknown, now?: number) => Promise<void>,
+ *   fail: (ref: unknown, retryable: boolean, response?: unknown, now?: number) => Promise<void>,
+ *   lookup: (key: { op: string, scope: string, key: string, now?: number }) => Promise<any>,
+ *   sweep: (now?: number) => Promise<number> }}
+ */
+export function createDbLedger(client, options = {}) {
+  if (client === null || typeof client !== 'object' || client.collections === null
+    || typeof client.collections !== 'object' || typeof client.transaction !== 'function') {
+    throw new TypeError('createDbLedger: client must be a @jarenjs/linq/db client — the root client, or the one a transaction callback received');
+  }
+  const name = options.collection === undefined ? DEFAULT_COLLECTION : options.collection;
+  if (typeof name !== 'string' || name === '') throw new TypeError('createDbLedger: collection must be a non-empty collection name');
+  if (!Object.hasOwn(client.collections, name)) {
+    throw new TypeError(`createDbLedger: the client declares no collection '${name}' — open the store with idempotencyLedgerModel, or a model that declares it`);
+  }
+  const ttlMs = options.ttlMs === undefined ? DEFAULT_TTL_MS : options.ttlMs;
+  if (!Number.isFinite(ttlMs) || ttlMs <= 0) throw new TypeError('createDbLedger: ttlMs must be a positive number');
+  let runtime;
+  try {
+    runtime = resolveRuntime(options.runtime);
+  }
+  catch (error) {
+    throw new TypeError(`createDbLedger: runtime: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  const clock = options.now === undefined ? runtime.now : options.now;
+  if (typeof clock !== 'function') throw new TypeError('createDbLedger: now must be a function');
+  // the memory ledger's clock discipline: one clock judges a record from
+  // claim to expiry — its own when given, else the binding's instants
+  const ownClock = options.now !== undefined || options.runtime !== undefined;
+  /** @type {number | null} */
+  let latest = null;
+  /** @param {number | undefined} given */
+  const instant = (given) => {
+    if (typeof given === 'number') {
+      if (!ownClock) latest = latest === null ? given : Math.max(latest, given);
+      return given;
+    }
+    return ownClock || latest === null ? clock() : latest;
+  };
+  // a root client owns a connection and takes the write lock up front; a
+  // transaction client is inside one already and nests a savepoint, so
+  // the settlement commits with the host's own writes
+  const root = typeof client.close === 'function';
+  /** @param {(tx: any) => Promise<any>} fn */
+  const inside = (fn) => (root ? client.transaction(fn, { mode: 'immediate' }) : client.transaction(fn));
+  /** @param {any} tx */
+  const rows = (tx) => tx.collections[name];
+
+  /**
+   * Settle the started record a ref names, or refuse (`JL2007`).
+   * @param {unknown} ref
+   * @param {{ status: 'committed' | 'failed', response: unknown, retryable: boolean | null }} changes
+   * @param {number | undefined} now
+   */
+  function settle(ref, changes, now) {
+    const r = /** @type {any} */ (ref);
+    if (r === null || typeof r !== 'object' || typeof r.id !== 'string' || typeof r.generation !== 'string') {
+      return Promise.reject(stale(ref, 'a ref is { id, generation } as this ledger issued it'));
+    }
+    const at = instant(now);
+    return inside(async (tx) => {
+      const c = rows(tx);
+      const record = await c.get(r.id);
+      if (record === undefined || record.generation !== r.generation || record.status !== 'started') {
+        throw stale(ref, 'the key expired, was reclaimed under a newer generation, or was settled already');
+      }
+      await c.put({ ...record, ...changes, updatedAt: at }, r.id);
+    });
+  }
+
+  return Object.freeze({
+    claim({ op, scope, key, hash, now }) {
+      const at = instant(now);
+      const id = ledgerId(op, scope, key);
+      return inside(async (tx) => {
+        const c = rows(tx);
+        const existing = await c.get(id);
+        if (existing !== undefined) {
+          if (existing.expiresAt <= at) await c.delete(id);
+          else if (existing.hash !== hash) return { state: 'mismatch' };
+          else if (existing.status === 'started') return { state: 'in-progress' };
+          else if (existing.status === 'committed') return { state: 'replay', response: existing.response };
+          else if (existing.retryable !== true && existing.response !== null) return { state: 'replay', response: existing.response };
+          else await c.delete(id); // a retryable failure: the key runs again
+        }
+        const generation = runtime.uuid();
+        await c.insert({
+          id, generation, op, scope, key, hash, status: 'started', response: null, retryable: null,
+          createdAt: at, updatedAt: at, expiresAt: at + ttlMs,
+        });
+        return { state: 'new', ref: Object.freeze({ id, generation }) };
+      });
+    },
+    commit(ref, response, now = undefined) {
+      return settle(ref, { status: 'committed', response, retryable: null }, now);
+    },
+    fail(ref, retryable, response = undefined, now = undefined) {
+      return settle(ref, { status: 'failed', response: response === undefined ? null : response, retryable: retryable === true }, now);
+    },
+    lookup({ op, scope, key, now = undefined }) {
+      const at = instant(now);
+      const id = ledgerId(op, scope, key);
+      return inside(async (tx) => {
+        const c = rows(tx);
+        const record = await c.get(id);
+        if (record === undefined) return null;
+        if (record.expiresAt <= at) {
+          await c.delete(id);
+          return null;
+        }
+        return record; // the store's fresh document: nothing of the ledger's own
+      });
+    },
+    sweep(now = undefined) {
+      const at = instant(now);
+      return inside(async (tx) => {
+        const c = rows(tx);
+        const expired = await c.where((/** @type {any} */ r) => r.expiresAt.le(at)).select((/** @type {any} */ r) => r.id).toArray();
+        for (const id of expired) await c.delete(id);
+        return expired.length;
+      });
+    },
+  });
+}