@jarenjs/db 0.56.0 → 0.67.0

package/src/json-bytes.js

@@ -0,0 +1,58 @@
+//@ts-check
+/** JSON byte accounting over decoded data, without allocating encoded text. */
+
+/** UTF-8 bytes of a JSON string, including quotes and well-formed escapes.
+ * @param {string} value @returns {number}
+ */
+export function jsonStringBytes(value) {
+  let bytes = 2;
+  for (let i = 0; i < value.length; i++) {
+    const code = value.charCodeAt(i);
+    if (code === 34 || code === 92 || code === 8 || code === 9
+      || code === 10 || code === 12 || code === 13) bytes += 2;
+    else if (code < 32) bytes += 6;
+    else if (code < 128) bytes++;
+    else if (code < 2048) bytes += 2;
+    else if (code >= 0xd800 && code <= 0xdfff) {
+      const next = value.charCodeAt(i + 1);
+      if (code <= 0xdbff && next >= 0xdc00 && next <= 0xdfff) { bytes += 4; i++; }
+      else bytes += 6;
+    }
+    else bytes += 3;
+  }
+  return bytes;
+}
+
+/** The JSON serialization size of decoded JSON data. Objects are memoized
+ * during decoding, so a nested include reads its size without another walk.
+ * @param {any} value @param {WeakMap<object, number>} [sizes]
+ * @returns {number}
+ */
+export function jsonBytes(value, sizes = new WeakMap()) {
+  if (value === null) return 4;
+  if (typeof value === 'string') return jsonStringBytes(value);
+  if (typeof value === 'boolean') return value ? 4 : 5;
+  if (typeof value === 'number') return Number.isFinite(value) ? String(value).length : 4;
+  if (typeof value !== 'object') throw new TypeError('byte accounting requires decoded JSON data');
+  const cached = sizes.get(value);
+  if (cached !== undefined) return cached;
+  const keys = Object.keys(value);
+  let bytes = 2 + Math.max(0, keys.length - 1);
+  const array = Array.isArray(value);
+  for (const key of keys) bytes += (array ? 0 : jsonStringBytes(key) + 1) + jsonBytes(value[key], sizes);
+  sizes.set(value, bytes);
+  return bytes;
+}
+
+/** Decode and account bottom-up in the decoder's construction traversal.
+ * The caller checks the incoming text bound before decoding and checks the
+ * recorded nested bounds before attaching any reconstructed children.
+ * @param {string} text @param {WeakMap<object, number>} sizes
+ * @returns {any}
+ */
+export function decodeCountedJson(text, sizes) {
+  return JSON.parse(text, (_key, value) => {
+    if (value !== null && typeof value === 'object') jsonBytes(value, sizes);
+    return value;
+  });
+}

package/src/live-join.js

@@ -0,0 +1,250 @@
+//@ts-check
+/** Indexed dependency maintenance over bounded, mapped entity roots. */
+import { compileJsonQuery } from '@jarenjs/json/query';
+import { stableStringify } from '@jarenjs/core/object';
+import { decodeJSONPointerSegment } from '@jarenjs/json/pointer';
+import { planEntityQuery, entityRoot } from './plan.js';
+import { joinTableRoots } from './model.js';
+import { keyToken } from './capture.js';
+import { DbRuntimeError } from './errors.js';
+import { utf8Length } from './cursor.js';
+
+/** Compile eligibility from the existing planner and declared mapping. @param {any} document @param {any} entities @param {any} mapping @param {any} operators */
+export function classifyEntityLive(document, entities, mapping, operators) {
+  const extra = joinTableRoots(entities, mapping);
+  const roots = new Map([...entities, ...extra.entities]);
+  const mapped = { ...mapping, entities: { ...mapping.entities, ...extra.mappings } };
+  // Canonical allowing-empty equality subquery: its native surrogate settles
+  // the dependency columns; the original expression still evaluates the tuple.
+  let surrogate = document;
+  let strategy = 'join';
+  const inner = Array.isArray(document) && document.length === 1 ? document[0] : document;
+  const entries = Object.entries(inner?.$for ?? {});
+  const globalRead = (node) => {
+    if (typeof node === 'string') return node === '$' || node.startsWith('$.') || node.startsWith('$[');
+    if (Array.isArray(node)) return node.some(globalRead);
+    return node !== null && typeof node === 'object'
+      && Object.entries(node).some(([key, value]) => key !== '$for' && globalRead(value));
+  };
+  if (entries.length === 1 && typeof entries[0][1] === 'string'
+    && Object.keys(inner).every((key) => ['$for', '$return'].includes(key))) {
+    const bindings = { ...inner.$for };
+    const predicates = [];
+    let valid = true;
+    const visit = (node) => {
+      if (node === null || typeof node !== 'object') return;
+      if (Array.isArray(node)) { node.forEach(visit); return; }
+      if (node.$for !== undefined) {
+        if (!Object.keys(node).every((key) => ['$for', '$where', '$return'].includes(key)) || node.$where === undefined) { valid = false; return; }
+        for (const [name, source] of Object.entries(node.$for)) {
+          if (Object.hasOwn(bindings, name) || typeof source !== 'string') { valid = false; return; }
+          bindings[name] = source;
+        }
+        predicates.push(node.$where);
+        visit(node.$return);
+      }
+      else Object.values(node).forEach(visit);
+    };
+    visit(inner.$return);
+    if (valid && predicates.length > 0 && !globalRead(inner.$return)) {
+      const terms = predicates.flatMap((predicate) => predicate.$and ?? [predicate]);
+      surrogate = [{ $for: bindings, $where: terms.length === 1 ? terms[0] : { $and: terms }, $return: `$${entries[0][0]}` }];
+      strategy = 'graph';
+    }
+  }
+  if (entries.length === 2 && Object.keys(inner).every((key) => ['$for', '$return'].includes(key))) {
+    const [outer, right] = entries;
+    const allowing = right[1];
+    const subquery = allowing?.$in;
+    const nested = Object.entries(subquery?.$for ?? {});
+    const equality = subquery?.$where?.$eq;
+    if (allowing?.['$allowing-empty'] === true && Object.keys(allowing).length === 2
+      && nested.length === 1 && subquery.$return === `$${nested[0][0]}`
+      && Object.keys(subquery).length === 3 && Object.keys(subquery.$where).length === 1
+      && Array.isArray(equality) && equality.length === 2 && equality.every((part) => typeof part === 'string')
+      && typeof outer[1] === 'string' && typeof nested[0][1] === 'string' && !globalRead(inner.$return)) {
+      const prefix = `$${nested[0][0]}.`;
+      surrogate = [{ $for: { [outer[0]]: outer[1], [right[0]]: nested[0][1] },
+        $where: { $eq: equality.map((part) => part.startsWith(prefix) ? `$${right[0]}.${part.slice(prefix.length)}` : part) },
+        $return: `$${outer[0]}` }];
+    }
+  }
+  const planned = planEntityQuery(surrogate, roots, mapped, operators);
+  const rerun = (reason) => ({ strategy: 'rerun', reason });
+  if (planned.mode !== 'native') return rerun(`entity dependency plan: ${planned.reasons[0]?.reason ?? 'unmapped expression'}`);
+  const plan = planned.plan;
+  if (plan.window !== null) return rerun('an entity offset or limit window re-runs');
+  if (plan.aggregate !== null) return rerun('an entity aggregate has no bounded tuple accumulator');
+  if (plan.order !== null) return rerun('an explicitly ordered entity join has no maintained ordering');
+  const bindings = plan.bindings.map((binding) => ({ ...binding, mapping: mapped.entities[binding.entity] }));
+  if (new Set(bindings.map((b) => b.entity)).size !== bindings.length) return rerun('a self join has ambiguous root invalidation');
+  const indexed = (binding, column) => {
+    const m = binding.mapping;
+    return m.keys[0] === column || m.indexes.some((index) => index.property === column)
+      || m.foreignKeys.some((fk) => fk.column === column);
+  };
+  const edges = plan.joins.flatMap((join) => join.on);
+  for (const edge of edges) {
+    if (edge.op !== 'eq') return rerun('a non-equality join refinement re-runs');
+    for (const side of [edge.left, edge.right]) {
+      if (!indexed(bindings.find((binding) => binding.name === side.binding), side.column))
+        return rerun(`join dependency '${side.binding}.${side.column}' has no declared index`);
+    }
+  }
+  if (bindings.some((binding) => binding.mapping.keys.length === 0)) return rerun('a join root has no stable key');
+  return { strategy, bindings, edges };
+}
+
+/** Maintain tuples through inverse key dependencies; query evaluation uses only affected root subsets.
+ * @param {any} description @param {any} context */
+export function joinStrategy(description, context) {
+  const { bindings, edges } = description;
+  const inner = Array.isArray(context.document) ? context.document[0] : context.document;
+  const evaluate = compileJsonQuery([{ $subsequence: [inner, 0, context.maxMaintained + 1] }]);
+  const caches = new Map(bindings.map((binding) => [binding.name, new Map()]));
+  const positions = new Map(bindings.map((binding) => [binding.name, new Map()]));
+  const indices = new Map();
+  const items = new Map();
+  let inputCount = 0;
+  let outputCount = 0;
+  let maintainedBytes = 0;
+  const bytesOf = (value) => utf8Length(stableStringify(value));
+  const counts = { dependencyReads: 0, refreshedRoots: 0, reruns: 0 };
+  const root = bindings[0];
+  const keyOf = (binding, row) => keyToken(binding.mapping.keys.map((name) => row[name]));
+  const sorted = (binding, values) => [...values].sort((a, b) =>
+    positions.get(binding.name).get(keyOf(binding, a)) - positions.get(binding.name).get(keyOf(binding, b)));
+  const signature = (binding, column) => JSON.stringify([binding, column]);
+  for (const edge of edges) for (const side of [edge.left, edge.right]) indices.set(signature(side.binding, side.column), new Map());
+  const bound = () => {
+    const size = inputCount + outputCount;
+    if (size > context.maxMaintained) throw new DbRuntimeError('JD2060', `the join dependency state exceeds live.maxMaintained (${context.maxMaintained})`);
+    if (maintainedBytes > context.maxBytes) throw new DbRuntimeError('JD2060', 'the join dependency state exceeds live.maxBytes');
+    return size;
+  };
+  const indexRow = (binding, row, insert) => {
+    const token = keyOf(binding, row);
+    for (const [signatureKey, index] of indices) {
+      const [name, column] = JSON.parse(signatureKey);
+      if (name !== binding.name) continue;
+      const value = row[column];
+      if (value === undefined || value === null) continue;
+      const key = stableStringify(value);
+      if (insert) {
+        if (!index.has(key)) index.set(key, new Set());
+        index.get(key).add(token);
+      }
+      else {
+        const set = index.get(key); set?.delete(token);
+        if (set?.size === 0) index.delete(key);
+      }
+    }
+  };
+  // A changed row walks equality edges in both directions to its bounded
+  // outer owners. The same walk works for multi-entity projection chains.
+  const connected = (binding, row) => {
+    const found = new Map(bindings.map((b) => [b.name, new Map()]));
+    const queue = [[binding, row]];
+    for (let i = 0; i < queue.length; i++) {
+      const [current, doc] = queue[i];
+      const key = keyOf(current, doc);
+      if (found.get(current.name).has(key)) continue;
+      found.get(current.name).set(key, doc);
+      // When finding owners, arriving at an owner completes this path.
+      // When evaluating one owner, crossing back to its siblings would
+      // widen a selective dependency into the entire connected component.
+      if (binding !== root && current === root) continue;
+      for (const edge of edges) {
+        const own = edge.left.binding === current.name ? edge.left : edge.right.binding === current.name ? edge.right : null;
+        if (own === null || doc[own.column] === undefined || doc[own.column] === null) continue;
+        const other = own === edge.left ? edge.right : edge.left;
+        if (binding === root && other.binding === root.name) continue;
+        const target = bindings.find((b) => b.name === other.binding);
+        for (const token of indices.get(signature(other.binding, other.column)).get(stableStringify(doc[own.column])) ?? []) {
+          const match = caches.get(other.binding).get(token);
+          if (!found.get(target.name).has(token)) queue.push([target, match]);
+        }
+      }
+      if (queue.length > context.maxMaintained * Math.max(1, edges.length * 2))
+        throw new DbRuntimeError('JD2060', 'the join dependency fan-out exceeds live.maxMaintained');
+    }
+    return found;
+  };
+  const refresh = (key) => {
+    const row = caches.get(root.name).get(key);
+    if (row === undefined) {
+      const previous = items.get(key);
+      if (previous !== undefined) { outputCount -= previous.length; maintainedBytes -= bytesOf(previous); }
+      items.delete(key); return;
+    }
+    const related = connected(root, row);
+    const input = Object.fromEntries(bindings.map((binding) => [binding.entity,
+      binding === root ? [row] : sorted(binding, related.get(binding.name).values())]));
+    const result = evaluate(input, context.externals);
+    const fresh = result === undefined ? [] : Array.isArray(result) ? result : [result];
+    const previous = items.get(key) ?? [];
+    outputCount += fresh.length - previous.length;
+    maintainedBytes += bytesOf(fresh) - (items.has(key) ? bytesOf(previous) : 0);
+    items.set(key, fresh.map((item, i) => stableStringify(previous[i]) === stableStringify(item) ? previous[i] : item));
+    counts.refreshedRoots++;
+    bound();
+  };
+  const flatten = () => sorted(root, caches.get(root.name).values()).flatMap((row) => items.get(keyOf(root, row)) ?? []);
+  return {
+    close() { for (const cache of caches.values()) cache.clear(); for (const index of indices.values()) index.clear();
+      for (const position of positions.values()) position.clear(); items.clear(); },
+    init() {
+      for (const binding of bindings) {
+        const document = [{ $subsequence: [{ $for: { it: entityRoot(binding.entity) }, $return: '$it' }, 0, context.maxMaintained + 1] }];
+        const rows = context.execute(document, { externals: context.externals });
+        for (const row of rows) {
+          const key = keyOf(binding, row);
+          caches.get(binding.name).set(key, row); indexRow(binding, row, true);
+          inputCount++; maintainedBytes += bytesOf(row);
+          bound();
+          positions.get(binding.name).set(key, context.dependencyPosition(binding.entity, key));
+        }
+        bound();
+      }
+      for (const key of caches.get(root.name).keys()) refresh(key);
+      return flatten();
+    },
+    entries: bound,
+    stats: () => ({ ...counts }),
+    apply(record, previousRows) {
+      const changed = new Map();
+      const affected = new Set();
+      for (const operation of record.patch) {
+        const [table, token] = operation.path.split('/').slice(1).map(decodeJSONPointerSegment);
+        const binding = bindings.find((b) => b.entity === table);
+        if (binding) changed.set(JSON.stringify([binding.name, token]), { binding, token });
+      }
+      for (const { binding, token } of changed.values()) {
+        const old = caches.get(binding.name).get(token);
+        if (binding === root) affected.add(token);
+        if (old !== undefined) for (const key of connected(binding, old).get(root.name).keys()) affected.add(key);
+      }
+      for (const { binding, token } of changed.values()) {
+        const cache = caches.get(binding.name);
+        const old = cache.get(token);
+        if (old !== undefined) { indexRow(binding, old, false); inputCount--; maintainedBytes -= bytesOf(old); }
+        const row = context.readDependency(binding.entity, token);
+        counts.dependencyReads++;
+        if (row === undefined) { cache.delete(token); positions.get(binding.name).delete(token); }
+        else {
+          cache.set(token, row); indexRow(binding, row, true);
+          inputCount++; maintainedBytes += bytesOf(row);
+          positions.get(binding.name).set(token, context.dependencyPosition(binding.entity, token));
+        }
+        bound();
+      }
+      for (const { binding, token } of changed.values()) {
+        const row = caches.get(binding.name).get(token);
+        if (row !== undefined) for (const key of connected(binding, row).get(root.name).keys()) affected.add(key);
+      }
+      for (const key of affected) refresh(key);
+      const next = flatten();
+      return context.diff(previousRows, next);
+    },
+  };
+}

package/src/live-nested.js

@@ -0,0 +1,120 @@
+//@ts-check
+/** Two-level groups use bounded per-parent recomputation over maintained leaves. */
+import { compileJsonQuery } from '@jarenjs/json/query';
+import { stableStringify } from '@jarenjs/core/object';
+import { DbRuntimeError } from './errors.js';
+import { utf8Length } from './cursor.js';
+
+/** Recognise nested groups whose parent key is a singular source member. @param {any} document */
+export function classifyNestedGroup(document) {
+  const inner = Array.isArray(document) && document.length === 1 ? document[0] : document;
+  if (inner === null || typeof inner !== 'object' || !inner.$for || !inner.$groupby) return null;
+  const bindings = Object.entries(inner.$for);
+  const groups = Object.entries(inner.$groupby);
+  if (bindings.length !== 1 || groups.length !== 1
+    || !Object.keys(inner).every((key) => ['$for', '$where', '$groupby', '$return'].includes(key))) return null;
+  const [binding, source] = bindings[0];
+  if (!(source === '$[*]' || (Array.isArray(source) && source.length === 1 && source[0] === '$[*]'))) return null;
+  const key = groups[0][1];
+  if (typeof key !== 'string' || !key.startsWith(`$${binding}.`) || !/^\$[A-Za-z_][A-Za-z0-9_]*\.[A-Za-z_][A-Za-z0-9_]*$/.test(key)) return null;
+  let count = 0;
+  let supported = true;
+  const allowed = new Set(['$for', '$where', '$groupby', '$return', '$count', '$sum', '$avg', '$min', '$max', '$default', '$eq', '$ne', '$lt', '$le', '$gt', '$ge', '$and', '$or']);
+  const visit = (node) => {
+    if (typeof node === 'string' && (node === '$' || node.startsWith('$.') || node.startsWith('$['))) supported = false;
+    if (Array.isArray(node)) { node.forEach(visit); return; }
+    if (node === null || typeof node !== 'object') return;
+    if (node.$groupby) count++;
+    if (node !== inner && node.$for) {
+      const nested = Object.values(node.$for);
+      if (nested.length !== 1 || !(nested[0] === `$${binding}`
+        || (Array.isArray(nested[0]) && nested[0].length === 1 && nested[0][0] === `$${binding}`))) supported = false;
+    }
+    for (const [name, value] of Object.entries(node)) {
+      if (node === inner && name === '$for') continue;
+      if (name.startsWith('$') && !allowed.has(name)) supported = false;
+      visit(value);
+    }
+  };
+  visit(inner);
+  if (count !== 2 || !supported) return null;
+  return { strategy: 'nested-group', inner, binding, key };
+}
+
+/** @param {any} description @param {any} context */
+export function nestedGroupStrategy(description, context) {
+  const { inner, binding, key } = description;
+  const keyOf = compileJsonQuery([{ $for: { [binding]: '$[*]' },
+    ...(inner.$where === undefined ? {} : { $where: inner.$where }), $return: [key] }]);
+  const evaluate = compileJsonQuery([inner]);
+  const docs = new Map();
+  const groups = new Map();
+  const results = new Map();
+  const positions = new Map();
+  let maintainedBytes = 0;
+  let resultCount = 0;
+  const bytesOf = (value) => utf8Length(stableStringify(value));
+  const stats = { refreshedGroups: 0, dependencyReads: 0, reruns: 0 };
+  const groupOf = (doc) => stableStringify(keyOf([doc], context.externals));
+  const sorted = (keys) => [...keys].sort((a, b) => positions.get(a) - positions.get(b));
+  const check = () => {
+    const entries = docs.size + resultCount;
+    if (entries > context.maxMaintained) throw new DbRuntimeError('JD2060', 'nested group dependencies exceed live.maxMaintained');
+    if (maintainedBytes > context.maxBytes) throw new DbRuntimeError('JD2060', 'nested group dependencies exceed live.maxBytes');
+    return entries;
+  };
+  const add = (token, doc) => {
+    const group = groupOf(doc);
+    docs.set(token, doc);
+    maintainedBytes += bytesOf(doc);
+    positions.set(token, context.rowPosition(token));
+    if (!groups.has(group)) groups.set(group, new Set());
+    groups.get(group).add(token);
+    return group;
+  };
+  const refresh = (group) => {
+    const keys = groups.get(group);
+    if (!keys || keys.size === 0) {
+      const previous = results.get(group);
+      if (previous !== undefined) { maintainedBytes -= bytesOf(previous); resultCount -= previous.length; }
+      groups.delete(group); results.delete(group); return;
+    }
+    const next = evaluate(sorted(keys).map((token) => docs.get(token)), context.externals);
+    const previous = results.get(group);
+    maintainedBytes += bytesOf(next) - (previous === undefined ? 0 : bytesOf(previous));
+    resultCount += next.length - (previous?.length ?? 0);
+    results.set(group, stableStringify(previous) === stableStringify(next) ? previous : next);
+    stats.refreshedGroups++;
+    check();
+  };
+  const flatten = () => [...groups.keys()].sort((a, b) =>
+    positions.get(sorted(groups.get(a))[0]) - positions.get(sorted(groups.get(b))[0]))
+    .flatMap((group) => results.get(group) ?? []);
+  return {
+    close() { docs.clear(); groups.clear(); results.clear(); positions.clear(); },
+    init() {
+      const source = [{ $subsequence: [{ $for: { it: '$[*]' }, $return: '$it' }, 0, context.maxMaintained + 1] }];
+      for (const doc of context.execute(source, { externals: context.externals })) add(context.keyOf(doc), doc);
+      check();
+      for (const group of groups.keys()) refresh(group);
+      return flatten();
+    }, entries: check, stats: () => ({ ...stats }),
+    apply(record, previousRows) {
+      const changes = context.touchedKeys(record, { whole: true, members: new Set() });
+      if (changes === null) return null;
+      const affected = new Set();
+      for (const token of changes.keys()) {
+        const previous = docs.get(token);
+        if (previous !== undefined) {
+          const group = groupOf(previous); affected.add(group); groups.get(group).delete(token);
+          docs.delete(token); positions.delete(token); maintainedBytes -= bytesOf(previous);
+        }
+        const doc = context.readRow(token); stats.dependencyReads++;
+        if (doc !== undefined) affected.add(add(token, doc));
+      }
+      check();
+      for (const group of affected) refresh(group);
+      return context.diff(previousRows, flatten());
+    },
+  };
+}

package/src/live.js

@@ -27,10 +27,12 @@ import { chain } from './driver.js';
 import { planQuery } from './plan.js';
 import { createSortedWindow } from './window.js';
 import { classifyEventTime, bucketStrategy, rollingStrategy } from './live-time.js';
+import { joinStrategy } from './live-join.js';
+import { classifyNestedGroup, nestedGroupStrategy } from './live-nested.js';
 
 /** The store-level live bounds and their defaults (§12: printed,
  * never silent). */
-export const LIVE_DEFAULTS = Object.freeze({ maxQueries: 64, maxMaintained: 10_000 });
+export const LIVE_DEFAULTS = Object.freeze({ maxQueries: 64, maxMaintained: 10_000, maxBytes: 4194304 });
 
 const AGGREGATE_MEMBERS = new Map([
   ['$count', 'count'], ['$sum', 'sum'], ['$avg', 'avg'],
@@ -263,6 +265,8 @@ export function classifyLiveQuery(document, queryShape, keyed, eventTime = null)
     return `'${forcing.construct}' — ${forcing.reason}`;
   };
   const { inner, whole, windowed, offset, limit, aggregate } = unwrapDocument(document);
+  const nested = classifyNestedGroup(inner);
+  if (nested !== null && !windowed && keyed && aggregate === null) return nested;
 
   // §13: a document that IS a temporal operator over the collection
   // answers to event time or re-runs, and never to the §7 table — the
@@ -855,9 +859,11 @@ function rerunStrategy(description, context) {
 /**
  * The store-level live-query registry: registration against the §12
  * bounds, capture-record delivery in commit order, lifecycle.
- * @param {{ maxQueries: number, maxMaintained: number }} bounds
+ * @param {{ maxQueries: number, maxMaintained: number, maxBytes?: number }} bounds
  */
 export function createLiveRegistry(bounds) {
+  if (bounds.maxBytes !== undefined && (!Number.isSafeInteger(bounds.maxBytes) || bounds.maxBytes < 1))
+    throw new TypeError('live.maxBytes must be a positive safe integer');
   /** @type {Set<any>} */
   const queries = new Set();
 
@@ -884,6 +890,12 @@ export function createLiveRegistry(bounds) {
       execute: definition.execute,
       readRow: definition.readRow,
       keyOf: definition.keyOf,
+      readDependency: definition.readDependency,
+      dependencyPosition: definition.dependencyPosition,
+      rowPosition: definition.rowPosition,
+      maxMaintained: bounds.maxMaintained,
+      maxBytes: bounds.maxBytes ?? LIVE_DEFAULTS.maxBytes,
+      diff: diffAgainst,
       // §8's touched-key reader, handed to the strategies rather than
       // imported by them: `live-time.js` maintains its own state and
       // must not become a second implementation of the pointer walk
@@ -891,7 +903,8 @@ export function createLiveRegistry(bounds) {
     };
     const STRATEGIES = {
       rows: rowsStrategy, window: windowStrategy, accumulator: accumulatorStrategy,
-      group: groupStrategy, bucket: bucketStrategy, rolling: rollingStrategy,
+      group: groupStrategy, bucket: bucketStrategy, rolling: rollingStrategy, join: joinStrategy, graph: joinStrategy,
+      'nested-group': nestedGroupStrategy,
     };
     const strategy = (STRATEGIES[classification.strategy] ?? rerunStrategy)(
       classification, context);
@@ -948,6 +961,7 @@ export function createLiveRegistry(bounds) {
           state.status = 'errored';
           state.error = error;
           queries.delete(query);
+          strategy.close?.();
           const failure = { error };
           for (const observer of observers) {
             try {
@@ -972,7 +986,7 @@ export function createLiveRegistry(bounds) {
         }
       },
       close() {
-        if (state.status === 'live') state.status = 'closed';
+        if (state.status === 'live') { state.status = 'closed'; strategy.close?.(); }
         queries.delete(query);
         observers.clear();
       },

package/src/logical-rows.js

@@ -0,0 +1,90 @@
+//@ts-check
+/** Logical row access through the store's validation and physical column plans. */
+import { chain } from './driver.js';
+import { keyToken } from './capture.js';
+import { DbRuntimeError } from './errors.js';
+
+/** @param {any} options */
+export function createLogicalRows({ connection, shapes, collectionCore, entityCore, capture, captureJoinDelete }) {
+  const dialect = connection.dialect;
+  const q = dialect.quoteIdentifier;
+  const statement = (sql, method, params = []) => chain(connection.prepare(sql), (s) => s[method](params));
+  const shapeOf = (table) => {
+    const shape = shapes.get(table);
+    if (!shape) throw new DbRuntimeError('JD2104', `replication names undeclared table '${table}'`);
+    return shape;
+  };
+  const keyColumns = (shape) => shape.keyIndexes.map((i) => shape.columns[i].name);
+  const partsOf = (shape, key) => {
+    if (shape.keyIndexes.length === 1) return [key];
+    let parts;
+    try { parts = JSON.parse(key); } catch { parts = null; }
+    if (!Array.isArray(parts) || parts.length !== shape.keyIndexes.length
+      || parts.some((part) => typeof part !== 'string' && !(typeof part === 'number' && Number.isFinite(part))))
+      throw new DbRuntimeError('JD2104', 'replication contains an invalid composite key');
+    return parts;
+  };
+  const where = (keys) => keys.map((key) => `${q(key)} = ?`).join(' AND ');
+  const entityKey = (shape, key) => Object.fromEntries(keyColumns(shape).map((name, i) => [name, partsOf(shape, key)[i]]));
+  const read = (table, key) => {
+    const shape = shapeOf(table);
+    if (shape.kind === 'collection') return collectionCore(table).get(key);
+    if (shape.kind === 'entity') return entityCore(table).get(entityKey(shape, key));
+    return chain(statement(`SELECT * FROM ${q(table)} WHERE ${where(keyColumns(shape))}`, 'get', partsOf(shape, key)),
+      (row) => row === undefined ? undefined : { ...row });
+  };
+  const write = (operation) => {
+    const { table, key, before, after } = operation;
+    const shape = shapeOf(table);
+    if (shape.kind === 'collection') {
+      const core = collectionCore(table);
+      return after === null ? core.delete(key) : core.put(after, key);
+    }
+    const keys = keyColumns(shape);
+    let names;
+    let params;
+    let expressions;
+    if (after !== null) {
+      if (keyToken(keys.map((name) => after[name])) !== key)
+        throw new DbRuntimeError('JD2104', 'replication cannot change a row identity');
+      if (shape.kind === 'entity') {
+        const core = entityCore(table);
+        core.validateOnly(after);
+        const { values, rest } = core.plan.split(after);
+        names = [...values.map((value) => value.name), 'doc'];
+        params = [...values.map((value) => value.value), JSON.stringify(rest)];
+        expressions = names.map((name) => name === 'doc' ? dialect.jsonEncode('?') : '?');
+      }
+      else {
+        if (Object.keys(after).length !== keys.length)
+          throw new DbRuntimeError('JD2104', 'a membership row contains only its two keys');
+        names = keys;
+        params = keys.map((name) => after[name]);
+        expressions = keys.map(() => '?');
+      }
+    }
+    const sql = after === null ? `DELETE FROM ${q(table)} WHERE ${where(keys)}`
+      : before === null ? `INSERT INTO ${q(table)} (${names.map(q).join(', ')}) VALUES (${expressions.join(', ')})`
+        : `UPDATE ${q(table)} SET ${names.map((name, i) => `${q(name)} = ${expressions[i]}`).join(', ')} WHERE ${where(keys)}`;
+    return chain(after === null && shape.kind === 'entity' ? captureJoinDelete?.(table, partsOf(shape, key)) : null,
+      () => chain(statement(sql, 'run', after === null ? partsOf(shape, key)
+      : before === null ? params : [...params, ...partsOf(shape, key)]), () => {
+      if (capture.mode === 'journal') capture.record(table, partsOf(shape, key), before, after);
+      }));
+  };
+  return { read, write, tables: [...shapes.keys()],
+    position: (table, key) => {
+      const shape = shapeOf(table);
+      return chain(statement(`SELECT ${dialect.rowIdentity()} AS position FROM ${q(table)} WHERE ${where(keyColumns(shape))}`, 'get', partsOf(shape, key)),
+        (row) => row?.position);
+    },
+    empty: () => {
+      let result = true;
+      const entries = [...shapes.keys()];
+      const next = (i) => i === entries.length ? result : chain(
+        statement(`SELECT 1 AS present FROM ${q(entries[i])} LIMIT 1`, 'get'),
+        (row) => { result &&= row === undefined; return next(i + 1); });
+      return next(0);
+    },
+  };
+}