@jarenjs/db 0.73.0 → 0.83.2

package/src/backup.js

@@ -20,13 +20,13 @@
  * platform reports progress (`rate` pages per step): the platform
  * itself takes no signal, so the signal is checked in the progress
  * callback and a throw there is what stops the pump. There is no
- * progress event with a zero remainder — the platform's completion
- * signal is the resolved copy, which answers the page total — so
- * progress events are handed on verbatim and completion is the promise.
+ * guaranteed terminal progress event — the platform's completion signal
+ * is the resolved copy, which answers the page total. Cancellation is
+ * checked again before publication, including after a terminal event.
  *
  * This module imports no runtime builtin: the copy, the rename and the
- * removal are the driver's primitives (`connection.backup`), present on
- * the Node binding and declared absent elsewhere.
+ * removal are the driver's primitives (`connection.backup`), supplied by
+ * Node online backup and Bun serialized snapshots.
  */
 
 import { DbRuntimeError, wrapDriverError } from './errors.js';
@@ -139,7 +139,8 @@ export function createBackup({ connection, readOnly, gated, checkpoint, random,
         };
         let copying;
         try {
-          copying = files.copy(tmpPath, rate === undefined ? { progress } : { rate, progress });
+          const copy = () => files.copy(tmpPath, rate === undefined ? { progress } : { rate, progress });
+          copying = files.snapshot === true ? gated(copy, 'a snapshot backup') : copy();
         }
         catch (error) {
           return discard(aborted ?? failed(error));
@@ -153,7 +154,11 @@ export function createBackup({ connection, readOnly, gated, checkpoint, random,
           attempt(() => files.rename(tmpPath, targetPath), failed),
           () => Object.freeze({ path: targetPath, pages: Number(pages), checkpoint: checkpointed ?? null }));
         return toPromise(copying)
-          .then((pages) => toPromise(publish(pages)))
+          .then((pages) => {
+            if (signal?.aborted === true) { aborted = cancelled(signal); throw aborted; }
+            callable(options, 'the temporary file was removed and the target path was not written');
+            return toPromise(publish(pages));
+          })
           .catch((error) => discard(aborted ?? failed(error)));
       });
     },

package/src/cursor.js

@@ -345,6 +345,12 @@ export function admitSyncCursor(cursor, admit) {
 /** The page size a page takes when none is given. */
 export const PAGE_LIMIT_DEFAULT = 100;
 
+/** Classify the cursor's byte, row and work refusals at structural adapter boundaries.
+ * @param {any} error @returns {boolean} */
+export function isCursorBudgetError(error) {
+  return ['JD2073', 'JD2074', 'JD2076'].includes(error?.code);
+}
+
 /**
  * Drain a cursor into ONE page: at most `limit` items, at most `maxBytes`
  * serialised bytes (`null` for no byte bound), stopping at an item
@@ -357,9 +363,13 @@ export const PAGE_LIMIT_DEFAULT = 100;
  * An item that does not fit beside earlier ones ends the page before
  * it: `hasMore` is true and the continuation is the last delivered
  * item's, so the next page starts at the item that did not fit.
- * `hasMore` is otherwise decided by one peek past `limit`.
+ * `hasMore` is otherwise decided by one peek past `limit`. With
+ * `lookahead: false`, a full page reports `hasMore: null` and `work`
+ * records each consumed root and its serialized payload bytes, including
+ * the root that stopped the page at its byte boundary. Failures preserve
+ * those counters on the error; pages using the default keep their shape.
  * @param {any} cursor - a `QueryCursor`
- * @param {{ limit: number, maxBytes: number | null, after?: any,
+ * @param {{ limit: number, maxBytes: number | null, after?: any, lookahead?: boolean,
  *   sizeOf: (item: any) => number, continuationOf: (item: any) => any }} options
  * @returns {any} value-or-promise, matching the cursor
  */
@@ -368,10 +378,13 @@ export function drainPage(cursor, options) {
   const after = options.after ?? null;
   const items = [];
   let bytes = 0;
+  const measured = options.lookahead === false;
+  const work = { rows: 0, bytes: 0 };
   let last = after;
   let hasMore = false;
   const finish = () => chain(cursor.return(), () => ({
     items, continuation: items.length > 0 ? last : (hasMore ? after : null), hasMore,
+    ...(measured ? { work: { ...work } } : {}),
   }));
   const consume = (pulled) => {
     if (items.length >= limit) {
@@ -380,7 +393,8 @@ export function drainPage(cursor, options) {
     }
     if (pulled.done === true) return finish();
     const item = pulled.value;
-    const size = maxBytes === null ? 0 : sizeOf(item);
+    const size = maxBytes === null && !measured ? 0 : sizeOf(item);
+    if (measured) { work.rows++; work.bytes += size; }
     if (maxBytes !== null && bytes + size > maxBytes) {
       if (items.length === 0) {
         return chain(cursor.return(), () => {
@@ -393,6 +407,10 @@ export function drainPage(cursor, options) {
     items.push(item);
     bytes += size;
     last = continuationOf(item);
+    if (options.lookahead === false && items.length === limit) {
+      hasMore = null;
+      return finish();
+    }
     return null;
   };
   const step = () => {
@@ -403,7 +421,12 @@ export function drainPage(cursor, options) {
       if (result !== null) return result;
     }
   };
-  return settling(step, () => cursor.return());
+  return settling(step, () => cursor.return(), (error) => {
+    // A refused boundary row was still consumed. Preserve that evidence
+    // through the owning error so a bounded caller cannot report zero work.
+    if (measured && error !== null && typeof error === 'object') error.work = { ...work };
+    return error;
+  });
 }
 
 /** The shared refusal for an indivisible item, including a replicated transaction.

package/src/dag-job.js

@@ -52,7 +52,7 @@ const fingerprint = (value) => hashContent(canonicalizeJson(value ?? null));
  *   concurrency?: number, pollInterval?: number, leaseMs?: number,
  *   owner?: string, renew?: boolean, onOutcome?: (event: any) => void,
  *   backoffBase?: number, backoffCap?: number,
- *   stopGraceMs?: number }} options
+ *   stopGraceMs?: number, effectSafety?: (job: any, context: any) => any }} options
  * @returns {{ start: () => any, stop: (options?: any) => Promise<any>, stats: () => any }}
  */
 export function createDagJobRunner(store, options) {
@@ -215,6 +215,7 @@ export function createDagJobRunner(store, options) {
     owner: options.owner,
     renew: options.renew,
     onOutcome: options.onOutcome,
+    effectSafety: options.effectSafety,
     backoffBase: options.backoffBase,
     backoffCap: options.backoffCap,
     // the runner's declared default for `stop()` with no override; an

package/src/ddl.js

@@ -14,6 +14,7 @@
  * silently indexing the wrong thing.
  */
 
+import { explainMapping } from './model.js';
 import { analyzeQuery } from '@jarenjs/json/query';
 import { DbCompileError } from './errors.js';
 import { chain } from './driver.js';
@@ -902,6 +903,9 @@ export function verifyShape(connection, plan, collection, docPath) {
  *   columnNames: Set<string> }}
  */
 export function planEntity(name, entityMapping, entities, dialect) {
+  if (entityMapping.document === false) return { table: entityMapping.table,
+    physical: { ...entityMapping, triggers: dialect.invariantTriggers?.(entityMapping, entities, dialect) ?? [] }, createSql: [], expected: { columns: [], indexes: [] },
+    columnNames: new Set(entityMapping.columns.map((c) => c.physical)) };
   const storageType = (storage) => dialect.typeFor(storage, 'generated');
   const keyType = (entityName) => {
     const target = entities.entities[entityName];
@@ -1037,3 +1041,12 @@ export function planJoinTable(tableName, join, entities, dialect) {
     },
   };
 }
+
+/** Plan explicit database-enforced persistence rules; never applies them.
+ * @param {any} model @param {{ dialect: any }} options @returns {any[]} */
+export function planInvariants(model, options) {
+  const mapping = explainMapping(model);
+  const dialect = options.dialect;
+  if (typeof dialect.invariantTriggers !== 'function') throw new DbCompileError('JD0005', 'this dialect cannot lower database invariants');
+  return Object.values(mapping.entities).flatMap((entity) => dialect.invariantTriggers(entity, mapping, dialect));
+}

package/src/derive.js

@@ -383,12 +383,23 @@ export function cellNeighbourhood(cell) {
  * external's bounding box, computed at bind time because a GeoJSON
  * object is not a value any database can bind. `null` when the value
  * has no box, which is what tells the caller to divert.
- * @param {{ kind: string, external: string, axis: string }} derived
- * @param {any} value - the bound external
+ * @param {any} derived
+ * @param {any} value - the bound external for bboxAxis; all externals for circleAxis
  * @returns {number | null}
  */
 export function derivedSlotValue(derived, value) {
-  const box = bboxOf(value);
+  let box;
+  if (derived.kind === 'bboxAxis') box = bboxOf(value);
+  else if (derived.kind === 'circleAxis') {
+    const read = (input) => 'external' in input ? value[input.external] : input.literal;
+    const at = probePosition(read(derived.centre));
+    const radius = read(derived.radius);
+    if (at === null || typeof radius !== 'number' || !Number.isFinite(radius) || radius < 0)
+      return null;
+    box = probeCircleBox(at, radius);
+    if (box !== null && (box[0] < -180 || box[2] > 180)) return null;
+  }
+  else throw new TypeError(`unknown derived parameter kind '${derived.kind}'`);
   return box === null ? null : box[BBOX_AT[derived.axis]];
 }
 

package/src/dialect.js

@@ -185,6 +185,12 @@ function normalizeCapabilities(declared) {
  *   memberPathOf?: (expression: string) => (JsonPathSegment[] | null),
  *   expressionOf?: (expression: string, byName: Record<string, string>) => (any | null),
  *   readGenerated?: (rows: any[]) => { name: string, expression: string }[],
+ *   physicalRead?: (codec: string, sql: string) => string,
+ *   mutationRowGuard?: (count: string, limit: number) => string,
+ *   codepoint?: (value: string) => string,
+ *   physicalTypeMatches?: (codec: string, type: string) => boolean,
+ *   invariantTriggers?: (mapping: any, all: any, dialect: any) => any[],
+ *   readChecks?: (rows: any[]) => { name: string, column?: string, values?: any[] }[],
  *   introspect: { version: () => string, compileOptions: () => string,
  *     pragma: (name: string) => string,
  *     tableExists: () => string, columns: (table: string) => string,
@@ -640,6 +646,12 @@ export function createDialect(spec) {
      * one that can read it.
      */
     readGenerated: spec.readGenerated,
+    readChecks: spec.readChecks,
+    physicalRead: spec.physicalRead,
+    mutationRowGuard: spec.mutationRowGuard,
+    codepoint: spec.codepoint,
+    physicalTypeMatches: spec.physicalTypeMatches,
+    invariantTriggers: spec.invariantTriggers,
     explainQuery: spec.explainQuery,
     /** The plan narrative, one line per row the engine answered. */
     explainLines: spec.explainLines,

package/src/dialects/check-read.js

@@ -0,0 +1,151 @@
+//@ts-check
+/** Recover only a complete scalar enum CHECK; unfamiliar SQL remains a loss. */
+
+/** Tokenize catalog SQL without treating quoted text or comments as syntax.
+ * @param {string} sql @returns {{ kind: string, value: string }[]} */
+export function sqlTokens(sql) {
+  const tokens = [];
+  for (let i = 0; i < sql.length;) {
+    const c = sql[i];
+    if (/\s/.test(c)) { i++; continue; }
+    if (sql.startsWith('--', i)) {
+      const end = sql.indexOf('\n', i + 2); i = end < 0 ? sql.length : end + 1; continue;
+    }
+    if (sql.startsWith('/*', i)) {
+      const end = sql.indexOf('*/', i + 2);
+      if (end < 0) return [];
+      i = end + 2; continue;
+    }
+    if (c === "'" || c === '"' || c === '`') {
+      let value = '';
+      let closed = false;
+      for (i++; i < sql.length; i++) {
+        if (sql[i] !== c) { value += sql[i]; continue; }
+        if (sql[i + 1] === c) { value += c; i++; continue; }
+        i++; closed = true; break;
+      }
+      if (!closed) return [];
+      tokens.push({ kind: c === "'" ? 'string' : 'identifier', value });
+      continue;
+    }
+    const number = /^(?:[0-9]+(?:\.[0-9]*)?|\.[0-9]+)(?:[eE][+-]?[0-9]+)?/.exec(sql.slice(i));
+    if (number) { tokens.push({ kind: 'number', value: number[0] }); i += number[0].length; continue; }
+    const word = /^[A-Za-z_][A-Za-z_0-9$]*/.exec(sql.slice(i));
+    if (word) { tokens.push({ kind: 'word', value: word[0] }); i += word[0].length; continue; }
+    const value = sql.startsWith('::', i) ? '::' : c;
+    tokens.push({ kind: 'symbol', value }); i += value.length;
+  }
+  return tokens;
+}
+
+/** @param {any[]} tokens @returns {{ column: string, values: any[] } | null} */
+function enumOf(tokens) {
+  let at = 0;
+  const take = (value) => {
+    const token = tokens[at];
+    if (token && token.kind !== 'string' && token.kind !== 'identifier'
+      && token.value.toUpperCase() === value) { at++; return true; }
+    return false;
+  };
+  const scalar = () => {
+    if (take('(')) {
+      const value = scalar();
+      return value === undefined || !take(')') ? undefined : cast(value);
+    }
+    const negative = take('-');
+    const token = tokens[at++];
+    if (!token) return undefined;
+    let value;
+    if (token.kind === 'number') value = Number(`${negative ? '-' : ''}${token.value}`);
+    else if (negative) return undefined;
+    else if (token.kind === 'string') value = token.value;
+    else if (token.kind === 'word' && /^(true|false)$/i.test(token.value)) value = token.value.toLowerCase() === 'true';
+    else return undefined;
+    if (typeof value === 'number' && !Number.isFinite(value)) return undefined;
+    return cast(value);
+  };
+  const cast = (value) => {
+    if (!take('::')) return value;
+    // Only exact scalar casts emitted by the catalog are understood.
+    // Rounding casts could change the enum's members.
+    const type = tokens[at++];
+    if (type?.kind !== 'word') return undefined;
+    const name = type.value.toLowerCase();
+    if (typeof value === 'string' && name === 'text') return value;
+    if (typeof value === 'boolean' && name === 'boolean') return value;
+    // PostgreSQL renders negative constants as quoted numeric casts,
+    // e.g. ('-1'::integer)::numeric. Decode only finite numeric syntax.
+    if (typeof value === 'string' && ['numeric', 'integer', 'bigint', 'smallint'].includes(name)
+      && /^-?(?:[0-9]+(?:\.[0-9]*)?|\.[0-9]+)(?:[eE][+-]?[0-9]+)?$/.test(value)) {
+      const number = Number(value);
+      if (!Number.isFinite(number) || (['integer', 'bigint', 'smallint'].includes(name)
+        && !Number.isSafeInteger(number))) return undefined;
+      return number;
+    }
+    if (typeof value === 'number' && name === 'numeric') return value;
+    if (typeof value === 'number' && ['integer', 'bigint', 'smallint'].includes(name)
+      && Number.isSafeInteger(value)) return value;
+    if (typeof value === 'number' && name === 'double' && take('PRECISION')) return value;
+    return undefined;
+  };
+  const expression = () => {
+    if (take('(')) {
+      const result = expression();
+      return result === null || !take(')') ? null : result;
+    }
+    const column = tokens[at++];
+    if (!column || !['identifier', 'word'].includes(column.kind)) return null;
+    const any = take('=');
+    // A singleton IN list is normalized to scalar equality by PostgreSQL.
+    if (any && !take('ANY')) {
+      const value = scalar();
+      return value === undefined ? null : { column: column.value, values: [value] };
+    }
+    if (any ? !(take('(') && take('ARRAY') && take('[')) : !(take('IN') && take('('))) return null;
+    const values = [];
+    do {
+      const value = scalar();
+      if (value === undefined) return null;
+      if (!values.includes(value)) values.push(value);
+    } while (take(','));
+    if (any ? !(take(']') && take(')')) : !take(')')) return null;
+    return { column: column.value, values };
+  };
+  const result = expression();
+  return at === tokens.length ? result : null;
+}
+
+/** SQLite retains the CREATE text, including inline and table CHECKs.
+ * @param {any[]} rows @returns {any[]} neutral constraints */
+export function sqliteChecks(rows) {
+  const checks = [];
+  for (const row of rows) {
+    const tokens = sqlTokens(String(row.sql ?? ''));
+    // A column's inherited collation changes IN equality even when the
+    // CHECK itself names no collation. Refuse conservatively per table.
+    const collated = tokens.some((token, i) => token.kind === 'word'
+      && token.value.toUpperCase() === 'COLLATE'
+      && tokens[i + 1]?.value.toUpperCase() !== 'BINARY');
+    for (let i = 0; i < tokens.length; i++) {
+      if (tokens[i].kind !== 'word' || tokens[i].value.toUpperCase() !== 'CHECK'
+        || tokens[i + 1]?.value !== '(') continue;
+      const start = i + 2;
+      let depth = 1;
+      for (i = start; i < tokens.length; i++) {
+        if (tokens[i].kind !== 'symbol') continue;
+        if (tokens[i].value === '(') depth++;
+        if (tokens[i].value === ')' && --depth === 0) break;
+      }
+      checks.push({ name: `check_${checks.length + 1}`,
+        ...(collated ? null : enumOf(tokens.slice(start, i))) });
+    }
+  }
+  return checks;
+}
+
+/** PostgreSQL exposes each CHECK expression separately.
+ * @param {any[]} rows @returns {any[]} neutral constraints */
+export function postgresChecks(rows) {
+  return rows.map((row) => ({ name: String(row.name),
+    ...(row.unsafe_collation ? null : enumOf(sqlTokens(String(row.expression ?? '')))) }));
+}

package/src/dialects/invariant-sql.js

@@ -0,0 +1,117 @@
+//@ts-check
+/** SQLite trigger lowering for bounded query predicates over old/new columns. */
+import { DbCompileError } from '../errors.js';
+
+/** @param {any} mapping @param {any} all @param {any} dialect @returns {any[]} */
+export function sqliteInvariantTriggers(mapping, all, dialect) {
+  const q = dialect.quoteIdentifier;
+  const sl = dialect.stringLiteral;
+  const fail = (why) => { throw new DbCompileError('JD0005', `database invariant: ${why}`); };
+  const rules = mapping.invariants ?? [];
+  const columns = mapping.columns;
+  let domains = new Set();
+  const scalar = (value, op) => {
+    if (typeof value === 'string' && value.startsWith('$.')) {
+      if (value === '$.op') return sl(op);
+      const match = /^\$\.(old|new)\.([A-Za-z_][A-Za-z0-9_]*)$/.exec(value);
+      if (!match) return fail(`unsupported record path '${value}'`);
+      const column = columns.find((c) => c.name === match[2]);
+      if (!column || column.null === 'absent' || !['text', 'integer', 'number', 'boolean', 'date', 'datetime'].includes(column.codec)) return fail(`'${match[2]}' needs a scalar column codec`);
+      if ((op === 'insert' && match[1] === 'old') || (op === 'delete' && match[1] === 'new')) return fail('a property of an unavailable record is absent, not SQL NULL');
+      const ref = `${match[1].toUpperCase()}.${q(column.physical)}`;
+      const type = `typeof(${ref})`;
+      let valid = ['integer', 'number', 'boolean'].includes(column.codec)
+        ? column.codec === 'number' ? `${type} IN ('integer', 'real') AND ${ref} BETWEEN -9007199254740991 AND 9007199254740991`
+          : `${type} = 'integer' AND ${column.codec === 'boolean' ? `${ref} IN (0, 1)` : `${ref} BETWEEN -9007199254740991 AND 9007199254740991`}`
+        : `${type} = 'text'`;
+      if (column.null === 'null') valid = `${ref} IS NULL OR (${valid})`;
+      domains.add(`(${valid})`);
+      return `(${ref} COLLATE BINARY)`;
+    }
+    if (value === null) return 'NULL';
+    if (typeof value === 'string') return sl(value);
+    if (typeof value === 'boolean') return value ? '1' : '0';
+    if (typeof value === 'number' && Number.isFinite(value) && (!Number.isInteger(value) || Number.isSafeInteger(value))) return String(value);
+    if (value && typeof value === 'object' && Object.keys(value).length === 1 && Object.hasOwn(value, '$const')) {
+      const literal = value.$const;
+      return typeof literal === 'string' ? sl(literal) : scalar(literal, op);
+    }
+    return fail('only scalar literals and old/new property paths can be lowered');
+  };
+  const typeOf = (value) => {
+    if (typeof value === 'string' && value.startsWith('$.')) {
+      if (value === '$.op') return 'string';
+      const name = value.slice(value.indexOf('.', 2) + 1);
+      const column = columns.find((c) => c.name === name);
+      return column?.codec === 'boolean' ? 'boolean'
+        : ['integer', 'number'].includes(column?.codec) ? 'number' : 'string';
+    }
+    if (value && typeof value === 'object' && Object.hasOwn(value, '$const')) return value.$const === null ? 'null' : typeof value.$const;
+    return value === null ? 'null' : typeof value;
+  };
+  const predicate = (node, op) => {
+    if (typeof node === 'boolean') return node ? '1' : '0';
+    if (!node || typeof node !== 'object' || Array.isArray(node) || Object.keys(node).length !== 1) return fail('predicate must be a bounded query expression');
+    const [key, args] = Object.entries(node)[0];
+    if (key === '$and' || key === '$or') {
+      if (!Array.isArray(args) || !args.length) return fail('logical predicates require operands');
+      return `(${args.map((a) => predicate(a, op)).join(key === '$and' ? ' AND ' : ' OR ')})`;
+    }
+    if (key === '$not') return `(NOT (${predicate(args, op)}))`;
+    const operators = { $eq: 'IS', $ne: 'IS NOT', $lt: '<', $le: '<=', $gt: '>', $ge: '>=' };
+    if (!operators[key] || !Array.isArray(args) || args.length !== 2) return fail(`unsupported predicate '${key}'`);
+    const left = scalar(args[0], op), right = scalar(args[1], op);
+    const lt = typeOf(args[0]), rt = typeOf(args[1]);
+    if (lt !== rt && lt !== 'null' && rt !== 'null') return key === '$ne' ? '1' : '0';
+    const compare = `(${left} ${operators[key]} ${right})`;
+    return key === '$eq' || key === '$ne' ? compare : `COALESCE(${compare}, 0)`;
+  };
+  const changed = columns.filter((c) => c.name !== mapping.version && !c.generated)
+    .map((c) => `OLD.${q(c.physical)} IS NOT NEW.${q(c.physical)}`).join(' OR ') || '0';
+  const out = [];
+  const groups = new Map();
+  const add = (op, stage, rule, when, body) => {
+    const key = `${op}_${stage}`;
+    if (!groups.has(key)) groups.set(key, { op, stage, rules: [], bodies: [] });
+    const group = groups.get(key);
+    group.rules.push(rule); group.bodies.push(`${body}${when ? ` WHERE ${when}` : ''};`);
+  };
+  for (const rule of rules) {
+    if (rule.enforcement !== 'database') continue;
+    if (mapping.document !== false || mapping.kind === 'view') fail('database rules require a writable explicit column layout');
+    for (const op of rule.on) {
+      domains = new Set();
+      const assertion = predicate(rule.assert, op);
+      if (rule.audit !== undefined) {
+        const target = all.entities[rule.audit.entity];
+        if (!target || target.document !== false || target.kind === 'view') fail('audit target must be a mapped application table');
+        if (target === mapping || (target.invariants ?? []).some((r) => r.audit)) fail('recursive or chained audit effects are refused');
+        const names = [], values = [];
+        for (const [member, expression] of Object.entries(rule.audit.values)) {
+          const column = target.columns.find((c) => c.name === member);
+          if (!column || column.generated || !['text', 'integer', 'number', 'boolean'].includes(column.codec)) fail(`audit member '${member}' needs a writable scalar codec`);
+          const expected = column.codec === 'text' ? 'string' : column.codec === 'boolean' ? 'boolean' : 'number';
+          const actual = typeOf(expression);
+          if (actual !== expected && actual !== 'null') fail(`audit member '${member}' needs a matching scalar type`);
+          const value = scalar(expression, op);
+          if (column.null === 'reject') domains.add(`(${value} IS NOT NULL)`);
+          names.push(q(column.physical)); values.push(value);
+        }
+        if (!names.length) fail('audit values cannot be empty');
+        add(op, 'AFTER', rule.name, op === 'update' ? `(${changed})` : '',
+          `INSERT INTO ${q(target.table)} (${names.join(', ')}) SELECT ${values.join(', ')}`);
+      }
+      const when = `${op === 'update' ? `(${changed}) AND ` : ''}(${[...domains, assertion].join(' AND ')}) IS NOT TRUE`;
+      add(op, 'BEFORE', rule.name, when, `SELECT RAISE(ABORT, ${sl(`jaren invariant:${rule.name}`)})`);
+    }
+  }
+  for (const op of ['insert', 'update', 'delete']) {
+    const checks = groups.get(`${op}_BEFORE`);
+    if (!checks) continue;
+    const bodies = [...checks.bodies, ...(groups.get(`${op}_AFTER`)?.bodies ?? [])];
+    const name = `_jaren_rule_${mapping.table.length}_${mapping.table}_${op}`;
+    out.push({ type: 'trigger', name, owner: mapping.table, rule: checks.rules.join(','),
+      sql: `CREATE TRIGGER ${q(name)} AFTER ${op.toUpperCase()} ON ${q(mapping.table)} BEGIN ${bodies.join(' ')} END` });
+  }
+  return out;
+}

package/src/dialects/postgres.js

@@ -39,6 +39,7 @@
 
 import { createDialect } from '../dialect.js';
 import { readExpression } from './expression-read.js';
+import { postgresChecks } from './check-read.js';
 
 /** PostgreSQL truncates an identifier past this many BYTES, silently
  * and with only a notice — so two long generated names would collide
@@ -519,6 +520,7 @@ export function postgresDialect(options = undefined) {
     memberPathOf,
     expressionOf,
     // the catalog already answers one row per generated column
+    readChecks: postgresChecks,
     readGenerated: (rows) => rows.map((row) => ({
       name: String(row.name), expression: String(row.expression ?? ''),
     })),
@@ -561,8 +563,11 @@ export function postgresDialect(options = undefined) {
       // fact the shape check reads beside the name and the type
       columns: (table) =>
         'SELECT a.attname AS name, format_type(a.atttypid, a.atttypmod) AS type, '
-        + "CASE WHEN a.attgenerated <> '' THEN 1 ELSE 0 END AS hidden "
+        + "CASE WHEN a.attgenerated <> '' THEN 1 ELSE 0 END AS hidden, "
+        + 'CASE WHEN a.attnotnull THEN 1 ELSE 0 END AS not_null, '
+        + 'pg_get_expr(d.adbin, d.adrelid) AS default_value '
         + 'FROM pg_attribute a JOIN pg_class c ON c.oid = a.attrelid '
+        + 'LEFT JOIN pg_attrdef d ON d.adrelid = a.attrelid AND d.adnum = a.attnum '
         + 'JOIN pg_namespace n ON n.oid = c.relnamespace '
         + `WHERE c.relname = ${stringLiteral(table)} AND ${inNamespace} `
         + 'AND a.attnum > 0 AND NOT a.attisdropped ORDER BY a.attnum',
@@ -571,7 +576,8 @@ export function postgresDialect(options = undefined) {
       // key's is the engine's own
       indexes: (table) =>
         'SELECT ci.relname AS name, CASE WHEN i.indisunique THEN 1 ELSE 0 END AS uniq, '
-        + "CASE WHEN i.indisprimary THEN 'pk' ELSE 'c' END AS origin "
+        + "CASE WHEN i.indisprimary THEN 'pk' ELSE 'c' END AS origin, "
+        + 'CASE WHEN i.indpred IS NULL THEN 0 ELSE 1 END AS partial '
         + 'FROM pg_index i JOIN pg_class ci ON ci.oid = i.indexrelid '
         + 'JOIN pg_class ct ON ct.oid = i.indrelid '
         + 'JOIN pg_namespace n ON n.oid = ct.relnamespace '
@@ -584,7 +590,7 @@ export function postgresDialect(options = undefined) {
         + 'JOIN pg_class ci ON ci.oid = i.indexrelid '
         + 'JOIN pg_namespace n ON n.oid = ci.relnamespace '
         + 'CROSS JOIN LATERAL unnest(i.indkey::int2[]) WITH ORDINALITY AS k(attnum, ord) '
-        + 'JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = k.attnum '
+        + 'LEFT JOIN pg_attribute a ON a.attrelid = i.indrelid AND a.attnum = k.attnum '
         + `WHERE ci.relname = ${stringLiteral(index)} AND ${inNamespace} ORDER BY k.ord`,
       // every table this store might own; a view is reported rather
       // than derived, and the engine's own schemas are never in scope
@@ -594,6 +600,15 @@ export function postgresDialect(options = undefined) {
         + 'JOIN pg_namespace n ON n.oid = c.relnamespace '
         + `WHERE c.relkind IN ('r', 'p', 'v', 'm') AND ${inNamespace} `
         + 'ORDER BY type, c.relname',
+      objects: () =>
+        "SELECT 'trigger' AS type, t.tgname AS name, c.relname AS owner, "
+        + 'pg_get_triggerdef(t.oid) AS sql FROM pg_trigger t '
+        + 'JOIN pg_class c ON c.oid = t.tgrelid JOIN pg_namespace n ON n.oid = c.relnamespace '
+        + `WHERE NOT t.tgisinternal AND ${inNamespace} UNION ALL `
+        + "SELECT 'index', ci.relname, c.relname, pg_get_indexdef(i.indexrelid) "
+        + 'FROM pg_index i JOIN pg_class c ON c.oid = i.indrelid '
+        + 'JOIN pg_class ci ON ci.oid = i.indexrelid JOIN pg_namespace n ON n.oid = c.relnamespace '
+        + `WHERE ${inNamespace} ORDER BY type, name`,
       generated: (table) =>
         'SELECT a.attname AS name, pg_get_expr(d.adbin, d.adrelid) AS expression '
         + 'FROM pg_attrdef d '
@@ -602,13 +617,22 @@ export function postgresDialect(options = undefined) {
         + 'JOIN pg_namespace n ON n.oid = c.relnamespace '
         + `WHERE c.relname = ${stringLiteral(table)} AND ${inNamespace} `
         + "AND a.attgenerated <> '' ORDER BY a.attnum",
+      checks: (table) =>
+        'SELECT c.conname AS name, pg_get_expr(c.conbin, c.conrelid) AS expression, '
+        + 'EXISTS (SELECT 1 FROM pg_attribute ca JOIN pg_collation co ON co.oid = ca.attcollation '
+        + 'WHERE ca.attrelid = c.conrelid AND ca.attnum = ANY(c.conkey) '
+        + 'AND NOT co.collisdeterministic) AS unsafe_collation '
+        + 'FROM pg_constraint c JOIN pg_class ct ON ct.oid = c.conrelid '
+        + 'JOIN pg_namespace n ON n.oid = ct.relnamespace '
+        + `WHERE c.contype = 'c' AND ct.relname = ${stringLiteral(table)} AND ${inNamespace} `
+        + 'ORDER BY c.conname',
       foreignKeyList: (table) => {
         const action = (column) => `CASE ${column} `
           + "WHEN 'a' THEN 'NO ACTION' WHEN 'r' THEN 'RESTRICT' WHEN 'c' THEN 'CASCADE' "
           + "WHEN 'n' THEN 'SET NULL' WHEN 'd' THEN 'SET DEFAULT' ELSE 'NO ACTION' END";
         return 'SELECT tt.relname AS target, sa.attname AS source_column, '
           + `ta.attname AS target_column, ${action('c.confdeltype')} AS on_delete, `
-          + `${action('c.confupdtype')} AS on_update, k.ord - 1 AS seq `
+          + `${action('c.confupdtype')} AS on_update, c.conname AS id, k.ord - 1 AS seq `
           + 'FROM pg_constraint c JOIN pg_class ct ON ct.oid = c.conrelid '
           + 'JOIN pg_namespace n ON n.oid = ct.relnamespace '
           + 'JOIN pg_class tt ON tt.oid = c.confrelid '

package/src/dialects/sqlite.js

@@ -11,6 +11,8 @@
 import { createDialect } from '../dialect.js';
 import { rtreeDdl } from './rtree-ddl.js';
 import { readExpression } from './expression-read.js';
+import { sqliteInvariantTriggers } from './invariant-sql.js';
+import { sqliteChecks } from './check-read.js';
 
 /** @param {string} s */
 function quoteIdentifier(s) {
@@ -427,6 +429,17 @@ export const sqliteDialect = createDialect({
       : `PRAGMA integrity_check(${pragmaValue(limit)})`),
     optimize: () => 'PRAGMA optimize',
   },
+  invariantTriggers: sqliteInvariantTriggers,
+  // The invalid path is evaluated only on overflow and carries a distinct
+  // marker through SQLite's error boundary, before any source row is written.
+  codepoint: (value) => `(${value} COLLATE BINARY)`,
+  mutationRowGuard: (count, limit) => `CASE WHEN ${count} > ${limit} `
+    + "THEN json_extract('{}', 'jaren-mutation-row-bound') ELSE 1 END",
+  physicalRead: (codec, sql) => codec === 'bigint' ? `CAST(${sql} AS TEXT)`
+    : codec === 'blob-hex' ? `CASE WHEN ${sql} IS NULL THEN NULL ELSE hex(${sql}) END` : sql,
+  physicalTypeMatches: (codec, type) => (codec === 'blob-hex' ? /BLOB/
+    : ['integer', 'bigint', 'boolean', 'epoch-ms'].includes(codec) ? /INT/
+      : codec === 'number' ? /REAL|FLOA|DOUB/ : /TEXT|CHAR|CLOB/).test(type),
   introspect: {
     version: () => 'SELECT sqlite_version() AS version',
     // the read-back of one configuration pragma: `PRAGMA name` answers
@@ -437,16 +450,17 @@ export const sqliteDialect = createDialect({
     tableExists: () =>
       "SELECT name FROM sqlite_schema WHERE type = 'table' AND name = ?",
     columns: (table) =>
-      `SELECT name, type, hidden FROM pragma_table_xinfo(${stringLiteral(table)})`,
+      `SELECT name, type, hidden, pk, "notnull" AS not_null, dflt_value AS default_value `
+      + `FROM pragma_table_xinfo(${stringLiteral(table)}) ORDER BY cid`,
     indexes: (table) =>
-      `SELECT name, "unique" AS uniq, origin FROM pragma_index_list(${stringLiteral(table)})`,
+      `SELECT name, "unique" AS uniq, origin, partial FROM pragma_index_list(${stringLiteral(table)})`,
     indexColumns: (index) =>
       `SELECT name FROM pragma_index_info(${stringLiteral(index)})`,
     foreignKeysOn: () => 'SELECT foreign_keys AS enabled FROM pragma_foreign_keys',
     dataVersion: () => 'SELECT data_version AS v FROM pragma_data_version',
     foreignKeyList: (table) =>
       `SELECT "table" AS target, "from" AS source_column, "to" AS target_column, `
-      + `on_delete, on_update, seq FROM pragma_foreign_key_list(${stringLiteral(table)}) `
+      + `on_delete, on_update, id, seq, match FROM pragma_foreign_key_list(${stringLiteral(table)}) `
       + 'ORDER BY id, seq',
     // Every schema object one table owns, with the CREATE text SQLite
     // stored verbatim. That text is where the physical facts no pragma
@@ -467,10 +481,16 @@ export const sqliteDialect = createDialect({
     // the CREATE text is where a generated column's expression lives
     generated: (table) =>
       `SELECT sql FROM sqlite_schema WHERE type = 'table' AND name = ${stringLiteral(table)}`,
+    checks: (table) =>
+      `SELECT sql FROM sqlite_schema WHERE type = 'table' AND name = ${stringLiteral(table)}`,
     // the whole declared schema, for shape-equality comparison after a
     // rebuild: every object that carries SQL text, in a stable order
     schemaDump: () =>
       "SELECT type, name, tbl_name AS owner, sql FROM sqlite_schema "
       + "WHERE sql IS NOT NULL ORDER BY type, name",
+    objects: () =>
+      'SELECT type, name, tbl_name AS owner, sql FROM sqlite_schema '
+      + "WHERE name NOT LIKE 'sqlite_%' ORDER BY type, name",
   },
+  readChecks: sqliteChecks,
 });

package/src/driver.js

@@ -822,6 +822,7 @@ export function finishConnection(raw, dialect, synchronous, capabilities, queueT
     // closed exactly as a statement is
     backup: capabilities.backup === true
       ? Object.freeze({
+        snapshot: raw.backup.snapshot === true,
         copy: (path, options) => { requireOpen(); return raw.backup.copy(path, options); },
         rename: (from, to) => { requireOpen(); return raw.backup.rename(from, to); },
         remove: (path) => { requireOpen(); return raw.backup.remove(path); },