@jarenjs/db 0.84.3 → 0.86.0

package/src/mutation.js

@@ -8,6 +8,7 @@ import { entityShape, planEntityPredicate } from './plan.js';
 import { createEntityPredicateEmitters } from './emit.js';
 import { physicalSelection } from './physical.js';
 import { utf8Length } from './cursor.js';
+import { relationalEmitter } from './dialects/sqlite-relational.js';
 
 /** Compile once per document, execute within the existing guarded transaction.
  * @param {any} connection @param {any} entity @param {any} mapping @param {any} core */
@@ -35,7 +36,9 @@ export function createEntityMutation(connection, entity, mapping, core) {
     if (entity.physical == null || dialect.name !== 'sqlite') fail('native mutations require a declared SQLite column layout');
     core.plan.writable();
     if (!document || typeof document !== 'object' || Array.isArray(document)) fail('a mutation is an object');
-    const allowed = { update: ['key', 'expectedRevision', 'set'], upsert: ['values', 'conflict', 'update'],
+    const allowed = { update: ['key', 'expectedRevision', 'set', 'where', 'reporting', 'expressions'],
+      delete: ['key', 'where', 'expectedRevision'],
+      upsert: ['values', 'conflict', 'conflictWhere', 'update', 'onConflict', 'reporting'],
       'insert-select': ['source', 'where', 'select', 'conflict', 'onConflict'] }[document.op];
     if (!allowed) fail('op must be update, upsert or insert-select');
     for (const key of Object.keys(document))
@@ -52,29 +55,75 @@ export function createEntityMutation(connection, entity, mapping, core) {
     const params = [];
     const param = (value) => { params.push(value); return dialect.parameterRef(params.length, 'v'); };
     const table = q(mapping.table);
+    const sqlExpression = (expression, inline = false) => {
+      const mapped = (value) => {
+        if (Array.isArray(value)) return value.map(mapped);
+        if (value === null || typeof value !== 'object') return value;
+        if (value.$sql === 'value') return value;
+        if (value.$sql === 'column') {
+          if (value.table !== undefined && value.table !== 'it') fail('mutation column expressions refer to the current entity');
+          return { $sql: 'column', name: column(value.name).physical };
+        }
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, mapped(item)]));
+      };
+      const emitter = relationalEmitter({ inline });
+      const result = emitter.expr(mapped(expression));
+      params.push(...emitter.params);
+      return result;
+    };
+    const predicate = (expression) => {
+      if (expression?.$sql !== undefined || typeof expression === 'number') return sqlExpression(expression);
+      const analyzed = analyzeQuery({ $for: { it: '$[*]' }, $where: expression, $return: '$it' });
+      const planned = planEntityPredicate(analyzed.root.where, analyzed.root.forBindings[0].slot, entityShape(entity, mapping));
+      if ('refusal' in planned) fail(planned.refusal.reason);
+      const emitter = createEntityPredicateEmitters(dialect, (slot) => {
+        if (!Object.hasOwn(slot, 'literal')) return fail('mutation predicates use literal values');
+        return param(slot.literal);
+      });
+      return emitter.emitPred(table, `${table}.${q('doc')}`, planned.pred);
+    };
     let sql;
     let prefix = '';
-    if (document.op === 'update') {
-      if (!document.set || typeof document.set !== 'object' || Array.isArray(document.set) || !Object.keys(document.set).length) fail('update needs a nonempty set object');
-      const assignments = Object.entries(document.set).map(([name, value]) => {
+    if (document.reporting !== undefined && !['matched', 'changed'].includes(document.reporting)) fail('reporting is matched or changed');
+    if (document.op === 'update' || document.op === 'delete') {
+      const set = document.set ?? {}, expressions = document.expressions ?? {};
+      if (document.op === 'update' && (!set || typeof set !== 'object' || Array.isArray(set)
+        || !expressions || typeof expressions !== 'object' || Array.isArray(expressions)
+        || !Object.keys(set).length && !Object.keys(expressions).length)) fail('update needs set or expressions assignments');
+      const assignments = Object.entries(set).map(([name, value]) => {
         const c = writableColumn(name);
         const encoded = core.plan.encodeColumn(name, value);
-        return { name: q(c.physical), compare: comparison(c), value: param(encoded), encoded };
+        return { name: q(c.physical), compare: comparison(c), value: param(encoded), different: () => param(encoded) };
       });
-      const parts = core.normalizeKey(document.key);
-      const where = core.plan.keys.map((key, i) => `${q(column(key).physical)} = ${param(core.plan.encodeColumn(key, parts[i]))}`);
+      for (const [name, expression] of Object.entries(expressions)) {
+        if (Object.hasOwn(set, name)) fail('an assignment has exactly one owner');
+        const c = writableColumn(name);
+        assignments.push({ name: q(c.physical), compare: comparison(c), value: sqlExpression(expression), different: () => sqlExpression(expression) });
+      }
+      const where = [];
+      if (Object.hasOwn(document, 'key')) {
+        const parts = core.normalizeKey(document.key);
+        where.push(...core.plan.keys.map((key, i) => `${q(column(key).physical)} = ${param(core.plan.encodeColumn(key, parts[i]))}`));
+      }
+      if (Object.hasOwn(document, 'where')) where.push(predicate(document.where));
+      if (!where.length) fail('update/delete require a key or an explicit predicate');
       if (entity.version !== null) {
         if (!Number.isSafeInteger(document.expectedRevision) || document.expectedRevision < 0) fail('a versioned update needs expectedRevision');
         where.push(`${q(column(entity.version).physical)} = ${param(document.expectedRevision)}`);
       }
       else if (document.expectedRevision !== undefined) fail('expectedRevision needs a declared version member');
-      where.push(`(${assignments.map((a) => `${a.compare} IS NOT ${param(a.encoded)}`).join(' OR ')})`);
+      if (document.op === 'update' && document.reporting !== 'matched')
+        where.push(`(${assignments.map((a) => `${a.compare} IS NOT ${a.different()}`).join(' OR ')})`);
       const sets = assignments.map((a) => `${a.name} = ${a.value}`);
       if (entity.version !== null) sets.push(`${q(column(entity.version).physical)} = ${q(column(entity.version).physical)} + 1`);
-      sql = `UPDATE ${table} SET ${sets.join(', ')} WHERE ${where.join(' AND ')}`;
+      sql = document.op === 'delete' ? `DELETE FROM ${table} WHERE ${where.map((part) => `(${part})`).join(' AND ')}`
+        : `UPDATE ${table} SET ${sets.join(', ')} WHERE ${where.map((part) => `(${part})`).join(' AND ')}`;
     }
     else {
-      if (JSON.stringify(document.conflict) !== JSON.stringify(core.plan.keys)) fail('conflict must name the complete ordered primary key');
+      if (!Array.isArray(document.conflict) || !document.conflict.length || new Set(document.conflict).size !== document.conflict.length)
+        fail('conflict must name distinct mapped columns');
+      document.conflict.forEach(column);
+      if (document.op === 'insert-select' && JSON.stringify(document.conflict) !== JSON.stringify(core.plan.keys)) fail('insert-select conflict must name the complete ordered primary key');
       let names;
       let source;
       if (document.op === 'upsert') {
@@ -82,7 +131,7 @@ export function createEntityMutation(connection, entity, mapping, core) {
         const complete = core.complete(document.values, { updating: false });
         const split = core.plan.split(complete);
         names = split.values.map((v) => v.name);
-        if (core.plan.keys.some((key) => !names.includes(key))) fail('upsert requires every primary-key value');
+        if (document.conflict.some((key) => !names.includes(key))) fail('upsert requires every conflict value');
         source = `VALUES (${split.values.map((v) => param(v.value)).join(', ')})`;
       }
       else {
@@ -120,8 +169,10 @@ export function createEntityMutation(connection, entity, mapping, core) {
           + dialect.mutationRowGuard(`(SELECT COUNT(*) FROM ${q('_jaren_source')})`, maxRows);
       }
       sql = `INSERT INTO ${table} (${names.map((name) => q(column(name).physical)).join(', ')}) ${source}`
-        + ` ON CONFLICT (${core.plan.keys.map((key) => q(column(key).physical)).join(', ')})`;
-      if (document.op === 'insert-select') sql += ' DO NOTHING';
+        + ` ON CONFLICT (${document.conflict.map((key) => q(column(key).physical)).join(', ')})`;
+      if (document.conflictWhere !== undefined) sql += ` WHERE ${sqlExpression(document.conflictWhere, true)}`;
+      if (document.onConflict !== undefined && !['nothing', 'update'].includes(document.onConflict)) fail('onConflict is nothing or update');
+      if (document.op === 'insert-select' || document.onConflict === 'nothing') sql += ' DO NOTHING';
       else {
         if (!Array.isArray(document.update) || !document.update.length || new Set(document.update).size !== document.update.length) fail('upsert update names distinct stored members');
         const changes = document.update.map((name) => {
@@ -131,7 +182,8 @@ export function createEntityMutation(connection, entity, mapping, core) {
         });
         const sets = changes.map(({ name }) => `${name} = excluded.${name}`);
         if (entity.version !== null) sets.push(`${q(column(entity.version).physical)} = ${table}.${q(column(entity.version).physical)} + 1`);
-        sql += ` DO UPDATE SET ${sets.join(', ')} WHERE ${changes.map(({ name, compare }) => `${compare} IS NOT excluded.${name}`).join(' OR ')}`;
+        sql += ` DO UPDATE SET ${sets.join(', ')}`;
+        if (document.reporting !== 'matched') sql += ` WHERE ${changes.map(({ name, compare }) => `${compare} IS NOT excluded.${name}`).join(' OR ')}`;
       }
     }
     sql = prefix + sql + ` RETURNING ${physicalSelection(mapping, dialect)}`;

package/src/physical.js

@@ -4,6 +4,8 @@ import { getEpochOfDateTimeRFC3339, getEpochOfDateOnlyRFC3339 } from '@jarenjs/c
 import { DbCompileError, DbRuntimeError } from './errors.js';
 import { chain } from './driver.js';
 import { canonicalizeJson } from '@jarenjs/json/canonical';
+import { planTable } from './dialects/sqlite-schema.js';
+import { sqlitePhysicalColumnType } from './dialects/sqlite.js';
 
 const compiledCodecs = new WeakMap();
 const CODECS = new Set(['text', 'integer', 'number', 'boolean', 'json', 'date', 'datetime', 'epoch-ms', 'bigint', 'decimal', 'blob-hex']);
@@ -19,7 +21,7 @@ export function normalizePhysical(physical, properties, keys, path) {
   const fail = (reason) => { throw new DbCompileError('JD0005', reason, `${path}/physical`); };
   if (!physical || typeof physical !== 'object' || Array.isArray(physical)) fail('physical must be an object');
   for (const key of Object.keys(physical))
-    if (!['table', 'kind', 'keys', 'columns'].includes(key)) fail(`unknown physical member '${key}'`);
+    if (!['table', 'kind', 'keys', 'columns', 'constraints', 'indexes', 'triggers', 'strict', 'withoutRowid'].includes(key)) fail(`unknown physical member '${key}'`);
   if (!identifier(physical.table)) fail('physical.table must be a nonempty SQL identifier');
   if (physical.kind !== undefined && !['table', 'view'].includes(physical.kind)) fail('physical.kind is table or view');
   if (!physical.columns || typeof physical.columns !== 'object' || Array.isArray(physical.columns)) fail('physical.columns is required');
@@ -28,26 +30,54 @@ export function normalizePhysical(physical, properties, keys, path) {
     || ordered.some((key) => !keys.includes(key))) fail('physical.keys must order every declared key exactly once');
   const used = new Set();
   const columns = [];
-  for (const [name, property] of properties) {
+  for (const name of Object.keys(physical.columns))
+    if (!properties.has(name) || properties.get(name).relation) fail(`column '${name}' is not a stored property`);
+  for (const [name, property] of properties)
+    if (!property.relation && !Object.hasOwn(physical.columns, name)) fail(`'${name}' needs an explicit supported column codec`);
+  const definitions = [];
+  for (const name of Object.keys(physical.columns)) {
+    const property = properties.get(name);
     if (property.relation) continue;
     const c = physical.columns[name];
     if (!c || typeof c !== 'object' || Array.isArray(c) || !CODECS.has(c.codec)) fail(`'${name}' needs an explicit supported column codec`);
     for (const key of Object.keys(c))
-      if (!['name', 'codec', 'null', 'default', 'generated'].includes(key)) fail(`unknown column member '${key}'`);
+      if (!['name', 'codec', 'null', 'default', 'generated', 'type', 'defaultValue', 'collation', 'identity', 'check', 'generatedExpression', 'stored'].includes(key)) fail(`unknown column member '${key}'`);
     if (!identifier(c.name) || used.has(c.name.toLowerCase())) fail(`'${name}' needs a distinct physical column name`);
     if (!['null', 'absent', 'reject'].includes(c.null)) fail(`'${name}' must declare SQL NULL as null, absent or reject`);
+    if (c.type !== undefined && c.type !== sqlitePhysicalColumnType(c.codec)) fail(`'${name}' declares an affinity incompatible with its codec`);
+    if (c.stored !== undefined && (typeof c.stored !== 'boolean' || c.generatedExpression === undefined))
+      fail(`'${name}' needs an explicit generated expression for stored ownership`);
     if (c.default !== undefined && c.default !== 'database') fail('column default ownership is database');
     if (c.generated !== undefined && typeof c.generated !== 'boolean') fail('generated must be boolean');
     if (property.key && (!['text', 'integer', 'bigint'].includes(c.codec) || c.null !== 'reject')) fail('keys require non-null text, integer or bigint codecs');
     if (property.column !== undefined) fail('physical codecs replace hybrid column overrides');
-    if (c.default === 'database' && property.default !== undefined && property.default !== 'auto') fail('a default has exactly one owner');
+    if ((c.default === 'database' || Object.hasOwn(c, 'defaultValue')) && property.default !== undefined && property.default !== 'auto') fail('a default has exactly one owner');
+    if (c.generatedExpression !== undefined && c.generated === false) fail('a generated expression requires generated ownership');
     used.add(c.name.toLowerCase());
-    columns.push({ name, physical: c.name, codec: c.codec, null: c.null, databaseDefault: c.default === 'database',
-      generated: c.generated === true, storage: STORAGE[c.codec], source: 'column', key: property.key });
+    columns.push({ name, physical: c.name, codec: c.codec, null: c.null, databaseDefault: c.default === 'database' || Object.hasOwn(c, 'defaultValue'),
+      generated: c.generated === true || c.generatedExpression !== undefined, storage: STORAGE[c.codec], source: 'column', key: property.key });
+    definitions.push({ name: c.name,
+      type: c.type ?? sqlitePhysicalColumnType(c.codec),
+      nullable: c.null !== 'reject',
+      ...(Object.hasOwn(c, 'defaultValue') ? { default: c.defaultValue } : {}),
+      ...(c.identity !== undefined || property.default === 'auto' ? { identity: c.identity ?? 'rowid' } : {}),
+      ...(c.collation === undefined ? {} : { collation: c.collation }),
+      ...(c.check === undefined ? {} : { check: c.check }),
+      ...(c.generatedExpression === undefined ? {} : { generated: c.generatedExpression, stored: c.stored === true }),
+    });
   }
   for (const name of Object.keys(physical.columns))
     if (!properties.has(name) || properties.get(name).relation) fail(`column '${name}' is not a stored property`);
-  return { table: physical.table, kind: physical.kind ?? 'table', keys: [...ordered], columns };
+  const definition = { name: physical.table, columns: definitions,
+    primaryKey: ordered.map((key) => physical.columns[key].name),
+    ...Object.fromEntries(['constraints', 'indexes', 'triggers', 'strict', 'withoutRowid']
+      .filter((key) => physical[key] !== undefined).map((key) => [key, physical[key]])) };
+  if (physical.kind !== 'view') planTable(definition);
+  // Database-owned expressions must be explicit before DDL can own them.
+  const ddl = physical.kind === 'view' || columns.some((c, i) => (c.generated && definitions[i].generated === undefined)
+    || (c.databaseDefault && !Object.hasOwn(definitions[i], 'default')))
+    ? null : definition;
+  return { table: physical.table, kind: physical.kind ?? 'table', keys: [...ordered], columns, ddl };
 }
 
 /** Compile one codec once, with a JSON-safe public value and a bound SQL value.

package/src/plan.js

@@ -182,6 +182,7 @@ const OPERATOR_REASONS = {
 
 /** Why an ENTITY document, or one of its clauses, stayed in the engine. */
 const ENTITY_REASONS = {
+  scalarAggregate: 'native scalar aggregation requires a scalar physical projection; sums and averages require exact integer accumulation',
   notFlwor: 'only a FLWOR over entity arrays is translated',
   bindingRoot: 'bindings must each range over one declared entity array ($.Entity[*])',
   joinKey: 'every binding past the first needs a column equality to one already joined — '
@@ -3190,7 +3191,7 @@ export function planEntityPredicate(node, slot, shape) {
     if (!('ref' in pred) || pred.ref === null) return pred;
     const canonical = canonicalOf(pred.ref.segments);
     const flavored = shape.entityFlavors.get(canonical);
-    if (shape.columnOnly && (flavored === undefined || flavored.unsafe || flavored.nullPolicy === 'null')) {
+    if (shape.columnOnly && (flavored === undefined || flavored.unsafe)) {
       blocked = refusal('physical', PREDICATE_REASONS.physicalCodec);
       return pred;
     }
@@ -3246,6 +3247,57 @@ export function planEntityPredicate(node, slot, shape) {
  *   kept in the set residual over the fetched root
  * @returns {any}
  */
+function flattenEntityProjection(root) {
+  const simple = (node) => node.kind === 'literal' || node.kind === 'var'
+    || (node.kind === 'path' && node.singular)
+    || (node.kind === 'object' && node.entries.every((e) => simple(e.expr)));
+  const plain = (node) => node?.kind === 'flwor' && node.fold === null
+    && node.letBindings.length === 0 && node.asChecks === null && node.count === null
+    && node.groupby === null && node.limits === null;
+  if (!plain(root)) return root;
+  while (root.forBindings.length === 1) {
+    const outer = root.forBindings[0];
+    if (outer.atSlot !== -1 || outer.allowingEmpty || outer.window !== null) break;
+    const inner = flattenEntityProjection(unpacked(outer.expr));
+    if (!plain(inner) || inner.orderby !== null || !simple(inner.ret)
+      || !['object', 'var'].includes(inner.ret.kind)) break;
+    let blocked = false;
+    const resolve = (projection, segments) => {
+      if (!segments.length) return projection;
+      if (projection.kind === 'object') {
+        const [part, ...rest] = segments;
+        const name = !part.descendant && part.selectors.length === 1 && part.selectors[0].kind === 'name'
+          ? part.selectors[0].name : null;
+        const member = projection.entries.find((e) => e.name === name);
+        if (member) return resolve(member.expr, rest);
+      }
+      if (projection.kind === 'var' && !projection.external)
+        return { kind: 'path', card: 2, name: projection.name, rootSlot: projection.slot,
+          external: false, rootCard: 1, segments, singular: true, docPath: projection.docPath };
+      if (projection.kind === 'path' && projection.singular)
+        return { ...projection, segments: [...projection.segments, ...segments] };
+      blocked = true; return projection;
+    };
+    const substitute = (node) => {
+      if (node === null || typeof node !== 'object') return node;
+      if (Array.isArray(node)) return node.map(substitute);
+      if (node.kind === 'literal') return node;
+      if (node.kind === 'var' && !node.external && node.slot === outer.slot) return inner.ret;
+      if (node.kind === 'path' && !node.external && node.rootSlot === outer.slot) {
+        if (!node.singular) { blocked = true; return node; }
+        return resolve(inner.ret, node.segments);
+      }
+      return Object.fromEntries(Object.entries(node).map(([key, value]) => [key, substitute(value)]));
+    };
+    const where = substitute(root.where), ret = substitute(root.ret), orderby = substitute(root.orderby);
+    if (blocked) break;
+    root = { ...root, forBindings: inner.forBindings, ret, orderby,
+      where: inner.where === null ? where : where === null ? inner.where
+        : { kind: 'op', card: 1, name: '$and', args: [inner.where, where], docPath: root.docPath } };
+  }
+  return root;
+}
+
 function planEntityQueryCore(document, entities, mapping, operators) {
   const analysis = analyzeQuery(document, analyzeOptionsFor(operators));
   let root = analysis.root;
@@ -3269,13 +3321,14 @@ function planEntityQueryCore(document, entities, mapping, operators) {
     assertDecidedKind(root);
   }
   let aggregate = null;
-  if (root.kind === 'op' && root.name === '$count' && windows.length === 0) {
-    aggregate = 'count';
+  if (root.kind === 'op' && ['$count', '$sum', '$avg', '$min', '$max'].includes(root.name) && windows.length === 0) {
+    aggregate = root.name.slice(1);
     root = root.args[0];
     assertDecidedKind(root);
   }
   if (root.kind !== 'flwor')
     return residual(root.kind, ENTITY_REASONS.notFlwor);
+  root = flattenEntityProjection(root);
   if (root.fold !== null || root.letBindings.length > 0 || root.asChecks !== null
     || root.count !== null)
     return residual('$let', KIND_REASONS.let);
@@ -3453,6 +3506,15 @@ function planEntityQueryCore(document, entities, mapping, operators) {
   if (retBinding === undefined && projection === null && group === null) {
     reasons.push(refusal('$return', ENTITY_REASONS.projection));
   }
+  let scalarAggregate = null;
+  if (aggregate !== null && aggregate !== 'count') {
+    const leaf = projection?.tree.p === 'leaf' ? projection.leaves[projection.tree.index] : null;
+    if (bindings.length !== 1 || !leaf?.ref || leaf.ref.flavor !== 'entity-column'
+      || !['text', 'integer', 'number'].includes(leaf.ref.codec)
+      || (['sum', 'avg'].includes(aggregate) && leaf.ref.type !== 'integer'))
+      return residual(`$${aggregate}`, ENTITY_REASONS.scalarAggregate);
+    scalarAggregate = { fn: aggregate, ref: leaf.ref };
+  }
   if (projection?.tree.p === 'leaf' && !projection.leaves[projection.tree.index].count && (aggregate === 'count' || windows.length > 0)) {
     const leaf = projection.leaves[projection.tree.index];
     const binding = bindings.find((entry) => entry.name === leaf.binding);
@@ -3546,6 +3608,7 @@ function planEntityQueryCore(document, entities, mapping, operators) {
       })),
       window,
       aggregate,
+      ...(scalarAggregate === null ? {} : { scalarAggregate }),
       group,
       ret: retBinding === undefined ? null : retBinding.name,
       // the projected shape, when the return is one: leaves that name

package/src/query-api.js

@@ -0,0 +1,5 @@
+//@ts-check
+/** Public query engines without store, jobs, replication or host bindings. */
+export { createQueryEngine, createEntityQueryEngine, createQueryState, createLoadEngine,
+  INCLUDE_DEPTH_DEFAULT, INCLUDE_ROWS_DEFAULT, INCLUDE_BYTES_DEFAULT } from './query.js';
+export { collectEntityRoots, entityRoot } from './plan.js';

package/src/query.js

@@ -34,7 +34,7 @@
 import { physicalSelection, columnCodec } from './physical.js';
 
 import { createSemanticCache } from '@jarenjs/core/cache';
-import { analyzeQuery } from '@jarenjs/json/query';
+import { analyzeQuery, JsonQueryRuntimeError } from '@jarenjs/json/query';
 
 import { DbCompileError, DbRuntimeError, wrapDriverError, classifyDriverError } from './errors.js';
 import { chain, attempt, isThenable } from './driver.js';
@@ -1653,7 +1653,7 @@ export function createEntityQueryEngine(context) {
       planned = { ...planned, mode: 'set', plan: null,
         reasons: [{ construct: 'pushdown', reason: BIND_REASONS.pushdown }] };
     }
-    if (planned.plan?.group && dialect.name !== 'sqlite') {
+    if ((planned.plan?.group || planned.plan?.scalarAggregate) && dialect.name !== 'sqlite') {
       planned = { ...planned, mode: 'set', plan: null,
         reasons: [{ construct: '$groupby', reason: 'entity grouping runtime guards are qualified for SQLite' }] };
     }
@@ -1872,11 +1872,30 @@ export function createEntityQueryEngine(context) {
     // the database cannot take (a missing external, a boolean, a null,
     // a region with no box) sends the call to the residual, where the
     // ENGINE raises its own error or answers with its own semantics
-    const params = entry.slots.map((slot) => slotValue(slot, externals));
-    if (params.some((value) => !bindable(value)))
+    const diverted = divertReason(entry, externals);
+    if (diverted !== null) {
+      entry.runtimeReason = diverted;
+      if (strict) throw new DbCompileError('JD0010',
+        `strict mode refused a residual: '${diverted.construct}' — ${diverted.reason}`);
+      if (profile?.refuseFullScan) throw profileEntityRefusal(
+        'the profile refuses the decoded scan required by the external binding', '/entities');
       return runResidual(entry, document, externals);
+    }
+    const params = entry.slots.map((slot) => slotValue(slot, externals));
     if (entry.statement === null) entry.statement = connection.prepare(entry.sql, { readOnly: true });
     return chain(guardEntityScan(entry), () => chain(entry.statement, (statement) => {
+      if (entry.planned.plan.scalarAggregate) return chain(statement.get(params), (row) => {
+        admittedRows(entry, row ? [row] : []);
+        if (row?._valid === 0) throw new DbRuntimeError('JD2003', 'an aggregate column refuses a lossy or invalid value');
+        if (row?._nulls > 0) throw new JsonQueryRuntimeError('JQ2001', 'an aggregate requires numbers or strings, got null');
+        if (row?._safe === 0) {
+          entry.runtimeReason = { construct: 'aggregate', reason: 'integer accumulation exceeded its runtime exactness bound' };
+          if (strict) throw new DbCompileError('JD0010', entry.runtimeReason.reason);
+          if (profile?.refuseFullScan) throw profileEntityRefusal('the profile refuses the decoded scan required by integer accumulation', '/entities');
+          return runResidual(entry, document, externals);
+        }
+        return wrapValue(entry, row?.value ?? (entry.planned.plan.aggregate === 'sum' ? 0 : undefined));
+      });
       if (entry.planned.plan.aggregate === 'count')
         return chain(statement.get(params), (row) => { admittedRows(entry, row ? [row] : []); return wrapValue(entry, row?.value ?? 0); });
       return chain(statement.all(params), (rows) => {
@@ -1928,7 +1947,8 @@ export function createEntityQueryEngine(context) {
    */
   const divertReason = (entry, externals) => {
     for (const slot of entry.slots) {
-      if (bindable(slotValue(slot, externals))) continue;
+      const value = slotValue(slot, externals);
+      if (bindable(value) || (slot.nullable === true && value === null)) continue;
       const name = 'external' in slot ? slot.external
         : 'derived' in slot ? (slot.derived.kind === 'bboxAxis' ? slot.derived.external
           : [slot.derived.centre, slot.derived.radius].find((input) => 'external' in input)?.external) : null;
@@ -1949,6 +1969,10 @@ export function createEntityQueryEngine(context) {
    */
   const cursorClass = (entry, externals) => {
     const buffered = (barrier) => ({ streaming: 'buffered', barrier });
+    if (entry.planned.mode === 'native' && externals !== null) {
+      const diverted = divertReason(entry, externals);
+      if (diverted !== null) return buffered(diverted);
+    }
     if (entry.planned.wrapped === true) {
       return buffered({ construct: 'window', reason: BIND_REASONS.wrappedWindow });
     }
@@ -1997,11 +2021,20 @@ export function createEntityQueryEngine(context) {
         + 'entity binding — read it untracked, or return the binding itself');
     }
     const each = register === undefined ? (item) => item : (item) => register(retEntity, item);
+    entry.runtimeReason = null;
     const classified = cursorClass(entry, externals);
+    if (classified.barrier?.construct === 'external') {
+      entry.admitted = { statements: 0, rows: 0, bytes: 0 };
+      entry.runtimeReason = classified.barrier;
+      if (strict) throw new DbCompileError('JD0010',
+        `strict mode refused a residual: 'external' — ${classified.barrier.reason}`);
+      if (profile?.refuseFullScan) throw profileEntityRefusal(
+        'the profile refuses the decoded scan required by the external binding', '/entities');
+    }
     refuseBuffered(options, classified, entities.get(entry.planned.retEntity ?? '')?.docPath);
     const signal = options?.signal;
     const deadline = options?.deadline;
-    if (entry.planned.wrapped === true || entry.planned.plan?.group) {
+    if (entry.planned.wrapped === true || entry.planned.plan?.group || entry.planned.plan?.scalarAggregate) {
       return cursorFactory({ ...classified, signal, deadline, now: state.now, wrap: driverWrap,
         materialize: () => chain(execute(document, options), (value) => entry.planned.wrapped === true
           ? [value] : value === undefined ? [] : Array.isArray(value) ? value : [value]) });

package/src/relational-api.js

@@ -0,0 +1,6 @@
+//@ts-check
+/** Lightweight column-first SQLite authoring and execution. */
+export { sql, planRelational, relational } from './dialects/sqlite-relational.js';
+export { defineTable, planTable } from './dialects/sqlite-schema.js';
+export { planTableMigration, applyTableMigration, withForeignKeysSuspended } from './table-migration.js';
+export { sqliteDialect } from './dialects/sqlite.js';

package/src/store.js

@@ -34,7 +34,7 @@ import { refuseUnsupportedPragmaKeys, resolvePragmaRequests, configurePragmas }
 import { createMaintenance } from './maintenance.js';
 import { createBackup } from './backup.js';
 import { normalizeProfile, assertProfileRoots } from './profile.js';
-import { normalizeEntities, explainMapping, joinTableRoots } from './model.js';
+import { compileEntityModel, joinTableRoots } from './model.js';
 import { entityCore } from './entity.js';
 import { verifyPhysical } from './physical.js';
 import { trustedSql, synchronousBody } from './sql.js';
@@ -59,7 +59,8 @@ import {
 } from './expression.js';
 
 /** The model format version this store implements. */
-export const MODEL_VERSION = '0.1';
+import { MODEL_VERSION } from './engine-metadata.js';
+export { MODEL_VERSION };
 
 const COLLECTION_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
 const IDENTITIES = new Set(['uuid', 'integer']);
@@ -975,8 +976,9 @@ export function openStore(model, options) {
   let mapping;
   try {
     collections = normalizeModel(model, options.expressions);
-    entities = normalizeEntities(model);
-    mapping = entities.size > 0 ? explainMapping(model) : null;
+    const compiled = compileEntityModel(model);
+    entities = compiled.entities;
+    mapping = entities.size > 0 ? compiled.mapping : null;
     if ([...entities.values()].some((e) => e.physical !== null) && (options.capture || options.replication))
       throw new DbCompileError('JD0051', 'column adoption preserves application triggers; complete capture is not qualified');
     if (options.adopt === true && (options.capture || options.replication))