@jarenjs/db 0.66.1 → 0.72.0

package/src/errors.js

@@ -51,6 +51,14 @@ export const DB_CODES = Object.freeze({
   JD0051: 'the demanded live mode is unavailable',
   JD0052: 'the live-query bound was reached',
   JD0053: 'the live event-time declaration is invalid',
+  JD0060: 'the replication document is invalid',
+  JD2100: 'replication encountered a sequence or causal gap',
+  JD2101: 'an envelope identity has a different payload or origin',
+  JD2102: 'the replica identity or model revision disagrees',
+  JD2103: 'the conflict resolver returned an invalid decision',
+  JD2104: 'a logical row disagrees with its replication history',
+  JD2105: 'replication requires an explicit snapshot reset',
+  JD2106: 'replication exceeded its operation bound',
   JD0020: "the migration's from-shape does not match the database",
   JD0021: 'the migration is missing a required data transform',
   JD0022: 'an applied migration disagrees with the history record',

package/src/index.js

@@ -98,3 +98,5 @@ export {
   describeValue, serializeResult,
 } from './jobs.js';
 export { createDagJobRunner, RUN_IDENTITY_NODE } from './dag-job.js';
+export { REPLICATION_VERSION, REPLICATION_DEFAULTS, normalizeFrontier,
+  normalizeReplication, normalizeReplicationSnapshot, encodeReplication, replicationIdentity } from './replication-format.js';

package/src/jobs.js

@@ -557,6 +557,12 @@ export function createJobEngine(options) {
     const lease = job?.lease;
     const generation = isLease(lease) ? lease.generation : 0;
     return {
+      inspect: (runId, nodeId) => chain(
+        prepared('cpIdentity', `SELECT value FROM "${JOB_CHECKPOINTS_TABLE}"
+          WHERE run_id=? AND node_id=? AND generation <= ?`).get([runId, nodeId, generation]),
+        (row) => chain(prepared('cpHasValues', `SELECT 1 AS present FROM "${JOB_CHECKPOINTS_TABLE}"
+          WHERE run_id=? AND node_id<>? AND generation <= ? LIMIT 1`).get([runId, nodeId, generation]),
+        (other) => ({ value: row === undefined ? undefined : JSON.parse(row.value), hasValues: other !== undefined }))),
       load: (runId) => chain(
         prepared('cpLoad', `SELECT node_id, value FROM "${JOB_CHECKPOINTS_TABLE}"
           WHERE run_id = ? AND generation <= ?`).all([runId, generation]),
@@ -772,6 +778,39 @@ export function createJobEngine(options) {
     });
   };
 
+  /**
+   * Explicitly discard one inactive run's checkpoints and start a new attempt
+   * budget. The caller must name the observed generation; a concurrent claim
+   * or reset invalidates that authorization. External task effects are not undone.
+   * @param {string} id
+   * @param {{ expectedGeneration: number, signal?: AbortSignal, deadline?: number }} resetOptions
+   */
+  const reset = (id, resetOptions) => {
+    if (typeof id !== 'string' || id === '') throw new TypeError('reset: id is a non-empty string');
+    const expected = resetOptions?.expectedGeneration;
+    if (!Number.isSafeInteger(expected) || expected < 0)
+      throw new TypeError('reset: expectedGeneration is the observed non-negative lease generation');
+    refuseCancelled(resetOptions, now, { abortCode: 'JD2081', aborted: 'reset() ran', passed: 'reset() ran' });
+    const at = now();
+    return connection.transaction(() => chain(
+      prepared('resetJob', `UPDATE "${JOBS_TABLE}" SET state='pending', attempts=0,
+        result=NULL, last_error=NULL, run_at=?, updated_at=?, lease_until=NULL,
+        lease_owner=NULL, lease_token=NULL, lease_generation=lease_generation+1
+        WHERE id=? AND lease_generation=? AND state<>'done'
+          AND (state<>'leased' OR lease_until<=?)`).run([at, at, id, expected, at]),
+      (out) => {
+        if (Number(out.changes ?? 0) === 0) return chain(get(id), (job) => {
+          const code = job?.state === 'leased' && job.leaseUntil > at ? 'JD2068'
+            : job !== undefined && job.leaseGeneration !== expected ? 'JD2066' : 'JD2065';
+          throw new DbRuntimeError(code,
+            `reset() refused: job '${id}' is unknown, completed, actively leased, or its generation changed; read it again before resetting`,
+            { docPath: '/jobs', collection: JOBS_TABLE, key: id });
+        });
+        return chain(prepared('resetCheckpoints', `DELETE FROM "${JOB_CHECKPOINTS_TABLE}" WHERE run_id=?`).run([id]),
+          (removed) => { wakeAll(); return { reset: true, discarded: Number(removed.changes ?? 0), generation: expected + 1 }; });
+      }));
+  };
+
   /**
    * Delete settled jobs (done, dead, cancelled) whose last change is
    * older than `settledBefore`, oldest first, at most `limit` of them,
@@ -1014,6 +1053,8 @@ export function createJobEngine(options) {
       // so a checkpoint can neither join an unrelated application
       // transaction nor still be writing when stop() has resolved
       attempt.checkpoints = {
+        inspect: (runId, nodeId) => io(() =>
+          checkpointsFor({ ...job, lease: attempt.lease }).inspect(runId, nodeId), 'a checkpoint identity read'),
         load: (runId) => io(() =>
           checkpointsFor({ ...job, lease: attempt.lease }).load(runId), 'a checkpoint read'),
         save: (runId, nodeId, value) => io(() =>
@@ -1297,6 +1338,7 @@ export function createJobEngine(options) {
     cancel,
     settledLocally,
     requeue,
+    reset,
     sweep,
     /** Stop every worker, bounded. Resolves to the per-worker outcome so
      * `close()` can report a handler it could not wait out rather than

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