@jarenjs/db 0.83.3 → 0.85.0

package/src/emit.js

@@ -41,7 +41,7 @@ function compareRefs(pred, read) {
 }
 
 /**
- * @typedef {{ external: string } | { literal: unknown } |
+ * @typedef {{ external: string, nullable?: boolean } | { literal: unknown } |
  *   { derived: { kind: 'bboxAxis', external: string,
  *     axis: 'w' | 's' | 'e' | 'n' } } |
  *   { derived: { kind: 'circleAxis', centre: { external: string } | { literal: unknown },
@@ -659,15 +659,20 @@ export function createEntityPredicateEmitters(dialect, param) {
 
   const emitColumnPred = (aliasSql, pred) => {
     const column = physicalComparable(pred.ref, `${aliasSql}.${q(pred.ref.column)}`, dialect);
+    const presentNull = pred.ref.nullPolicy === 'null';
+    const present = presentNull ? dialect.booleanLiteral(true) : `${column} IS NOT NULL`;
     if (pred.p === 'typeIs') {
       if (pred.types.length === 0)
-        return pred.positive ? `${column} IS NOT NULL` : `${column} IS NULL`;
+        return pred.positive ? present : presentNull ? dialect.booleanLiteral(false) : `${column} IS NULL`;
       if (pred.types[0] === 'null')
-        return pred.positive ? dialect.booleanLiteral(false) : `${column} IS NOT NULL`;
+        return pred.positive ? presentNull ? `${column} IS NULL` : dialect.booleanLiteral(false) : `${column} IS NOT NULL`;
+      if (pred.ref.storage !== 'boolean')
+        return pred.positive ? dialect.booleanLiteral(false) : present;
       const wanted = pred.types[0] === 'true' ? 1 : 0;
       return pred.positive
         ? `(${column} IS NOT NULL AND ${column} = ${param({ literal: wanted })})`
-        : `(${column} IS NOT NULL AND ${column} <> ${param({ literal: wanted })})`;
+        : presentNull ? `${column} IS NOT ${param({ literal: wanted })}`
+          : `(${column} IS NOT NULL AND ${column} <> ${param({ literal: wanted })})`;
     }
     if (pred.p === 'strop') {
       const form = stropForm(dialect, param, column, pred);
@@ -675,6 +680,26 @@ export function createEntityPredicateEmitters(dialect, param) {
     }
     const symbol = { eq: '=', ne: '<>', lt: '<', le: '<=', gt: '>', ge: '>=' }[pred.op];
     if ('ext' in pred.operand) {
+      if (dialect.name === 'sqlite') {
+        // SQL NULL is a present Jaren null only for an explicit null
+        // policy. Keep type guards: SQLite affinity must not turn a
+        // numeric lookup into a string lookup, or invert inequality.
+        const value = () => param({ external: pred.operand.ext, nullable: true });
+        const kind = pred.ref.storage === 'string' ? 'text' : 'number';
+        const guard = () => kind === 'text'
+          ? `${dialect.valueTypeOf(value())} = ${sl('text')}`
+          : pred.ref.storage === 'boolean' ? dialect.booleanLiteral(false)
+            : `${dialect.valueTypeOf(value())} IN ${NUMERIC()}`;
+        if (pred.op === 'eq') {
+          const nullCase = presentNull ? `(${column} IS NULL AND ${value()} IS NULL) OR ` : '';
+          return `(${nullCase}(${column} IS NOT NULL AND ${guard()} AND ${column} = ${value()}))`;
+        }
+        if (pred.op === 'ne') {
+          const nullCase = presentNull ? `(${column} IS NULL AND ${value()} IS NOT NULL) OR ` : '';
+          return `(${nullCase}(${column} IS NOT NULL AND (NOT (${guard()}) OR ${column} <> ${value()})))`;
+        }
+        return `(${column} IS NOT NULL AND ${guard()} AND ${column} ${symbol} ${value()})`;
+      }
       const kind = pred.ref.storage === 'string' ? 'text' : 'number';
       const guard = kind === 'text'
         ? `${dialect.valueTypeOf(externalSlot(pred.operand.ext))} = ${sl('text')}`
@@ -688,7 +713,8 @@ export function createEntityPredicateEmitters(dialect, param) {
     const storageKind = pred.ref.storage === 'string' ? 'string'
       : pred.ref.storage === 'boolean' ? 'boolean' : 'number';
     if (storageKind === 'boolean' || litKind === 'other' || storageKind !== litKind)
-      return pred.op === 'ne' ? `${column} IS NOT NULL` : dialect.booleanLiteral(false);
+      return pred.op === 'ne' ? present : dialect.booleanLiteral(false);
+    if (presentNull && pred.op === 'ne') return `${column} IS NOT ${param({ literal: lit })}`;
     return `(${column} IS NOT NULL AND ${column} ${symbol} ${param({ literal: lit })})`;
   };
 
@@ -875,6 +901,12 @@ export function emitEntityPlan(plan, dialect, physicalOf) {
           ? `CAST(${groupValue(entry.ref)} AS REAL)` : groupValue(entry.ref))} AS ${q(`a${i}`)}`),
       ...group.aggregates.flatMap((entry, i) => numericGroup(entry) ? [`${groupSafe(entry)} AS ${q(`_safe${i}`)}`] : []),
       ...(groupRefs.length ? [`${groupRefs.map(groupValid).join(' AND ')} AS ${q('_valid')}`] : [])].join(', ')
+    : plan.scalarAggregate
+    ? `${dialect.groupAggregate(plan.scalarAggregate.fn, plan.scalarAggregate.ref.type === 'string'
+      ? groupValue(plan.scalarAggregate.ref) : `CAST(${groupValue(plan.scalarAggregate.ref)} AS REAL)`)} AS ${q('value')}, `
+      + `${groupValid(plan.scalarAggregate.ref)} AS ${q('_valid')}, `
+      + `${plan.scalarAggregate.ref.nullPolicy === 'null' ? `COUNT(*) - COUNT(${groupValue(plan.scalarAggregate.ref)})` : '0'} AS ${q('_nulls')}, `
+      + `${numericGroup(plan.scalarAggregate) ? groupSafe(plan.scalarAggregate) : '1'} AS ${q('_safe')}`
     : plan.aggregate === 'count'
     ? `COUNT(*) AS ${q('value')}`
     : plan.project != null

package/src/engine-metadata.js

@@ -0,0 +1,18 @@
+//@ts-check
+/** Inert metadata: inspecting a schema must not load its runtime owners. */
+import { REPLICATION_TABLES } from './replication-tables.js';
+/** Current model document version. */
+export const MODEL_VERSION = '0.1';
+/** Migration receipt table. */
+export const HISTORY_TABLE = '_jaren_migrations';
+/** Change ledger table. */
+export const CHANGES_TABLE = '_jaren_changes';
+/** Change ledger retention state. */
+export const CHANGES_STATE_TABLE = '_jaren_changes_state';
+/** Durable job queue. */
+export const JOBS_TABLE = '_jaren_jobs';
+/** Durable job checkpoints. */
+export const JOB_CHECKPOINTS_TABLE = '_jaren_job_checkpoints';
+/** Tables excluded from model adoption and schema drift comparisons. */
+export const ENGINE_TABLES = new Set([HISTORY_TABLE, CHANGES_TABLE, CHANGES_STATE_TABLE,
+  JOBS_TABLE, JOB_CHECKPOINTS_TABLE, ...Object.values(REPLICATION_TABLES)]);

package/src/index.js

@@ -66,7 +66,7 @@ export {
   applyMandatoryPredicate, applyRowBound,
 } from './profile.js';
 export { translatePatch } from './patch-sql.js';
-export { normalizeEntities, explainMapping, relationTables } from './model.js';
+export { normalizeEntities, explainMapping, compileEntityModel, relationTables } from './model.js';
 export { planEntity, planJoinTable } from './ddl.js';
 export { entityCore } from './entity.js';
 export { entityEmitModel } from './emit-model.js';
@@ -103,3 +103,6 @@ export { REPLICATION_VERSION, REPLICATION_DEFAULTS, normalizeFrontier,
 
 export { planInvariants } from './ddl.js';
 export { planPhysicalMigration } from './migrate.js';
+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';

package/src/introspect.js

@@ -30,8 +30,7 @@
 import { chain } from './driver.js';
 import { DbCompileError } from './errors.js';
 import { KEY_COLUMN, DOC_COLUMN } from './ddl.js';
-import { MODEL_VERSION } from './store.js';
-import { ENGINE_TABLES } from './migrate.js';
+import { MODEL_VERSION, ENGINE_TABLES } from './engine-metadata.js';
 import { registeredName, expressionMembers } from './expression.js';
 
 /**

package/src/jobs.js

@@ -1,4 +1,6 @@
 //@ts-check
+import { JOBS_TABLE, JOB_CHECKPOINTS_TABLE } from './engine-metadata.js';
+export { JOBS_TABLE, JOB_CHECKPOINTS_TABLE };
 /**
  * @file The durable job queue (JOBS-FORMAT): enqueue, the
  * single-statement guarded claim (§3 — one statement is one
@@ -44,8 +46,8 @@ import { DbCompileError, DbRuntimeError, wrapDriverError } from './errors.js';
 import { createCursor, rowClassOf, PAGE_LIMIT_DEFAULT } from './cursor.js';
 import { refuseCancelled } from './cancellation.js';
 
-export const JOBS_TABLE = '_jaren_jobs';
-export const JOB_CHECKPOINTS_TABLE = '_jaren_job_checkpoints';
+
+
 
 /** §4 defaults, all overridable per worker. */
 export const JOB_DEFAULTS = Object.freeze({

package/src/migrate.js

@@ -34,9 +34,8 @@ import { chain, toPromise } from './driver.js';
 import { normalizeModel } from './store.js';
 import { planQuery } from './plan.js';
 import { createQueryEngine, createQueryState } from './query.js';
-import { CHANGES_TABLE, CHANGES_STATE_TABLE } from './capture.js';
-import { JOBS_TABLE, JOB_CHECKPOINTS_TABLE } from './jobs.js';
-import { REPLICATION_TABLES } from './replication-tables.js';
+import { HISTORY_TABLE, ENGINE_TABLES } from './engine-metadata.js';
+export { HISTORY_TABLE, ENGINE_TABLES };
 import { planCollection, verifyShape, planEntity, planJoinTable } from './ddl.js';
 import { normalizeEntities, explainMapping } from './model.js';
 import { derivedValue, memberAt, registerDeriveFunctions } from './derive.js';
@@ -74,17 +73,6 @@ function mappingFor(connection, expressions = undefined) {
   };
 }
 
-/** The history table name (outside the model's identifier namespace
- * conventions on purpose — a collection cannot collide with it). */
-export const HISTORY_TABLE = '_jaren_migrations';
-/** The tables the engine owns beside a model's: never a shape-drift finding. */
-/** The tables this package owns. A model never declared one, so one
- * found in a database is the engine's own bookkeeping rather than
- * anybody's drift — the drift check skips them and the introspector
- * does not derive them. */
-export const ENGINE_TABLES = new Set([HISTORY_TABLE, CHANGES_TABLE, CHANGES_STATE_TABLE,
-  JOBS_TABLE, JOB_CHECKPOINTS_TABLE, ...Object.values(REPLICATION_TABLES)]);
-
 /**
  * The signature-grade identity of a model SHAPE.
  * @param {any} model - A jaren-model document
@@ -198,8 +186,16 @@ export function planMigration(fromModel, toModel, options = undefined) {
   const dialect = options?.dialect ?? null;
   if (dialect === null || typeof dialect !== 'object')
     throw new TypeError('planMigration needs { dialect } (the store dialect renders the DDL)');
-  if ([fromModel, toModel].some((m) => Object.values(m.entities ?? {}).some((e) => e.physical !== undefined)))
-    throw refuse('JD0021', 'column layouts require planPhysicalMigration with explicit preservation dispositions');
+  if ([fromModel, toModel].some((m) => Object.values(m.entities ?? {}).some((e) => e.physical !== undefined))) {
+    normalizeEntities(fromModel);
+    normalizeEntities(toModel);
+    if (canonicalizeJson(fromModel) !== canonicalizeJson(toModel))
+      throw refuse('JD0021', 'changed column layouts require planTableMigration on the open connection or planPhysicalMigration with explicit preservation dispositions');
+    return { migration: { $migration: MIGRATION_VERSION,
+      id: options?.id ?? `to-${shapeHash(toModel).slice(0, 8)}`,
+      from: shapeHash(fromModel), to: shapeHash(toModel), steps: [] },
+    report: { renamed: [], added: [], removed: [], schemaChanged: [], drafts: [], destructive: false } };
+  }
   const mapping = { derived: options?.derived ?? 'virtual', rtree: options?.rtree !== false,
     // a model that declares an index EXPRESSION resolves its functions
     // here too: a plan is DDL, and DDL over a function this planner was

package/src/model-api.js

@@ -0,0 +1,4 @@
+//@ts-check
+/** Model metadata and read-only schema inspection without opening a store. */
+export { normalizeEntities, explainMapping, compileEntityModel, relationTables } from './model.js';
+export { readSchema, introspectModel, INTROSPECT_CODES } from './introspect.js';

package/src/model.js

@@ -557,7 +557,19 @@ export function relationTables(entities) {
  * @returns {any}
  */
 export function explainMapping(model) {
+  return mappingOf(model, normalizeEntities(model));
+}
+
+/** Normalize and map once for lightweight engines sharing model metadata.
+ * No process-global cache retains the model or any connection.
+ * @param {any} model @returns {{entities:Map<string,any>,mapping:any}} */
+export function compileEntityModel(model) {
   const entities = normalizeEntities(model);
+  return { entities, mapping: mappingOf(model, entities) };
+}
+
+/** @param {any} model @param {Map<string,any>} entities @returns {any} */
+function mappingOf(model, entities) {
   /** @type {any} */
   const mapping = { entities: {}, joinTables: {} };
 

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';