@jarenjs/db 0.86.0 → 0.89.0

package/src/migration-target.js

@@ -0,0 +1,104 @@
+//@ts-check
+/** Acquisition and complete physical acceptance for migration entry points. */
+import { isThenable } from '@jarenjs/core/function';
+import { chain, toPromise } from './driver.js';
+import { DbCompileError } from './errors.js';
+import { readSchema } from './introspect.js';
+import { ENGINE_TABLES } from './engine-metadata.js';
+import { comparableDeclaredSql } from './schema-sql.js';
+
+/** Keep synchronous borrowed work synchronous; close only acquired resources.
+ * Cleanup failures retain the original failure as well as the close failure.
+ * @param {any} target @param {(connection:any)=>any} run @returns {any} */
+export function withMigrationConnection(target, run) {
+  const borrowed = target?.connection !== undefined;
+  if (!target || typeof target !== 'object' || (borrowed
+    ? target.driver !== undefined || target.path !== undefined || target.busyTimeout !== undefined
+      || typeof target.connection?.prepare !== 'function' || typeof target.connection?.transaction !== 'function'
+    : typeof target.driver?.open !== 'function'))
+    throw new TypeError('migration target needs { driver, path? } or { connection }');
+  if (borrowed) return run(target.connection);
+  return toPromise(chain(target.driver.open(target.path ?? ':memory:', { timeout: target.busyTimeout ?? 5000 }), (connection) => {
+    const finish = (value) => chain(connection.close(), () => value);
+    const fail = (error) => {
+      const both = (closeError) => { throw new AggregateError([error, closeError], 'migration failed and its connection could not close', { cause: error }); };
+      let closed;
+      try { closed = connection.close(); }
+      catch (closeError) { return both(closeError); }
+      if (isThenable(closed)) return closed.then(() => { throw error; }, both);
+      throw error;
+    };
+    let result;
+    try { result = run(connection); }
+    catch (error) { return fail(error); }
+    return isThenable(result) ? result.then(finish, fail) : finish(result);
+  }));
+}
+
+/** SQLite supplies the main database's canonical filename; private in-memory
+ * databases have no filename and cannot be identified by an empty string.
+ * @param {any} connection @returns {any} value-or-promise of string or null */
+export function sqliteDatabasePath(connection) {
+  return chain(connection.prepare(connection.dialect.introspect.pragma('database_list')), (statement) =>
+    chain(statement.all([]), (rows) => rows.find((row) => row.name === 'main')?.file || null));
+}
+
+/** Reject an alias before any shadow callback or replay statement can write.
+ * Native bindings identify files by device/inode; injected SQLite drivers may
+ * supply the same hook, with the engine's canonical filename as the fallback.
+ * @param {any} primary @param {any} shadow @param {any} driver @returns {any} */
+export function verifyShadowOwnership(primary, shadow, driver) {
+  if (primary.dialect.name !== 'sqlite' || shadow.dialect.name !== 'sqlite') return null;
+  const identify = typeof driver.databaseIdentity === 'function'
+    ? (connection) => driver.databaseIdentity(connection) : sqliteDatabasePath;
+  return chain(identify(primary), (source) => chain(identify(shadow), (target) => {
+    if (source !== null && source !== undefined && source === target)
+      throw new DbCompileError('JD0021', 'shadow replay needs a different database from the primary');
+  }));
+}
+
+/** Validate a complete owned-program inventory. Omitted tables are derived from
+ * object owners; explicit absent table names express reviewed drops.
+ * @param {any} target @returns {{objects:any[],tables:string[]}} */
+export function physicalTargetOf(target) {
+  const fail = () => { throw new DbCompileError('JD0021', 'physicalTarget requires complete objects and optional owned tables'); };
+  if (!target || typeof target !== 'object' || !Array.isArray(target.objects)
+    || Object.keys(target).some((k) => !['objects', 'tables'].includes(k))) fail();
+  const names = new Set();
+  const objects = target.objects.map((object) => {
+    if (!object || !['table', 'view', 'index', 'trigger'].includes(object.type)
+      || typeof object.name !== 'string' || !object.name || typeof object.owner !== 'string' || !object.owner
+      || typeof object.sql !== 'string' || ENGINE_TABLES.has(object.name) || ENGINE_TABLES.has(object.owner)
+      || names.has(`${object.type}:${object.name}`)) fail();
+    names.add(`${object.type}:${object.name}`);
+    return { type: object.type, name: object.name, owner: object.owner,
+      sql: comparableDeclaredSql(object.sql) };
+  });
+  const tables = target.tables ?? [...new Set(objects.map((o) => o.owner))];
+  if (!Array.isArray(tables) || new Set(tables).size !== tables.length
+    || tables.some((t) => typeof t !== 'string' || !t || ENGINE_TABLES.has(t))
+    || objects.some((o) => !tables.includes(o.owner))) fail();
+  if (objects.some((o) => ['index', 'trigger'].includes(o.type)
+    && !objects.some((t) => ['table', 'view'].includes(t.type) && t.name === o.owner))) fail();
+  return { objects, tables };
+}
+
+/** One acceptance owner for apply, repeated startup and status. Exact quoted
+ * programs and physical column order remain significant; unrelated tables stay
+ * outside the reviewed ownership set.
+ * @param {any} connection @param {any} target @returns {any} */
+export function comparePhysicalTarget(connection, target) {
+  if (connection.dialect.name !== 'sqlite') throw new DbCompileError('JD0021', 'complete physical target verification is qualified for SQLite');
+  const wanted = physicalTargetOf(target);
+  const selection = [...new Set([...wanted.tables, ...wanted.objects.map((o) => o.name)])];
+  return chain(readSchema(connection, { tables: selection }), (schema) => {
+    const actual = new Map(schema.objects.map((o) => [`${o.type}:${o.name}`, o]));
+    for (const object of wanted.objects) {
+      const key = `${object.type}:${object.name}`, have = actual.get(key);
+      if (!have) return `missing ${key}`;
+      if (object.owner !== have.owner || object.sql !== comparableDeclaredSql(have.sql)) return `different ${key}`;
+      actual.delete(key);
+    }
+    return actual.size ? `unexpected ${actual.keys().next().value}` : null;
+  });
+}

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/physical-transform.js

@@ -0,0 +1,207 @@
+//@ts-check
+/** Bounded physical migration reads and key-preserving column assignments. */
+import { canonicalizeJson } from '@jarenjs/json/canonical';
+import { createBoundedCache } from '@jarenjs/core/cache';
+import { setObjectMember } from '@jarenjs/core/object';
+import { chain, isThenable } from './driver.js';
+import { DbCompileError } from './errors.js';
+import { readSchema } from './introspect.js';
+import { columnCodec, physicalSelection, verifyPhysical } from './physical.js';
+import { entityCore } from './entity.js';
+import { sqliteTableMigration } from './dialects/sqlite.js';
+
+const member = (value, name) => Object.hasOwn(value, name) ? value[name] : undefined;
+const same = (a, b) => a === undefined || b === undefined
+  ? a === b : canonicalizeJson(a) === canonicalizeJson(b);
+
+/** Prove text cursors survived the binding without replacement characters. */
+function textKeyReadPlan(connection, mapping, keys) {
+  const columns = keys.filter((column) => column.codec === 'text');
+  if (columns.length === 0) return null;
+  const names = new Set(mapping.columns.map((column) => column.physical.toLowerCase()));
+  const aliases = columns.map((_, index) => {
+    let name = `__jaren_key_bytes_${index}`;
+    while (names.has(name.toLowerCase())) name += '_';
+    names.add(name.toLowerCase());
+    return name;
+  });
+  const q = connection.dialect.quoteIdentifier;
+  const projection = columns.map((column, index) =>
+    `${sqliteTableMigration.binaryCast(q(column.physical))} AS ${q(aliases[index])}`).join(', ');
+  return chain(connection.prepare(connection.dialect.introspect.pragma('encoding')), (statement) => chain(statement.get([]), (row) => {
+    // Raw SQLite text bytes use the database encoding, including UTF-16 files.
+    // A fatal decoder refuses malformed text; preserving BOM makes equality
+    // with the binding's public key exact, without changing its byte identity.
+    const decoder = new TextDecoder(row.encoding, { fatal: true, ignoreBOM: true });
+    // Some native bindings read a leading BOM correctly but strip it when
+    // binding the cursor back. Probe once; those keys must refuse before paging.
+    const probe = `SELECT ${sqliteTableMigration.binaryCast(connection.dialect.parameterRef(1, 'text'))} AS ${q('bytes')}`;
+    return chain(connection.prepare(probe), (statement) => chain(statement.get(['\uFEFFx']), (bound) => {
+      const keepsLeadingBom = decoder.decode(bound.bytes) === '\uFEFFx';
+      const read = (rows) => {
+        for (const row of rows) for (let index = 0; index < columns.length; index++) {
+          let decoded;
+          try { decoded = decoder.decode(row[aliases[index]]); }
+          catch { /* The common refusal below also covers replacement decoding. */ }
+          if (decoded === undefined || decoded !== row[columns[index].physical]
+            || !keepsLeadingBom && decoded.startsWith('\uFEFF'))
+            throw new DbCompileError('JD0021', `physical '${mapping.table}' key '${columns[index].name}' cannot round-trip through its SQLite text encoding`);
+        }
+        return rows.map((row) => {
+          const clean = { ...row };
+          for (const alias of aliases) delete clean[alias];
+          return clean;
+        });
+      };
+      return { projection, read };
+    }));
+  }));
+}
+
+/** Validate the physical read before preparing a statement over mapped columns. */
+function physicalReader(connection, mapping, batchSize, check) {
+  if (connection.dialect.name !== 'sqlite' || mapping.document !== false
+    || !mapping.keys?.length || !['table', 'view'].includes(mapping.kind))
+    throw new DbCompileError('JD0021', 'a physical migration read needs a declared SQLite table or view and mapped keys');
+  if (!Number.isSafeInteger(batchSize) || batchSize < 1)
+    throw new TypeError('physical migration batchSize must be a positive safe integer');
+  check?.();
+  return chain(readSchema(connection), (schema) => chain(verifyPhysical(connection, mapping, schema), () => {
+    const dialect = connection.dialect, q = dialect.quoteIdentifier;
+    const keys = mapping.keys.map((name) => mapping.columns.find((column) => column.name === name));
+    if (keys.some((column) => !column || !['text', 'integer', 'bigint'].includes(column.codec)))
+      throw new DbCompileError('JD0021', 'physical migration keys need text, integer or bigint codecs');
+    return chain(textKeyReadPlan(connection, mapping, keys), (textKeys) => {
+      // One explicit ordering governs both the cursor and comparisons. A table's
+      // actual PRIMARY KEY proves uniqueness; a view has no such proof and uses
+      // bounded offset pages. Big integers remain strings only at the binding
+      // boundary; comparison reads the INTEGER column with its SQLite affinity.
+      const ordered = keys.map((column) => column.codec === 'text'
+        ? dialect.codepoint(q(column.physical)) : q(column.physical));
+      const keyValues = (row) => keys.map((column) => {
+        const codec = columnCodec(column);
+        return codec.encode(codec.decode(row[column.physical]));
+      });
+      const table = q(mapping.table), projection = physicalSelection(mapping, dialect);
+      const select = `SELECT ${projection}${textKeys === null ? '' : `, ${textKeys.projection}`} FROM ${table}`;
+      const ordering = ` ORDER BY ${ordered.join(', ')}`;
+      const bounded = dialect.limitClause(batchSize, undefined);
+      const keyset = mapping.kind === 'table';
+      const seek = ` WHERE (${ordered.join(', ')}) > (${keys.map((_, i) => dialect.parameterRef(i + 1, 'key')).join(', ')})`;
+      const count = () => chain(connection.prepare(`SELECT COUNT(*) AS ${q('n')} FROM ${table}`), (s) => chain(s.get([]), (row) => Number(row.n)));
+      const walk = (handle) => chain(connection.prepare(select + ordering + bounded), (first) =>
+        chain(keyset ? connection.prepare(select + seek + ordering + bounded) : null, (following) => {
+          let after = null, offset = 0;
+          const done = Symbol('physical-migration-done');
+          const consume = (rows) => {
+            if (rows.length === 0) return done;
+            if (textKeys !== null) rows = textKeys.read(rows);
+            // Capture the continuation before a handler can mutate its batch.
+            if (keyset) after = keyValues(rows[rows.length - 1]);
+            offset += rows.length;
+            return handle(rows);
+          };
+          const advance = () => {
+            for (;;) {
+              check?.();
+              const page = keyset
+                ? (after === null ? first.all([]) : following.all(after))
+                : offset === 0 ? first.all([]) : chain(connection.prepare(select + ordering + dialect.limitClause(batchSize, offset)), (s) => s.all([]));
+              if (isThenable(page)) return page.then((rows) => {
+                const result = consume(rows);
+                return result === done ? null : chain(result, advance);
+              });
+              const result = consume(page);
+              if (result === done) return null;
+              if (isThenable(result)) return result.then(advance);
+            }
+          };
+          return advance();
+        }));
+      return { walk, count, keys, ordered, table };
+    });
+  }));
+}
+
+/** Read mapped rows without synthetic aliases that could overwrite stored names.
+ * @param {any} connection @param {any} mapping @param {number} batchSize
+ * @param {(rows: any[]) => any} handle @param {(() => void)} [check] @returns {any} */
+export function walkPhysicalRows(connection, mapping, batchSize, handle, check) {
+  return chain(physicalReader(connection, mapping, batchSize, check), (reader) => reader.walk(handle));
+}
+
+/** Transform column-only entities without application defaults/version stamps.
+ * The migration's surrounding savepoint owns every assignment and invariant.
+ * @param {any} connection @param {{entity: any, mapping: any}} target
+ * @param {any} operation @param {{batchSize: number, runtime?: any, check?: Function,
+ * onProgress?: Function, migration: string, collection: string}} options @returns {any} */
+export function transformPhysicalRows(connection, target, operation, options) {
+  const { entity, mapping } = target;
+  const core = entityCore(connection, entity, mapping, null, options.runtime);
+  core.plan.writable();
+  const columns = core.plan.scalarColumns;
+  const known = new Set(columns.map((column) => column.name));
+  const keyNames = new Set(core.plan.keys);
+  const statements = createBoundedCache(64);
+  return chain(physicalReader(connection, mapping, options.batchSize, options.check), (reader) =>
+    chain(reader.count(), (initialCount) => {
+      let visited = 0, transformed = 0;
+      const apply = (row) => {
+        const before = core.plan.merge(row);
+        const identity = Object.fromEntries(core.plan.keys.map((name) => [name, before[name]]));
+        const output = operation.apply(structuredClone(before), canonicalizeJson(identity));
+        for (const name of Object.keys(output)) if (!known.has(name))
+          operation.fail(`a physical transform cannot store unknown or relation member '${name}'`);
+        const values = [];
+        const candidate = {};
+        for (const column of columns) {
+          const name = column.name;
+          const supplied = Object.hasOwn(output, name);
+          const prior = member(before, name), raw = supplied ? output[name] : undefined;
+          const value = (column.generated || column.databaseDefault) && !supplied
+            ? prior : column.codecPlan.normalize(raw);
+          if (column.generated && !same(value, prior)) operation.fail(`generated column '${name}' is database-owned`);
+          if (keyNames.has(name) && !same(value, prior)) operation.fail(`a physical transform cannot change key '${name}'`);
+          if (value !== undefined) setObjectMember(candidate, name, value);
+          if (!column.generated && !keyNames.has(name) && !same(value, prior))
+            values.push({ name, value: core.plan.encodeColumn(name, raw) });
+        }
+        if (values.length === 0) return null;
+        const dialect = connection.dialect, q = dialect.quoteIdentifier;
+        const assignments = values.map((value, i) => `${q(core.plan.physicalName(value.name))} = ${dialect.parameterRef(i + 1, 'value')}`);
+        const where = reader.ordered.map((column, i) => `${column} = ${dialect.parameterRef(values.length + i + 1, 'key')}`).join(' AND ');
+        const sql = `UPDATE ${reader.table} SET ${assignments.join(', ')} WHERE ${where}`;
+        const params = [...values.map((value) => value.value), ...core.plan.keys.map((name) => core.plan.encodeColumn(name, before[name]))];
+        return chain(statements.getOrCreate(sql, (text) => connection.prepare(text)), (statement) => chain(statement.run(params), (result) => {
+          if (Number(result.changes) !== 1) operation.fail('the physical transform did not update exactly its addressed row');
+          return chain(core.get(core.plan.keys.length === 1 ? before[core.plan.keys[0]] : identity), (stored) => {
+            if (!stored || core.plan.keys.some((name) => !same(stored[name], before[name])))
+              operation.fail('the physical transform changed or lost its addressed key');
+            if (values.some(({ name }) => !same(member(stored, name), member(candidate, name))))
+              operation.fail('the physical transform did not store its requested column values');
+            core.plan.checkMutation('update', before, stored);
+            transformed++;
+            return null;
+          });
+        }));
+      };
+      return chain(reader.walk((rows) => {
+        visited += rows.length;
+        if (visited > initialCount) operation.fail('a physical transform changed source row membership');
+        let index = 0;
+        const next = () => {
+          while (index < rows.length) {
+            const result = apply(rows[index++]);
+            if (isThenable(result)) return result.then(next);
+          }
+          options.onProgress?.({ migration: options.migration, collection: options.collection, transformed });
+          return null;
+        };
+        return next();
+      }), () => chain(reader.count(), (finalCount) => {
+        if (finalCount !== initialCount || visited !== initialCount)
+          operation.fail('a physical transform changed source row membership');
+        return transformed;
+      }));
+    }));
+}

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/schema-sql.js

@@ -0,0 +1,184 @@
+//@ts-check
+/** Conservative SQLite declaration identity. Quoted bytes are never formatting. */
+
+/** @typedef {{ kind: string, text: string }} SqlToken */
+/** @typedef {{ columnOrder?: 'preserve' | 'ignore' }} DeclaredSqlOptions */
+
+/** @param {string} reason @returns {never} */
+function invalid(reason) {
+  throw new TypeError(`SQL declaration cannot be compared: ${reason}`);
+}
+
+/** SQLite whitespace excludes Unicode identifier characters and vertical tab. */
+const whitespace = (/** @type {number} */ code) => code === 32 || code === 9
+  || code === 10 || code === 12 || code === 13;
+const wordStart = (/** @type {number} */ code) => code >= 128 || code === 95
+  || code >= 65 && code <= 90 || code >= 97 && code <= 122;
+const wordPart = (/** @type {number} */ code) => wordStart(code) || code === 36
+  || code >= 48 && code <= 57;
+
+/** Lex before discarding comments or whitespace; retain each quoted token raw.
+ * @param {string} sql @returns {SqlToken[]} */
+function tokensOf(sql) {
+  if (typeof sql !== 'string') invalid('text is required');
+  /** @type {SqlToken[]} */
+  const tokens = [];
+  let depth = 0;
+  for (let i = 0; i < sql.length;) {
+    const start = i, c = sql[i];
+    if (whitespace(sql.charCodeAt(i))) { 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) invalid('unterminated comment');
+      i = end + 2;
+      continue;
+    }
+    const blob = (c === 'x' || c === 'X') && sql[i + 1] === "'";
+    if (blob) i++;
+    const quote = sql[i];
+    if (blob || quote === "'" || quote === '"' || quote === '`' || quote === '[') {
+      const close = quote === '[' ? ']' : quote;
+      let closed = false;
+      for (i++; i < sql.length; i++) {
+        if (sql.charCodeAt(i) === 0) invalid('NUL in quoted text');
+        if (sql[i] !== close) continue;
+        if (quote !== '[' && sql[i + 1] === close) { i++; continue; }
+        i++; closed = true; break;
+      }
+      if (!closed) invalid('unterminated quoted token');
+      const text = sql.slice(start, i);
+      if (blob && !/^[xX]'(?:[0-9a-fA-F]{2})*'$/.test(text)) invalid('invalid blob literal');
+      tokens.push({ kind: blob ? 'blob' : quote === "'" ? 'string' : 'identifier', text });
+      continue;
+    }
+    if (wordStart(sql.charCodeAt(i))) {
+      while (++i < sql.length && wordPart(sql.charCodeAt(i))) { /* whole identifier */ }
+      tokens.push({ kind: 'word', text: sql.slice(start, i) });
+      continue;
+    }
+    const number = /^(?:0[xX][0-9a-fA-F](?:_?[0-9a-fA-F])*|(?:[0-9](?:_?[0-9])*(?:\.(?:[0-9](?:_?[0-9])*)?)?|\.[0-9](?:_?[0-9])*)(?:[eE][+-]?[0-9](?:_?[0-9])*)?)/.exec(sql.slice(i));
+    if (number !== null) {
+      tokens.push({ kind: 'number', text: number[0] });
+      i += number[0].length;
+      if (wordPart(sql.charCodeAt(i)) || sql[i] === '.') invalid('invalid numeric token');
+      continue;
+    }
+    const operator = /^(?:->>|->|\|\||<<|>>|<=|>=|==|!=|<>|[(),.;+*/%~&|=<>-])/.exec(sql.slice(i));
+    if (operator === null) invalid(`unsupported token at ${i}`);
+    const text = operator[0];
+    if (text === '(') depth++;
+    else if (text === ')' && --depth < 0) invalid('unbalanced parentheses');
+    tokens.push({ kind: 'symbol', text });
+    i += text.length;
+  }
+  if (depth !== 0) invalid('unbalanced parentheses');
+  if (tokens.length === 0) invalid('empty declaration');
+  return tokens;
+}
+
+/** @param {SqlToken | undefined} token @param {string} word */
+const isWord = (token, word) => token?.kind === 'word' && token.text.toUpperCase() === word;
+
+/** Remove only the CREATE prefix clause SQLite omits from its catalog.
+ * @param {SqlToken[]} tokens @returns {SqlToken[]} */
+function withoutExistenceClause(tokens) {
+  if (!isWord(tokens[0], 'CREATE')) return tokens;
+  let at = 1;
+  if (isWord(tokens[at], 'TEMP') || isWord(tokens[at], 'TEMPORARY')) at++;
+  if (isWord(tokens[at], 'UNIQUE') || isWord(tokens[at], 'VIRTUAL')) at++;
+  if (!['TABLE', 'INDEX', 'TRIGGER', 'VIEW'].some((word) => isWord(tokens[at], word))) return tokens;
+  at++;
+  return isWord(tokens[at], 'IF') && isWord(tokens[at + 1], 'NOT') && isWord(tokens[at + 2], 'EXISTS')
+    ? [...tokens.slice(0, at), ...tokens.slice(at + 3)] : tokens;
+}
+
+/** Stable whitespace between tokens; punctuation cannot join words/operators.
+ * @param {SqlToken[]} tokens @returns {string} */
+function render(tokens) {
+  let out = '';
+  for (let i = 0; i < tokens.length; i++) {
+    const token = tokens[i], previous = tokens[i - 1];
+    const tight = token.kind === 'symbol' && ['(', ')', ','].includes(token.text)
+      || previous?.kind === 'symbol' && ['(', ')', ','].includes(previous.text);
+    out += (i === 0 || tight ? '' : ' ') + token.text;
+  }
+  return out;
+}
+
+/** Reorder only ordinary named columns with no order-sensitive inline clauses.
+ * Table constraints and every token inside a definition retain their order.
+ * Unrecognized table shapes keep strict order rather than guessing equivalence.
+ * @param {SqlToken[]} tokens @returns {SqlToken[]} */
+function namedColumnOrder(tokens) {
+  if (!isWord(tokens[0], 'CREATE')) return tokens;
+  let at = 1;
+  if (isWord(tokens[at], 'TEMP') || isWord(tokens[at], 'TEMPORARY')) at++;
+  if (!isWord(tokens[at++], 'TABLE')) return tokens;
+  const name = (/** @type {SqlToken | undefined} */ token) => token?.kind === 'word' || token?.kind === 'identifier';
+  if (!name(tokens[at++])) return tokens;
+  if (tokens[at]?.text === '.') {
+    at++;
+    if (!name(tokens[at++])) return tokens;
+  }
+  if (tokens[at]?.text !== '(') return tokens;
+  const open = at++;
+  /** @type {SqlToken[][]} */
+  const items = [];
+  let start = at, depth = 0, close = -1;
+  for (; at < tokens.length; at++) {
+    const token = tokens[at];
+    if (token.kind !== 'symbol') continue;
+    if (token.text === '(') depth++;
+    else if (token.text === ')') {
+      if (depth === 0) { items.push(tokens.slice(start, at)); close = at; break; }
+      depth--;
+    }
+    else if (token.text === ',' && depth === 0) { items.push(tokens.slice(start, at)); start = at + 1; }
+  }
+  if (close < 0 || items.some((item) => item.length === 0)) return tokens;
+  const constraint = (/** @type {SqlToken[]} */ item) => ['CONSTRAINT', 'PRIMARY', 'UNIQUE', 'CHECK', 'FOREIGN']
+    .some((word) => isWord(item[0], word));
+  const firstConstraint = items.findIndex(constraint);
+  const split = firstConstraint < 0 ? items.length : firstConstraint;
+  const columns = items.slice(0, split), constraints = items.slice(split);
+  if (constraints.some((item) => !constraint(item)) || columns.some((item) => !name(item[0]))) return tokens;
+  // Default evaluation and check/conflict/cascade order can change values,
+  // errors or surviving rows even when every access names its columns.
+  if (columns.some((item) => item.slice(1).some((token) =>
+    ['DEFAULT', 'CHECK', 'UNIQUE', 'REFERENCES', 'COLLATE', 'CONFLICT'].some((word) => isWord(token, word))))) return tokens;
+  columns.sort((a, b) => {
+    const left = render(a), right = render(b);
+    return left < right ? -1 : left > right ? 1 : 0;
+  });
+  const reordered = [...columns, ...constraints];
+  return [...tokens.slice(0, open + 1), ...reordered.flatMap((item, i) =>
+    i === 0 ? item : [{ kind: 'symbol', text: ',' }, ...item]), ...tokens.slice(close)];
+}
+
+/** A conservative declaration identity, preserving physical column order by default.
+ * `ignore` is for managed tables whose consumers address columns by name. Index,
+ * trigger and table-constraint order is always preserved; order-sensitive inline
+ * constraints and unfamiliar table structures retain strict column order too.
+ * Quoted bytes are exact. Comments and ordinary token whitespace are formatting.
+ * @param {string} sql
+ * @param {DeclaredSqlOptions} [options]
+ * @returns {string}
+ * @throws {TypeError} for malformed/unsupported lexical input or policy
+ */
+export function comparableDeclaredSql(sql, options = {}) {
+  const columnOrder = options.columnOrder ?? 'preserve';
+  if (!['preserve', 'ignore'].includes(columnOrder)) invalid('unknown columnOrder policy');
+  const tokens = withoutExistenceClause(tokensOf(sql));
+  return render(columnOrder === 'ignore' ? namedColumnOrder(tokens) : tokens);
+}
+
+/** Normalize formatting only, through the declaration comparison owner.
+ * @param {string} sql @returns {string} */
+export function normalizeDeclaredSql(sql) {
+  return comparableDeclaredSql(sql);
+}