@jarenjs/db 0.66.1 → 0.67.0

package/schemas/jaren-replication.schema.json

@@ -0,0 +1,82 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://jarenjs.dev/schemas/jaren-replication",
+  "title": "Portable logical replication transaction",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "$replication",
+    "replica",
+    "seq",
+    "frontier",
+    "model",
+    "operations"
+  ],
+  "properties": {
+    "$replication": {
+      "const": "0.1"
+    },
+    "replica": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128
+    },
+    "seq": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 9007199254740991
+    },
+    "frontier": {
+      "type": "object",
+      "propertyNames": {
+        "type": "string",
+        "minLength": 1,
+        "maxLength": 128
+      },
+      "additionalProperties": {
+        "type": "integer",
+        "minimum": 0,
+        "maximum": 9007199254740991
+      }
+    },
+    "model": {
+      "type": "string",
+      "minLength": 1
+    },
+    "operations": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "table",
+          "key",
+          "before",
+          "after"
+        ],
+        "properties": {
+          "table": {
+            "type": "string",
+            "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+          },
+          "key": {
+            "type": "string"
+          },
+          "before": {
+            "type": [
+              "object",
+              "null"
+            ]
+          },
+          "after": {
+            "type": [
+              "object",
+              "null"
+            ]
+          }
+        }
+      }
+    }
+  }
+}

package/src/capture.js

@@ -328,7 +328,8 @@ export function translateOperations(connection, shapes, operations) {
  *   mode: 'session' | 'journal',
  *   log: boolean, retention: number,
  *   now?: () => number,
- *   bracket?: (fn: () => any) => any }} options - `now` is the clock a
+ *   bracket?: (fn: () => any) => any,
+ *   beforeCommit?: (patch: any[], context: any) => any }} options - `now` is the clock a
  *   delivery is stamped with (the store's runtime record); the platform's
  *   when absent. `bracket` runs the first-open DDL (the store's immediate
  *   transaction on a writable store); bare when absent
@@ -353,6 +354,7 @@ export function createCaptureEngine(options) {
   // from the durable row — never an answer to a watermark question
   let seq = 0;
   let depth = 0;
+  let context = null;
   /** @type {any} */
   let session = null;
   /** @type {any[]} */
@@ -572,6 +574,7 @@ export function createCaptureEngine(options) {
     depth = 1;
     const cleanupFailure = () => {
       depth = 0;
+      context = null;
       if (session !== null) {
         session.close();
         session = null;
@@ -584,7 +587,7 @@ export function createCaptureEngine(options) {
       else journal = [];
       outcome = connection.transaction((...scopeArgs) =>
         chain(fn(...scopeArgs), (result) =>
-          chain(collect(), (patch) => {
+          chain(collect(), (patch) => chain(options.beforeCommit?.(patch, context), () => {
             if (patch.length === 0) return { result, delivery: null };
             const at = clock();
             return chain(persist(patch, at), () => ({
@@ -597,7 +600,7 @@ export function createCaptureEngine(options) {
                 patch,
               },
             }));
-          })));
+          }))));
     }
     catch (error) {
       cleanupFailure();
@@ -605,6 +608,7 @@ export function createCaptureEngine(options) {
     }
     const finish = (bundle) => {
       depth = 0;
+      context = null;
       if (bundle.delivery !== null) pendingDeliveries.push(bundle.delivery);
       deliver();
       return bundle.result;
@@ -669,6 +673,12 @@ export function createCaptureEngine(options) {
     mark,
     truncate,
     record,
+    // Metadata belongs to this capture transaction and is cleared on every
+    // settlement, including a failure while collecting or persisting changes.
+    setContext(value) {
+      if (depth === 0) throw new TypeError('capture context needs an active transaction');
+      context = value;
+    },
     observe(fn) {
       if (typeof fn !== 'function')
         throw new TypeError('observe needs a function');

package/src/cursor.js

@@ -384,11 +384,7 @@ export function drainPage(cursor, options) {
     if (maxBytes !== null && bytes + size > maxBytes) {
       if (items.length === 0) {
         return chain(cursor.return(), () => {
-          throw new DbRuntimeError('JD2074',
-            `the next item is ${size} serialised bytes, more than the page's maxBytes bound of `
-            + `${maxBytes}; the continuation was not advanced — raise the bound, or bound the `
-            + "item itself (an include's maxBytes, a narrower document)",
-            { errors: [{ bytes: size, maxBytes, at: continuationOf(item) }] });
+          assertItemBytes(size, maxBytes, continuationOf(item));
         });
       }
       hasMore = true;
@@ -409,3 +405,13 @@ export function drainPage(cursor, options) {
   };
   return settling(step, () => cursor.return());
 }
+
+/** The shared refusal for an indivisible item, including a replicated transaction.
+ * @param {number} size @param {number} maxBytes @param {any} [at] */
+export function assertItemBytes(size, maxBytes, at) {
+  if (size > maxBytes) throw new DbRuntimeError('JD2074',
+    `the next item is ${size} serialised bytes, more than the page's maxBytes bound of `
+    + `${maxBytes}; the continuation was not advanced — raise the bound, or bound the `
+    + "item itself (an include's maxBytes, a narrower document)",
+    { errors: [{ bytes: size, maxBytes, at }] });
+}

package/src/dialect.js

@@ -171,7 +171,7 @@ function normalizeCapabilities(declared) {
  *   usesIndex: (line: string, index: string) => boolean,
  *   excludedRef: (columnSql: string) => string,
  *   tx: { begin: string, beginImmediate: string, commit: string,
- *     rollback: string,
+ *     rollback: string, deferForeignKeys?: string,
  *     savepoint: (n: string) => string, release: (n: string) => string,
  *     rollbackTo: (n: string) => string },
  *   pragma?: { set: (name: string, value: number | string) => string,

package/src/dialects/sqlite.js

@@ -401,6 +401,7 @@ export const sqliteDialect = createDialect({
   tx: {
     begin: 'BEGIN',
     beginImmediate: 'BEGIN IMMEDIATE',
+    deferForeignKeys: 'PRAGMA defer_foreign_keys = ON',
     commit: 'COMMIT',
     rollback: 'ROLLBACK',
     savepoint: (n) => `SAVEPOINT ${quoteIdentifier(n)}`,

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