@jarenjs/db 0.86.0 → 0.87.0

package/ARCHITECTURE.md

@@ -1186,7 +1186,9 @@ both hosts, including transaction failures.
 
 `dialects/sqlite-relational.js` owns the explicit SQLite expression and statement
 compiler; `dialects/sqlite-schema.js` reuses it for ordered tables, indexes and
-triggers. `table-migration.js` owns reviewed source/target guards, native copying
+triggers, sharing its column/reference renderer with native ADD COLUMN.
+`table-migration.js` owns reviewed source/settings guards for additive/object
+changes and source/target guards for native copying
 and preservation checks, with catalog/pragma spellings in the SQLite dialect.
 The supplied driver owns transactions and cursors. These programs are explicitly
 SQLite-semantic and never enter the JSON residual evaluator. See
@@ -1196,6 +1198,8 @@ SQLite-semantic and never enter the JSON residual evaluator. See
 does not import runtime owners. `/query`, `/model` and `/entity` expose those
 mechanisms without the root store import. `compileEntityModel` performs one model
 normalization for both entities and mapping; openStore reuses that result.
+`mutation.js` keeps bounded statement reuse keyed by emitted SQL; bindings,
+projections and limits are call-local, so cached plans do not retain old payloads.
 
 `drivers/worker-client.js` and `drivers/sqlite-endpoint.js` own the shared bounded
 RPC contract. Thread and process entries supply their transports. The process

package/README.md

@@ -1441,12 +1441,17 @@ Native column reads and bounded mutation documents are specified in [NATIVE-PLAN
 
 `@jarenjs/db/search` composes the resident ranker with bounded authoritative entity reads and optional atomic snapshot storage. See [persisted search](docs/SEARCH.md).
 
-Column-first table definitions, guarded same-connection rebuilds, exact matched writes,
+Column-first table definitions, native additive/object DDL, guarded same-connection rebuilds, exact matched writes,
 partial conflicts, raw-text JSON queries and byte-valued operations use
 [`@jarenjs/db/relational`](docs/SQLITE-RELATIONAL.md). Both host entries export
 `snapshotDatabase(connection, newPath)` for a disk-backed committed-WAL copy.
 Existing-connection consumers can import `/query`, `/model` and `/entity`;
 `compileEntityModel` shares one normalization between queries and mapping.
+`sql.call('json_type', ...)` preserves native missing/null/type distinctions.
+`planSchemaChange`/`applySchemaChange` guard a reviewed ADD COLUMN, DROP INDEX,
+RENAME TABLE or DROP TABLE against source drift. Identity-changing policies stay
+explicit; ordinary rebuilds retain key and row preservation. Mutation statements
+are reused by SQL without retaining previous payload-bearing documents.
 
 `@jarenjs/db/node-process` adds supervised native execution with finite owner
 admission, caller deadlines, generation fencing and separate process-exit and

package/docs/MODEL-FORMAT.md

@@ -2425,3 +2425,8 @@ physical entity retains adoption-only behavior. Public plans create complete
 ordered declarations; an incomplete generated/default definition or view remains
 adoption metadata. SQLite expressions preserve a separate, explicit semantic
 contract for raw text, bytes, nulls, collations and floating totals.
+`planSchemaChange`/`applySchemaChange` expose explicit native ADD COLUMN, DROP
+INDEX, RENAME TABLE and DROP TABLE with source/settings guards. They do not infer
+identity remapping or row deletion; that policy stays in an explicitly reviewed
+transaction. Entity mutation statement reuse is keyed by emitted SQL, while
+bindings, output projections and resource limits belong to each execution.

package/docs/NATIVE-PLANS.md

@@ -65,9 +65,11 @@ row limits bound fetched results; byte limits bound each decoded result item.
 
 ## Mutations
 
-The asynchronous entity set exposes `mutate(document)`. It compiles and caches a
-closed document into one parameterized SQLite data statement, inside the same
-guarded transaction used by the entity writer. It supports adopted writable
+The asynchronous entity set exposes `mutate(document)`. It compiles each closed
+document into one parameterized SQLite data statement and reuses statements by
+their complete SQL in a bounded cache. Bindings, projections and output limits
+remain local to each call; earlier payload-bearing documents are not retained.
+Execution uses the same guarded transaction as the entity writer. It supports adopted writable
 column layouts. Hybrid entities, PostgreSQL physical layouts, arbitrary SQL,
 store-enforced before/after invariants and unsupported expression shapes refuse
 with `JD0038`. Database constraints and invariant triggers retain enforcement.

package/docs/SQLITE-RELATIONAL.md

@@ -49,9 +49,16 @@ Selections support table and subquery sources, inner/left/cross joins, correlate
 `sql.scalar`/`sql.exists`, CASE, IN/NOT IN, DISTINCT, grouped and distinct
 aggregates, HAVING, UNION/UNION ALL and ordered windows. The declaration file
 lists the closed operators and functions, including trim/coalesce, LIKE, JSON
-extraction, casts and SQLite date functions. Neither arbitrary function names
+extraction/type inspection, casts and SQLite date functions. Neither arbitrary function names
 nor a raw-expression escape hatch is accepted.
 
+`sql.call('json_type', [document, path])` distinguishes a missing path (SQL NULL)
+from JSON null (text `'null'`) and reports SQLite's native scalar/container type
+names. Omitting the path inspects the whole document. SQL-null input stays null;
+malformed JSON raises SQLite's error. It composes with CASE and synchronous
+cursors without decoding or rewriting the original column. See
+[SQLite JSON type inspection](https://www.sqlite.org/json1.html#the_json_type_function).
+
 ## Exact writes and bytes
 
 ```js
@@ -114,7 +121,9 @@ applyTableMigration(connection, migration);
 Columns retain declaration order and exact INTEGER/REAL/TEXT/BLOB/NUMERIC/ANY
 types. Definitions support ordered primary keys, rowid or AUTOINCREMENT identity,
 nullability, database defaults, generated columns, STRICT/WITHOUT ROWID, named
-UNIQUE/CHECK/foreign-key constraints and delete/update actions. Index terms
+UNIQUE/CHECK/foreign-key constraints and delete/update actions. A column can also
+declare `references: { table, columns: [name], onDelete, onUpdate, deferred }`.
+Index terms
 support expressions, direction and collation, with an optional partial predicate.
 Triggers support BEFORE/AFTER, INSERT/UPDATE/DELETE, UPDATE OF, OLD/NEW conditions,
 mutation steps and RAISE. Schema expressions use the same structural emitter,
@@ -132,8 +141,9 @@ physical tables use the live-schema `planTableMigration` API.
 ## Guarded upgrades
 
 Planning inspects the existing schema without modifying it. A differing existing
-table requires `allowRebuild: true`; additions currently use the same guarded
-rebuild. Every removed column needs `dropColumns`; removing an existing explicit
+table requires `allowRebuild: true` when using `planTableMigration`; use the narrow
+schema operations below to append a column without rebuilding. Every removed
+column needs `dropColumns`; removing an existing explicit
 index/trigger requires `dropObjects`. Unmentioned indexes and triggers survive.
 An optional `copy` maps writable non-key target columns to structural expressions;
 new columns otherwise use their defaults. The plan retains the source schema and
@@ -157,6 +167,90 @@ refuses before DDL. Node/Bun regressions cover populated history and references,
 failed copies, repeat reopening, nested rollback, and process death after DROP
 with WAL recovery. These tests do not establish power-loss durability.
 
+## Additive and object operations
+
+`planSchemaChange(connection, operation)` returns a reviewable
+`{ version, operation, sql, source, settings, checksum }`. It reads the main schema
+and relevant connection settings without executing DDL. `applySchemaChange`
+checks that source and settings again under an IMMEDIATE transaction before
+executing the single statement. It returns `{ changed }`, the number of schema
+operations that changed the catalog, rather than the number of affected rows.
+Both methods require the same available synchronous SQLite ownership as rebuilds.
+
+```js
+import { planSchemaChange, applySchemaChange, sql } from '@jarenjs/db/relational';
+const addition = planSchemaChange(connection, {
+  op: 'addColumn', table: 'entries', column: {
+    name: 'revision', type: 'INTEGER', nullable: false, default: 1,
+    check: sql.binary('>=', sql.column('revision'), 1),
+  },
+});
+// Review addition.sql and addition.source before execution.
+applySchemaChange(connection, addition);
+applySchemaChange(connection, planSchemaChange(connection, {
+  op: 'dropIndex', name: 'obsolete_index', ifExists: true,
+}));
+```
+
+The closed operations are `addColumn` (`table`, `column`), `dropIndex` (`name`,
+optional `ifExists`), `renameTable` (`table`, `to`) and `dropTable` (`table`,
+optional `ifExists`). Identifiers address **main** explicitly; a temporary table
+with the same spelling cannot redirect an operation. A dot inside a name is a
+literal character. Attached database operations are not part of this surface.
+The column definition and expression renderer are shared with `planTable`.
+
+ADD COLUMN appends a declaration and preserves existing rowids, values, storage
+classes, column order, indexes and triggers. It does not derive a complete table
+definition, normalize unknown constraints or copy the table. Literal defaults
+are supported; identity columns, STORED generated columns and expression defaults
+refuse. Ordinary NOT NULL additions require a non-null default. REFERENCES
+additions require a NULL default (or no default), and a single referenced column.
+SQLite checks existing rows for a new CHECK or generated NOT NULL constraint;
+those checks can scan the table even though the operation does not copy it.
+See [SQLite ADD COLUMN restrictions](https://www.sqlite.org/lang_altertable.html#alter_table_add_column).
+
+Drop operations fail on absence unless `ifExists: true` is supplied. A missing
+object then returns `changed: 0`. DROP INDEX affects the named index, not its
+table or triggers. DROP TABLE removes the table and its owned indexes/triggers;
+SQLite's active foreign-key actions still apply. RENAME follows SQLite's current
+dependency rewriting behavior and the reviewed `legacy_alter_table` setting.
+See [DROP TABLE](https://www.sqlite.org/lang_droptable.html) and
+[RENAME TABLE](https://www.sqlite.org/lang_altertable.html#alter_table_rename).
+
+These are **single-source plans**, not durable migration receipts. Replan after
+any schema change. Reapplying a successful ADD/RENAME plan refuses as stale;
+it does not infer completion from a same-named object. An ordered migration must
+check its trusted schema/version receipt before planning the next operation and
+record completion in the same transaction. Unknown members or unsupported column
+declarations refuse with `JD0005`; modified/stale plans refuse with `JD0021`.
+Native object, data-constraint and dependency errors are left to SQLite. A
+checksum detects accidental plan edits; it does not authorize untrusted plans.
+
+## Explicit identity-changing upgrades
+
+The ordinary rebuild planner continues to refuse key reassignment or row loss.
+A reviewed upgrade can use the primitive operations under
+`withForeignKeysSuspended`, with its own explicit data policy:
+
+1. Check the durable migration receipt or the exact supported legacy schema.
+2. Create a distinct replacement table with `planTable`.
+3. Use relational insert-select with a scoped correlated selection, deterministic
+   identity choice and explicit exclusion predicate. Assert selected, inserted
+   and excluded counts, and any business-specific preservation requirements.
+4. Plan/apply `dropTable` for the original and then `renameTable` for the
+   replacement. Create the required indexes/triggers and validate dependents.
+5. Record completion inside the same transaction so another opening does no work.
+
+Create the replacement before dropping the original; renaming the original first
+can redirect dependent references. Plan each primitive inside the FK scope, after
+the preceding schema operation. The helper checks references before commit and
+restores connection settings. The caller must review incoming key references,
+views, triggers, immutable neighbors and each row disposition. Conflicts fail and
+roll back; there is no inferred permission to discard rows. The installed native
+[qualification fixture](../../../test/db/fixtures/schema-upgrade.mjs) demonstrates
+scoped minimum-ID selection, explicit exclusions, rollback, repeated reopening
+and recovery after actual process death at DROP.
+
 ## Read-only inspection and disk snapshots
 
 `readSchema` from `@jarenjs/db/model` inventories tables without adopting them,
@@ -188,3 +282,15 @@ calls. No global strong model cache is introduced. Keep connection/query caches
 bounded and reuse compiled metadata. Smaller import graphs alone do not prove
 the complete application meets its RSS budget; measure application memory with
 representative workloads.
+
+Entity mutation engines retain prepared statements by their complete emitted SQL
+in the bounded core LRU cache. Bound values, output projections and row/byte limits
+belong to each execution; changing a payload does not retain another document and
+another copy of the same statement. Distinct SQL stays isolated. This reduces
+retained payload memory, at the cost of rebinding/compiling an identical mutation
+document on each call. The synthetic retention probe at
+`test/db/fixtures/mutation-memory.mjs` reports both varying-payload and identical
+mutation timings, heap and RSS on Node (`--expose-gc`) and Bun. Such samples do not
+replace a complete application's resource gate. Metadata remains caller-owned;
+keep one compiled mapping per used model, one query state per connection, and
+release facade/cache references on close. Driver cursors remain ephemeral.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/db",
   "private": false,
-  "version": "0.86.0",
+  "version": "0.87.0",
   "type": "module",
   "main": "./src/index.js",
   "types": "./types/index.d.ts",
@@ -108,9 +108,9 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.86.0",
-    "@jarenjs/json": "^0.86.0",
-    "@jarenjs/validate": "^0.86.0"
+    "@jarenjs/core": "^0.87.0",
+    "@jarenjs/json": "^0.87.0",
+    "@jarenjs/validate": "^0.87.0"
   },
   "bin": {
     "jaren-db": "./src/cli.js"

package/src/dialects/sqlite-relational.js

@@ -22,7 +22,7 @@ export function relationalIdentifier(name) {
 }
 const q = relationalIdentifier;
 const binary = new Set(['=', '<>', '<', '<=', '>', '>=', 'IS', 'IS NOT', '+', '-', '*', '/', '%', '||', 'AND', 'OR', 'LIKE', 'NOT LIKE', 'GLOB']);
-const functions = new Set(['coalesce', 'nullif', 'trim', 'ltrim', 'rtrim', 'lower', 'upper', 'length', 'abs', 'round', 'typeof', 'json_extract', 'json_valid', 'count', 'sum', 'total', 'avg', 'min', 'max', 'date', 'time', 'datetime', 'julianday', 'unixepoch', 'strftime']);
+const functions = new Set(['coalesce', 'nullif', 'trim', 'ltrim', 'rtrim', 'lower', 'upper', 'length', 'abs', 'round', 'typeof', 'json_extract', 'json_valid', 'json_type', 'count', 'sum', 'total', 'avg', 'min', 'max', 'date', 'time', 'datetime', 'julianday', 'unixepoch', 'strftime']);
 const types = new Set(['INTEGER', 'REAL', 'TEXT', 'BLOB', 'NUMERIC']);
 const collations = new Set(['BINARY', 'NOCASE', 'RTRIM']);
 const node = (kind, spec) => ({ $sql: kind, ...spec });
@@ -104,6 +104,7 @@ export function relationalEmitter(options = {}) {
         if (value.distinct !== undefined && typeof value.distinct !== 'boolean') fail('DISTINCT must be boolean');
         if (value.distinct && value.args.length !== 1) fail('DISTINCT functions require one argument');
         if (!value.args.length && value.name !== 'count') fail('SQL function requires arguments');
+        if (value.name === 'json_type' && value.args.length > 2) fail('json_type requires one or two arguments');
         return `${value.name.toUpperCase()}(${value.distinct ? 'DISTINCT ' : ''}${value.args.length ? value.args.map(next).join(', ') : '*'})`;
       }
       case 'cast':

package/src/dialects/sqlite-schema.js

@@ -34,37 +34,13 @@ export function planTable(definition) {
   for (const key of ['constraints', 'indexes', 'triggers']) if (definition[key] !== undefined && !Array.isArray(definition[key])) fail(`${key} must be a list`);
   const emitter = relationalEmitter({ inline: true });
   const names = new Set();
-  let inlineKey = false;
   const columns = definition.columns.map((column) => {
-    check(column, ['name', 'type', 'nullable', 'default', 'collation', 'identity', 'check', 'generated', 'stored'], 'column definition');
-    const name = q(column.name);
+    const text = columnSql(column, definition, emitter);
     if (names.has(column.name.toLowerCase())) fail('physical column names must be distinct');
     names.add(column.name.toLowerCase());
-    if (!['INTEGER', 'REAL', 'TEXT', 'BLOB', 'NUMERIC', 'ANY'].includes(column.type)) fail('unsupported SQLite column type');
-    if (definition.strict && column.type === 'NUMERIC') fail('STRICT tables do not support NUMERIC');
-    if (column.nullable !== undefined && typeof column.nullable !== 'boolean') fail('nullable must be boolean');
-    if (column.stored !== undefined && (typeof column.stored !== 'boolean' || column.generated === undefined)) fail('stored requires a generated expression');
-    let out = `${name} ${column.type}`;
-    if (column.identity !== undefined) {
-      if (!['rowid', 'autoincrement'].includes(column.identity) || column.type !== 'INTEGER'
-        || definition.withoutRowid || definition.primaryKey?.length !== 1
-        || definition.primaryKey[0] !== column.name || column.generated !== undefined) fail('identity requires a single INTEGER rowid primary key');
-      inlineKey = true;
-      out += ` PRIMARY KEY${column.identity === 'autoincrement' ? ' AUTOINCREMENT' : ''}`;
-    }
-    if (column.nullable === false) out += ' NOT NULL';
-    if (column.collation !== undefined) {
-      if (!['BINARY', 'NOCASE', 'RTRIM'].includes(column.collation)) fail('unsupported column collation');
-      out += ` COLLATE ${column.collation}`;
-    }
-    if (Object.hasOwn(column, 'default')) out += ` DEFAULT (${emitter.expr(column.default)})`;
-    if (column.check !== undefined) out += ` CHECK (${emitter.expr(column.check)})`;
-    if (column.generated !== undefined) {
-      if (Object.hasOwn(column, 'default')) fail('a generated column cannot have a default');
-      out += ` GENERATED ALWAYS AS (${emitter.expr(column.generated)}) ${column.stored ? 'STORED' : 'VIRTUAL'}`;
-    }
-    return out;
+    return text;
   });
+  const inlineKey = definition.columns.some((column) => column.identity !== undefined);
   const members = (values) => {
     const text = list(values, 'constraint columns');
     if (values.some((name) => !names.has(name.toLowerCase()))) fail('constraint names an undeclared column');
@@ -79,11 +55,12 @@ export function planTable(definition) {
     else if (constraint.kind === 'check') columns.push(`${prefix}CHECK (${emitter.expr(constraint.expression)})`);
     else if (constraint.kind === 'foreignKey') {
       if (constraint.columns?.length !== constraint.references?.length) fail('foreign-key columns must have equal arity');
-      if (constraint.deferred !== undefined && typeof constraint.deferred !== 'boolean') fail('deferred must be boolean');
-      columns.push(`${prefix}FOREIGN KEY (${members(constraint.columns)}) REFERENCES ${q(constraint.table)} (${list(constraint.references, 'references')})`
-        + (constraint.onDelete === undefined ? '' : ` ON DELETE ${action(constraint.onDelete)}`)
-        + (constraint.onUpdate === undefined ? '' : ` ON UPDATE ${action(constraint.onUpdate)}`)
-        + (constraint.deferred ? ' DEFERRABLE INITIALLY DEFERRED' : ''));
+      columns.push(`${prefix}FOREIGN KEY (${members(constraint.columns)}) ${referenceSql({
+        table: constraint.table, columns: constraint.references,
+        ...(constraint.onDelete === undefined ? {} : { onDelete: constraint.onDelete }),
+        ...(constraint.onUpdate === undefined ? {} : { onUpdate: constraint.onUpdate }),
+        ...(constraint.deferred === undefined ? {} : { deferred: constraint.deferred }),
+      })}`);
     }
     else fail('constraint kind is unique, check or foreignKey');
     const keys = constraint.kind === 'unique' ? ['kind', 'name', 'columns']
@@ -140,3 +117,76 @@ export function planTable(definition) {
     indexes: (definition.indexes ?? []).map((i) => ({ name: i.name, unique: i.unique === true, terms: i.terms })),
   } };
 }
+
+/** One REFERENCES clause shared by table constraints and column declarations. */
+function referenceSql(reference) {
+  check(reference, ['table', 'columns', 'onDelete', 'onUpdate', 'deferred'], 'reference');
+  if (reference.deferred !== undefined && typeof reference.deferred !== 'boolean') fail('deferred must be boolean');
+  return `REFERENCES ${q(reference.table)} (${list(reference.columns, 'references')})`
+    + (reference.onDelete === undefined ? '' : ` ON DELETE ${action(reference.onDelete)}`)
+    + (reference.onUpdate === undefined ? '' : ` ON UPDATE ${action(reference.onUpdate)}`)
+    + (reference.deferred ? ' DEFERRABLE INITIALLY DEFERRED' : '');
+}
+
+/** Render one typed column without reconstructing any surrounding schema. */
+function columnSql(column, context, emitter) {
+  check(column, ['name', 'type', 'nullable', 'default', 'collation', 'identity', 'check', 'generated', 'stored', 'references'], 'column definition');
+  const name = q(column.name);
+  if (!['INTEGER', 'REAL', 'TEXT', 'BLOB', 'NUMERIC', 'ANY'].includes(column.type)) fail('unsupported SQLite column type');
+  if (context.strict && column.type === 'NUMERIC') fail('STRICT tables do not support NUMERIC');
+  if (column.nullable !== undefined && typeof column.nullable !== 'boolean') fail('nullable must be boolean');
+  if (column.stored !== undefined && (typeof column.stored !== 'boolean' || column.generated === undefined)) fail('stored requires a generated expression');
+  const hasDefault = Object.hasOwn(column, 'default');
+  if (context.additive) {
+    if (column.identity !== undefined || column.stored === true) fail('ADD COLUMN cannot add an identity or STORED column');
+    const value = column.default?.$sql === 'value' ? column.default.value : column.default;
+    if (hasDefault && !(value === null || typeof value === 'string' || typeof value === 'bigint'
+      || (typeof value === 'number' && Number.isFinite(value)))) fail('ADD COLUMN requires a literal default');
+    if (column.generated === undefined && column.nullable === false && (!hasDefault || value === null)) fail('ADD COLUMN NOT NULL requires a non-null default');
+    if (column.references !== undefined && hasDefault && value !== null) fail('ADD COLUMN REFERENCES requires a NULL default');
+  }
+  let out = `${name} ${column.type}`;
+  if (column.identity !== undefined) {
+    if (!['rowid', 'autoincrement'].includes(column.identity) || column.type !== 'INTEGER'
+      || context.withoutRowid || context.primaryKey?.length !== 1
+      || context.primaryKey[0] !== column.name || column.generated !== undefined) fail('identity requires a single INTEGER rowid primary key');
+    out += ` PRIMARY KEY${column.identity === 'autoincrement' ? ' AUTOINCREMENT' : ''}`;
+  }
+  if (column.nullable === false) out += ' NOT NULL';
+  if (column.collation !== undefined) {
+    if (!['BINARY', 'NOCASE', 'RTRIM'].includes(column.collation)) fail('unsupported column collation');
+    out += ` COLLATE ${column.collation}`;
+  }
+  if (hasDefault) out += context.additive ? ` DEFAULT ${emitter.expr(column.default)}` : ` DEFAULT (${emitter.expr(column.default)})`;
+  if (column.check !== undefined) out += ` CHECK (${emitter.expr(column.check)})`;
+  if (column.generated !== undefined) {
+    if (hasDefault) fail('a generated column cannot have a default');
+    out += ` GENERATED ALWAYS AS (${emitter.expr(column.generated)}) ${column.stored ? 'STORED' : 'VIRTUAL'}`;
+  }
+  if (column.references !== undefined) {
+    if (column.references?.columns?.length !== 1) fail('a column reference requires one referenced column');
+    out += ` ${referenceSql(column.references)}`;
+  }
+  return out;
+}
+
+/** Render one explicit main-schema operation; validation never executes SQL.
+ * @param {any} operation @returns {string} */
+export function schemaChangeSql(operation) {
+  check(operation, ['op', 'table', 'column', 'name', 'to', 'ifExists'], 'schema change');
+  switch (operation.op) {
+    case 'addColumn':
+      check(operation, ['op', 'table', 'column'], 'addColumn');
+      return `ALTER TABLE "main".${q(operation.table)} ADD COLUMN ${columnSql(operation.column, { additive: true }, relationalEmitter({ inline: true }))}`;
+    case 'renameTable':
+      check(operation, ['op', 'table', 'to'], 'renameTable');
+      return `ALTER TABLE "main".${q(operation.table)} RENAME TO ${q(operation.to)}`;
+    case 'dropIndex': case 'dropTable': {
+      const index = operation.op === 'dropIndex';
+      check(operation, ['op', index ? 'name' : 'table', 'ifExists'], operation.op);
+      if (operation.ifExists !== undefined && typeof operation.ifExists !== 'boolean') fail('ifExists must be boolean');
+      return `DROP ${index ? 'INDEX' : 'TABLE'}${operation.ifExists ? ' IF EXISTS' : ''} "main".${q(index ? operation.name : operation.table)}`;
+    }
+    default: return fail('schema change is addColumn, dropIndex, renameTable or dropTable');
+  }
+}

package/src/index.js

@@ -105,4 +105,4 @@ export { planInvariants } from './ddl.js';
 export { planPhysicalMigration } from './migrate.js';
 export { sql, planRelational, relational } from './dialects/sqlite-relational.js';
 export { defineTable, planTable } from './dialects/sqlite-schema.js';
-export { planTableMigration, applyTableMigration, withForeignKeysSuspended } from './table-migration.js';
+export { planTableMigration, applyTableMigration, withForeignKeysSuspended, planSchemaChange, applySchemaChange } from './table-migration.js';

package/src/mutation.js

@@ -1,7 +1,7 @@
 //@ts-check
 /** Bounded column mutation documents, lowered through the entity's writer plan. */
 import { analyzeQuery } from '@jarenjs/json/query';
-import { canonicalizeJson } from '@jarenjs/json/canonical';
+import { createBoundedCache } from '@jarenjs/core/cache';
 import { chain, attempt } from './driver.js';
 import { DbCompileError, DbRuntimeError, wrapDriverError } from './errors.js';
 import { entityShape, planEntityPredicate } from './plan.js';
@@ -10,12 +10,13 @@ import { physicalSelection } from './physical.js';
 import { utf8Length } from './cursor.js';
 import { relationalEmitter } from './dialects/sqlite-relational.js';
 
-/** Compile once per document, execute within the existing guarded transaction.
+/** Bind each document, reuse its SQL statement within the guarded transaction.
  * @param {any} connection @param {any} entity @param {any} mapping @param {any} core */
 export function createEntityMutation(connection, entity, mapping, core) {
   const dialect = connection.dialect;
   const q = dialect.quoteIdentifier;
-  const plans = new Map();
+  // Cache executable structure, never a value-bearing document or its bindings.
+  const statements = createBoundedCache(64);
   const fail = (reason) => { throw new DbCompileError('JD0038', reason, entity.docPath); };
   const column = (name) => {
     const c = mapping.columns.find((entry) => entry.name === name);
@@ -56,15 +57,17 @@ export function createEntityMutation(connection, entity, mapping, core) {
     const param = (value) => { params.push(value); return dialect.parameterRef(params.length, 'v'); };
     const table = q(mapping.table);
     const sqlExpression = (expression, inline = false) => {
-      const mapped = (value) => {
-        if (Array.isArray(value)) return value.map(mapped);
+      const mapped = (value, depth = 0) => {
+        if (depth > 64) fail('SQL expression nesting exceeds 64');
+        const next = (child) => mapped(child, depth + 1);
+        if (Array.isArray(value)) return value.map(next);
         if (value === null || typeof value !== 'object') return value;
         if (value.$sql === 'value') return value;
         if (value.$sql === 'column') {
           if (value.table !== undefined && value.table !== 'it') fail('mutation column expressions refer to the current entity');
           return { $sql: 'column', name: column(value.name).physical };
         }
-        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, mapped(item)]));
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, next(item)]));
       };
       const emitter = relationalEmitter({ inline });
       const result = emitter.expr(mapped(expression));
@@ -187,19 +190,13 @@ export function createEntityMutation(connection, entity, mapping, core) {
       }
     }
     sql = prefix + sql + ` RETURNING ${physicalSelection(mapping, dialect)}`;
-    return { sql, params, returning, maxRows, maxBytes, statement: null };
+    return { sql, params, returning, maxRows, maxBytes };
   };
   return (document) => {
-    const key = canonicalizeJson(document);
-    let plan = plans.get(key);
-    if (!plan) {
-      plan = compile(document);
-      if (plans.size >= 64) plans.delete(plans.keys().next().value);
-      plans.set(key, plan);
-    }
+    const plan = compile(document);
     return connection.transaction(() => {
-      plan.statement ??= connection.prepare(plan.sql);
-      return chain(plan.statement, (statement) => chain(attempt(() => statement.all(plan.params),
+      const prepared = statements.getOrCreate(plan.sql, (text) => connection.prepare(text));
+      return chain(prepared, (statement) => chain(attempt(() => statement.all(plan.params),
         (error) => String(error?.message).includes('jaren-mutation-row-bound')
           ? new DbRuntimeError('JD2007', 'insert-select exceeded its source row bound', { cause: error })
           : wrapDriverError(error, { collection: entity.name, docPath: entity.docPath })), (rows) => {

package/src/relational-api.js

@@ -2,5 +2,5 @@
 /** Lightweight column-first SQLite authoring and execution. */
 export { sql, planRelational, relational } from './dialects/sqlite-relational.js';
 export { defineTable, planTable } from './dialects/sqlite-schema.js';
-export { planTableMigration, applyTableMigration, withForeignKeysSuspended } from './table-migration.js';
+export { planTableMigration, applyTableMigration, withForeignKeysSuspended, planSchemaChange, applySchemaChange } from './table-migration.js';
 export { sqliteDialect } from './dialects/sqlite.js';

package/src/table-migration.js

@@ -3,7 +3,7 @@
 import { hashContent } from '@jarenjs/core/string';
 import { canonicalizeJson } from '@jarenjs/json/canonical';
 import { DbCompileError } from './errors.js';
-import { defineTable, planTable } from './dialects/sqlite-schema.js';
+import { defineTable, planTable, schemaChangeSql } from './dialects/sqlite-schema.js';
 import { relationalEmitter, relationalIdentifier as q, sql } from './dialects/sqlite-relational.js';
 import { sqliteDialect as dialect, sqliteTableMigration } from './dialects/sqlite.js';
 import { sqlTokens } from './dialects/check-read.js';
@@ -17,6 +17,39 @@ const sync = (connection) => {
   if (connection.dialect.name !== 'sqlite' || !connection.synchronous || connection.mustQueue) refuse('table migration requires an available synchronous SQLite connection');
 };
 
+/** Connection settings that govern the meaning of an additive/drop/rename plan. */
+function schemaSettings(connection) {
+  return ['foreign_keys', 'legacy_alter_table', 'schema_version'].map((name) =>
+    connection.prepare(dialect.introspect.pragma(name)).get([])[name]);
+}
+
+/** Review one native main-schema change without changing the database.
+ * Plans describe one source snapshot; callers own durable migration receipts.
+ * @param {any} connection @param {any} operation */
+export function planSchemaChange(connection, operation) {
+  sync(connection);
+  const text = schemaChangeSql(operation);
+  const body = { version: 1, operation: structuredClone(operation), sql: text,
+    source: schema(connection), settings: schemaSettings(connection) };
+  return { ...body, checksum: fingerprint({ ...body, operation: text }) };
+}
+
+/** Apply a reviewed native change atomically, refusing schema/settings drift.
+ * Replan after any schema change; only explicit drop ifExists handles absence.
+ * @param {any} connection @param {ReturnType<typeof planSchemaChange>} plan */
+export function applySchemaChange(connection, plan) {
+  sync(connection);
+  const { checksum, ...body } = plan;
+  if (body.version !== 1 || checksum !== fingerprint({ ...body, operation: plan.sql }) || plan.sql !== schemaChangeSql(plan.operation)) refuse('schema change checksum or statement differs');
+  return connection.transaction(() => {
+    const before = schema(connection);
+    if (fingerprint(before) !== fingerprint(plan.source) || fingerprint(schemaSettings(connection)) !== fingerprint(plan.settings))
+      refuse('source schema or connection settings changed after planning');
+    connection.exec(plan.sql);
+    return { changed: fingerprint(before) === fingerprint(schema(connection)) ? 0 : 1 };
+  }, { mode: 'immediate' });
+}
+
 /** Inspect a live schema and generate a table plan without changing it.
  * Rebuilds require explicit opt-in. Unlisted indexes and triggers are preserved.
  * @param {any} connection @param {any} definition

package/types/index.d.ts

@@ -2045,4 +2045,4 @@ export declare function planPhysicalMigration(connection: unknown, fromModel: un
   options: { id: string; steps: readonly unknown[]; dispositions: Readonly<Record<string, 'preserve' | 'replace' | 'drop'>>;
     assertions?: readonly { sql: string; params?: readonly unknown[]; expected: readonly unknown[] }[] }): unknown;
 
-export { sql, relational, planRelational, defineTable, planTable, planTableMigration, applyTableMigration, withForeignKeysSuspended } from './relational.js';
+export { sql, relational, planRelational, defineTable, planTable, planTableMigration, applyTableMigration, withForeignKeysSuspended, planSchemaChange, applySchemaChange } from './relational.js';

package/types/relational.d.ts

@@ -4,7 +4,7 @@ export type SqlInput = SqlValue | SqlExpression;
 export type SqlOperator = '=' | '<>' | '<' | '<=' | '>' | '>=' | 'IS' | 'IS NOT'
   | '+' | '-' | '*' | '/' | '%' | '||' | 'AND' | 'OR' | 'LIKE' | 'NOT LIKE' | 'GLOB';
 export type SqlFunction = 'coalesce' | 'nullif' | 'trim' | 'ltrim' | 'rtrim' | 'lower' | 'upper'
-  | 'length' | 'abs' | 'round' | 'typeof' | 'json_extract' | 'json_valid'
+  | 'length' | 'abs' | 'round' | 'typeof' | 'json_extract' | 'json_valid' | 'json_type'
   | 'count' | 'sum' | 'total' | 'avg' | 'min' | 'max'
   | 'date' | 'time' | 'datetime' | 'julianday' | 'unixepoch' | 'strftime';
 export type SqlType = 'INTEGER' | 'REAL' | 'TEXT' | 'BLOB' | 'NUMERIC';
@@ -78,8 +78,13 @@ export interface TableColumn {
   readonly default?: SqlInput; readonly collation?: SqlCollation;
   readonly identity?: 'rowid' | 'autoincrement'; readonly check?: SqlInput;
   readonly generated?: SqlInput; readonly stored?: boolean;
+  readonly references?: ColumnReference;
 }
 export type ForeignKeyAction = 'cascade' | 'restrict' | 'no action' | 'set null' | 'set default';
+export interface ColumnReference {
+  readonly table: string; readonly columns: readonly [string];
+  readonly onDelete?: ForeignKeyAction; readonly onUpdate?: ForeignKeyAction; readonly deferred?: boolean;
+}
 export type TableConstraint = { readonly name?: string } & (
   { readonly kind: 'unique'; readonly columns: readonly string[] }
   | { readonly kind: 'check'; readonly expression: SqlInput }
@@ -111,4 +116,17 @@ export interface TableMigrationPlan {
 export declare function planTableMigration(connection: unknown, definition: TableDefinition, options: TableMigrationOptions): TableMigrationPlan;
 export declare function applyTableMigration(connection: unknown, plan: TableMigrationPlan): { changed: number };
 export declare function withForeignKeysSuspended<T>(connection: unknown, fn: () => T): T;
+export type SchemaChange =
+  | { readonly op: 'addColumn'; readonly table: string; readonly column: TableColumn }
+  | { readonly op: 'dropIndex'; readonly name: string; readonly ifExists?: boolean }
+  | { readonly op: 'renameTable'; readonly table: string; readonly to: string }
+  | { readonly op: 'dropTable'; readonly table: string; readonly ifExists?: boolean };
+export interface SchemaChangePlan {
+  readonly version: 1; readonly operation: SchemaChange; readonly sql: string;
+  readonly source: readonly unknown[]; readonly settings: readonly number[]; readonly checksum: string;
+}
+/** Main-schema snapshot; does not execute SQL or infer replay/disposition policy. */
+export declare function planSchemaChange(connection: unknown, operation: SchemaChange): SchemaChangePlan;
+/** Refuses stale source/settings under an immediate transaction. */
+export declare function applySchemaChange(connection: unknown, plan: SchemaChangePlan): { changed: number };
 export { sqliteDialect } from './index.js';