@jarenjs/db 0.75.0 → 0.83.2

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
@@ -653,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`;
@@ -710,7 +715,7 @@ export function createEntityPredicateEmitters(dialect, param) {
   const emitPred = (aliasSql, docSql, pred) => {
     if (pred.p === 'refCmp') return compareRefs(pred, (ref) => {
       if (ref.flavor === 'entity-column') {
-        const value = `${aliasSql}.${q(ref.column)}`;
+        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.
@@ -804,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]
@@ -829,7 +849,33 @@ 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
@@ -839,15 +885,18 @@ export function emitEntityPlan(plan, dialect, physicalOf) {
       // 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
@@ -863,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));
-    },
-  };
+  }
 }

package/src/errors.js

@@ -46,6 +46,7 @@ export const DB_CODES = Object.freeze({
   JD0035: 'the continuation does not belong to this ordering',
   JD0036: 'a snapshot page needs an immutable ordering',
   JD0037: 'strictStreaming refused a plan that buffers',
+  JD0038: 'the native mutation document is unsupported or invalid',
   JD0040: 'the save spans a relation cycle',
   JD0050: 'live queries require change capture',
   JD0051: 'the demanded live mode is unavailable',
@@ -109,6 +110,8 @@ export const DB_CODES = Object.freeze({
   JD2092: 'a worker transport bound was exceeded',
   JD2093: 'the worker protocol frame is invalid',
   JD2094: 'the durable snapshot failed and the connection is invalid',
+  JD2095: 'the trusted SQL or synchronous transaction authority was refused',
+  JD2096: 'a persistence invariant rejected the mutation',
 });
 
 /**
@@ -554,6 +557,11 @@ export function wrapDriverError(error, details = {}) {
     generic.retryable = false;
     return generic;
   }
+  if (typeof error?.message === 'string' && error.message.includes('jaren invariant:')) {
+    const wrapped = new DbRuntimeError('JD2096', error.message, { ...details, cause: error });
+    wrapped.class = 'constraint'; wrapped.retryable = false;
+    return wrapped;
+  }
   const classified = classifyDriverError(error, details.unique);
   const message = error?.message ?? String(error);
   /** @type {any} */

package/src/graph.js

@@ -14,6 +14,8 @@
  * whole one.
  */
 
+import { columnCodec } from './physical.js';
+
 import { DbRuntimeError } from './errors.js';
 import { utf8Length } from './cursor.js';
 import { jsonBytes, decodeCountedJson } from './json-bytes.js';
@@ -73,9 +75,14 @@ function checkBounds(node, include, keyed, raw, sizes) {
  * @returns {any}
  */
 export function mergeEntityRow(entityMapping, row, docField = 'doc') {
-  const doc = JSON.parse(row[docField]);
+  const doc = entityMapping.document === false ? {} : JSON.parse(row[docField]);
   for (const column of entityMapping.columns) {
     if (column.source === 'epoch(document)') continue;
+    if (entityMapping.document === false && column.codec) {
+      const value = columnCodec(column).decode(row[column.physical ?? column.name]);
+      if (value !== undefined) Object.defineProperty(doc, column.name, { value, enumerable: true, writable: true, configurable: true });
+      continue;
+    }
     const value = row[column.name];
     if (value === null || value === undefined) continue;
     doc[column.name] = column.storage === 'boolean' ? value === 1 : value;

package/src/index.js

@@ -100,3 +100,6 @@ export {
 export { createDagJobRunner, RUN_IDENTITY_NODE } from './dag-job.js';
 export { REPLICATION_VERSION, REPLICATION_DEFAULTS, normalizeFrontier,
   normalizeReplication, normalizeReplicationSnapshot, encodeReplication, replicationIdentity } from './replication-format.js';
+
+export { planInvariants } from './ddl.js';
+export { planPhysicalMigration } from './migrate.js';

package/src/introspect.js

@@ -73,7 +73,7 @@ function loss(code, object, detail) {
  * @param {string} table
  * @returns {any} value-or-promise
  */
-function readTable(connection, table) {
+function readTable(connection, table, objects) {
   const dialect = connection.dialect;
   const all = (sql) => chain(connection.prepare(sql), (statement) => statement.all([]));
   return chain(all(dialect.introspect.columns(table)), (columnRows) =>
@@ -97,6 +97,7 @@ function readTable(connection, table) {
                 unique: Number(declared[i].uniq) !== 0,
                 partial: Number(declared[i].partial ?? 0) !== 0,
                 columns: rows.map((row) => row.name == null ? null : String(row.name)),
+                sql: objects.find((o) => o.type === 'index' && o.name === String(declared[i].name))?.sql ?? null,
               }]));
           };
           return chain(withColumns(0, []), (indexes) =>
@@ -106,11 +107,18 @@ function readTable(connection, table) {
               chain(dialect.introspect.checks === undefined ? []
                 : all(dialect.introspect.checks(table)), (checkRows) => ({
               name: table,
-              primaryKey: keyRows.map((row) => String(row.name)),
+              sql: objects.find((o) => o.type === 'table' && o.name === table)?.sql ?? null,
+              primaryKey: columnRows.some((row) => Number(row.pk) > 0)
+                ? columnRows.filter((row) => Number(row.pk) > 0)
+                  .sort((a, b) => Number(a.pk) - Number(b.pk)).map((row) => String(row.name))
+                : keyRows.map((row) => String(row.name)),
               columns: columnRows.map((row) => ({
                 name: String(row.name),
                 type: String(row.type),
                 generated: Number(row.hidden) !== 0,
+                primaryKeyOrdinal: Number(row.pk ?? 0),
+                nullable: Number(row.not_null ?? 0) === 0,
+                default: row.default_value ?? null,
               })),
               generated: dialect.readGenerated(generatedRows),
               indexes,
@@ -121,6 +129,10 @@ function readTable(connection, table) {
                 targetColumn: row.target_column === null || row.target_column === undefined
                   ? null : String(row.target_column),
                 onDelete: String(row.on_delete ?? 'NO ACTION').toUpperCase(),
+                onUpdate: String(row.on_update ?? 'NO ACTION').toUpperCase(),
+                group: row.id ?? null,
+                ordinal: Number(row.seq ?? 0),
+                match: String(row.match ?? 'NONE'),
               })),
             }))));
         }))));
@@ -153,10 +165,23 @@ export function readSchema(connection, options = undefined) {
         if (String(row.type) === 'view') views.push(name);
         else names.push(name);
       }
-      const step = (i, out) => (i >= names.length
-        ? { tables: out, views }
-        : chain(readTable(connection, names[i]), (table) => step(i + 1, [...out, table])));
-      return step(0, []);
+      const readObjects = dialect.introspect.objects === undefined ? []
+        : chain(connection.prepare(dialect.introspect.objects()), (s) => s.all([]));
+      return chain(readObjects, (catalog) => {
+        const complete = [...catalog];
+        for (const row of rows) {
+          if (!complete.some((o) => o.type === row.type && o.name === row.name))
+            complete.push({ ...row, owner: row.name, sql: null });
+        }
+        const objects = complete.filter((row) => !engine.has(String(row.owner))
+          && (wanted === null || wanted.has(String(row.owner)) || wanted.has(String(row.name))))
+          .map((row) => ({ type: String(row.type), name: String(row.name),
+            owner: String(row.owner), sql: row.sql ?? null }));
+        const step = (i, out) => (i >= names.length
+          ? { tables: out, views, objects }
+          : chain(readTable(connection, names[i], objects), (table) => step(i + 1, [...out, table])));
+        return step(0, []);
+      });
     }));
 }
 
@@ -547,6 +572,11 @@ export function introspectModel(connection, options = undefined) {
       add(loss('unmapped-view', view,
         'a view is not a shape a model document can declare'));
     }
+    for (const object of schema.objects) {
+      if (object.type === 'trigger') add({ ...loss('unmapped-object', object.name,
+        'an application-owned trigger program must be explicitly preserved; inspection grants no drop permission'),
+      sql: object.sql, owner: object.owner });
+    }
 
     const joinTables = new Set(schema.tables
       .filter((table) => looksLikeJoinTable(dialect, table))
@@ -610,6 +640,13 @@ export function introspectModel(connection, options = undefined) {
         + `thing(s) the model would — ${report.map((row) => `${row.code} (${row.object})`)
           .join(', ')}`);
     }
-    return { model, report: Object.freeze(report.map((row) => Object.freeze(row))) };
+    const inventory = schema.objects.map((object) => Object.freeze({ ...object,
+      disposition: object.type === 'trigger' || object.type === 'view'
+        || report.some((row) => row.object === object.name
+          || row.object === `${object.owner}.${object.name}`
+          || (row.code === 'unmapped-table' && row.object === object.owner))
+        ? 'preserve' : 'derived' }));
+    return { model, report: Object.freeze(report.map((row) => Object.freeze(row))),
+      inventory: Object.freeze(inventory) };
   });
 }