@jarenjs/db 0.75.0 → 0.83.2

package/src/store.js

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

package/src/tracker.js

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

package/src/window.js

@@ -100,6 +100,7 @@ export function createSortedWindow(terms, limit) {
   return {
     compare,
     size: () => entries.length,
+    clear: () => { entries.length = 0; byToken.clear(); },
     /** The visible slice: the first `limit` entries (all, unbounded). */
     visible: () => (limit === null ? [...entries] : entries.slice(0, limit)),
     /**

package/types/index.d.ts

@@ -291,6 +291,8 @@ export interface LoadContinuation {
  * write may change; `'live'` (the default) reports the truth in
  * `snapshot`. */
 export interface PageOptions<C = LoadContinuation> extends EntityCursorOptions {
+  /** False admits no lookahead row; a full page reports hasMore: null. */
+  lookahead?: boolean;
   limit?: number;
   after?: C;
   maxBytes?: number | null;
@@ -305,8 +307,11 @@ export interface PageOptions<C = LoadContinuation> extends EntityCursorOptions {
 export interface Page<T, C = LoadContinuation> {
   readonly items: T[];
   readonly continuation: C | null;
-  readonly hasMore: boolean;
+  readonly hasMore: boolean | null;
   readonly snapshot: boolean;
+  /** Present with lookahead:false; includes a row consumed at the byte boundary.
+   * Bytes count the serialized payloads consumed, excluding array punctuation. */
+  readonly work?: { readonly rows: number; readonly bytes: number };
 }
 
 export interface LoadExplanation {
@@ -594,12 +599,26 @@ export interface UntrackedReads<T = unknown> {
   load(spec?: LoadSpec): Promise<T[]>;
 }
 
+/** Closed native mutation forms over declared SQLite column layouts. */
+export type EntityMutation = {
+  returning?: readonly string[]; maxRows?: number; maxBytes?: number;
+} & ({ op: 'update'; key: EntityKeyArg; expectedRevision?: number; set: Readonly<Record<string, unknown>> }
+  | { op: 'upsert'; values: Readonly<Record<string, unknown>>; conflict: readonly string[]; update: readonly string[] }
+  | { op: 'insert-select'; source: string; where?: unknown; select: Readonly<Record<string, string | { $literal: unknown }>>;
+      conflict: readonly string[]; onConflict: 'nothing' });
+export interface MutationResult {
+  readonly mode: 'native'; readonly affected: number; readonly rows: ReadonlyArray<Readonly<Record<string, unknown>>>;
+  readonly admitted: { readonly statements: number; readonly rows: number; readonly bytes: number };
+}
+
 export interface EntitySet<T = unknown, I = unknown> {
   /** The provider phantom: a chain over this set infers its item type. */
   readonly __item?: T;
   create(doc: I): Promise<Readonly<T>>;
   get(key: EntityKeyArg): Promise<Readonly<T> | undefined>;
   update(key: EntityKeyArg, changes: Partial<T>): Promise<Readonly<T>>;
+  /** One bounded native SQLite column mutation; unsupported shapes refuse JD0038. */
+  mutate(document: EntityMutation): Promise<MutationResult>;
   delete(key: EntityKeyArg): Promise<boolean>;
   load(spec?: LoadSpec): Promise<ReadonlyArray<Readonly<T>>>;
   /** The graph cursor: one root graph per pull, its includes attached
@@ -695,7 +714,7 @@ export interface SyncStore {
    * the consumer's words; the handle's writes take it and reads answer it. */
   collection<T = unknown>(name: string): SyncCollection<T>;
   entity(name: string): SyncEntitySet;
-  transaction<R>(fn: (store: TransactionStore) => R): R;
+  transaction<R>(fn: (store: TransactionStore) => R, options?: { mode?: 'deferred' | 'immediate' }): R;
   execute?<R = unknown>(document: unknown, options?: ExecuteOptions): SequenceResult<R>;
   explain?(document: unknown, options?: ExecuteOptions): unknown;
   /** The entity roots this store-level provider serves (present with
@@ -813,7 +832,7 @@ export interface TransactionScopeOptions {
    * upgrade `SQLITE_BUSY` the busy handler cannot retry — what a claim
    * needs under concurrent writers; `'deferred'` (the default) is the
    * savepoint as always. A nested `tx.transaction()` is a savepoint
-   * whichever mode the root chose; the synchronous twin has no mode. */
+   * whichever mode the root chose; the root synchronous twin accepts the same mode. */
   mode?: 'deferred' | 'immediate';
 }
 
@@ -845,6 +864,7 @@ export interface SyncSavepointController {
 /** The synchronous surface a transaction view carries: the store's,
  * plus the transaction-only savepoint group. */
 export interface TransactionSyncStore extends SyncStore {
+  readonly sql: TrustedSyncSql;
   readonly savepoints: SyncSavepointController;
 }
 
@@ -871,6 +891,7 @@ export interface TransactionStore extends Omit<Store,
   | 'jobs' | 'replication'> {
   /** The transactional outbox (JOBS-FORMAT §3): no administration here —
    * an admin operation is a root call. */
+  readonly sql: TrustedSql;
   readonly jobs?: JobsApi;
   transaction<R>(fn: (store: TransactionStore) => R | Promise<R>): Promise<Awaited<R>>;
   /** Named partial rollback over the transaction's one savepoint stack
@@ -1051,6 +1072,8 @@ export interface LiveBounds {
 }
 
 export interface OpenStoreOptions {
+  /** Verify existing objects and create no schema or infrastructure. */
+  adopt?: boolean;
   replication?: ReplicationOptions;
   driver: Driver;
   path?: string;
@@ -1775,6 +1798,8 @@ export interface JobWorker {
 }
 
 export interface JobWorkerOptions {
+  /** Admit only when current durable effect policy returns true. */
+  effectSafety?: (job: ClaimedJob, context: { lease(): JobLease; signal: AbortSignal }) => boolean | Promise<boolean>;
   /**
    * `checkpoints` is bound to THIS attempt and follows its current
    * lease, so a renewal does not strand it. `signal` aborts for either
@@ -1784,6 +1809,9 @@ export interface JobWorkerOptions {
    */
   handlers: Record<string, (payload: unknown, context: {
     job: ClaimedJob;
+    lease(): JobLease;
+    /** Pause as cancelled, permitting explicit requeue for reconciliation. */
+    pause(): Promise<boolean>;
     checkpoints: { load(runId: string): unknown;
       save(runId: string, nodeId: string, value: unknown): unknown;
       complete(runId: string, result: unknown): unknown };
@@ -1824,6 +1852,8 @@ export interface JobsApi {
    * expired), never a silent `false`.
    */
   renew(lease: JobLease, options?: { leaseMs?: number }): Promise<JobLease>;
+  /** Check the existing token/expiry fence without writing. */
+  assertLease(lease: JobLease): Promise<boolean>;
   /** Settle the attempt this lease holds. `true`, or one of the three
    * coded refusals above — a caller that cannot tell "already done"
    * from "you are stale" guesses, and guesses wrong. */
@@ -1899,6 +1929,7 @@ export interface JobsOptions {
 }
 
 export declare function createDagJobRunner(store: Store, options: {
+  effectSafety?: JobWorkerOptions['effectSafety'];
   compileDag: Function;
   documents: Record<string, unknown>;
   tasks?: Record<string, Function | { run: Function; version?: string; taskVersions?: Record<string, string> }>;
@@ -1982,3 +2013,27 @@ export interface ReplicationSnapshot {
   receipts: ReplicationEnvelope[];
 }
 export declare function normalizeReplicationSnapshot(document: unknown): ReplicationSnapshot;
+
+/** Trusted prepared SQL; statements belong to one transaction scope. */
+export interface TrustedSql {
+  prepare(sql: string, options: { access: 'read' | 'write'; affects?: readonly string[] }): {
+    run(params?: readonly unknown[]): unknown;
+    get(params?: readonly unknown[]): Record<string, any> | undefined | Promise<Record<string, any> | undefined>;
+    all(params?: readonly unknown[]): Record<string, any>[] | Promise<Record<string, any>[]>;
+    close(): void;
+  };
+}
+export interface TrustedSyncSql {
+  prepare(sql: string, options: { access: 'read' | 'write'; affects?: readonly string[] }): {
+    run(params?: readonly unknown[]): unknown;
+    get(params?: readonly unknown[]): Record<string, any> | undefined;
+    all(params?: readonly unknown[]): Record<string, any>[];
+    close(): void;
+  };
+}
+export declare function planInvariants(model: unknown, options: { dialect: Dialect }): {
+  type: 'trigger'; name: string; owner: string; rule: string; sql: string;
+}[];
+export declare function planPhysicalMigration(connection: unknown, fromModel: unknown, toModel: unknown,
+  options: { id: string; steps: readonly unknown[]; dispositions: Readonly<Record<string, 'preserve' | 'replace' | 'drop'>>;
+    assertions?: readonly { sql: string; params?: readonly unknown[]; expected: readonly unknown[] }[] }): unknown;

package/types/search.d.ts

@@ -0,0 +1,20 @@
+import type { Store } from './index.js';
+import type { LexicalDefinition } from '@jarenjs/core/search';
+
+export interface SearchStorage {
+  load(id: string): Promise<string | null>;
+  save(id: string, payload: string): Promise<{ changes: number }>;
+}
+export declare function createDbSearchStorage(store: Store, collection: string, options?: { maxBytes?: number }): SearchStorage;
+export interface DbSearch {
+  readonly sourceRevision: string;
+  refresh(): Promise<any>;
+  search(text: string, request?: Record<string, unknown>): Promise<any>;
+  row(id: string, revision: string): any;
+  subscribe(observer: (event: any) => void): () => void;
+  explain(): { mode: string; nativeFTS: boolean; reason: string; maxRows: number; maxBytes: number; capture: string; externalChanges: string };
+  stats(): any;
+  dispose(): Promise<void>;
+}
+export declare function createDbSearch(store: Store, entity: string, definition: LexicalDefinition,
+  options: { source: string; maxRows?: number; maxBytes?: number; storage?: SearchStorage; snapshotKey?: string }): Promise<DbSearch>;

package/types/typed.d.ts

@@ -101,6 +101,7 @@ export interface TypedUntrackedReads<E extends MetaMap<E>, M extends EntityMeta>
 }
 
 export interface TypedEntitySet<E extends MetaMap<E>, M extends EntityMeta> {
+  mutate(document: import('./index.js').EntityMutation): Promise<import('./index.js').MutationResult>;
   /** The provider phantom: `from(typed.entity('User'))` infers `User`
    * without a cast. */
   readonly __item?: M['doc'];