@jarenjs/db 0.75.0 → 0.83.3

package/src/query.js

@@ -31,6 +31,8 @@
  * the whole document runs over them.
  */
 
+import { physicalSelection, columnCodec } from './physical.js';
+
 import { createSemanticCache } from '@jarenjs/core/cache';
 import { analyzeQuery } from '@jarenjs/json/query';
 
@@ -292,7 +294,11 @@ function segmentsOf(ref) {
  * @param {string} suffix
  * @returns {any[]} the item, or nothing where the member is absent
  */
-function leafItems(row, suffix) {
+function leafItems(row, suffix, column = undefined) {
+  if (column !== undefined) {
+    const value = columnCodec(column).decode(row[`v${suffix}`]);
+    return value === undefined ? [] : [value];
+  }
   const type = row[`t${suffix}`];
   if (type === null || type === undefined) return [];
   const value = row[`v${suffix}`];
@@ -321,7 +327,8 @@ function leafItems(row, suffix) {
 function projectedTreeItems(project, row, prefix = '') {
   const build = (node) => {
     if (node.p === 'lit') return [node.value];
-    if (node.p === 'leaf') return leafItems(row, `${prefix}${node.index}`);
+    if (node.p === 'leaf') return leafItems(row, `${prefix}${node.index}`,
+      project.leaves[node.index].ref?.codecColumn);
     if (node.p === 'object') {
       /** @type {any} */
       const out = {};
@@ -338,6 +345,47 @@ function projectedTreeItems(project, row, prefix = '') {
   return build(project.tree);
 }
 
+  /**
+   * The items a GENERAL grouping answers: one per group row, built from
+   * the group's keys and aggregates through the plan's own tree. A key
+   * comes back with its JSON type beside it, so an absent key leaves
+   * its member out exactly as the object constructor does; an aggregate
+   * over no values follows the mapping the plan recorded — `0` for a
+   * count or a sum, the empty sequence for the other three, which is
+   * the ENGINE's answer, not SQL's `NULL`.
+   * @param {any} entry
+   * @param {any[]} rows
+   * @returns {any[]}
+   */
+  function groupItems(group, rows) {
+    const aggregateItems = (row, index) => {
+      const value = row[`a${index}`] ?? null;
+      const empty = group.aggregates[index].empty;
+      if (value === null) return empty === 'omit' ? [] : [empty === 'zero' ? 0 : null];
+      const aggregate = group.aggregates[index];
+      return [aggregate.ref?.codecColumn && ['min', 'max'].includes(aggregate.fn)
+        ? columnCodec(aggregate.ref.codecColumn).decode(value) : value];
+    };
+    const build = (node, row) => {
+      if (node.p === 'lit') return [node.value];
+      if (node.p === 'key') return leafItems(row, `k${node.index}`, group.keys[node.index].ref.codecColumn);
+      if (node.p === 'agg') return aggregateItems(row, node.index);
+      if (node.p === 'object') {
+        /** @type {any} */
+        const out = {};
+        for (const member of node.members) {
+          const items = build(member.node, row);
+          if (items.length > 0) out[member.name] = items[0];
+        }
+        return [out];
+      }
+      const items = [];
+      for (const item of node.items) items.push(...build(item, row));
+      return [items];
+    };
+    return rows.flatMap((row) => build(group.tree, row));
+  }
+
 /**
  * The query engine for one collection.
  * @param {{ connection: any, state: any, collection: any,
@@ -517,7 +565,6 @@ export function createQueryEngine(context) {
           : { ...planned.series, mode: 'engine', index: null, prefix: [] },
       };
     }
-
     if (profile !== null) {
       // the member allow-list: what the caller may OBTAIN, checked
       // against every member path the document references, before a
@@ -849,46 +896,6 @@ export function createQueryEngine(context) {
     return items;
   };
 
-  /**
-   * The items a GENERAL grouping answers: one per group row, built from
-   * the group's keys and aggregates through the plan's own tree. A key
-   * comes back with its JSON type beside it, so an absent key leaves
-   * its member out exactly as the object constructor does; an aggregate
-   * over no values follows the mapping the plan recorded — `0` for a
-   * count or a sum, the empty sequence for the other three, which is
-   * the ENGINE's answer, not SQL's `NULL`.
-   * @param {any} entry
-   * @param {any[]} rows
-   * @returns {any[]}
-   */
-  const groupItems = (entry, rows) => {
-    const group = entry.plan.group;
-    const aggregateItems = (row, index) => {
-      const value = row[`a${index}`] ?? null;
-      const empty = group.aggregates[index].empty;
-      if (value === null) return empty === 'omit' ? [] : [empty === 'zero' ? 0 : null];
-      return [value];
-    };
-    const build = (node, row) => {
-      if (node.p === 'lit') return [node.value];
-      if (node.p === 'key') return leafItems(row, `k${node.index}`);
-      if (node.p === 'agg') return aggregateItems(row, node.index);
-      if (node.p === 'object') {
-        /** @type {any} */
-        const out = {};
-        for (const member of node.members) {
-          const items = build(member.node, row);
-          if (items.length > 0) out[member.name] = items[0];
-        }
-        return [out];
-      }
-      const items = [];
-      for (const item of node.items) items.push(...build(item, row));
-      return [items];
-    };
-    return rows.flatMap((row) => build(group.tree, row));
-  };
-
   /** How many ITEMS an engine result carries (its own shape rule). */
   const itemCount = (answer) => (answer === undefined ? 0
     : Array.isArray(answer) ? answer.length : 1);
@@ -1111,7 +1118,7 @@ export function createQueryEngine(context) {
         }
         if (entry.plan.group !== null) {
           return chain(runAll(entry, externals, statement), (rows) =>
-            answerOf(entry, groupItems(entry, checkRowBound(entry, rows))));
+            answerOf(entry, groupItems(entry.plan.group, checkRowBound(entry, rows))));
         }
         if (entry.plan.bucket !== null) {
           return chain(runAll(entry, externals, statement), (rows) => {
@@ -1213,7 +1220,7 @@ export function createQueryEngine(context) {
       return createCursor({ ...classified, signal, deadline, now: state.now, wrap: driverWrap,
         materialize: () => chain(guardScan(entry), () => chain(statementOf(entry), (statement) =>
           chain(runAll(entry, externals, statement), (rows) =>
-            groupItems(entry, checkRowBound(entry, rows))))) });
+            groupItems(entry.plan.group, checkRowBound(entry, rows))))) });
     }
     if (entry.plan.bucket !== null) {
       // a native bucket is a barrier: the groups are the answer
@@ -1599,7 +1606,11 @@ export function createEntityQueryEngine(context) {
   const q = dialect.quoteIdentifier;
   const physicalOf = (name) => ({ table: mapping.entities[name].table,
     // a join-table root has no document column of its own (§10.7)
-    document: mapping.entities[name].document !== false });
+    document: mapping.entities[name].document !== false,
+    ...(entities.get(name)?.physical == null ? {} : {
+      mapping: mapping.entities[name],
+      keys: mapping.entities[name].keys.map((key) => mapping.entities[name].columns.find((c) => c.name === key).physical),
+    }) });
   // the relation tables of every root this engine serves (§10.1): the
   // engine is the scope every entity set of the store shares, so a
   // producer holding one set can follow a hop into another root
@@ -1642,6 +1653,10 @@ export function createEntityQueryEngine(context) {
       planned = { ...planned, mode: 'set', plan: null,
         reasons: [{ construct: 'pushdown', reason: BIND_REASONS.pushdown }] };
     }
+    if (planned.plan?.group && dialect.name !== 'sqlite') {
+      planned = { ...planned, mode: 'set', plan: null,
+        reasons: [{ construct: '$groupby', reason: 'entity grouping runtime guards are qualified for SQLite' }] };
+    }
     const docPath = entities.get(planned.referenced[0])?.docPath;
     // the profile, applied exactly as on a collection (MODEL-FORMAT §8):
     // the roots a document may read, the references it may make, the
@@ -1700,6 +1715,8 @@ export function createEntityQueryEngine(context) {
       residualLimits: profile === null ? undefined : profile.limits,
       needsScanCheck: profile !== null && profile.refuseFullScan === true,
       scanChecked: false,
+      admitted: null,
+      runtimeReason: null,
     };
     if (planned.mode === 'native') {
       let plan = planned.plan;
@@ -1709,6 +1726,9 @@ export function createEntityQueryEngine(context) {
           const predicate = mandatory.get(binding.entity);
           return predicate === undefined ? entry : { ...entry, filter: conjoin(entry.filter, predicate) };
         }) };
+        if (plan.project) plan = { ...plan, project: { ...plan.project, leaves: plan.project.leaves.map((leaf) =>
+          leaf.count && mandatory.has(leaf.count.entity) ? { ...leaf, count: { ...leaf.count,
+            filter: conjoin(leaf.count.filter, mandatory.get(leaf.count.entity)) } } : leaf) } };
       }
       if (entry.rowBound !== null && plan.aggregate === null) {
         const cap = entry.rowBound + 1;
@@ -1734,6 +1754,13 @@ export function createEntityQueryEngine(context) {
     }
     return rows;
   };
+  const admittedRows = (entry, rows) => {
+    entry.admitted ??= { statements: 0, rows: 0, bytes: 0 };
+    entry.admitted.statements++;
+    entry.admitted.rows += rows.length;
+    entry.admitted.bytes += utf8Length(JSON.stringify(rows));
+    return rows;
+  };
   /** One merged entity document against the profile's byte bound
    * (JD2076): measured after the merge, because the mapped scalars live
    * in columns and the row's own JSON text holds only the rest. */
@@ -1789,11 +1816,15 @@ export function createEntityQueryEngine(context) {
         const limit = entry.rowBound === null ? '' : ` ${dialect.limitClause(entry.rowBound + 1, undefined)}`;
         return {
           name,
-          sql: `SELECT ${q('t')}.*, ${mapping.entities[name].document === false
-            ? dialect.stringLiteral('{}')
-            : dialect.jsonText(`${q('t')}.${q('doc')}`)} AS ${q('__doc')} `
+          sql: `SELECT ${entities.get(name)?.physical != null ? physicalSelection(mapping.entities[name], dialect, `${q('t')}.`)
+            : `${q('t')}.*, ${mapping.entities[name].document === false ? dialect.stringLiteral('{}')
+              : dialect.jsonText(`${q('t')}.${q('doc')}`)} AS ${q('__doc')}`} `
             + `FROM ${q(mapping.entities[name].table)} AS ${q('t')}${where} `
-            + `ORDER BY ${q('t')}.${dialect.rowIdentity()}${limit}`,
+            + `ORDER BY ${entities.get(name)?.physical != null ? mapping.entities[name].keys.map((k) => {
+              const column = mapping.entities[name].columns.find((c) => c.name === k);
+              const value = `${q('t')}.${q(column.physical)}`;
+              return column.codec === 'text' ? dialect.codepoint(value) : value;
+            }).join(', ') : `${q('t')}.${dialect.rowIdentity()}`}${limit}`,
           params: slots.map((slot) => slot.literal),
           statement: null,
         };
@@ -1807,6 +1838,7 @@ export function createEntityQueryEngine(context) {
       if (fetcher.statement === null) fetcher.statement = connection.prepare(fetcher.sql, { readOnly: true });
       return chain(fetcher.statement, (statement) =>
         chain(statement.all(fetcher.params), (rows) => {
+          admittedRows(entry, rows);
           root[fetcher.name] = checkRows(entry, rows, fetcher.name).map((row) =>
             checkBytes(entry, mergeEntityRow(mapping.entities[fetcher.name], row, '__doc'), fetcher.name));
           return next(i + 1);
@@ -1825,6 +1857,8 @@ export function createEntityQueryEngine(context) {
     requireCallable(options, state.now);
     const { externals, strict, pushdown, profile } = callState(options);
     const entry = entryFor(document, pushdown, profile);
+    entry.admitted = { statements: 0, rows: 0, bytes: 0 };
+    entry.runtimeReason = null;
     if (entry.planned.mode !== 'native') {
       if (strict) {
         const forcing = entry.planned.reasons[0];
@@ -1844,12 +1878,30 @@ export function createEntityQueryEngine(context) {
     if (entry.statement === null) entry.statement = connection.prepare(entry.sql, { readOnly: true });
     return chain(guardEntityScan(entry), () => chain(entry.statement, (statement) => {
       if (entry.planned.plan.aggregate === 'count')
-        return chain(statement.get(params), (row) => wrapValue(entry, row?.value ?? 0));
+        return chain(statement.get(params), (row) => { admittedRows(entry, row ? [row] : []); return wrapValue(entry, row?.value ?? 0); });
       return chain(statement.all(params), (rows) => {
+        admittedRows(entry, rows);
+        checkRows(entry, rows, entry.planned.referenced[0]);
+        if (entry.planned.plan.group) {
+          const group = entry.planned.plan.group;
+          if (rows.some((row) => row._valid === 0))
+            throw new DbRuntimeError('JD2003', 'a grouped physical column refuses a lossy or invalid value');
+          if (rows.some((row) => group.aggregates.some((aggregate, i) =>
+            ['sum', 'avg'].includes(aggregate.fn) && row[`_safe${i}`] !== 1))) {
+            entry.runtimeReason = { construct: '$groupby', reason: 'integer accumulation exceeded its runtime exactness bound' };
+            if (strict) throw new DbCompileError('JD0010', entry.runtimeReason.reason);
+            if (profile?.refuseFullScan) throw profileEntityRefusal(
+              'the profile refuses the decoded scan required by the integer accumulation bound', '/entities');
+            return runResidual(entry, document, externals);
+          }
+          return answerOf(entry, groupItems(group, rows)
+            .map((row) => checkBytes(entry, row, entry.planned.referenced[0])));
+        }
         const project = entry.planned.plan.project;
         if (project != null) {
           return answerOf(entry,
-            rows.flatMap((row) => projectedTreeItems(project, row, 'p')));
+            rows.flatMap((row) => projectedTreeItems(project, row, 'p'))
+              .map((row) => checkBytes(entry, row, entry.planned.referenced[0])));
         }
         const retEntity = entry.planned.plan.bindings
           .find((binding) => binding.name === entry.planned.plan.ret).entity;
@@ -1900,6 +1952,8 @@ export function createEntityQueryEngine(context) {
     if (entry.planned.wrapped === true) {
       return buffered({ construct: 'window', reason: BIND_REASONS.wrappedWindow });
     }
+    if (entry.planned.plan?.group)
+      return buffered({ construct: '$groupby', reason: 'group results are validated and reconstructed together' });
     if (entry.planned.mode !== 'native') {
       const forcing = entry.planned.reasons[0]
         ?? { construct: 'residual', reason: BIND_REASONS.untranslated };
@@ -1947,14 +2001,17 @@ export function createEntityQueryEngine(context) {
     refuseBuffered(options, classified, entities.get(entry.planned.retEntity ?? '')?.docPath);
     const signal = options?.signal;
     const deadline = options?.deadline;
-    if (entry.planned.wrapped === true) {
+    if (entry.planned.wrapped === true || entry.planned.plan?.group) {
       return cursorFactory({ ...classified, signal, deadline, now: state.now, wrap: driverWrap,
-        materialize: () => chain(execute(document, options), (value) => [value]) });
+        materialize: () => chain(execute(document, options), (value) => entry.planned.wrapped === true
+          ? [value] : value === undefined ? [] : Array.isArray(value) ? value : [value]) });
     }
     if (classified.barrier !== null) {
       return cursorFactory({ ...classified, signal, deadline, now: state.now, wrap: driverWrap,
-        materialize: () => chain(fetchRoot(entry), (root) =>
-          packedResidualOf(entry, document)(root, externals).map(each)) });
+        materialize: () => {
+          entry.admitted = { statements: 0, rows: 0, bytes: 0 };
+          return chain(fetchRoot(entry), (root) => packedResidualOf(entry, document)(root, externals).map(each));
+        } });
     }
     const params = entry.slots.map((slot) => slotValue(slot, externals));
     // the statement is prepared by the first PULL, not here: a root
@@ -1967,7 +2024,11 @@ export function createEntityQueryEngine(context) {
     if (entry.planned.plan.aggregate === 'count') {
       return cursorFactory({ ...classified, signal, deadline, now: state.now, wrap: driverWrap,
         materialize: () => chain(guardEntityScan(entry), () => chain(prepared(), (statement) =>
-          chain(statement.get(params), (row) => [row?.value ?? 0]))) });
+          chain(statement.get(params), (row) => {
+            entry.admitted = { statements: 0, rows: 0, bytes: 0 };
+            admittedRows(entry, row ? [row] : []);
+            return [row?.value ?? 0];
+          }))) });
     }
     const rowEntity = entry.planned.plan.ret === null ? null
       : entry.planned.plan.bindings
@@ -1976,17 +2037,23 @@ export function createEntityQueryEngine(context) {
     // a statement of its own per cursor: two live iterators over one
     // cached statement invalidate each other at the driver
     return cursorFactory({ ...classified, signal, deadline, now: state.now, wrap: driverWrap,
-      open: () => chain(guardEntityScan(entry), () => chain(connection.prepare(entry.sql, { readOnly: true, ephemeral: true }),
-        (statement) => statement.iterate(params))),
+      open: () => {
+        entry.admitted = { statements: 1, rows: 0, bytes: 2 };
+        return chain(guardEntityScan(entry), () => chain(connection.prepare(entry.sql, { readOnly: true, ephemeral: true }),
+          (statement) => statement.iterate(params)));
+      },
       items: (row) => {
         pulledRows++;
+        entry.admitted.bytes += utf8Length(JSON.stringify(row)) + (entry.admitted.rows ? 1 : 0);
+        entry.admitted.rows++;
         if (entry.rowBound !== null && pulledRows > entry.rowBound) {
           throw new DbRuntimeError('JD2007',
             `the fetch crossed the profile's maxRows bound of ${entry.rowBound}`,
             { docPath: entities.get(rowEntity)?.docPath, collection: rowEntity });
         }
         const project = entry.planned.plan.project;
-        if (project != null) return projectedTreeItems(project, row, 'p');
+        if (project != null) return projectedTreeItems(project, row, 'p')
+          .map((item) => checkBytes(entry, item, entry.planned.referenced[0]));
         return [each(checkBytes(entry, mergeEntityRow(mapping.entities[rowEntity], row, '__doc'), rowEntity))];
       } });
   };
@@ -2001,21 +2068,23 @@ export function createEntityQueryEngine(context) {
     const classified = cursorClass(entry, options?.externals ?? null);
     const diverted = entry.planned.mode === 'native' && classified.barrier !== null
       && classified.barrier.construct === 'external';
-    const mode = diverted ? 'set' : entry.planned.mode;
-    const reasons = diverted && classified.barrier !== null
+    const runtime = entry.runtimeReason;
+    const mode = diverted || runtime ? 'set' : entry.planned.mode;
+    const reasons = runtime ? [runtime, ...entry.planned.reasons] : diverted && classified.barrier !== null
       ? [classified.barrier, ...entry.planned.reasons] : entry.planned.reasons;
     const base = {
       mode,
       streaming: classified.streaming,
-      barrier: classified.barrier,
+      barrier: runtime ?? classified.barrier,
       budget: budgetOf(profile, profileSource, connection.capabilities),
       wrapped: entry.planned.wrapped === true,
       referenced: [...entry.planned.referenced],
+      admitted: entry.admitted === null ? null : { ...entry.admitted },
       reasons,
       // the same effective-order vocabulary the collection engine and
       // the graph loader report; `null` when no statement answers
-      order: diverted ? null : planOrder(entry.planned.plan),
-      sql: diverted ? null : entry.sql,
+      order: mode === 'native' ? planOrder(entry.planned.plan) : null,
+      sql: mode === 'native' ? entry.sql : null,
       residual: mode === 'native'
         ? null
         : { mode: 'set', reasons },
@@ -2449,6 +2518,8 @@ export function createLoadEngine(context, entityName) {
       if (spec?.[member] !== undefined && !isWindowBound(spec[member]))
         throw refuse(`${member} must be a non-negative integer`, []);
     }
+    if (entities.get(entityName)?.physical != null && (keyset || spec?.after !== undefined))
+      throw refuse('column codecs require decoded identities; physical keyset continuation is not qualified', []);
     const tree = buildTree(entityName, spec ?? {}, 0, maxDepth, [], new Set(), profile);
     const rendered = render(tree, 'r', param, emitters);
 
@@ -2538,7 +2609,8 @@ export function createLoadEngine(context, entityName) {
       pagination = 'offset';
     }
 
-    let sql = `SELECT ${rendered.aliasSql}.*, ${dialect.jsonText(rendered.docSql)} AS ${q('__doc')}`
+    let sql = `SELECT ${tree.entity.physical != null ? physicalSelection(tree.entityMapping, dialect, `${rendered.aliasSql}.`)
+      : `${rendered.aliasSql}.*, ${tree.entityMapping.document === false ? dialect.stringLiteral('{}') : dialect.jsonText(rendered.docSql)} AS ${q('__doc')}`}`
       + includeSql
       + ` FROM ${q(tree.entityMapping.table)} AS ${rendered.aliasSql}`;
     if (conditions.length > 0) sql += ` WHERE ${conditions.join(' AND ')}`;
@@ -2552,7 +2624,7 @@ export function createLoadEngine(context, entityName) {
         const nullsFirst = term.emptyGreatest === term.desc;
         return `${value} ${term.desc ? 'DESC' : 'ASC'}${dialect.orderNulls(nullsFirst)}`;
       });
-    if (identity === null) orderSql.push(`${rendered.aliasSql}.${dialect.rowIdentity()}`);
+    if (identity === null) orderSql.push(...(tree.entity.physical != null ? tree.entityMapping.keys.map((k) => `${rendered.aliasSql}.${q(tree.entityMapping.columns.find((c) => c.name === k).physical)}`) : [`${rendered.aliasSql}.${dialect.rowIdentity()}`]));
     sql += ` ORDER BY ${orderSql.join(', ')}`;
     // the profile's row bound rides the root as LIMIT maxRows + 1, so
     // a load past it is detected at the bound and refused (JD2007)
@@ -2704,7 +2776,7 @@ export function createLoadEngine(context, entityName) {
      * the truth either way.
      * @param {any} spec
      * @param {{ limit?: number, after?: any, maxBytes?: number | null,
-     *   consistency?: 'live' | 'snapshot', signal?: AbortSignal }} [options]
+     *   consistency?: 'live' | 'snapshot', signal?: AbortSignal, lookahead?: boolean }} [options]
      * @param {((tree: any, doc: any) => any) | undefined} [register]
      */
     page(spec, options = undefined, register = undefined, cursorFactory = createCursor) {
@@ -2723,7 +2795,9 @@ export function createLoadEngine(context, entityName) {
       if (spec?.take !== undefined || spec?.skip !== undefined)
         throw refuse('page() windows by its limit and continuation — a take or skip in the spec is refused', []);
       const after = options?.after ?? spec?.after ?? undefined;
-      const paged = { ...(spec ?? {}), take: limit + 1 };
+      if (options?.lookahead !== undefined && typeof options.lookahead !== 'boolean')
+        throw refuse('page() lookahead must be boolean', []);
+      const paged = { ...(spec ?? {}), take: limit + (options?.lookahead === false ? 0 : 1) };
       if (after === undefined) delete paged.after;
       else paged.after = after;
       const entry = buildLoad(paged, true, profileOf(options));
@@ -2741,7 +2815,7 @@ export function createLoadEngine(context, entityName) {
       // of work
       const cursor = openCursor(entry, options?.signal, undefined, options?.deadline, cursorFactory);
       return chain(drainPage(cursor, {
-        limit, maxBytes, after: after ?? null,
+        limit, maxBytes, after: after ?? null, lookahead: options?.lookahead,
         sizeOf: (doc) => utf8Length(JSON.stringify(doc)),
         continuationOf: (doc) => continuationOf(entry, doc),
       }), (page) => ({

package/src/search.js

@@ -0,0 +1,144 @@
+//@ts-check
+/** Optional lexical persistence and bounded execution over authoritative entity snapshots. */
+import { compileLexical } from '@jarenjs/core/search';
+import { createLexicalProvider } from '@jarenjs/json/query';
+import { canonicalizeJson } from '@jarenjs/json/canonical';
+import { utf8ByteLength } from '@jarenjs/core/string';
+import { isCursorBudgetError } from './cursor.js';
+
+/** Atomic snapshot storage over a host-declared collection of {id, payload} documents.
+ * Snapshot rows are derived caches and never answer catalog queries.
+ * @param {any} store @param {string} collection @param {{maxBytes?:number}} [options] */
+export function createDbSearchStorage(store, collection, options = {}) {
+  const maxBytes = options.maxBytes ?? 64 * 1024 * 1024;
+  if (typeof collection !== 'string' || !collection || !Number.isSafeInteger(maxBytes) || maxBytes < 1)
+    throw new TypeError('Invalid lexical snapshot storage');
+  return {
+    async load(id) { const row = await store.collection(collection).get(id);
+      if (!row) return null;
+      if (typeof row.payload !== 'string' || row.payload.length > maxBytes || utf8ByteLength(row.payload) > maxBytes)
+        throw new RangeError('Snapshot storage byte credits');
+      return row.payload;
+    },
+    async save(id, payload) {
+      if (typeof id !== 'string' || !id || typeof payload !== 'string' || payload.length > maxBytes || utf8ByteLength(payload) > maxBytes)
+        throw new RangeError('Snapshot storage byte credits');
+      return store.transaction(async (tx) => {
+        const target = tx.collection(collection), old = await target.get(id);
+        if (old?.payload === payload) return { changes: 0 };
+        await target.put({ id, payload }); return { changes: 1 };
+      });
+    },
+  };
+}
+
+/**
+ * Read a bounded, complete entity snapshot inside the store transaction; captured
+ * commits invalidate it. External SQL invalidates through dataVersion on request.
+ * A SHA-256 source-content revision also detects uncaptured edits across reopen.
+ * Native FTS is deliberately refused: this adapter executes the shared ranker.
+ * @param {any} store @param {string} entity
+ * @param {import('@jarenjs/core/search').LexicalDefinition} definition
+ * @param {{source:string, maxRows?:number, maxBytes?:number, storage?:{load:(key:string)=>Promise<string|null>,save:(key:string,payload:string)=>Promise<any>}, snapshotKey?:string}} options
+ * @returns {Promise<any>}
+ */
+export async function createDbSearch(store, entity, definition, options) {
+  const maxRows = options?.maxRows ?? 10000, maxBytes = options?.maxBytes ?? 8 * 1024 * 1024;
+  if (typeof options?.source !== 'string' || !options.source || !Number.isSafeInteger(maxRows) || maxRows < 1
+    || !Number.isSafeInteger(maxBytes) || maxBytes < 2) throw new TypeError('Invalid lexical source credits');
+  if (!store.capabilities?.capture || store.capabilities.capture === 'none') throw new TypeError('Lexical freshness requires committed capture');
+  const compiled = compileLexical(definition), index = compiled.create(), storage = options.storage;
+  const snapshotKey = options.snapshotKey ?? `${options.source}:${entity}`;
+  let rows = new Map(), sourceRevision = '', dataVersion, dirty = true, disposed = false, epoch = 0, busy = null;
+  let reads = 0, writes = 0, restores = 0, rebuilds = 0, sourceBytes = 0, recovery = null, pendingSnapshot = null;
+  const observers = new Set(), controller = new AbortController();
+  const invalidate = (reason) => {
+    dirty = true; epoch++;
+    for (const observer of observers) { try { observer({ type: 'reset', reason, revision: epoch, sourceRevision }); }
+      catch { /* An observer cannot suppress a sibling's invalidation. */ } }
+  };
+  const unsubscribe = store.observe((record) => { if (record.collections.includes(entity)) invalidate('source-changed'); });
+  const refusal = (state, reason) => ({ state, reason, hits: [], total: null, sourceRevision });
+  const refresh = async () => {
+    if (disposed) return refusal('error', 'disposed');
+    if (busy) return busy;
+    const run = async () => {
+      try {
+        const loaded = await store.transaction(async (tx) => {
+          const current = await tx.dataVersion();
+          if (dataVersion !== undefined && current !== dataVersion) invalidate('external-source-changed');
+          dataVersion = current;
+          if (!dirty) return null;
+          const page = await tx.entity(entity).page({ orderBy: '$it.id' },
+            { limit: maxRows + 1, maxBytes, lookahead: false, signal: controller.signal });
+          reads++;
+          if (page.hasMore !== false || page.items.length > maxRows) throw new RangeError('Lexical source exceeds row credits');
+          const source = canonicalizeJson(page.items);
+          if (utf8ByteLength(source) > maxBytes) throw new RangeError('Lexical source exceeds byte credits');
+          const digest = await globalThis.crypto.subtle.digest('SHA-256', new TextEncoder().encode(source));
+          const revision = `${options.source}:${Array.from(new Uint8Array(digest), (b) => b.toString(16).padStart(2, '0')).join('')}`;
+          return { items: page.items, revision, bytes: utf8ByteLength(source), epoch };
+        }, { signal: controller.signal });
+        if (disposed) return refusal('error', 'disposed');
+        if (!loaded) return { state: 'complete', changes: 0, sourceRevision };
+        if (loaded.epoch !== epoch) return refusal('invalidated', 'source-changed');
+        if (loaded.revision === sourceRevision) {
+          if (pendingSnapshot !== null) { writes += (await storage.save(snapshotKey, pendingSnapshot)).changes; pendingSnapshot = null; }
+          if (disposed || loaded.epoch !== epoch) return refusal(disposed ? 'error' : 'invalidated', disposed ? 'disposed' : 'source-changed');
+          dirty = false; return { state: 'complete', changes: 0, sourceRevision };
+        }
+        const nextRows = new Map(loaded.items.map((row) => [row.id, Object.freeze(row)]));
+        if (nextRows.size !== loaded.items.length) throw new TypeError('Duplicate lexical source IDs');
+        let result;
+        if (!sourceRevision && storage) {
+          const saved = await storage.load(snapshotKey);
+          if (saved !== null) {
+            result = index.restore(saved, { sourceRevision: loaded.revision });
+            if (result.state === 'complete') restores++; else recovery = result.reason;
+          }
+        }
+        if (disposed || loaded.epoch !== epoch) return refusal(disposed ? 'error' : 'invalidated', disposed ? 'disposed' : 'source-changed');
+        if (result?.state !== 'complete') {
+          result = index.rebuild(loaded.items, { sourceRevision: loaded.revision }); rebuilds++;
+        }
+        if (result.state !== 'complete') return { ...result, hits: [], total: null };
+        rows = nextRows; sourceRevision = loaded.revision; sourceBytes = loaded.bytes; dirty = false;
+        if (storage) { pendingSnapshot = index.snapshot(); writes += (await storage.save(snapshotKey, pendingSnapshot)).changes; pendingSnapshot = null; }
+        if (disposed || loaded.epoch !== epoch) return refusal(disposed ? 'error' : 'invalidated', disposed ? 'disposed' : 'source-changed');
+        return { state: 'complete', changes: result.changes, sourceRevision };
+      }
+      catch (error) { dirty = true; return refusal(error instanceof RangeError || isCursorBudgetError(error)
+        ? 'budget-exhausted' : 'error', disposed ? 'disposed' : error?.message ?? String(error)); }
+    };
+    busy = run().finally(() => { busy = null; }); return busy;
+  };
+  const service = {
+    refresh,
+    get sourceRevision() { return sourceRevision; },
+    async search(text, spec = {}) {
+      const ready = await refresh(); if (ready.state !== 'complete') return ready;
+      return createLexicalProvider(index, { row: (id) => rows.get(id) }).compile(spec)(text);
+    },
+    /** Access a row only under its published search revision. */
+    row(id, revision) {
+      if (disposed || dirty || revision !== sourceRevision) throw new Error('Lexical source snapshot changed');
+      return structuredClone(rows.get(id));
+    },
+    subscribe(fn) {
+      if (disposed || typeof fn !== 'function') throw new TypeError('Invalid lexical observer');
+      if (observers.size >= 8) throw new RangeError('Lexical subscription credits');
+      observers.add(fn); return () => observers.delete(fn);
+    },
+    explain() { return { mode: 'resident', nativeFTS: false, reason: 'native-token-rank-parity-unqualified',
+      maxRows, maxBytes, capture: store.capabilities.capture, externalChanges: 'dataVersion plus authoritative SHA-256 on refresh' }; },
+    stats() { return { ...index.stats(), sourceRows: rows.size, sourceBytes, reads, writes, restores, rebuilds,
+      recovery, dirty, pending: busy ? 1 : 0, subscriptions: observers.size }; },
+    async dispose() {
+      disposed = true; controller.abort(); unsubscribe(); observers.clear();
+      await busy; index.dispose(); rows.clear(); sourceBytes = 0; pendingSnapshot = null;
+    },
+  };
+  const ready = await refresh();
+  if (ready.state !== 'complete') { await service.dispose(); throw new Error(`Lexical source: ${ready.reason}`); }
+  return service;
+}

package/src/sql.js

@@ -0,0 +1,60 @@
+//@ts-check
+/** Trusted prepared statements, restricted to a live transaction's authority. */
+import { sqlTokens } from './dialects/check-read.js';
+import { chain, attempt } from './driver.js';
+import { DbRuntimeError, wrapDriverError } from './errors.js';
+
+/** @param {any} context @returns {any} a scoped SQL capability */
+export function trustedSql({ connection, requireScope, beforeWrite, afterWrite, readOnly }) {
+  return Object.freeze({
+    /** Compile one statement. Access is explicit; this is trusted application SQL,
+     * not a sandbox for untrusted query text or side-effecting host functions.
+     * @param {string} sql @param {{ access: 'read' | 'write', affects?: readonly string[] }} options */
+    prepare(sql, options) {
+      requireScope();
+      const refuse = (why) => { throw new DbRuntimeError('JD2095', why); };
+      if (typeof sql !== 'string' || !['read', 'write'].includes(options?.access)) refuse('SQL prepare requires text and explicit read/write access');
+      const tokens = sqlTokens(sql);
+      const words = tokens.filter((t) => t.kind === 'word').map((t) => t.value.toUpperCase());
+      if (!tokens.length || tokens[0].kind !== 'word' || !['SELECT', 'WITH', 'INSERT', 'UPDATE', 'DELETE', 'REPLACE'].includes(words[0])) refuse('trusted SQL accepts a single SELECT or data mutation');
+      if (tokens.some((t, i) => t.value === ';' && t.kind === 'symbol' && i !== tokens.length - 1)
+        || words.some((w) => /^(?:BEGIN|COMMIT|ROLLBACK|SAVEPOINT|RELEASE|ATTACH|DETACH|PRAGMA|CREATE|ALTER|DROP|VACUUM)$/.test(w))) refuse('SQL cannot change transaction ownership, schema or connection configuration');
+      const writing = options.access === 'write';
+      if (!writing && words.some((w) => ['INSERT', 'UPDATE', 'DELETE', 'REPLACE'].includes(w))) refuse('a mutation requires write access');
+      if (writing && readOnly) refuse('this store grants no SQL write authority');
+      if (options.affects !== undefined && (!Array.isArray(options.affects) || options.affects.some((v) => typeof v !== 'string'))) refuse('affects is an array of entity names');
+      let closed = false;
+      const check = () => {
+        requireScope();
+        if (closed) refuse('the prepared SQL statement is closed');
+      };
+      const statement = connection.prepare(sql, { readOnly: !writing });
+      const run = (method, params = []) => {
+        check();
+        if (!Array.isArray(params)) refuse('SQL parameters must be an array');
+        return attempt(() => chain(statement, (s) => {
+          check();
+          if (writing) beforeWrite(options.affects);
+          return chain(s[method](params), (result) => {
+            if (writing) afterWrite(options.affects);
+            return result;
+          });
+        }), (error) => wrapDriverError(error, { docPath: '/sql' }));
+      };
+      return Object.freeze({ run: (params) => run('run', params),
+        get: (params) => run('get', params), all: (params) => run('all', params),
+        close: () => { requireScope(); closed = true; } });
+    },
+  });
+}
+
+/** A synchronous transaction ends at callback return, including a thenable return.
+ * @param {Function} fn @param {any} tx @returns {any} */
+export function synchronousBody(fn, tx) {
+  const value = fn(tx);
+  if (value != null && typeof value.then === 'function') {
+    Promise.resolve(value).catch(() => {});
+    throw new DbRuntimeError('JD2095', 'a synchronous transaction callback must not return a thenable');
+  }
+  return value;
+}