@jarenjs/db 0.73.0 → 0.83.2

package/src/search.js

@@ -0,0 +1,144 @@
+//@ts-check
+/** Optional lexical persistence and bounded execution over authoritative entity snapshots. */
+import { compileLexical } from '@jarenjs/core/search';
+import { createLexicalProvider } from '@jarenjs/json/query';
+import { canonicalizeJson } from '@jarenjs/json/canonical';
+import { utf8ByteLength } from '@jarenjs/core/string';
+import { isCursorBudgetError } from './cursor.js';
+
+/** Atomic snapshot storage over a host-declared collection of {id, payload} documents.
+ * Snapshot rows are derived caches and never answer catalog queries.
+ * @param {any} store @param {string} collection @param {{maxBytes?:number}} [options] */
+export function createDbSearchStorage(store, collection, options = {}) {
+  const maxBytes = options.maxBytes ?? 64 * 1024 * 1024;
+  if (typeof collection !== 'string' || !collection || !Number.isSafeInteger(maxBytes) || maxBytes < 1)
+    throw new TypeError('Invalid lexical snapshot storage');
+  return {
+    async load(id) { const row = await store.collection(collection).get(id);
+      if (!row) return null;
+      if (typeof row.payload !== 'string' || row.payload.length > maxBytes || utf8ByteLength(row.payload) > maxBytes)
+        throw new RangeError('Snapshot storage byte credits');
+      return row.payload;
+    },
+    async save(id, payload) {
+      if (typeof id !== 'string' || !id || typeof payload !== 'string' || payload.length > maxBytes || utf8ByteLength(payload) > maxBytes)
+        throw new RangeError('Snapshot storage byte credits');
+      return store.transaction(async (tx) => {
+        const target = tx.collection(collection), old = await target.get(id);
+        if (old?.payload === payload) return { changes: 0 };
+        await target.put({ id, payload }); return { changes: 1 };
+      });
+    },
+  };
+}
+
+/**
+ * Read a bounded, complete entity snapshot inside the store transaction; captured
+ * commits invalidate it. External SQL invalidates through dataVersion on request.
+ * A SHA-256 source-content revision also detects uncaptured edits across reopen.
+ * Native FTS is deliberately refused: this adapter executes the shared ranker.
+ * @param {any} store @param {string} entity
+ * @param {import('@jarenjs/core/search').LexicalDefinition} definition
+ * @param {{source:string, maxRows?:number, maxBytes?:number, storage?:{load:(key:string)=>Promise<string|null>,save:(key:string,payload:string)=>Promise<any>}, snapshotKey?:string}} options
+ * @returns {Promise<any>}
+ */
+export async function createDbSearch(store, entity, definition, options) {
+  const maxRows = options?.maxRows ?? 10000, maxBytes = options?.maxBytes ?? 8 * 1024 * 1024;
+  if (typeof options?.source !== 'string' || !options.source || !Number.isSafeInteger(maxRows) || maxRows < 1
+    || !Number.isSafeInteger(maxBytes) || maxBytes < 2) throw new TypeError('Invalid lexical source credits');
+  if (!store.capabilities?.capture || store.capabilities.capture === 'none') throw new TypeError('Lexical freshness requires committed capture');
+  const compiled = compileLexical(definition), index = compiled.create(), storage = options.storage;
+  const snapshotKey = options.snapshotKey ?? `${options.source}:${entity}`;
+  let rows = new Map(), sourceRevision = '', dataVersion, dirty = true, disposed = false, epoch = 0, busy = null;
+  let reads = 0, writes = 0, restores = 0, rebuilds = 0, sourceBytes = 0, recovery = null, pendingSnapshot = null;
+  const observers = new Set(), controller = new AbortController();
+  const invalidate = (reason) => {
+    dirty = true; epoch++;
+    for (const observer of observers) { try { observer({ type: 'reset', reason, revision: epoch, sourceRevision }); }
+      catch { /* An observer cannot suppress a sibling's invalidation. */ } }
+  };
+  const unsubscribe = store.observe((record) => { if (record.collections.includes(entity)) invalidate('source-changed'); });
+  const refusal = (state, reason) => ({ state, reason, hits: [], total: null, sourceRevision });
+  const refresh = async () => {
+    if (disposed) return refusal('error', 'disposed');
+    if (busy) return busy;
+    const run = async () => {
+      try {
+        const loaded = await store.transaction(async (tx) => {
+          const current = await tx.dataVersion();
+          if (dataVersion !== undefined && current !== dataVersion) invalidate('external-source-changed');
+          dataVersion = current;
+          if (!dirty) return null;
+          const page = await tx.entity(entity).page({ orderBy: '$it.id' },
+            { limit: maxRows + 1, maxBytes, lookahead: false, signal: controller.signal });
+          reads++;
+          if (page.hasMore !== false || page.items.length > maxRows) throw new RangeError('Lexical source exceeds row credits');
+          const source = canonicalizeJson(page.items);
+          if (utf8ByteLength(source) > maxBytes) throw new RangeError('Lexical source exceeds byte credits');
+          const digest = await globalThis.crypto.subtle.digest('SHA-256', new TextEncoder().encode(source));
+          const revision = `${options.source}:${Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, '0')).join('')}`;
+          return { items: page.items, revision, bytes: utf8ByteLength(source), epoch };
+        }, { signal: controller.signal });
+        if (disposed) return refusal('error', 'disposed');
+        if (!loaded) return { state: 'complete', changes: 0, sourceRevision };
+        if (loaded.epoch !== epoch) return refusal('invalidated', 'source-changed');
+        if (loaded.revision === sourceRevision) {
+          if (pendingSnapshot !== null) { writes += (await storage.save(snapshotKey, pendingSnapshot)).changes; pendingSnapshot = null; }
+          if (disposed || loaded.epoch !== epoch) return refusal(disposed ? 'error' : 'invalidated', disposed ? 'disposed' : 'source-changed');
+          dirty = false; return { state: 'complete', changes: 0, sourceRevision };
+        }
+        const nextRows = new Map(loaded.items.map((row) => [row.id, Object.freeze(row)]));
+        if (nextRows.size !== loaded.items.length) throw new TypeError('Duplicate lexical source IDs');
+        let result;
+        if (!sourceRevision && storage) {
+          const saved = await storage.load(snapshotKey);
+          if (saved !== null) {
+            result = index.restore(saved, { sourceRevision: loaded.revision });
+            if (result.state === 'complete') restores++; else recovery = result.reason;
+          }
+        }
+        if (disposed || loaded.epoch !== epoch) return refusal(disposed ? 'error' : 'invalidated', disposed ? 'disposed' : 'source-changed');
+        if (result?.state !== 'complete') {
+          result = index.rebuild(loaded.items, { sourceRevision: loaded.revision }); rebuilds++;
+        }
+        if (result.state !== 'complete') return { ...result, hits: [], total: null };
+        rows = nextRows; sourceRevision = loaded.revision; sourceBytes = loaded.bytes; dirty = false;
+        if (storage) { pendingSnapshot = index.snapshot(); writes += (await storage.save(snapshotKey, pendingSnapshot)).changes; pendingSnapshot = null; }
+        if (disposed || loaded.epoch !== epoch) return refusal(disposed ? 'error' : 'invalidated', disposed ? 'disposed' : 'source-changed');
+        return { state: 'complete', changes: result.changes, sourceRevision };
+      }
+      catch (error) { dirty = true; return refusal(error instanceof RangeError || isCursorBudgetError(error)
+        ? 'budget-exhausted' : 'error', disposed ? 'disposed' : error?.message ?? String(error)); }
+    };
+    busy = run().finally(() => { busy = null; }); return busy;
+  };
+  const service = {
+    refresh,
+    get sourceRevision() { return sourceRevision; },
+    async search(text, spec = {}) {
+      const ready = await refresh(); if (ready.state !== 'complete') return ready;
+      return createLexicalProvider(index, { row: (id) => rows.get(id) }).compile(spec)(text);
+    },
+    /** Access a row only under its published search revision. */
+    row(id, revision) {
+      if (disposed || dirty || revision !== sourceRevision) throw new Error('Lexical source snapshot changed');
+      return structuredClone(rows.get(id));
+    },
+    subscribe(fn) {
+      if (disposed || typeof fn !== 'function') throw new TypeError('Invalid lexical observer');
+      if (observers.size >= 8) throw new RangeError('Lexical subscription credits');
+      observers.add(fn); return () => observers.delete(fn);
+    },
+    explain() { return { mode: 'resident', nativeFTS: false, reason: 'native-token-rank-parity-unqualified',
+      maxRows, maxBytes, capture: store.capabilities.capture, externalChanges: 'dataVersion plus authoritative SHA-256 on refresh' }; },
+    stats() { return { ...index.stats(), sourceRows: rows.size, sourceBytes, reads, writes, restores, rebuilds,
+      recovery, dirty, pending: busy ? 1 : 0, subscriptions: observers.size }; },
+    async dispose() {
+      disposed = true; controller.abort(); unsubscribe(); observers.clear();
+      await busy; index.dispose(); rows.clear(); sourceBytes = 0; pendingSnapshot = null;
+    },
+  };
+  const ready = await refresh();
+  if (ready.state !== 'complete') { await service.dispose(); throw new Error(`Lexical source: ${ready.reason}`); }
+  return service;
+}

package/src/sql.js

@@ -0,0 +1,60 @@
+//@ts-check
+/** Trusted prepared statements, restricted to a live transaction's authority. */
+import { sqlTokens } from './dialects/check-read.js';
+import { chain, attempt } from './driver.js';
+import { DbRuntimeError, wrapDriverError } from './errors.js';
+
+/** @param {any} context @returns {any} a scoped SQL capability */
+export function trustedSql({ connection, requireScope, beforeWrite, afterWrite, readOnly }) {
+  return Object.freeze({
+    /** Compile one statement. Access is explicit; this is trusted application SQL,
+     * not a sandbox for untrusted query text or side-effecting host functions.
+     * @param {string} sql @param {{ access: 'read' | 'write', affects?: readonly string[] }} options */
+    prepare(sql, options) {
+      requireScope();
+      const refuse = (why) => { throw new DbRuntimeError('JD2095', why); };
+      if (typeof sql !== 'string' || !['read', 'write'].includes(options?.access)) refuse('SQL prepare requires text and explicit read/write access');
+      const tokens = sqlTokens(sql);
+      const words = tokens.filter((t) => t.kind === 'word').map((t) => t.value.toUpperCase());
+      if (!tokens.length || tokens[0].kind !== 'word' || !['SELECT', 'WITH', 'INSERT', 'UPDATE', 'DELETE', 'REPLACE'].includes(words[0])) refuse('trusted SQL accepts a single SELECT or data mutation');
+      if (tokens.some((t, i) => t.value === ';' && t.kind === 'symbol' && i !== tokens.length - 1)
+        || words.some((w) => /^(?:BEGIN|COMMIT|ROLLBACK|SAVEPOINT|RELEASE|ATTACH|DETACH|PRAGMA|CREATE|ALTER|DROP|VACUUM)$/.test(w))) refuse('SQL cannot change transaction ownership, schema or connection configuration');
+      const writing = options.access === 'write';
+      if (!writing && words.some((w) => ['INSERT', 'UPDATE', 'DELETE', 'REPLACE'].includes(w))) refuse('a mutation requires write access');
+      if (writing && readOnly) refuse('this store grants no SQL write authority');
+      if (options.affects !== undefined && (!Array.isArray(options.affects) || options.affects.some((v) => typeof v !== 'string'))) refuse('affects is an array of entity names');
+      let closed = false;
+      const check = () => {
+        requireScope();
+        if (closed) refuse('the prepared SQL statement is closed');
+      };
+      const statement = connection.prepare(sql, { readOnly: !writing });
+      const run = (method, params = []) => {
+        check();
+        if (!Array.isArray(params)) refuse('SQL parameters must be an array');
+        return attempt(() => chain(statement, (s) => {
+          check();
+          if (writing) beforeWrite(options.affects);
+          return chain(s[method](params), (result) => {
+            if (writing) afterWrite(options.affects);
+            return result;
+          });
+        }), (error) => wrapDriverError(error, { docPath: '/sql' }));
+      };
+      return Object.freeze({ run: (params) => run('run', params),
+        get: (params) => run('get', params), all: (params) => run('all', params),
+        close: () => { requireScope(); closed = true; } });
+    },
+  });
+}
+
+/** A synchronous transaction ends at callback return, including a thenable return.
+ * @param {Function} fn @param {any} tx @returns {any} */
+export function synchronousBody(fn, tx) {
+  const value = fn(tx);
+  if (value != null && typeof value.then === 'function') {
+    Promise.resolve(value).catch(() => {});
+    throw new DbRuntimeError('JD2095', 'a synchronous transaction callback must not return a thenable');
+  }
+  return value;
+}

package/src/store.js

@@ -36,6 +36,8 @@ import { createBackup } from './backup.js';
 import { normalizeProfile, assertProfileRoots } from './profile.js';
 import { normalizeEntities, explainMapping, joinTableRoots } from './model.js';
 import { entityCore } from './entity.js';
+import { verifyPhysical } from './physical.js';
+import { trustedSql, synchronousBody } from './sql.js';
 import { createTracker, membershipKeys } from './tracker.js';
 import { createCaptureEngine, DEFAULT_RETENTION } from './capture.js';
 import { createReplicationEngine } from './replication.js';
@@ -46,7 +48,7 @@ import { createLiveRegistry, classifyLiveQuery, LIVE_DEFAULTS } from './live.js'
 import { classifyEntityLive } from './live-join.js';
 import { normalizeEventTime } from './live-time.js';
 import { createJobEngine } from './jobs.js';
-import { introspectModel } from './introspect.js';
+import { introspectModel, readSchema } from './introspect.js';
 import { collectEntityRoots, entityRoot } from './plan.js';
 import {
   DERIVE_KINDS, PHYSICAL_KINDS, PRECISION_MIN, PRECISION_MAX, DIMS_MIN, DIMS_MAX,
@@ -486,6 +488,7 @@ function immediately(connection, fn, retry = true) {
 function ensureShape(connection, collections, plans, readOnly) {
   const dialect = connection.dialect;
   const names = [...collections.keys()];
+  if (names.length === 0) return null;
   // a read-only store creates nothing, and cannot take a write lock
   const bracket = readOnly ? (fn) => fn() : (fn) => immediately(connection, fn);
   return bracket(() => {
@@ -537,6 +540,8 @@ function ensureEntityShape(connection, entityPlans, entities, readOnly) {
       const name = names[i];
       const plan = entityPlans.get(name);
       const docPath = entities.get(name)?.docPath ?? `/entities/${name}`;
+      if (plan.physical) return chain(readSchema(connection), (schema) =>
+        chain(verifyPhysical(connection, plan.physical, schema), () => step(i + 1)));
       return chain(connection.prepare(dialect.introspect.tableExists()), (statement) =>
         chain(statement.get([name]), (row) => {
           if (row === undefined) {
@@ -824,10 +829,11 @@ function asyncCollection(core, live) {
  */
 function writeSchemaOf(entity) {
   const schema = entity.schema;
-  const auto = entity.keys.find((key) => entity.properties.get(key).default === 'auto');
-  if (auto === undefined || !Array.isArray(schema?.required) || !schema.required.includes(auto))
-    return schema;
-  const out = { ...schema, required: schema.required.filter((name) => name !== auto) };
+  const generated = new Set(entity.keys.filter((key) => entity.properties.get(key).default === 'auto'));
+  for (const column of entity.physical?.columns ?? [])
+    if (column.databaseDefault || column.generated) generated.add(column.name);
+  if (!Array.isArray(schema?.required) || !schema.required.some((name) => generated.has(name))) return schema;
+  const out = { ...schema, required: schema.required.filter((name) => !generated.has(name)) };
   if (out.required.length === 0) delete out.required;
   return out;
 }
@@ -971,6 +977,10 @@ export function openStore(model, options) {
     collections = normalizeModel(model, options.expressions);
     entities = normalizeEntities(model);
     mapping = entities.size > 0 ? explainMapping(model) : null;
+    if ([...entities.values()].some((e) => e.physical !== null) && (options.capture || options.replication))
+      throw new DbCompileError('JD0051', 'column adoption preserves application triggers; complete capture is not qualified');
+    if (options.adopt === true && (options.capture || options.replication))
+      throw new DbCompileError('JD0005', 'adoption creates no infrastructure; configure it through an explicit migration');
     if (options.replication !== undefined && [...collections.keys(), ...entities.keys()]
       .some((name) => name.toLowerCase().startsWith('_jaren_replica')))
       throw new DbCompileError('JD0060', 'replication reserves table names beginning with _jaren_replica');
@@ -1425,8 +1435,8 @@ export function openStore(model, options) {
         chain(registerExpressionFunctions(connection, expressionNames,
           options.expressions ?? {}), () =>
         chain(needsDeriveFunctions ? registerDeriveFunctions(connection) : null, () =>
-        chain(ensureShape(connection, collections, plans, readOnly), () =>
-        chain(ensureEntityShape(connection, entityPlans, entities, readOnly), () => {
+        chain(ensureShape(connection, collections, plans, readOnly || options.adopt === true), () =>
+        chain(ensureEntityShape(connection, entityPlans, entities, readOnly || options.adopt === true), () => {
           /** @type {Map<string, any>} */
           const cores = new Map();
           const coreFor = (name) => {
@@ -1598,6 +1608,7 @@ export function openStore(model, options) {
           }
           const jobsEngine = !jobsRequested ? null : createJobEngine({
             connection,
+            adopt: options.adopt === true,
             bracket: firstOpen,
             // the WORKER's control-plane I/O (claims, renewals, its
             // checkpoint stores, its settlements) is root-owned and takes
@@ -1994,6 +2005,7 @@ export function openStore(model, options) {
               return next(0);
             };
             ops = {
+              mutate: (document) => core.mutate(document),
               create: (doc) => {
                 const memberships = membershipsOf(doc);
                 if (memberships.length === 0)
@@ -2066,6 +2078,7 @@ export function openStore(model, options) {
                   create: lift((doc) => ops.create(doc)),
                   get: lift((key) => ops.get(key)),
                   update: lift((key, changes) => ops.update(key, changes)),
+                  mutate: lift((document) => ops.mutate(document)),
                   delete: lift((key) => ops.delete(key)),
                   load: lift((spec, loadOptions) => ops.load(spec, loadOptions)),
                   loadCursor: (spec, cursorOptions) => ops.loadCursor(spec, cursorOptions),
@@ -2252,7 +2265,8 @@ export function openStore(model, options) {
             for (const member of names) {
               if (typeof handle[member] !== 'function') continue;
               out[member] = (/** @type {any[]} */ ...args) =>
-                lift(() => gated(() => handle[member](...args)))();
+                lift(() => gated(() => handle[member](...args), undefined,
+                  member === 'page' ? args[1]?.signal : undefined))();
             }
             for (const member of valued) {
               if (typeof handle[member] !== 'function') continue;
@@ -2315,7 +2329,7 @@ export function openStore(model, options) {
                 // collection's `query` does: admitted one item at a time,
                 // never held across the caller's loop
                 handle = gatedMembers(inner,
-                  ['create', 'get', 'update', 'delete', 'load', 'page', 'explain'],
+                  ['create', 'get', 'update', 'mutate', 'delete', 'load', 'page', 'explain'],
                   ['execute']);
                 const untracked = gatedMembers(inner.asNoTracking(), ['get', 'load']);
                 handle = Object.freeze({
@@ -2434,6 +2448,7 @@ export function openStore(model, options) {
               get: lift((...args) => gated(() => jobsEngine.get(...args), 'a root job read')),
               counts: lift(() => gated(() => jobsEngine.counts(), 'a root job read')),
               claim: lift((...args) => gated(() => jobsEngine.claim(...args), 'a root job claim')),
+              assertLease: lift((...args) => gated(() => jobsEngine.assertLease(...args), 'a root lease check')),
               renew: lift((...args) => gated(() => jobsEngine.renew(...args), 'a root lease renewal')),
               complete: lift((...args) => gated(() => jobsEngine.complete(...args), 'a root job settlement')),
               fail: lift((...args) => gated(() => jobsEngine.fail(...args), 'a root job settlement')),
@@ -2598,7 +2613,7 @@ export function openStore(model, options) {
               scopedMembers(identity, inner.asNoTracking(), ['get', 'load']));
             return Object.freeze({
               ...scopedMembers(identity, inner,
-                ['create', 'get', 'update', 'delete', 'load', 'page', 'explain'],
+                ['create', 'get', 'update', 'mutate', 'delete', 'load', 'page', 'explain'],
                 ['execute', 'add', 'put', 'remove', 'discard', 'link', 'unlink']),
               cursor: (/** @type {any} */ document, /** @type {any} */ queryOptions) =>
                 scopedCursor(identity, () => inner.cursor(document, queryOptions)),
@@ -2771,7 +2786,21 @@ export function openStore(model, options) {
               });
             };
 
+            const sql = trustedSql({ connection, readOnly, requireScope: () => requireScope(identity),
+              beforeWrite: () => {
+                if ([...entities.values()].some((e) => e.invariants.some((r) => r.enforcement === 'store')))
+                  throw new DbRuntimeError('JD2095', 'trusted SQL cannot bypass store-only invariants');
+                if (capture !== null) throw new DbRuntimeError('JD0051', 'trusted SQL writes cannot guarantee complete live/capture/replication coverage');
+                myWork.tracker?.assertSqlWritable();
+                if (rootWork !== myWork) rootWork.tracker?.assertSqlWritable();
+              },
+              afterWrite: () => {
+                myWork.tracker?.invalidate();
+                if (rootWork !== myWork) rootWork.tracker?.invalidate();
+              },
+            });
             const members = {
+              sql: override(sql),
               transaction: override((/** @type {any} */ fn) => lift(() => nested(fn))()),
               collection: override(collectionFor),
               entity: override(entityFor),
@@ -2865,6 +2894,10 @@ export function openStore(model, options) {
                   requireScope(identity);
                   return jobsEngine.claim(...args);
                 }),
+                assertLease: lift((/** @type {any[]} */ ...args) => {
+                  requireScope(identity);
+                  return jobsEngine.assertLease(...args);
+                }),
                 renew: lift((/** @type {any[]} */ ...args) => {
                   requireScope(identity);
                   return jobsEngine.renew(...args);
@@ -2931,7 +2964,8 @@ export function openStore(model, options) {
                   }
                   return handle;
                 },
-                transaction: nested,
+                sql,
+                transaction: (fn) => nested((tx) => synchronousBody(fn, tx)),
                 savepoints: Object.freeze({
                   create: savepointCreate,
                   rollbackTo: savepointRollbackTo,
@@ -3011,7 +3045,7 @@ export function openStore(model, options) {
                 }
                 return handle;
               },
-              transaction: (fn) => {
+              transaction: (fn, transactionOptions) => {
                 // the synchronous surface answers values: while a
                 // transaction owns the connection it could only QUEUE,
                 // which handed a Promise back under a value's type
@@ -3021,7 +3055,9 @@ export function openStore(model, options) {
                     + 'settle — nest through the store the callback received, or use the '
                     + 'asynchronous store.transaction()');
                 }
-                return topLevelTransaction(fn);
+                const mode = transactionOptions?.mode;
+                if (mode !== undefined && mode !== 'deferred' && mode !== 'immediate') throw new TypeError('invalid transaction mode');
+                return topLevelTransaction((tx) => synchronousBody(fn, tx), undefined, undefined, mode);
               },
               entity(name) {
                 let handle = gatedSyncEntities.get(name);

package/src/tracker.js

@@ -31,7 +31,7 @@
 import { createJSONPatch } from '@jarenjs/json/patch';
 import { parseJSONPointer } from '@jarenjs/json/pointer';
 
-import { DbCompileError, DbRuntimeError } from './errors.js';
+import { DbCompileError, DbRuntimeError, wrapDriverError } from './errors.js';
 import { chain, attempt } from './driver.js';
 import { translatePatch } from './patch-sql.js';
 
@@ -383,12 +383,15 @@ export function createTracker(context) {
           fallback = true;
           continue;
         }
+        if (plan.scalarColumns.some((c) => c.name === first && c.generated))
+          throw contractError(entityName, `'${first}' is generated by the database`);
         const value = op.op === 'remove' ? undefined : op.value;
         columnSets.set(first, plan.encodeColumn(first, value));
         // the epoch string ALSO lives in the document
         if (isEpoch) docOps.push(op);
         continue;
       }
+      if (plan.document === false) throw contractError(entityName, `'${first}' is not a mapped column`);
       docOps.push(op);
     }
     let docBuild = null;
@@ -505,6 +508,8 @@ export function createTracker(context) {
     for (const record of records.values()) {
       const core = coreFor(record.entity);
       if (record.pendingInsert === true) {
+        core.plan.writable?.();
+        if (core.plan.document !== false) core.plan.checkMutation?.('insert', null, record.current);
         let list = inserts.get(record.entity);
         if (list === undefined) {
           list = [];
@@ -522,7 +527,9 @@ export function createTracker(context) {
       // probe before stamping: an update stamp must never turn a
       // deep-equal replacement into a phantom write
       if (createJSONPatch(record.snapshot, record.current).length === 0) continue;
+      core.plan.writable?.();
       record.stamped = core.stampUpdated(record.current);
+      if (core.plan.document !== false) core.plan.checkMutation?.('update', record.snapshot, record.stamped);
       const parts = partitionDiff(record.entity, record);
       for (const member of parts.m2mMembers) {
         joinOps.push(joinDiff(record.entity, record.snapshot, record.stamped,
@@ -546,6 +553,8 @@ export function createTracker(context) {
     /** @type {any[]} */
     const deletes = [];
     for (const removal of removals.values()) {
+      coreFor(removal.entity).plan.writable?.();
+      coreFor(removal.entity).plan.checkMutation?.('delete', removal.snapshot, null);
       deletes.push(removal);
       if (coreFor(removal.entity).plan.version === null)
         unversioned.add(removal.entity);
@@ -620,21 +629,21 @@ export function createTracker(context) {
         }
         for (const group of shapes.values()) {
           const names = group[0].split.values.map((value) => value.name);
-          const paramsPerRow = names.length + 1;
-          const rowsPerBatch = Math.max(1, Math.min(BATCH_ROW_BOUND,
+          const paramsPerRow = names.length + (plan.document === false ? 0 : 1);
+          const rowsPerBatch = names.length === 0 ? 1 : Math.max(1, Math.min(BATCH_ROW_BOUND,
             Math.floor(BATCH_PARAM_BUDGET / paramsPerRow)));
           for (let at = 0; at < group.length; at += rowsPerBatch) {
             const batch = group.slice(at, at + rowsPerBatch);
             const returning = plan.autoKey !== null && !names.includes(plan.autoKey);
             const rowSql = (base) => `(${[...names.map((_, i) => parameterAt(base + i + 1)),
-              dialect.jsonEncode(parameterAt(base + names.length + 1))].join(', ')})`;
-            const sql = `INSERT INTO ${q(plan.table)} `
-              + `(${[...names.map(q), q('doc')].join(', ')}) VALUES `
-              + batch.map((_, i) => rowSql(i * paramsPerRow)).join(', ')
-              + (returning ? ` RETURNING ${q(plan.autoKey)} AS ${q('key')}` : '');
+              ...(plan.document === false ? [] : [dialect.jsonEncode(parameterAt(base + names.length + 1))])].join(', ')})`;
+            const sql = (plan.document === false && names.length === 0 ? `INSERT INTO ${q(plan.table)} DEFAULT VALUES` : `INSERT INTO ${q(plan.table)} `
+              + `(${[...names.map((n) => q(plan.physicalName(n))), ...(plan.document === false ? [] : [q('doc')])].join(', ')}) VALUES `
+              + batch.map((_, i) => rowSql(i * paramsPerRow)).join(', '))
+              + (returning ? ` RETURNING ${q(plan.physicalName(plan.autoKey))} AS ${q('key')}` : '');
             const params = batch.flatMap(({ split }) => [
               ...split.values.map((value) => value.value),
-              JSON.stringify(split.rest),
+              ...(plan.document === false ? [] : [JSON.stringify(split.rest)]),
             ]);
             statements.push({
               kind: 'insert', entity: entityName, sql, params, returning,
@@ -653,15 +662,17 @@ export function createTracker(context) {
           const split = plan.split(record.stamped);
           for (const value of split.values) {
             if (value.name === plan.version) continue;
-            assignments.push(`${q(value.name)} = ${parameterAt(params.length + 1)}`);
+            assignments.push(`${q(plan.physicalName(value.name))} = ${parameterAt(params.length + 1)}`);
             params.push(value.value);
           }
-          assignments.push(`${q('doc')} = ${dialect.jsonEncode(parameterAt(params.length + 1))}`);
-          params.push(JSON.stringify(split.rest));
+          if (plan.document !== false) {
+            assignments.push(`${q('doc')} = ${dialect.jsonEncode(parameterAt(params.length + 1))}`);
+            params.push(JSON.stringify(split.rest));
+          }
         }
         else {
           for (const [name, value] of parts.columnSets) {
-            assignments.push(`${q(name)} = ${parameterAt(params.length + 1)}`);
+            assignments.push(`${q(plan.physicalName(name))} = ${parameterAt(params.length + 1)}`);
             params.push(value);
           }
           if (parts.docBuild !== null) {
@@ -673,16 +684,16 @@ export function createTracker(context) {
         const snapshotVersion = plan.version === null
           ? null : Number(record.snapshot[plan.version]) || 0;
         if (plan.version !== null) {
-          assignments.push(`${q(plan.version)} = ${parameterAt(params.length + 1)}`);
+          assignments.push(`${q(plan.physicalName(plan.version))} = ${parameterAt(params.length + 1)}`);
           params.push(snapshotVersion + 1);
         }
         const wheres = plan.keys.map((key) => {
-          params.push(record.snapshot[key]);
-          return `${q(key)} = ${parameterAt(params.length)}`;
+          params.push(plan.encodeColumn(key, record.snapshot[key]));
+          return `${q(plan.physicalName(key))} = ${parameterAt(params.length)}`;
         });
         if (plan.version !== null) {
           params.push(snapshotVersion);
-          wheres.push(`${q(plan.version)} = ${parameterAt(params.length)}`);
+          wheres.push(`${q(plan.physicalName(plan.version))} = ${parameterAt(params.length)}`);
         }
         statements.push({
           kind: 'update', entity: record.entity, record,
@@ -729,13 +740,13 @@ export function createTracker(context) {
         const plan = coreFor(entityName).plan;
         for (const removal of deletes) {
           if (removal.entity !== entityName) continue;
-          const params = [...removal.parts];
-          const wheres = plan.keys.map((key, i) => `${q(key)} = ${parameterAt(i + 1)}`);
+          const params = removal.parts.map((v, i) => plan.encodeColumn(plan.keys[i], v));
+          const wheres = plan.keys.map((key, i) => `${q(plan.physicalName(key))} = ${parameterAt(i + 1)}`);
           const snapshotVersion = plan.version !== null && removal.snapshot !== null
             ? Number(removal.snapshot[plan.version]) || 0 : null;
           if (snapshotVersion !== null) {
             params.push(snapshotVersion);
-            wheres.push(`${q(plan.version)} = ${parameterAt(params.length)}`);
+            wheres.push(`${q(plan.physicalName(plan.version))} = ${parameterAt(params.length)}`);
           }
           statements.push({
             kind: 'delete', entity: entityName, removal,
@@ -772,14 +783,9 @@ export function createTracker(context) {
   };
 
   const wrapDb = (error, statement) => {
-    if (typeof (/** @type {any} */ (error))?.code === 'string'
-      && String((/** @type {any} */ (error)).code).startsWith('JD')) return error;
-    return new DbRuntimeError('JD2005',
-      `the database rejected the operation: ${/** @type {any} */ (error)?.message ?? String(error)}`,
-      {
+    return wrapDriverError(error, {
         docPath: entities.get(statement.entity)?.docPath,
         collection: statement.entity,
-        cause: error,
       });
   };
 
@@ -787,6 +793,24 @@ export function createTracker(context) {
     const next = (i) => {
       if (i >= statements.length) return report;
       const statement = statements[i];
+      const advance = () => {
+        if (!['insert', 'update'].includes(statement.kind) || coreFor(statement.entity).plan.document !== false) return next(i + 1);
+        const core = coreFor(statement.entity);
+        const records = statement.kind === 'insert' ? statement.records : [statement.record];
+        statement.stored = [];
+        const refresh = (at) => {
+          if (at >= records.length) return next(i + 1);
+          const record = records[at];
+          const key = statement.returning ? { ...record.current, [core.plan.autoKey]: statement.generatedKeys[at] } : record.current;
+          return chain(core.get(key), (stored) => {
+            core.validateOnly(stored);
+            core.plan.checkMutation(statement.kind, statement.kind === 'insert' ? null : record.snapshot, stored);
+            statement.stored.push(deepFreeze(stored));
+            return refresh(at + 1);
+          });
+        };
+        return refresh(0);
+      };
       // a join row whose own key the save allocates: the INSERT that
       // allocates it has already run (inserts precede join rows), so the
       // key is on the record by now
@@ -798,13 +822,7 @@ export function createTracker(context) {
       }
       return chain(connection.prepare(statement.sql), (prepared) => {
         if (statement.kind === 'insert' && statement.returning === true) {
-          let fetched;
-          try {
-            fetched = prepared.all(statement.params);
-          }
-          catch (error) {
-            throw wrapDb(error, statement);
-          }
+          const fetched = attempt(() => prepared.all(statement.params), (error) => wrapDb(error, statement));
           return chain(fetched, (rows) => {
             // auto keys allocate monotonically in insertion order —
             // sort ascending to pair rows with records (asserted by
@@ -816,7 +834,7 @@ export function createTracker(context) {
             statement.records.forEach((record, at) => { record.allocatedKey = keys[at]; });
             report.inserted += statement.records.length;
             report.statements.push({ sql: statement.sql, rows: statement.records.length });
-            return next(i + 1);
+            return advance();
           });
         }
         return chain(
@@ -840,7 +858,7 @@ export function createTracker(context) {
           }
           else if (statement.kind === 'join-insert') report.joinInserted += changed;
           else if (statement.kind === 'join-delete') report.joinDeleted += changed;
-          return next(i + 1);
+          return advance();
         });
           });
       });
@@ -949,9 +967,9 @@ export function createTracker(context) {
           // the row this statement wrote is the one the save PLANNED; an
           // edit made to the same record afterwards is not in the database
           const planned = undo.fields.get(record)?.current ?? record.current;
-          const doc = statement.returning === true
+          const doc = statement.stored?.[i] ?? (statement.returning === true
             ? deepFreeze({ ...planned, [plan.autoKey]: statement.generatedKeys[i] })
-            : planned;
+            : planned);
           // re-key under the real identity
           records.delete(record.pendingKey);
           const key = recordKeyFor(statement.entity, doc);
@@ -968,9 +986,9 @@ export function createTracker(context) {
         const record = statement.record;
         const plan = coreFor(statement.entity).plan;
         const before = record.snapshot;
-        const saved = statement.newVersion === null
+        const saved = statement.stored?.[0] ?? (statement.newVersion === null
           ? record.stamped
-          : deepFreeze({ ...record.stamped, [plan.version]: statement.newVersion });
+          : deepFreeze({ ...record.stamped, [plan.version]: statement.newVersion }));
         const pending = untouched(record) ? null : record.current;
         record.snapshot = deepFreeze(saved);
         record.current = pending ?? record.snapshot;
@@ -1069,7 +1087,13 @@ export function createTracker(context) {
     }
   };
 
+  const assertSqlWritable = () => {
+    if (removals.size || memberships.size || [...records.values()].some((r) => r.pendingInsert || r.current !== r.snapshot))
+      throw new DbRuntimeError('JD2040', 'trusted SQL requires saving or discarding pending tracked changes first');
+  };
+  const invalidate = () => { assertSqlWritable(); records.clear(); };
   return {
+    assertSqlWritable, invalidate,
     register, registerGraph, add, put, remove, discard, link, unlink, counts, saveChanges,
   };
 }