@jarenjs/db 0.73.0 → 0.83.2

package/src/drivers/bun.js

@@ -27,7 +27,7 @@ import { PRAGMA_NAMES } from '../pragmas.js';
  * with its shape) into a probed connection. Exported so the adapter is
  * exercisable without the builtin.
  * @param {any} db - A Bun `Database`-shaped database
- * @param {{ queueTimeout?: number }} [options]
+ * @param {{ queueTimeout?: number, backup?: any }} [options]
  * @returns {any} a Connection, or a promise of one
  */
 export function adaptBunDatabase(db, options) {
@@ -38,6 +38,7 @@ export function adaptBunDatabase(db, options) {
   const statements = new Set();
   const collected = new FinalizationRegistry((ref) => statements.delete(ref));
   const raw = {
+    ...(options?.backup ? { backup: options.backup } : {}),
     /** @param {string} sql */
     exec: (sql) => db.run(sql),
     /** @param {string} sql */
@@ -91,6 +92,7 @@ export function adaptBunDatabase(db, options) {
     synchronous: true,
     queueTimeout: options?.queueTimeout,
     declared: {
+      backup: options?.backup !== undefined,
       sessions: false,
       userFunctions: false,
       deterministicIndexableFunctions: false,
@@ -112,9 +114,25 @@ export function adaptBunDatabase(db, options) {
  * @returns {any}
  */
 export function fromBunModule(mod, path, options) {
-  return adaptBunDatabase(options?.readOnly === true
-    ? new mod.Database(path, { readonly: true })
-    : new mod.Database(path), options);
+  const db = options?.readOnly === true ? new mod.Database(path, { readonly: true }) : new mod.Database(path);
+  const backup = typeof db.serialize !== 'function' ? undefined : {
+    snapshot: true,
+    copy: async (target, copyOptions) => {
+      const bytes = db.serialize();
+      const pageSize = ((bytes[16] << 8) | bytes[17]) || 65536;
+      const pages = bytes.length / (pageSize === 1 ? 65536 : pageSize);
+      copyOptions?.progress?.({ totalPages: pages, remainingPages: pages });
+      const fs = await import('node:fs/promises');
+      const file = await fs.open(target, 'wx');
+      try { await file.writeFile(bytes); await file.sync(); }
+      finally { await file.close(); }
+      copyOptions?.progress?.({ totalPages: pages, remainingPages: 0 });
+      return pages;
+    },
+    rename: (from, to) => import('node:fs/promises').then((fs) => fs.rename(from, to)),
+    remove: (target) => import('node:fs/promises').then((fs) => fs.rm(target, { force: true })),
+  };
+  return adaptBunDatabase(db, { ...options, ...(backup ? { backup } : {}) });
 }
 
 /**

package/src/emit.js

@@ -17,6 +17,11 @@
  */
 
 import { codePointPrefixSuccessor } from '@jarenjs/core/string';
+import { physicalSelection } from './physical.js';
+
+/** Physical text expressions must not inherit an application's collation. */
+const physicalComparable = (ref, sql, dialect) => ref.codec !== undefined
+  && ['text', 'date', 'datetime'].includes(ref.codec) ? dialect.codepoint(sql) : sql;
 
 /**
  * A promoted path the dialect's JSON path grammar cannot spell (a
@@ -26,10 +31,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 +101,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 +123,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 +138,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 +320,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 +465,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 +490,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 +516,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 +549,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)) };
@@ -627,7 +658,7 @@ export function createEntityPredicateEmitters(dialect, param) {
   };
 
   const emitColumnPred = (aliasSql, pred) => {
-    const column = `${aliasSql}.${q(pred.ref.column)}`;
+    const column = physicalComparable(pred.ref, `${aliasSql}.${q(pred.ref.column)}`, dialect);
     if (pred.p === 'typeIs') {
       if (pred.types.length === 0)
         return pred.positive ? `${column} IS NOT NULL` : `${column} IS NULL`;
@@ -682,6 +713,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 = physicalComparable(ref, `${aliasSql}.${q(ref.column)}`, dialect);
+        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 +785,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,
@@ -764,12 +809,27 @@ export function emitEntityPlan(plan, dialect, physicalOf) {
   const projectedPair = (leaf, suffix) => {
     const names = `${q(`v${suffix}`)}`;
     const typeName = `${q(`t${suffix}`)}`;
+    if (leaf.count) {
+      const count = leaf.count;
+      const alias = q(`c${suffix}`);
+      const value = (side) => physicalComparable(side.ref,
+        `${side.binding === count.binding ? alias : aliasOf(side.binding)}.${q(side.ref.column)}`, dialect);
+      const predicates = count.edges.map((edge) => `${value(edge.left)} = ${value(edge.right)}`);
+      if (count.filter) predicates.push(emitters.emitPred(alias, `${alias}.${q('doc')}`, count.filter));
+      return `(SELECT COUNT(*) FROM ${q(physicalOf(count.entity).table)} AS ${alias} `
+        + `WHERE ${predicates.join(' AND ')}) AS ${names}, ${sl('integer')} AS ${typeName}`;
+    }
     if (leaf.ref.flavor === 'entity-column') {
-      const column = `${aliasOf(leaf.binding)}.${q(leaf.ref.column)}`;
+      const raw = `${aliasOf(leaf.binding)}.${q(leaf.ref.column)}`;
+      const column = physicalComparable(leaf.ref,
+        leaf.ref.codec === 'integer'
+          ? `CASE WHEN ${dialect.valueTypeOf(raw)} = ${sl('integer')} THEN CAST(${raw} AS REAL) ELSE ${raw} END`
+          : raw, dialect);
+      const emptyType = leaf.ref.nullPolicy === 'null' ? sl('null') : 'NULL';
       const type = leaf.ref.storage === 'boolean'
-        ? `CASE WHEN ${column} IS NULL THEN NULL WHEN ${column} = 0 `
+        ? `CASE WHEN ${column} IS NULL THEN ${emptyType} WHEN ${column} = 0 `
           + `THEN ${sl('false')} ELSE ${sl('true')} END`
-        : `CASE WHEN ${column} IS NULL THEN NULL ELSE ${sl(
+        : `CASE WHEN ${column} IS NULL THEN ${emptyType} ELSE ${sl(
           leaf.ref.storage === 'string' ? 'text'
             : leaf.ref.storage === 'integer'
               ? dialect.numericTypeNames[0]
@@ -789,24 +849,54 @@ export function emitEntityPlan(plan, dialect, physicalOf) {
   // every returned column plus the document rendered to text; the
   // caller merges them back into the entity shape — or, for a projected
   // shape, one value/type pair per DISTINCT leaf and no document at all
-  const selection = plan.aggregate === 'count'
+  const group = plan.group;
+  const groupValue = (ref) => physicalComparable(ref,
+    `${aliasOf(plan.bindings[0].name)}.${q(ref.column)}`, dialect);
+  // Every integer addition is exact when the largest magnitude times
+  // the number of terms fits in the safe range. Sum as REAL so even a
+  // rejected group cannot overflow SQLite's integer accumulator first.
+  const numericGroup = (entry) => ['sum', 'avg'].includes(entry.fn);
+  const groupSafe = (entry) => `(COUNT(${groupValue(entry.ref)}) = 0 OR `
+    + `MAX(ABS(CAST(${groupValue(entry.ref)} AS REAL))) <= 9007199254740991 / COUNT(${groupValue(entry.ref)}))`;
+  const groupValid = (ref) => {
+    const value = groupValue(ref);
+    const type = dialect.valueTypeOf(value);
+    const valid = ref.codec === 'text' ? `${type} = ${sl('text')}`
+      : ref.codec === 'boolean' ? `${type} = ${sl('integer')} AND ${value} IN (0, 1)`
+        : `${type} ${ref.codec === 'integer' ? `= ${sl('integer')}` : `IN (${sl('integer')}, ${sl('real')})`}`
+          + ` AND ABS(CAST(${value} AS REAL)) <= 9007199254740991`;
+    return `MIN(CASE WHEN ${ref.nullPolicy === 'reject' ? '' : `${value} IS NULL OR `}(${valid}) THEN 1 ELSE 0 END)`;
+  };
+  const groupRefs = group ? [...group.keys, ...group.aggregates].map((entry) => entry.ref).filter((ref) => ref?.codecColumn) : [];
+  const selection = group
+    ? [...group.keys.map((key, i) => projectedPair({ binding: plan.bindings[0].name, ref: key.ref }, `k${i}`)),
+      ...group.aggregates.map((entry, i) => `${entry.fn === 'rows' ? 'COUNT(*)'
+        : dialect.groupAggregate(entry.fn, numericGroup(entry) || entry.ref.codec === 'integer'
+          ? `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.aggregate === 'count'
     ? `COUNT(*) AS ${q('value')}`
     : 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
-        ? `${aliasOf(ret)}.*, ${sl('{}')} AS ${q('__doc')}`
+        ? physicalOf(entityOf.get(ret)).mapping
+          ? physicalSelection(physicalOf(entityOf.get(ret)).mapping, dialect, `${aliasOf(ret)}.`)
+          : `${aliasOf(ret)}.*, ${sl('{}')} AS ${q('__doc')}`
         : `${aliasOf(ret)}.*, ${dialect.jsonText(docOf(ret))} AS ${q('__doc')}`;
 
   const tableOf = (name) =>
     `${q(physicalOf(entityOf.get(name)).table)} AS ${aliasOf(name)}`;
   const JOIN_OPS = { eq: '=', ne: '<>', lt: '<', le: '<=', gt: '>', ge: '>=' };
   const onSql = (edge) =>
-    `${aliasOf(edge.left.binding)}.${q(edge.left.column)}`
-    + ` ${JOIN_OPS[edge.op ?? 'eq']} ${aliasOf(edge.right.binding)}.${q(edge.right.column)}`;
+    physicalComparable(edge.left, `${aliasOf(edge.left.binding)}.${q(edge.left.column)}`, dialect)
+    + ` ${JOIN_OPS[edge.op ?? 'eq']} `
+    + physicalComparable(edge.right, `${aliasOf(edge.right.binding)}.${q(edge.right.column)}`, dialect);
 
   let sql = `SELECT ${selection} FROM `;
   // the JOIN order the planner settled: the first binding, then each
@@ -822,21 +912,39 @@ export function emitEntityPlan(plan, dialect, physicalOf) {
     .map((entry) => emitPred(entry.binding, entry.filter));
   if (filterSql.length > 0) sql += ` WHERE ${filterSql.join(' AND ')}`;
 
-  if (plan.aggregate === null) {
+  if (group) {
+    sql += ` GROUP BY ${group.keys.map((key, i) => `${q(`vk${i}`)}, ${q(`tk${i}`)}`).join(', ')}`;
+    const terms = group.order === 'first-seen' ? [] : group.order.map((term) =>
+      `${q(term.aggregate === undefined ? `vk${term.index}` : `a${term.aggregate}`)} ${term.desc ? 'DESC' : 'ASC'}${dialect.orderNulls(term.nullsFirst)}`);
+    const physical = physicalOf(plan.bindings[0].entity);
+    for (const key of physical.keys ?? [null]) {
+      const value = `${aliasOf(plan.bindings[0].name)}.${key === null ? dialect.rowIdentity() : q(key)}`;
+      const column = physical.mapping?.columns.find((c) => c.physical === key);
+      terms.push(`MIN(${column ? physicalComparable(column, value, dialect) : value})`);
+    }
+    sql += ` ORDER BY ${terms.join(', ')}`;
+    if (plan.window !== null) sql += ` ${dialect.limitClause(plan.window.limit, plan.window.offset)}`;
+  }
+  else if (plan.aggregate === null) {
     const terms = (plan.order ?? []).map((term) => {
       // only a plain mapped column orders by its column; an epoch
       // path orders by the document string — codepoint order, exactly
       // the engine's — because mixed stored precisions would let the
       // integer column sort differently
       const value = term.ref.flavor === 'entity-column'
-        ? `${aliasOf(term.binding)}.${q(term.ref.column)}`
+        ? physicalComparable(term.ref, `${aliasOf(term.binding)}.${q(term.ref.column)}`, dialect)
         : dialect.jsonExtract(docOf(term.binding), pathTextOf(term.ref), 'text');
       const nullsFirst = term.emptyGreatest === term.desc;
       return `${value} ${term.desc ? 'DESC' : 'ASC'}${dialect.orderNulls(nullsFirst)}`;
     });
     // the engine's nested-loop order: binding-order row identities
-    for (const binding of plan.bindings)
-      terms.push(`${aliasOf(binding.name)}.${dialect.rowIdentity()}`);
+    for (const binding of plan.bindings) {
+      const keys = physicalOf(binding.entity).keys;
+      if (keys) terms.push(...keys.map((key) => physicalComparable(
+        physicalOf(binding.entity).mapping.columns.find((c) => c.physical === key),
+        `${aliasOf(binding.name)}.${q(key)}`, dialect)));
+      else terms.push(`${aliasOf(binding.name)}.${dialect.rowIdentity()}`);
+    }
     sql += ` ORDER BY ${terms.join(', ')}`;
     if (plan.window !== null)
       sql += ` ${dialect.limitClause(plan.window.limit, plan.window.offset)}`;

package/src/entity.js

@@ -22,6 +22,11 @@ import { resolveRuntime } from '@jarenjs/core/runtime';
 
 import { DbRuntimeError, wrapDriverError } from './errors.js';
 import { chain, attempt } from './driver.js';
+import { checkInvariants } from './invariants.js';
+import { columnCodec, physicalRead } from './physical.js';
+import { mergeEntityRow } from './graph.js';
+import { createJSONPatch } from '@jarenjs/json/patch';
+import { createEntityMutation } from './mutation.js';
 
 /**
  * The write/read machinery for one entity, prepared once.
@@ -40,6 +45,11 @@ export function entityCore(connection, entity, entityMapping, validate, runtime
   const q = dialect.quoteIdentifier;
   const table = entityMapping.table;
   const docPath = entity.docPath;
+  const physical = entityMapping.document === false;
+  const physicalName = (name) => entityMapping.columns.find((c) => c.name === name)?.physical ?? name;
+  const writable = () => {
+    if (entityMapping.kind === 'view') throw new DbRuntimeError('JD2003', `entity '${entity.name}' is a read-only view`);
+  };
 
   // the column plan: mapped scalars (epoch ones derived), then FKs;
   // everything else lives in the JSONB document
@@ -47,6 +57,7 @@ export function entityCore(connection, entity, entityMapping, validate, runtime
     ...column,
     epoch: column.source === 'epoch(document)',
     property: entity.properties.get(column.name),
+    codecPlan: physical ? columnCodec(column) : null,
   }));
   // a declared via property is ALREADY a scalar column — the foreign
   // key adds a column only when no property claims it
@@ -90,7 +101,7 @@ export function entityCore(connection, entity, entityMapping, validate, runtime
 
   /** Split a completed document into bound column values + the rest.
    * Relation members are PROJECTIONS (§10.1) — never stored. */
-  const split = (doc) => {
+  const split = (doc, { updating = false } = {}) => {
     const values = [];
     /** @type {any} */
     const rest = {};
@@ -99,7 +110,12 @@ export function entityCore(connection, entity, entityMapping, validate, runtime
     }
     for (const column of scalarColumns) {
       if (column.name === autoKey && doc[column.name] === undefined) continue;
+      if (physical && (column.generated || (!updating && column.databaseDefault && doc[column.name] === undefined))) continue;
       const value = doc[column.name];
+      if (physical) {
+        values.push({ name: column.name, value: column.codecPlan.encode(value) });
+        continue;
+      }
       if (column.epoch) {
         // derived: the string stays in the document, the epoch rides
         // the column
@@ -118,24 +134,13 @@ export function entityCore(connection, entity, entityMapping, validate, runtime
       const value = doc[fk];
       values.push({ name: fk, value: value === undefined || value === null ? null : value });
     }
+    if (physical && Object.keys(rest).length > 0) throw new DbRuntimeError('JD2003',
+      `column-only entity '${entity.name}' cannot store undeclared members: ${Object.keys(rest).join(', ')}`);
     return { values, rest };
   };
 
   /** Merge a row back into a document. */
-  const merge = (row) => {
-    const doc = JSON.parse(row.doc);
-    for (const column of scalarColumns) {
-      if (column.epoch) continue; // the string is already in the doc
-      const value = row[column.name];
-      if (value === null || value === undefined) continue; // absent (§9.3)
-      doc[column.name] = column.storage === 'boolean' ? value === 1 : value;
-    }
-    for (const fk of fkColumns) {
-      const value = row[fk];
-      if (value !== null && value !== undefined) doc[fk] = value;
-    }
-    return doc;
-  };
+  const merge = (row) => mergeEntityRow(entityMapping, row);
 
   /** The document as a read will answer it. For a column-mapped scalar,
    * JSON `null` and absence both store as SQL NULL and read back ABSENT
@@ -145,6 +150,7 @@ export function entityCore(connection, entity, entityMapping, validate, runtime
    * `column: "json"` and stays in the document, where it survives; an
    * epoch column keeps its string in the document for the same reason. */
   const asStored = (doc) => {
+    if (physical) return doc;
     let out = doc;
     const drop = (name) => {
       if (!(name in out) || (out[name] !== null && out[name] !== undefined)) return;
@@ -158,6 +164,17 @@ export function entityCore(connection, entity, entityMapping, validate, runtime
     for (const fk of fkColumns) drop(fk);
     return out;
   };
+  const normalizePhysicalDoc = (doc) => {
+    if (!physical) return doc;
+    const normalized = { ...doc };
+    for (const column of scalarColumns) {
+      if (column.generated || !Object.hasOwn(doc, column.name)) continue;
+      const value = column.codecPlan.normalize(doc[column.name]);
+      if (value === undefined) delete normalized[column.name];
+      else normalized[column.name] = value;
+    }
+    return normalized;
+  };
 
   // defaults, compiled once
   const defaulters = [];
@@ -255,22 +272,24 @@ export function entityCore(connection, entity, entityMapping, validate, runtime
   };
   const parameterAt = (i) => dialect.parameterRef(i, 'v');
   const keyWhere = (offset) => keys
-    .map((key, i) => `${q(key)} = ${parameterAt(offset + i + 1)}`).join(' AND ');
+    .map((key, i) => `${q(physicalName(key))} = ${parameterAt(offset + i + 1)}`).join(' AND ');
   const selectColumns = [
-    ...scalarColumns.filter((column) => !column.epoch).map((column) => q(column.name)),
+    ...scalarColumns.filter((column) => !column.epoch).map((column) => physical
+      ? `${physicalRead(column, dialect)} AS ${q(physicalName(column.name))}` : q(column.name)),
     ...fkColumns.map((column) => q(column)),
-    `${dialect.jsonText(q('doc'))} AS ${q('doc')}`,
+    ...(physical ? [] : [`${dialect.jsonText(q('doc'))} AS ${q('doc')}`]),
   ].join(', ');
 
   const insertSqlFor = (names) => {
-    const withDoc = [...names, 'doc'];
-    const refs = withDoc.map((name, i) => (name === 'doc'
+    const withDoc = physical ? names : [...names, 'doc'];
+    const refs = withDoc.map((name, i) => (!physical && name === 'doc'
       ? dialect.jsonEncode(parameterAt(i + 1))
       : parameterAt(i + 1)));
     const returning = autoKey !== null && !names.includes(autoKey)
-      ? ` RETURNING ${q(autoKey)} AS ${q('key')}`
+      ? ` RETURNING ${q(physicalName(autoKey))} AS ${q('key')}`
       : '';
-    return `INSERT INTO ${q(table)} (${withDoc.map(q).join(', ')}) `
+    if (withDoc.length === 0) return `INSERT INTO ${q(table)} DEFAULT VALUES${returning}`;
+    return `INSERT INTO ${q(table)} (${withDoc.map((n) => q(physicalName(n))).join(', ')}) `
       + `VALUES (${refs.join(', ')})${returning}`;
   };
 
@@ -303,17 +322,22 @@ export function entityCore(connection, entity, entityMapping, validate, runtime
   /** Encode ONE column assignment the way {@link split} would. */
   const encodeColumn = (name, value) => {
     const column = columnByName.get(name);
+    if (physical && column) return column.codecPlan.encode(value);
     if (column !== undefined && column.epoch)
       return value === undefined ? null : epochOf(column.property, value);
     if (value === undefined || value === null) return null;
     return typeof value === 'boolean' ? (value ? 1 : 0) : value;
   };
 
-  return {
+  const core = {
     // the unit-of-work exposure (tracker.js): the column plan and the
     // completion/validation/stamping machinery, one source of truth
     plan: {
       table,
+      document: !physical,
+      physicalName,
+      writable,
+      checkMutation: (op, before, after) => checkInvariants(entity.invariants, op, before, after),
       keys,
       autoKey,
       version: entity.version ?? null,
@@ -325,7 +349,10 @@ export function entityCore(connection, entity, entityMapping, validate, runtime
       encodeColumn,
     },
     complete: (doc, { updating }) => {
-      const completed = applyDefaults(doc, { updating });
+      writable();
+      if (!updating && physical && scalarColumns.some((c) => c.generated && Object.hasOwn(doc, c.name)))
+        throw new DbRuntimeError('JD2003', 'generated columns are database-owned');
+      const completed = applyDefaults(normalizePhysicalDoc(doc), { updating });
       checkValid(completed);
       return asStored(completed);
     },
@@ -338,23 +365,33 @@ export function entityCore(connection, entity, entityMapping, validate, runtime
     },
     normalizeKey: (key) => normalizeKeyArg(key),
     create(doc) {
+      writable();
       refuseProjections(doc, 'create', true);
       const completed = applyDefaults(doc, { updating: false });
       checkValid(completed);
+      if (!physical) checkInvariants(entity.invariants, 'insert', null, completed);
+      if (physical && scalarColumns.some((c) => c.generated && Object.hasOwn(doc, c.name)))
+        throw new DbRuntimeError('JD2003', 'generated columns are database-owned');
       const { values, rest } = split(completed);
       const names = values.map((value) => value.name);
       const sql = insertSqlFor(names);
-      return chain(prepared(`insert:${names.join(',')}`, sql), (statement) => {
-        const params = [...values.map((value) => value.value), JSON.stringify(rest)];
+      const insert = () => chain(prepared(`insert:${names.join(',')}`, sql), (statement) => {
+        const params = [...values.map((value) => value.value), ...(physical ? [] : [JSON.stringify(rest)])];
         const returning = autoKey !== null && !names.includes(autoKey);
         return chain(
           attempt(() => (returning ? statement.get(params) : statement.run(params)),
             (error) => wrapWrite(error, completed[keys[0]])),
-          (out) => asStored(returning ? { ...completed, [autoKey]: out.key } : completed));
+          (out) => {
+            const made = returning ? { ...completed, [autoKey]: out.key } : completed;
+            return physical ? chain(this.get(made), (stored) => {
+              checkValid(stored); checkInvariants(entity.invariants, 'insert', null, stored); return stored;
+            }) : asStored(made);
+          });
       });
+      return physical ? connection.transaction(insert) : insert();
     },
     get(key) {
-      const parts = normalizeKeyArg(key);
+      const parts = normalizeKeyArg(key).map((v, i) => physical ? columnByName.get(keys[i]).codecPlan.encode(v) : v);
       const sql = `SELECT ${selectColumns} FROM ${q(table)} WHERE ${keyWhere(0)}`;
       // classified like every read of the query engines, never raw
       return attempt(() => chain(prepared('get', sql), (statement) =>
@@ -362,9 +399,10 @@ export function entityCore(connection, entity, entityMapping, validate, runtime
       (error) => wrapDriverError(error, { docPath, collection: entity.name, key }));
     },
     update(key, changes) {
-      const parts = normalizeKeyArg(key);
+      writable();
+      const parts = normalizeKeyArg(key).map((v, i) => physical ? columnByName.get(keys[i]).codecPlan.encode(v) : v);
       refuseProjections(changes, 'update', false);
-      return chain(this.get(key), (current) => {
+      const update = () => chain(this.get(key), (current) => {
         if (current === undefined) {
           throw new DbRuntimeError('JD2006',
             `no '${entity.name}' to update under that key`,
@@ -379,32 +417,51 @@ export function entityCore(connection, entity, entityMapping, validate, runtime
               { docPath, collection: entity.name, key: parts[0] });
           }
         }
-        const next = applyDefaults({ ...current, ...changes }, { updating: true });
+        const candidate = normalizePhysicalDoc({ ...current, ...changes });
+        if (physical && createJSONPatch(current, candidate).length === 0) return current;
+        if (physical && scalarColumns.some((c) => c.generated && Object.hasOwn(changes, c.name)
+          && changes[c.name] !== current[c.name])) throw new DbRuntimeError('JD2003', 'generated columns are database-owned');
+        const next = applyDefaults(candidate, { updating: true });
         // an explicit update is last-write-wins by contract (§11.2),
         // but it still moves a declared version token so optimistic
         // savers see the row changed
         if (entity.version !== null && entity.version !== undefined)
           next[entity.version] = (Number(current[entity.version]) || 0) + 1;
         checkValid(next);
-        const { values, rest } = split(next);
+        if (!physical) checkInvariants(entity.invariants, 'update', current, next);
+        const { values, rest } = split(next, { updating: true });
         const assignments = [
-          ...values.map((value, i) => `${q(value.name)} = ${parameterAt(i + 1)}`),
-          `${q('doc')} = ${dialect.jsonEncode(parameterAt(values.length + 1))}`,
+          ...values.map((value, i) => `${q(physicalName(value.name))} = ${parameterAt(i + 1)}`),
+          ...(physical ? [] : [`${q('doc')} = ${dialect.jsonEncode(parameterAt(values.length + 1))}`]),
         ].join(', ');
         const sql = `UPDATE ${q(table)} SET ${assignments} `
-          + `WHERE ${keyWhere(values.length + 1)}`;
-        return chain(prepared(`update:${values.length}`, sql), (statement) =>
+          + `WHERE ${keyWhere(values.length + (physical ? 0 : 1))}`;
+        return chain(prepared(`update:${values.map((v) => v.name).join(',')}`, sql), (statement) =>
           chain(attempt(() => statement.run([...values.map((value) => value.value),
-            JSON.stringify(rest), ...parts]), (error) => wrapWrite(error, parts[0])),
-          () => asStored(next)));
+            ...(physical ? [] : [JSON.stringify(rest)]), ...parts]), (error) => wrapWrite(error, parts[0])),
+          () => physical ? chain(this.get(key), (stored) => {
+            checkValid(stored); checkInvariants(entity.invariants, 'update', current, stored); return stored;
+          }) : asStored(next)));
       });
+      return physical ? connection.transaction(update) : update();
     },
     delete(key) {
-      const parts = normalizeKeyArg(key);
+      writable();
+      if (entity.invariants.some((r) => r.enforcement === 'store' && r.on.includes('delete')))
+        return chain(this.get(key), (before) => {
+          checkInvariants(entity.invariants, 'delete', before, null);
+          return remove(key);
+        });
+      return remove(key);
+    },
+  };
+  core.mutate = createEntityMutation(connection, entity, entityMapping, core);
+  return core;
+  function remove(key) {
+      const parts = normalizeKeyArg(key).map((v, i) => physical ? columnByName.get(keys[i]).codecPlan.encode(v) : v);
       const sql = `DELETE FROM ${q(table)} WHERE ${keyWhere(0)}`;
       return chain(prepared('delete', sql), (statement) =>
         chain(attempt(() => statement.run(parts), (error) => wrapWrite(error, parts[0])),
           (result) => Number(result?.changes ?? 0) > 0));
-    },
-  };
+  }
 }