@jarenjs/db 0.84.3 → 0.86.0

package/src/drivers/sqlite-endpoint.js

@@ -0,0 +1,113 @@
+//@ts-check
+/** One worker owns one SQLite handle. Only bounded credit frames carry rows. */
+import { nodeDriver } from './node.js';
+import { DbRuntimeError, cloneDriverError } from '../errors.js';
+import { validRequest, generationFailure, rowBytes } from './worker-protocol.js';
+
+/** @param {any} parentPort @param {any} configuration */
+export async function serveSqliteEndpoint(parentPort, configuration) {
+  const { generation, path, options, limits } = configuration;
+  let connection;
+  let sequence = 0;
+  const statements = new Map();
+  const cursors = new Map();
+  const frame = (kind, id, value) => ({ v: 1, generation, kind, id, ...value });
+  const transaction = () => {
+    try { return connection.transactionState(); }
+    catch { return null; }
+  };
+  const bound = (reason) => new DbRuntimeError('JD2092', reason);
+  const release = (id) => {
+    const cursor = cursors.get(id);
+    if (cursor === undefined) return;
+    cursors.delete(id);
+    cursor.iterator.return?.();
+    if (cursor.ephemeral) statements.delete(cursor.statement);
+  };
+  const statementOf = (id) => {
+    const statement = statements.get(id);
+    if (statement === undefined) throw generationFailure(generation);
+    return statement;
+  };
+  const dispatch = (request) => {
+    switch (request.op) {
+      case 'exec': return connection.exec(request.sql);
+      case 'prepare': {
+        if (statements.size >= limits.statements) throw bound(`worker statement capacity ${limits.statements} exceeded`);
+        const id = ++sequence;
+        statements.set(id, { statement: connection.prepare(request.sql), ephemeral: request.ephemeral === true });
+        return id;
+      }
+      case 'get': {
+        const row = statementOf(request.statement).statement.get(request.params);
+        if (rowBytes(row) > limits.bytes) throw bound(`one worker row exceeds ${limits.bytes} bytes`);
+        return row;
+      }
+      case 'run': return statementOf(request.statement).statement.run(request.params);
+      case 'iterate': {
+        if (cursors.size >= limits.cursors) throw bound(`worker cursor capacity ${limits.cursors} exceeded`);
+        const record = statementOf(request.statement);
+        const id = ++sequence;
+        cursors.set(id, { iterator: record.statement.iterate(request.params),
+          statement: request.statement, ephemeral: record.ephemeral, buffered: null });
+        return id;
+      }
+      case 'next': {
+        const cursor = cursors.get(request.cursor);
+        if (cursor === undefined) throw generationFailure(generation);
+        if (request.rows > limits.rows || request.bytes > limits.bytes) throw bound('worker cursor credit exceeds the negotiated window');
+        const rows = [];
+        let bytes = 0;
+        try {
+          while (rows.length < request.rows) {
+            const step = cursor.buffered ?? cursor.iterator.next();
+            cursor.buffered = null;
+            if (step.done) { release(request.cursor); return { rows, bytes, done: true }; }
+            const size = rowBytes(step.value);
+            if (size > request.bytes) throw bound(`one worker row of ${size} bytes exceeds the ${request.bytes} byte window`);
+            if (bytes + size > request.bytes) { cursor.buffered = step; break; }
+            rows.push(step.value);
+            bytes += size;
+          }
+          return { rows, bytes, done: false };
+        }
+        catch (error) { release(request.cursor); throw error; }
+      }
+      case 'return': release(request.cursor); return undefined;
+      case 'finalize': {
+        for (const [id, cursor] of cursors) if (cursor.statement === request.statement) release(id);
+        statements.delete(request.statement);
+        return undefined;
+      }
+      case 'close': {
+        for (const id of cursors.keys()) release(id);
+        statements.clear();
+        return connection.close();
+      }
+    }
+  };
+  try {
+    connection = await nodeDriver().open(path, options);
+    // Functions cannot cross structured clone. Capture uses the existing
+    // journal path; a live query requires a synchronous connection.
+    parentPort.postMessage(frame('ready', 0, { capabilities: { ...connection.capabilities,
+      sessions: false, userFunctions: false, deterministicIndexableFunctions: false,
+      aggregateFunctions: false, backup: false, worker: true, pooling: false } }));
+    parentPort.on('message', (request) => {
+      try {
+        if (!validRequest(request)) throw new DbRuntimeError('JD2093', 'invalid worker protocol request');
+        if (request.generation !== generation) throw generationFailure(request.generation);
+        const value = dispatch(request);
+        parentPort.postMessage(frame('result', request.id, { value,
+          transaction: request.op === 'close' ? null : transaction() }));
+        if (request.op === 'close') parentPort.close();
+      }
+      catch (error) { parentPort.postMessage(frame('failure', request?.id ?? 0, {
+        error: cloneDriverError(error), transaction: transaction() })); }
+    });
+  }
+  catch (error) {
+    parentPort.postMessage(frame('failure', 0, { error: cloneDriverError(error) }));
+    parentPort.close();
+  }
+}

package/src/drivers/worker-client.js

@@ -0,0 +1,185 @@
+//@ts-check
+/** Shared bounded RPC Connection client for owned SQLite execution hosts. */
+import { finishConnection } from '../driver.js';
+import { sqliteDialect } from '../dialects/sqlite.js';
+import { DbRuntimeError } from '../errors.js';
+import { generationFailure, queueFailure, rowBytes, validResponse, validResult } from './worker-protocol.js';
+
+/** @param {any} worker @param {any} settings @returns {Promise<any>} */
+export async function createWorkerConnection(worker, settings) {
+  const { epoch, options, limits, maxPending, allRows, allBytes, closeMs, startupMs, reopen, hooks = {} } = settings;
+  const pending = new Map();
+  let sequence = 0;
+  let failed = null;
+  let closing = false;
+  let closed = false;
+  let transactionDepth = 0;
+  let closePromise;
+  const metrics = { frames: 0, rows: 0, maxFrameRows: 0, maxFrameBytes: 0, maxPending: 0 };
+  let readyResolve;
+  let readyReject;
+  const ready = new Promise((resolve, reject) => { readyResolve = resolve; readyReject = reject; });
+  const lose = (cause) => {
+    if (failed !== null || closed) return;
+    failed = generationFailure(epoch, transactionDepth > 0, cause);
+    hooks.lost?.(failed, [...pending.values()]);
+    readyReject(failed);
+    for (const request of pending.values()) request.reject(failed);
+    pending.clear();
+  };
+  hooks.control?.({ lose });
+  worker.on('error', lose);
+  worker.on('exit', (code) => { if (!closed) lose(new Error(`worker exited (${code})`)); });
+  worker.on('message', (message) => {
+    if (!validResponse(message, epoch)) { lose(new Error('invalid worker response')); return; }
+    if (message.kind === 'ready') { readyResolve(message.capabilities); return; }
+    if (message.kind === 'failure' && message.id === 0) {
+      readyReject(Object.assign(new Error(message.error.message), message.error)); return;
+    }
+    const request = pending.get(message.id);
+    if (request === undefined) return;
+    pending.delete(message.id);
+    if (message.kind === 'failure') {
+      hooks.failure?.(request.op, request.data, message.transaction);
+      const error = message.error;
+      request.reject(Object.assign(error.code?.startsWith('JD')
+        ? new DbRuntimeError(error.code, error.message) : new Error(error.message), error));
+    }
+    else if (message.kind === 'result' && validResult(request.op, message.value, limits)) {
+      hooks.result?.(request.op, request.data, message.value, message.transaction); request.resolve(message.value);
+    }
+    else { request.reject(generationFailure(epoch, transactionDepth > 0)); lose(new Error('invalid worker response')); }
+  });
+  const timer = setTimeout(() => { lose(new Error('worker startup timed out')); worker.terminate(); }, startupMs);
+  let capabilities;
+  try { capabilities = await ready; }
+  catch (error) {
+    const termination = worker.terminate();
+    if (settings.awaitStartupExit !== false) await termination;
+    else termination.catch(() => {});
+    throw error;
+  }
+  finally { clearTimeout(timer); }
+  const request = (op, data = {}, cleanup = false) => {
+    if (failed !== null) return Promise.reject(failed);
+    if (closed || (closing && !cleanup)) return Promise.reject(new DbRuntimeError('JD2063', 'the worker connection is closing or closed'));
+    if (!cleanup && pending.size >= maxPending)
+      return Promise.reject(queueFailure(`worker request capacity ${maxPending} exceeded`, pending.size));
+    // One return per live cursor and one close have reserved capacity.
+    if (cleanup && pending.size >= maxPending + limits.cursors + 1)
+      return Promise.reject(queueFailure('worker cleanup capacity exceeded', pending.size));
+    const id = ++sequence;
+    return new Promise((resolve, reject) => {
+      pending.set(id, { resolve, reject, op, data });
+      metrics.maxPending = Math.max(metrics.maxPending, pending.size);
+      try { hooks.request?.(op, data); worker.postMessage({ v: 1, generation: epoch, kind: 'request', id, op, ...data }); }
+      catch (error) { pending.delete(id); reject(error); }
+    });
+  };
+  const raw = {
+    closeDrainsIterators: true,
+    exec: (sql) => {
+      if (/^(?:SAVEPOINT|BEGIN)\b/.test(sql)) transactionDepth++;
+      return request('exec', { sql }).then((value) => {
+        if (/^RELEASE\b/.test(sql)) transactionDepth = Math.max(0, transactionDepth - 1);
+        if (/^(?:COMMIT|ROLLBACK(?! TO))\b/.test(sql)) transactionDepth = 0;
+        return value;
+      });
+    },
+    prepare: async (sql, metadata = {}) => {
+      const id = await request('prepare', { sql, ephemeral: metadata.ephemeral === true });
+      const iterate = async (params = []) => {
+        const cursor = await request('iterate', { statement: id, params });
+        let rows = [];
+        let at = 0;
+        let done = false;
+        let returned = false;
+        let pulling = Promise.resolve();
+        const next = async () => {
+          if (failed !== null) throw failed;
+          if (returned) return { done: true, value: undefined };
+          if (at < rows.length) return { done: false, value: rows[at++] };
+          if (done) return { done: true, value: undefined };
+          const batch = await request('next', { cursor, rows: limits.rows, bytes: limits.bytes });
+          metrics.frames++;
+          metrics.rows += batch.rows.length;
+          metrics.maxFrameRows = Math.max(metrics.maxFrameRows, batch.rows.length);
+          metrics.maxFrameBytes = Math.max(metrics.maxFrameBytes, batch.bytes);
+          if (returned) return { done: true, value: undefined };
+          rows = batch.rows;
+          at = 0;
+          done = batch.done;
+          return at < rows.length ? { done: false, value: rows[at++] } : { done: true, value: undefined };
+        };
+        return {
+          next: () => {
+            const result = pulling.then(next);
+            pulling = result.then(() => undefined, () => undefined);
+            return result;
+          },
+          return: async () => {
+            if (returned) return { done: true, value: undefined };
+            returned = true;
+            rows = [];
+            if (!done) await request('return', { cursor }, true);
+            return { done: true, value: undefined };
+          },
+        };
+      };
+      return {
+        run: (params = []) => request('run', { statement: id, params }),
+        get: (params = []) => request('get', { statement: id, params }),
+        iterate,
+        all: async (params = []) => {
+          const iterator = await iterate(params);
+          const rows = [];
+          let bytes = 0;
+          try {
+            for (;;) {
+              const step = await iterator.next();
+              if (step.done) return rows;
+              bytes += rowBytes(step.value);
+              if (rows.length >= allRows || bytes > allBytes)
+                throw new DbRuntimeError('JD2092', `worker all() exceeds its ${allRows} row / ${allBytes} byte bound; use a cursor`);
+              rows.push(step.value);
+            }
+          }
+          finally { await iterator.return(); }
+        },
+      };
+    },
+    close: () => {
+      if (closePromise !== undefined) return closePromise;
+      closing = true;
+      closePromise = new Promise((resolve, reject) => {
+        const timeout = setTimeout(() => {
+          lose(new Error('worker close timed out'));
+          // V8 termination cannot preempt a synchronous native SQLite
+          // call. Fence and detach now; never hold the caller's deadline
+          // hostage to that native call or claim it was rolled back.
+          worker.unref();
+          worker.terminate().catch(() => {});
+          reject(failed);
+        }, closeMs);
+        request('close', {}, true).then(() => {
+          closed = true;
+          clearTimeout(timeout);
+          worker.terminate().then(() => resolve(undefined), reject);
+        }, (error) => {
+          clearTimeout(timeout);
+          worker.unref();
+          worker.terminate().catch(() => {});
+          reject(error);
+        });
+      });
+      return closePromise;
+    },
+  };
+  const connection = finishConnection(raw, sqliteDialect, false, Object.freeze(capabilities), options.queueTimeout);
+  return Object.freeze({ ...connection,
+    get mustQueue() { return connection.mustQueue; },
+    generation: epoch,
+    metrics: () => Object.freeze({ ...metrics, pending: pending.size, generation: epoch, healthy: failed === null && !closed }),
+    restart: async () => { lose(new Error('worker restarted')); await worker.terminate(); return reopen(); },
+  });
+}

package/src/drivers/worker-protocol.js

@@ -4,6 +4,11 @@ import { DbRuntimeError } from '../errors.js';
 import { jsonStringBytes } from '../json-bytes.js';
 
 export const WORKER_PROTOCOL_VERSION = 1;
+export const WORKER_DEFAULTS = Object.freeze({ windowRows: 64, windowBytes: 1048576,
+  maxPending: 64, maxStatements: 1024, maxCursors: 64, allMaxRows: 100000,
+  allMaxBytes: 16777216, closeTimeoutMs: 5000, startupTimeoutMs: 10000 });
+export const PROCESS_DEFAULTS = Object.freeze({ ...WORKER_DEFAULTS, closeTimeoutMs: 1000,
+  maxOwners: 4, timeoutMs: 250, maxRequestBytes: 1048576 });
 const operations = new Set(['exec', 'prepare', 'run', 'get', 'iterate', 'next', 'return', 'finalize', 'close']);
 
 /** @param {number} generation @param {boolean} [transaction] @param {unknown} [cause] */
@@ -73,6 +78,16 @@ export function positiveOption(name, value, fallback) {
   return value;
 }
 
+/** One validation and spelling of shared transport credits.
+ * @param {any} configuration @param {typeof WORKER_DEFAULTS} [defaults] */
+export function workerSettings(configuration, defaults = WORKER_DEFAULTS) {
+  const values = Object.fromEntries(Object.keys(WORKER_DEFAULTS).map((name) =>
+    [name, positiveOption(name, configuration[name], defaults[name])]));
+  return { limits: { rows: values.windowRows, bytes: values.windowBytes, statements: values.maxStatements, cursors: values.maxCursors },
+    maxPending: values.maxPending, allRows: values.allMaxRows, allBytes: values.allMaxBytes,
+    closeMs: values.closeTimeoutMs, startupMs: values.startupTimeoutMs };
+}
+
 /** @param {string} reason @param {number} depth */
 export function queueFailure(reason, depth) {
   return Object.assign(new DbRuntimeError('JD2091', reason), { class: 'queue', retryable: true, depth });

package/src/emit.js

@@ -41,7 +41,7 @@ function compareRefs(pred, read) {
 }
 
 /**
- * @typedef {{ external: string } | { literal: unknown } |
+ * @typedef {{ external: string, nullable?: boolean } | { literal: unknown } |
  *   { derived: { kind: 'bboxAxis', external: string,
  *     axis: 'w' | 's' | 'e' | 'n' } } |
  *   { derived: { kind: 'circleAxis', centre: { external: string } | { literal: unknown },
@@ -659,15 +659,20 @@ export function createEntityPredicateEmitters(dialect, param) {
 
   const emitColumnPred = (aliasSql, pred) => {
     const column = physicalComparable(pred.ref, `${aliasSql}.${q(pred.ref.column)}`, dialect);
+    const presentNull = pred.ref.nullPolicy === 'null';
+    const present = presentNull ? dialect.booleanLiteral(true) : `${column} IS NOT NULL`;
     if (pred.p === 'typeIs') {
       if (pred.types.length === 0)
-        return pred.positive ? `${column} IS NOT NULL` : `${column} IS NULL`;
+        return pred.positive ? present : presentNull ? dialect.booleanLiteral(false) : `${column} IS NULL`;
       if (pred.types[0] === 'null')
-        return pred.positive ? dialect.booleanLiteral(false) : `${column} IS NOT NULL`;
+        return pred.positive ? presentNull ? `${column} IS NULL` : dialect.booleanLiteral(false) : `${column} IS NOT NULL`;
+      if (pred.ref.storage !== 'boolean')
+        return pred.positive ? dialect.booleanLiteral(false) : present;
       const wanted = pred.types[0] === 'true' ? 1 : 0;
       return pred.positive
         ? `(${column} IS NOT NULL AND ${column} = ${param({ literal: wanted })})`
-        : `(${column} IS NOT NULL AND ${column} <> ${param({ literal: wanted })})`;
+        : presentNull ? `${column} IS NOT ${param({ literal: wanted })}`
+          : `(${column} IS NOT NULL AND ${column} <> ${param({ literal: wanted })})`;
     }
     if (pred.p === 'strop') {
       const form = stropForm(dialect, param, column, pred);
@@ -675,6 +680,26 @@ export function createEntityPredicateEmitters(dialect, param) {
     }
     const symbol = { eq: '=', ne: '<>', lt: '<', le: '<=', gt: '>', ge: '>=' }[pred.op];
     if ('ext' in pred.operand) {
+      if (dialect.name === 'sqlite') {
+        // SQL NULL is a present Jaren null only for an explicit null
+        // policy. Keep type guards: SQLite affinity must not turn a
+        // numeric lookup into a string lookup, or invert inequality.
+        const value = () => param({ external: pred.operand.ext, nullable: true });
+        const kind = pred.ref.storage === 'string' ? 'text' : 'number';
+        const guard = () => kind === 'text'
+          ? `${dialect.valueTypeOf(value())} = ${sl('text')}`
+          : pred.ref.storage === 'boolean' ? dialect.booleanLiteral(false)
+            : `${dialect.valueTypeOf(value())} IN ${NUMERIC()}`;
+        if (pred.op === 'eq') {
+          const nullCase = presentNull ? `(${column} IS NULL AND ${value()} IS NULL) OR ` : '';
+          return `(${nullCase}(${column} IS NOT NULL AND ${guard()} AND ${column} = ${value()}))`;
+        }
+        if (pred.op === 'ne') {
+          const nullCase = presentNull ? `(${column} IS NULL AND ${value()} IS NOT NULL) OR ` : '';
+          return `(${nullCase}(${column} IS NOT NULL AND (NOT (${guard()}) OR ${column} <> ${value()})))`;
+        }
+        return `(${column} IS NOT NULL AND ${guard()} AND ${column} ${symbol} ${value()})`;
+      }
       const kind = pred.ref.storage === 'string' ? 'text' : 'number';
       const guard = kind === 'text'
         ? `${dialect.valueTypeOf(externalSlot(pred.operand.ext))} = ${sl('text')}`
@@ -688,7 +713,8 @@ export function createEntityPredicateEmitters(dialect, param) {
     const storageKind = pred.ref.storage === 'string' ? 'string'
       : pred.ref.storage === 'boolean' ? 'boolean' : 'number';
     if (storageKind === 'boolean' || litKind === 'other' || storageKind !== litKind)
-      return pred.op === 'ne' ? `${column} IS NOT NULL` : dialect.booleanLiteral(false);
+      return pred.op === 'ne' ? present : dialect.booleanLiteral(false);
+    if (presentNull && pred.op === 'ne') return `${column} IS NOT ${param({ literal: lit })}`;
     return `(${column} IS NOT NULL AND ${column} ${symbol} ${param({ literal: lit })})`;
   };
 
@@ -875,6 +901,12 @@ export function emitEntityPlan(plan, dialect, physicalOf) {
           ? `CAST(${groupValue(entry.ref)} AS REAL)` : groupValue(entry.ref))} AS ${q(`a${i}`)}`),
       ...group.aggregates.flatMap((entry, i) => numericGroup(entry) ? [`${groupSafe(entry)} AS ${q(`_safe${i}`)}`] : []),
       ...(groupRefs.length ? [`${groupRefs.map(groupValid).join(' AND ')} AS ${q('_valid')}`] : [])].join(', ')
+    : plan.scalarAggregate
+    ? `${dialect.groupAggregate(plan.scalarAggregate.fn, plan.scalarAggregate.ref.type === 'string'
+      ? groupValue(plan.scalarAggregate.ref) : `CAST(${groupValue(plan.scalarAggregate.ref)} AS REAL)`)} AS ${q('value')}, `
+      + `${groupValid(plan.scalarAggregate.ref)} AS ${q('_valid')}, `
+      + `${plan.scalarAggregate.ref.nullPolicy === 'null' ? `COUNT(*) - COUNT(${groupValue(plan.scalarAggregate.ref)})` : '0'} AS ${q('_nulls')}, `
+      + `${numericGroup(plan.scalarAggregate) ? groupSafe(plan.scalarAggregate) : '1'} AS ${q('_safe')}`
     : plan.aggregate === 'count'
     ? `COUNT(*) AS ${q('value')}`
     : plan.project != null

package/src/engine-metadata.js

@@ -0,0 +1,18 @@
+//@ts-check
+/** Inert metadata: inspecting a schema must not load its runtime owners. */
+import { REPLICATION_TABLES } from './replication-tables.js';
+/** Current model document version. */
+export const MODEL_VERSION = '0.1';
+/** Migration receipt table. */
+export const HISTORY_TABLE = '_jaren_migrations';
+/** Change ledger table. */
+export const CHANGES_TABLE = '_jaren_changes';
+/** Change ledger retention state. */
+export const CHANGES_STATE_TABLE = '_jaren_changes_state';
+/** Durable job queue. */
+export const JOBS_TABLE = '_jaren_jobs';
+/** Durable job checkpoints. */
+export const JOB_CHECKPOINTS_TABLE = '_jaren_job_checkpoints';
+/** Tables excluded from model adoption and schema drift comparisons. */
+export const ENGINE_TABLES = new Set([HISTORY_TABLE, CHANGES_TABLE, CHANGES_STATE_TABLE,
+  JOBS_TABLE, JOB_CHECKPOINTS_TABLE, ...Object.values(REPLICATION_TABLES)]);

package/src/errors.js

@@ -112,6 +112,7 @@ export const DB_CODES = Object.freeze({
   JD2094: 'the durable snapshot failed and the connection is invalid',
   JD2095: 'the trusted SQL or synchronous transaction authority was refused',
   JD2096: 'a persistence invariant rejected the mutation',
+  JD2097: 'the supervised operation was cancelled or exceeded its response deadline',
 });
 
 /**

package/src/index.js

@@ -66,7 +66,7 @@ export {
   applyMandatoryPredicate, applyRowBound,
 } from './profile.js';
 export { translatePatch } from './patch-sql.js';
-export { normalizeEntities, explainMapping, relationTables } from './model.js';
+export { normalizeEntities, explainMapping, compileEntityModel, relationTables } from './model.js';
 export { planEntity, planJoinTable } from './ddl.js';
 export { entityCore } from './entity.js';
 export { entityEmitModel } from './emit-model.js';
@@ -103,3 +103,6 @@ export { REPLICATION_VERSION, REPLICATION_DEFAULTS, normalizeFrontier,
 
 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';

package/src/introspect.js

@@ -30,8 +30,7 @@
 import { chain } from './driver.js';
 import { DbCompileError } from './errors.js';
 import { KEY_COLUMN, DOC_COLUMN } from './ddl.js';
-import { MODEL_VERSION } from './store.js';
-import { ENGINE_TABLES } from './migrate.js';
+import { MODEL_VERSION, ENGINE_TABLES } from './engine-metadata.js';
 import { registeredName, expressionMembers } from './expression.js';
 
 /**

package/src/jobs.js

@@ -1,4 +1,6 @@
 //@ts-check
+import { JOBS_TABLE, JOB_CHECKPOINTS_TABLE } from './engine-metadata.js';
+export { JOBS_TABLE, JOB_CHECKPOINTS_TABLE };
 /**
  * @file The durable job queue (JOBS-FORMAT): enqueue, the
  * single-statement guarded claim (§3 — one statement is one
@@ -44,8 +46,8 @@ import { DbCompileError, DbRuntimeError, wrapDriverError } from './errors.js';
 import { createCursor, rowClassOf, PAGE_LIMIT_DEFAULT } from './cursor.js';
 import { refuseCancelled } from './cancellation.js';
 
-export const JOBS_TABLE = '_jaren_jobs';
-export const JOB_CHECKPOINTS_TABLE = '_jaren_job_checkpoints';
+
+
 
 /** §4 defaults, all overridable per worker. */
 export const JOB_DEFAULTS = Object.freeze({

package/src/migrate.js

@@ -34,9 +34,8 @@ import { chain, toPromise } from './driver.js';
 import { normalizeModel } from './store.js';
 import { planQuery } from './plan.js';
 import { createQueryEngine, createQueryState } from './query.js';
-import { CHANGES_TABLE, CHANGES_STATE_TABLE } from './capture.js';
-import { JOBS_TABLE, JOB_CHECKPOINTS_TABLE } from './jobs.js';
-import { REPLICATION_TABLES } from './replication-tables.js';
+import { HISTORY_TABLE, ENGINE_TABLES } from './engine-metadata.js';
+export { HISTORY_TABLE, ENGINE_TABLES };
 import { planCollection, verifyShape, planEntity, planJoinTable } from './ddl.js';
 import { normalizeEntities, explainMapping } from './model.js';
 import { derivedValue, memberAt, registerDeriveFunctions } from './derive.js';
@@ -74,17 +73,6 @@ function mappingFor(connection, expressions = undefined) {
   };
 }
 
-/** The history table name (outside the model's identifier namespace
- * conventions on purpose — a collection cannot collide with it). */
-export const HISTORY_TABLE = '_jaren_migrations';
-/** The tables the engine owns beside a model's: never a shape-drift finding. */
-/** The tables this package owns. A model never declared one, so one
- * found in a database is the engine's own bookkeeping rather than
- * anybody's drift — the drift check skips them and the introspector
- * does not derive them. */
-export const ENGINE_TABLES = new Set([HISTORY_TABLE, CHANGES_TABLE, CHANGES_STATE_TABLE,
-  JOBS_TABLE, JOB_CHECKPOINTS_TABLE, ...Object.values(REPLICATION_TABLES)]);
-
 /**
  * The signature-grade identity of a model SHAPE.
  * @param {any} model - A jaren-model document
@@ -198,8 +186,16 @@ export function planMigration(fromModel, toModel, options = undefined) {
   const dialect = options?.dialect ?? null;
   if (dialect === null || typeof dialect !== 'object')
     throw new TypeError('planMigration needs { dialect } (the store dialect renders the DDL)');
-  if ([fromModel, toModel].some((m) => Object.values(m.entities ?? {}).some((e) => e.physical !== undefined)))
-    throw refuse('JD0021', 'column layouts require planPhysicalMigration with explicit preservation dispositions');
+  if ([fromModel, toModel].some((m) => Object.values(m.entities ?? {}).some((e) => e.physical !== undefined))) {
+    normalizeEntities(fromModel);
+    normalizeEntities(toModel);
+    if (canonicalizeJson(fromModel) !== canonicalizeJson(toModel))
+      throw refuse('JD0021', 'changed column layouts require planTableMigration on the open connection or planPhysicalMigration with explicit preservation dispositions');
+    return { migration: { $migration: MIGRATION_VERSION,
+      id: options?.id ?? `to-${shapeHash(toModel).slice(0, 8)}`,
+      from: shapeHash(fromModel), to: shapeHash(toModel), steps: [] },
+    report: { renamed: [], added: [], removed: [], schemaChanged: [], drafts: [], destructive: false } };
+  }
   const mapping = { derived: options?.derived ?? 'virtual', rtree: options?.rtree !== false,
     // a model that declares an index EXPRESSION resolves its functions
     // here too: a plan is DDL, and DDL over a function this planner was

package/src/model-api.js

@@ -0,0 +1,4 @@
+//@ts-check
+/** Model metadata and read-only schema inspection without opening a store. */
+export { normalizeEntities, explainMapping, compileEntityModel, relationTables } from './model.js';
+export { readSchema, introspectModel, INTROSPECT_CODES } from './introspect.js';

package/src/model.js

@@ -557,7 +557,19 @@ export function relationTables(entities) {
  * @returns {any}
  */
 export function explainMapping(model) {
+  return mappingOf(model, normalizeEntities(model));
+}
+
+/** Normalize and map once for lightweight engines sharing model metadata.
+ * No process-global cache retains the model or any connection.
+ * @param {any} model @returns {{entities:Map<string,any>,mapping:any}} */
+export function compileEntityModel(model) {
   const entities = normalizeEntities(model);
+  return { entities, mapping: mappingOf(model, entities) };
+}
+
+/** @param {any} model @param {Map<string,any>} entities @returns {any} */
+function mappingOf(model, entities) {
   /** @type {any} */
   const mapping = { entities: {}, joinTables: {} };