@jarenjs/db 0.73.0 → 0.75.0

package/src/dialects/check-read.js

@@ -0,0 +1,151 @@
+//@ts-check
+/** Recover only a complete scalar enum CHECK; unfamiliar SQL remains a loss. */
+
+/** Tokenize catalog SQL without treating quoted text or comments as syntax.
+ * @param {string} sql @returns {{ kind: string, value: string }[]} */
+function tokensOf(sql) {
+  const tokens = [];
+  for (let i = 0; i < sql.length;) {
+    const c = sql[i];
+    if (/\s/.test(c)) { i++; continue; }
+    if (sql.startsWith('--', i)) {
+      const end = sql.indexOf('\n', i + 2); i = end < 0 ? sql.length : end + 1; continue;
+    }
+    if (sql.startsWith('/*', i)) {
+      const end = sql.indexOf('*/', i + 2);
+      if (end < 0) return [];
+      i = end + 2; continue;
+    }
+    if (c === "'" || c === '"' || c === '`') {
+      let value = '';
+      let closed = false;
+      for (i++; i < sql.length; i++) {
+        if (sql[i] !== c) { value += sql[i]; continue; }
+        if (sql[i + 1] === c) { value += c; i++; continue; }
+        i++; closed = true; break;
+      }
+      if (!closed) return [];
+      tokens.push({ kind: c === "'" ? 'string' : 'identifier', value });
+      continue;
+    }
+    const number = /^(?:[0-9]+(?:\.[0-9]*)?|\.[0-9]+)(?:[eE][+-]?[0-9]+)?/.exec(sql.slice(i));
+    if (number) { tokens.push({ kind: 'number', value: number[0] }); i += number[0].length; continue; }
+    const word = /^[A-Za-z_][A-Za-z_0-9$]*/.exec(sql.slice(i));
+    if (word) { tokens.push({ kind: 'word', value: word[0] }); i += word[0].length; continue; }
+    const value = sql.startsWith('::', i) ? '::' : c;
+    tokens.push({ kind: 'symbol', value }); i += value.length;
+  }
+  return tokens;
+}
+
+/** @param {any[]} tokens @returns {{ column: string, values: any[] } | null} */
+function enumOf(tokens) {
+  let at = 0;
+  const take = (value) => {
+    const token = tokens[at];
+    if (token && token.kind !== 'string' && token.kind !== 'identifier'
+      && token.value.toUpperCase() === value) { at++; return true; }
+    return false;
+  };
+  const scalar = () => {
+    if (take('(')) {
+      const value = scalar();
+      return value === undefined || !take(')') ? undefined : cast(value);
+    }
+    const negative = take('-');
+    const token = tokens[at++];
+    if (!token) return undefined;
+    let value;
+    if (token.kind === 'number') value = Number(`${negative ? '-' : ''}${token.value}`);
+    else if (negative) return undefined;
+    else if (token.kind === 'string') value = token.value;
+    else if (token.kind === 'word' && /^(true|false)$/i.test(token.value)) value = token.value.toLowerCase() === 'true';
+    else return undefined;
+    if (typeof value === 'number' && !Number.isFinite(value)) return undefined;
+    return cast(value);
+  };
+  const cast = (value) => {
+    if (!take('::')) return value;
+    // Only exact scalar casts emitted by the catalog are understood.
+    // Rounding casts could change the enum's members.
+    const type = tokens[at++];
+    if (type?.kind !== 'word') return undefined;
+    const name = type.value.toLowerCase();
+    if (typeof value === 'string' && name === 'text') return value;
+    if (typeof value === 'boolean' && name === 'boolean') return value;
+    // PostgreSQL renders negative constants as quoted numeric casts,
+    // e.g. ('-1'::integer)::numeric. Decode only finite numeric syntax.
+    if (typeof value === 'string' && ['numeric', 'integer', 'bigint', 'smallint'].includes(name)
+      && /^-?(?:[0-9]+(?:\.[0-9]*)?|\.[0-9]+)(?:[eE][+-]?[0-9]+)?$/.test(value)) {
+      const number = Number(value);
+      if (!Number.isFinite(number) || (['integer', 'bigint', 'smallint'].includes(name)
+        && !Number.isSafeInteger(number))) return undefined;
+      return number;
+    }
+    if (typeof value === 'number' && name === 'numeric') return value;
+    if (typeof value === 'number' && ['integer', 'bigint', 'smallint'].includes(name)
+      && Number.isSafeInteger(value)) return value;
+    if (typeof value === 'number' && name === 'double' && take('PRECISION')) return value;
+    return undefined;
+  };
+  const expression = () => {
+    if (take('(')) {
+      const result = expression();
+      return result === null || !take(')') ? null : result;
+    }
+    const column = tokens[at++];
+    if (!column || !['identifier', 'word'].includes(column.kind)) return null;
+    const any = take('=');
+    // A singleton IN list is normalized to scalar equality by PostgreSQL.
+    if (any && !take('ANY')) {
+      const value = scalar();
+      return value === undefined ? null : { column: column.value, values: [value] };
+    }
+    if (any ? !(take('(') && take('ARRAY') && take('[')) : !(take('IN') && take('('))) return null;
+    const values = [];
+    do {
+      const value = scalar();
+      if (value === undefined) return null;
+      if (!values.includes(value)) values.push(value);
+    } while (take(','));
+    if (any ? !(take(']') && take(')')) : !take(')')) return null;
+    return { column: column.value, values };
+  };
+  const result = expression();
+  return at === tokens.length ? result : null;
+}
+
+/** SQLite retains the CREATE text, including inline and table CHECKs.
+ * @param {any[]} rows @returns {any[]} neutral constraints */
+export function sqliteChecks(rows) {
+  const checks = [];
+  for (const row of rows) {
+    const tokens = tokensOf(String(row.sql ?? ''));
+    // A column's inherited collation changes IN equality even when the
+    // CHECK itself names no collation. Refuse conservatively per table.
+    const collated = tokens.some((token, i) => token.kind === 'word'
+      && token.value.toUpperCase() === 'COLLATE'
+      && tokens[i + 1]?.value.toUpperCase() !== 'BINARY');
+    for (let i = 0; i < tokens.length; i++) {
+      if (tokens[i].kind !== 'word' || tokens[i].value.toUpperCase() !== 'CHECK'
+        || tokens[i + 1]?.value !== '(') continue;
+      const start = i + 2;
+      let depth = 1;
+      for (i = start; i < tokens.length; i++) {
+        if (tokens[i].kind !== 'symbol') continue;
+        if (tokens[i].value === '(') depth++;
+        if (tokens[i].value === ')' && --depth === 0) break;
+      }
+      checks.push({ name: `check_${checks.length + 1}`,
+        ...(collated ? null : enumOf(tokens.slice(start, i))) });
+    }
+  }
+  return checks;
+}
+
+/** PostgreSQL exposes each CHECK expression separately.
+ * @param {any[]} rows @returns {any[]} neutral constraints */
+export function postgresChecks(rows) {
+  return rows.map((row) => ({ name: String(row.name),
+    ...(row.unsafe_collation ? null : enumOf(tokensOf(String(row.expression ?? '')))) }));
+}

package/src/dialects/postgres.js

@@ -39,6 +39,7 @@
 
 import { createDialect } from '../dialect.js';
 import { readExpression } from './expression-read.js';
+import { postgresChecks } from './check-read.js';
 
 /** PostgreSQL truncates an identifier past this many BYTES, silently
  * and with only a notice — so two long generated names would collide
@@ -519,6 +520,7 @@ export function postgresDialect(options = undefined) {
     memberPathOf,
     expressionOf,
     // the catalog already answers one row per generated column
+    readChecks: postgresChecks,
     readGenerated: (rows) => rows.map((row) => ({
       name: String(row.name), expression: String(row.expression ?? ''),
     })),
@@ -571,7 +573,8 @@ export function postgresDialect(options = undefined) {
       // key's is the engine's own
       indexes: (table) =>
         'SELECT ci.relname AS name, CASE WHEN i.indisunique THEN 1 ELSE 0 END AS uniq, '
-        + "CASE WHEN i.indisprimary THEN 'pk' ELSE 'c' END AS origin "
+        + "CASE WHEN i.indisprimary THEN 'pk' ELSE 'c' END AS origin, "
+        + 'CASE WHEN i.indpred IS NULL THEN 0 ELSE 1 END AS partial '
         + 'FROM pg_index i JOIN pg_class ci ON ci.oid = i.indexrelid '
         + 'JOIN pg_class ct ON ct.oid = i.indrelid '
         + 'JOIN pg_namespace n ON n.oid = ct.relnamespace '
@@ -584,7 +587,7 @@ export function postgresDialect(options = undefined) {
         + 'JOIN pg_class ci ON ci.oid = i.indexrelid '
         + 'JOIN pg_namespace n ON n.oid = ci.relnamespace '
         + 'CROSS JOIN LATERAL unnest(i.indkey::int2[]) WITH ORDINALITY AS k(attnum, ord) '
-        + 'JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = k.attnum '
+        + 'LEFT JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = k.attnum '
         + `WHERE ci.relname = ${stringLiteral(index)} AND ${inNamespace} ORDER BY k.ord`,
       // every table this store might own; a view is reported rather
       // than derived, and the engine's own schemas are never in scope
@@ -602,6 +605,15 @@ export function postgresDialect(options = undefined) {
         + 'JOIN pg_namespace n ON n.oid = c.relnamespace '
         + `WHERE c.relname = ${stringLiteral(table)} AND ${inNamespace} `
         + "AND a.attgenerated <> '' ORDER BY a.attnum",
+      checks: (table) =>
+        'SELECT c.conname AS name, pg_get_expr(c.conbin, c.conrelid) AS expression, '
+        + 'EXISTS (SELECT 1 FROM pg_attribute ca JOIN pg_collation co ON co.oid = ca.attcollation '
+        + 'WHERE ca.attrelid = c.conrelid AND ca.attnum = ANY(c.conkey) '
+        + 'AND NOT co.collisdeterministic) AS unsafe_collation '
+        + 'FROM pg_constraint c JOIN pg_class ct ON ct.oid = c.conrelid '
+        + 'JOIN pg_namespace n ON n.oid = ct.relnamespace '
+        + `WHERE c.contype = 'c' AND ct.relname = ${stringLiteral(table)} AND ${inNamespace} `
+        + 'ORDER BY c.conname',
       foreignKeyList: (table) => {
         const action = (column) => `CASE ${column} `
           + "WHEN 'a' THEN 'NO ACTION' WHEN 'r' THEN 'RESTRICT' WHEN 'c' THEN 'CASCADE' "

package/src/dialects/sqlite.js

@@ -11,6 +11,7 @@
 import { createDialect } from '../dialect.js';
 import { rtreeDdl } from './rtree-ddl.js';
 import { readExpression } from './expression-read.js';
+import { sqliteChecks } from './check-read.js';
 
 /** @param {string} s */
 function quoteIdentifier(s) {
@@ -439,7 +440,7 @@ export const sqliteDialect = createDialect({
     columns: (table) =>
       `SELECT name, type, hidden FROM pragma_table_xinfo(${stringLiteral(table)})`,
     indexes: (table) =>
-      `SELECT name, "unique" AS uniq, origin FROM pragma_index_list(${stringLiteral(table)})`,
+      `SELECT name, "unique" AS uniq, origin, partial FROM pragma_index_list(${stringLiteral(table)})`,
     indexColumns: (index) =>
       `SELECT name FROM pragma_index_info(${stringLiteral(index)})`,
     foreignKeysOn: () => 'SELECT foreign_keys AS enabled FROM pragma_foreign_keys',
@@ -467,10 +468,13 @@ export const sqliteDialect = createDialect({
     // the CREATE text is where a generated column's expression lives
     generated: (table) =>
       `SELECT sql FROM sqlite_schema WHERE type = 'table' AND name = ${stringLiteral(table)}`,
+    checks: (table) =>
+      `SELECT sql FROM sqlite_schema WHERE type = 'table' AND name = ${stringLiteral(table)}`,
     // the whole declared schema, for shape-equality comparison after a
     // rebuild: every object that carries SQL text, in a stable order
     schemaDump: () =>
       "SELECT type, name, tbl_name AS owner, sql FROM sqlite_schema "
       + "WHERE sql IS NOT NULL ORDER BY type, name",
   },
+  readChecks: sqliteChecks,
 });

package/src/emit.js

@@ -26,10 +26,21 @@ import { codePointPrefixSuccessor } from '@jarenjs/core/string';
  */
 export class UnrepresentablePath extends Error {}
 
+/** A comparison of schema-compatible paths is false if either is absent.
+ * @param {any} pred @param {(ref: any) => { value: string, present: string }} read */
+function compareRefs(pred, read) {
+  const left = read(pred.left);
+  const right = read(pred.right);
+  const symbol = { eq: '=', ne: '<>', lt: '<', le: '<=', gt: '>', ge: '>=' }[pred.op];
+  return `(${left.present} AND ${right.present} AND ${left.value} ${symbol} ${right.value})`;
+}
+
 /**
  * @typedef {{ external: string } | { literal: unknown } |
  *   { derived: { kind: 'bboxAxis', external: string,
  *     axis: 'w' | 's' | 'e' | 'n' } } |
+ *   { derived: { kind: 'circleAxis', centre: { external: string } | { literal: unknown },
+ *     radius: { external: string } | { literal: unknown }, axis: 'w' | 's' | 'e' | 'n' } } |
  *   { typed: { seek: string, type: 'number' | 'text' } }} ParamSlot
  *   Four kinds, closed. A DERIVED slot is the escape for a value SQL
  *   cannot bind at all: a GeoJSON region arrives as an external object,
@@ -85,7 +96,7 @@ function stropForm(dialect, param, valueSql, pred) {
  */
 function slotName(slot) {
   if ('external' in slot) return slot.external;
-  if ('derived' in slot) return slot.derived.external;
+  if ('derived' in slot) return slot.derived.kind === 'bboxAxis' ? slot.derived.external : 'circle';
   if ('typed' in slot) return slot.typed.seek;
   return 'value';
 }
@@ -107,6 +118,8 @@ const BOX_AT = { w: 0, s: 1, e: 2, n: 3 };
  * @returns {string}
  */
 function probeEdge(probe, param, axis) {
+  if ('circle' in probe)
+    return param({ derived: { kind: 'circleAxis', ...probe.circle, axis } });
   return 'box' in probe
     ? param({ literal: probe.box[BOX_AT[axis]] })
     : param({ derived: { kind: 'bboxAxis', external: probe.ext, axis } });
@@ -120,6 +133,11 @@ function probeEdge(probe, param, axis) {
  * @returns {{ sql: string, slots: ParamSlot[] }}
  */
 export function emitPlan(plan, dialect, physical) {
+  if (plan.group !== null && plan.aggregate?.fn === 'count') {
+    const inner = emitPlan({ ...plan, aggregate: null }, dialect, physical);
+    return { ...inner, sql: `SELECT COUNT(*) AS ${dialect.quoteIdentifier('value')} `
+      + `FROM (${inner.sql}) AS ${dialect.quoteIdentifier('_groups')}` };
+  }
   const q = dialect.quoteIdentifier;
   const docColumn = q(physical.docColumn);
   /** @type {ParamSlot[]} */
@@ -297,6 +315,9 @@ export function emitPlan(plan, dialect, physical) {
    */
   const emitPred = (pred) => {
     switch (pred.p) {
+      case 'refCmp':
+        return compareRefs(pred, (ref) => ({ value: valueOf(ref, kindOf(ref)),
+          present: `${typeOf(ref)} IS NOT NULL` }));
       case 'and':
         return `(${pred.items.map(emitPred).join(' AND ')})`;
       case 'or':
@@ -439,9 +460,12 @@ export function emitPlan(plan, dialect, physical) {
       + `${q(plan.rank.alternatives[0].column)} AS ${q('vec')}`
     : plan.group !== null
       ? [...plan.group.keys.map((key, i) => projectedPair(key.ref, `k${i}`)),
-        ...plan.group.aggregates.map((entry, i) =>
-          `${dialect.groupAggregate(entry.fn, foldValue(entry.fn, entry.ref))} `
-          + `AS ${q(`a${i}`)}`)].join(', ')
+        ...plan.group.aggregates.map((entry, i) => {
+          const value = dialect.groupAggregate(entry.fn, foldValue(entry.fn, entry.ref));
+          // Empty sums order as zero, the same value reconstruction
+          // returns. Naming that value also works in PostgreSQL ORDER BY.
+          return `${entry.empty === 'zero' ? `COALESCE(${value}, 0)` : value} AS ${q(`a${i}`)}`;
+        })].join(', ')
       : plan.bucket !== null
         ? [`${bucketSql} AS ${q(plan.bucket.as)}`,
         ...plan.bucket.aggregates.map((entry) =>
@@ -461,7 +485,8 @@ export function emitPlan(plan, dialect, physical) {
             // a projection TREE: the same value/type pair per DISTINCT
             // leaf, numbered, and nothing else — the document blob is
             // never selected, and a leaf named twice is fetched once
-            : plan.project.leaves.map((ref, i) => projectedPair(ref, String(i))).join(', '))
+            : (plan.project.leaves.map((ref, i) => projectedPair(ref, String(i))).join(', ')
+              || `1 AS ${q('_row')}`))
         : plan.aggregate.fn === 'count'
           ? `COUNT(*) AS ${q('value')}`
           // a REGISTERED aggregate calls the function the store
@@ -486,10 +511,11 @@ export function emitPlan(plan, dialect, physical) {
     // the groups' order: the engine's own order of first appearance —
     // over a collection, each group's earliest row identity — or the
     // key ordering an `$orderby` declared
-    sql += ` ORDER BY ${plan.group.order === 'first-seen'
-      ? dialect.groupAggregate('min', dialect.rowIdentity())
-      : plan.group.order.map((term) => `${q(`vk${term.index}`)} `
-        + `${term.desc ? 'DESC' : 'ASC'}${dialect.orderNulls(term.nullsFirst)}`).join(', ')}`;
+    const order = plan.group.order === 'first-seen' ? []
+      : plan.group.order.map((term) => `${q(term.aggregate === undefined ? `vk${term.index}` : `a${term.aggregate}`)} `
+        + `${term.desc ? 'DESC' : 'ASC'}${dialect.orderNulls(term.nullsFirst)}`);
+    order.push(dialect.groupAggregate('min', dialect.rowIdentity()));
+    sql += ` ORDER BY ${order.join(', ')}`;
   }
   if (plan.bucket !== null) {
     // `first-seen` is the engine's own group order (§6.5, first
@@ -518,7 +544,7 @@ export function emitPlan(plan, dialect, physical) {
     terms.push(dialect.rowIdentity());
     sql += ` ORDER BY ${terms.join(', ')}`;
   }
-  if (plan.window !== null && plan.aggregate === null && plan.group === null) {
+  if (plan.window !== null && plan.aggregate === null) {
     sql += ` ${dialect.limitClause(plan.window.limit, plan.window.offset)}`;
   }
   return { sql, slots, seeks: (plan.seeks ?? []).map((seek) => emitSeek(seek)) };
@@ -682,6 +708,15 @@ export function createEntityPredicateEmitters(dialect, param) {
   };
 
   const emitPred = (aliasSql, docSql, pred) => {
+    if (pred.p === 'refCmp') return compareRefs(pred, (ref) => {
+      if (ref.flavor === 'entity-column') {
+        const value = `${aliasSql}.${q(ref.column)}`;
+        return { value, present: `${value} IS NOT NULL` };
+      }
+      // Epoch columns retain the document's lexical comparison rule.
+      return { value: memberAt(docSql, ref, ref.type === 'string' ? 'text' : 'number'),
+        present: `${dialect.jsonTypeOf(docSql, pathTextOf(ref))} IS NOT NULL` };
+    });
     if (pred.p === 'and')
       return `(${pred.items.map((item) => emitPred(aliasSql, docSql, item)).join(' AND ')})`;
     if (pred.p === 'or')
@@ -745,8 +780,13 @@ export function emitEntityPlan(plan, dialect, physicalOf) {
 
   const entityOf = new Map(plan.bindings.map((binding) => [binding.name, binding.entity]));
   const emitters = createEntityPredicateEmitters(dialect, param);
-  const emitPred = (bindingName, pred) =>
-    emitters.emitPred(aliasOf(bindingName), docOf(bindingName), pred);
+  const emitPred = (bindingName, pred) => {
+    if (pred.p === 'binding') return emitPred(pred.binding, pred.filter);
+    if (pred.p === 'and' || pred.p === 'or') return `(${pred.items
+      .map((item) => emitPred(bindingName, item)).join(pred.p === 'and' ? ' AND ' : ' OR ')})`;
+    if (pred.p === 'not') return `NOT (${emitPred(bindingName, pred.item)})`;
+    return emitters.emitPred(aliasOf(bindingName), docOf(bindingName), pred);
+  };
 
   /**
    * One projected member of a binding: its value beside its JSON type,
@@ -794,7 +834,8 @@ export function emitEntityPlan(plan, dialect, physicalOf) {
     : plan.project != null
       // `p`-prefixed, because a bare `t0` would collide with this
       // plan's own binding aliases
-      ? plan.project.leaves.map((leaf, i) => projectedPair(leaf, `p${i}`)).join(', ')
+      ? (plan.project.leaves.map((leaf, i) => projectedPair(leaf, `p${i}`)).join(', ')
+        || `1 AS ${q('_row')}`)
       // a join-table root IS its two key columns: it has no document
       // column, so the merge is handed an empty one
       : physicalOf(entityOf.get(ret)).document === false

package/src/introspect.js

@@ -95,13 +95,16 @@ function readTable(connection, table) {
               (rows) => withColumns(i + 1, [...out, {
                 name: String(declared[i].name),
                 unique: Number(declared[i].uniq) !== 0,
-                columns: rows.map((row) => String(row.name)),
+                partial: Number(declared[i].partial ?? 0) !== 0,
+                columns: rows.map((row) => row.name == null ? null : String(row.name)),
               }]));
           };
           return chain(withColumns(0, []), (indexes) =>
             chain(keyIndex === undefined
               ? []
-              : all(dialect.introspect.indexColumns(String(keyIndex.name))), (keyRows) => ({
+              : all(dialect.introspect.indexColumns(String(keyIndex.name))), (keyRows) =>
+              chain(dialect.introspect.checks === undefined ? []
+                : all(dialect.introspect.checks(table)), (checkRows) => ({
               name: table,
               primaryKey: keyRows.map((row) => String(row.name)),
               columns: columnRows.map((row) => ({
@@ -111,6 +114,7 @@ function readTable(connection, table) {
               })),
               generated: dialect.readGenerated(generatedRows),
               indexes,
+              checks: dialect.readChecks?.(checkRows) ?? [],
               foreignKeys: fkRows.map((row) => ({
                 column: String(row.source_column),
                 target: String(row.target),
@@ -118,7 +122,7 @@ function readTable(connection, table) {
                   ? null : String(row.target_column),
                 onDelete: String(row.on_delete ?? 'NO ACTION').toUpperCase(),
               })),
-            })));
+            }))));
         }))));
 }
 
@@ -229,6 +233,11 @@ function deriveCollection(dialect, table, report, keys, functionNames) {
 
   const indexes = [];
   for (const index of table.indexes) {
+    if (index.partial || index.columns.some((column) => column === null)) {
+      report(loss('unmapped-index', `${table.name}.${index.name}`,
+        'a partial predicate or expression term cannot be represented by an unconditional member index'));
+      continue;
+    }
     if (index.columns.length === 1 && computed.has(index.columns[0])) {
       const declared = { name: indexName(table.name, index.name),
         expression: computed.get(index.columns[0]) };
@@ -416,9 +425,10 @@ function deriveEntity(dialect, table, report) {
   const uniqueColumns = new Set();
   const indexedColumns = new Set();
   for (const index of table.indexes) {
-    if (index.columns.length !== 1) {
+    if (index.partial || index.columns.some((column) => column === null)
+      || index.columns.length !== 1) {
       report(loss('unmapped-index', `${table.name}.${index.name}`,
-        'a composite index over an entity is not a property-level declaration'));
+        'a partial, expression or composite entity index is not a property-level declaration'));
       continue;
     }
     (index.unique ? uniqueColumns : indexedColumns).add(index.columns[0]);
@@ -461,6 +471,26 @@ function deriveEntity(dialect, table, report) {
     if (Object.keys(entity).length > 0) property['x-entity'] = entity;
     properties[column.name] = property;
   }
+  for (const check of table.checks) {
+    const property = properties[check.column];
+    const family = property?.type === 'integer' ? 'number'
+      : property?.type === 'string' ? 'string' : property?.type;
+    if (check.values === undefined || property === undefined
+      || check.values.some((value) => typeof value !== family
+        || (property.type === 'integer' && !Number.isInteger(value)))) {
+      report(loss('unmapped-constraint', `${table.name}.${check.name}`,
+        'the CHECK is not a complete scalar enum of the mapped column type'));
+      continue;
+    }
+    // Several enum CHECKs constrain the same column by intersection.
+    const values = property.enum === undefined ? check.values
+      : property.enum.filter((value) => check.values.includes(value));
+    if (values.length === 0) {
+      report(loss('unmapped-constraint', `${table.name}.${check.name}`,
+        'the enum CHECKs have an empty intersection, which a non-empty schema enum cannot declare'));
+    }
+    else property.enum = values;
+  }
   report(loss('document-members', table.name,
     'an entity\'s document column holds every property the mapping did not give a column, '
     + 'and those are not in the physical shape'));
@@ -530,6 +560,8 @@ export function introspectModel(connection, options = undefined) {
       if (joinTables.has(table.name)) continue;
       if (looksLikeCollection(dialect, table)) {
         collections[table.name] = deriveCollection(dialect, table, add, options?.keys, byName);
+        for (const check of table.checks) add(loss('unmapped-constraint', `${table.name}.${check.name}`,
+          'a CHECK over physical collection columns does not constrain the document schema'));
         continue;
       }
       const hasDocument = table.columns.some((column) => column.name === DOC_COLUMN);

package/src/live-nested.js

@@ -1,5 +1,5 @@
 //@ts-check
-/** Two-level groups use bounded per-parent recomputation over maintained leaves. */
+/** Collection groups use bounded per-group recomputation over maintained leaves. */
 import { compileJsonQuery } from '@jarenjs/json/query';
 import { stableStringify } from '@jarenjs/core/object';
 import { DbRuntimeError } from './errors.js';
@@ -47,6 +47,8 @@ export function nestedGroupStrategy(description, context) {
   const keyOf = compileJsonQuery([{ $for: { [binding]: '$[*]' },
     ...(inner.$where === undefined ? {} : { $where: inner.$where }), $return: [key] }]);
   const evaluate = compileJsonQuery([inner]);
+  const aggregate = description.aggregate === undefined ? null
+    : compileJsonQuery([{ [description.aggregate]: '$[*]' }]);
   const docs = new Map();
   const groups = new Map();
   const results = new Map();
@@ -55,18 +57,25 @@ export function nestedGroupStrategy(description, context) {
   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 groupOf = (doc) => {
+    const keys = keyOf([doc], context.externals);
+    return keys.length === 0 ? null : stableStringify(keys);
+  };
   const sorted = (keys) => [...keys].sort((a, b) => positions.get(a) - positions.get(b));
   const check = () => {
-    const entries = docs.size + resultCount;
+    const entries = docs.size + resultCount + (aggregate === null ? 0 : 1);
     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);
+    if (group === null) return null;
+    const bytes = bytesOf(doc);
+    if (docs.size + resultCount + 1 > context.maxMaintained || maintainedBytes + bytes > context.maxBytes)
+      throw new DbRuntimeError('JD2060', 'group dependencies exceed live state credits');
     docs.set(token, doc);
-    maintainedBytes += bytesOf(doc);
+    maintainedBytes += bytes;
     positions.set(token, context.rowPosition(token));
     if (!groups.has(group)) groups.set(group, new Set());
     groups.get(group).add(token);
@@ -87,20 +96,25 @@ export function nestedGroupStrategy(description, context) {
     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) ?? []);
+  const flatten = () => {
+    const rows = [...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 aggregate === null ? rows : aggregate(rows, context.externals);
+  };
   return {
     close() { docs.clear(); groups.clear(); results.clear(); positions.clear(); },
     init() {
-      const source = [{ $subsequence: [{ $for: { it: '$[*]' }, $return: '$it' }, 0, context.maxMaintained + 1] }];
+      const carrier = description.carrier ?? { $for: { [binding]: '$[*]' },
+        ...(inner.$where === undefined ? {} : { $where: inner.$where }), $return: `$${binding}` };
+      const source = [{ $subsequence: [carrier, 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() });
+      const changes = context.touchedKeys(record, description.deps ?? { whole: true, members: new Set() });
       if (changes === null) return null;
       const affected = new Set();
       for (const token of changes.keys()) {
@@ -110,7 +124,10 @@ export function nestedGroupStrategy(description, context) {
           docs.delete(token); positions.delete(token); maintainedBytes -= bytesOf(previous);
         }
         const doc = context.readRow(token); stats.dependencyReads++;
-        if (doc !== undefined) affected.add(add(token, doc));
+        if (doc !== undefined) {
+          const group = add(token, doc);
+          if (group !== null) affected.add(group);
+        }
       }
       check();
       for (const group of affected) refresh(group);