@jarenjs/linq 0.75.0 → 0.83.3

package/src/db/runs.js

@@ -0,0 +1,164 @@
+//@ts-check
+/** Existing domain run identities and bounded event pages over mapped application tables. */
+import { canonicalizeJson } from '@jarenjs/json/canonical';
+import { mappedRecords, recordTransaction, copyRecord, refuseRecord } from './records.js';
+
+const zero = Object.freeze({ changes: 0, writes: 0, revisions: 0 });
+/**
+ * Checkpoints remain the existing workflow's format. Status mapping and public
+ * summaries are application policy; events never contain the checkpoint input,
+ * provider credentials, live resources or raw exceptions.
+ * @param {any} client
+ * @param {{ runs: any, events: any, statuses?: Record<string, string>,
+ * summary?: (snapshot: any) => any, canReset?: (tx: any, record: any) => any,
+ * maxPage?: number, maxBytes?: number }} options
+ */
+export function createDbRunStore(client, options) {
+  const runs = mappedRecords(client, options?.runs), events = mappedRecords(client, options?.events);
+  if (runs.name === events.name) throw new TypeError('runs and events must be distinct collections');
+  const { maxPage = 128, maxBytes = 262144 } = options;
+  for (const limit of [maxPage, maxBytes]) if (!Number.isSafeInteger(limit) || limit < 1) throw new TypeError('run observation limits must be positive finite integers');
+  const statuses = { running: 'running', waiting: 'waiting', done: 'done', failed: 'failed', cancelled: 'cancelled', ...options.statuses };
+  if (Object.values(statuses).some((value) => typeof value !== 'string' || !value)) throw new TypeError('status mapping values must be nonempty strings');
+  const summary = options.summary ?? ((snapshot) => ({ status: snapshot.status, generation: snapshot.generation }));
+  const inside = (fn) => recordTransaction(client, fn);
+  const bytes = (value) => new TextEncoder().encode(canonicalizeJson(value)).byteLength;
+  const bounded = (page) => {
+    if (bytes(page) > maxBytes) throw refuseRecord('run page exceeds byte budget');
+    return page;
+  };
+  const eventId = (id, revision) => canonicalizeJson([id, revision]);
+  const requireRun = async (tx, id) => {
+    const record = await runs.get(tx, id);
+    if (!record || !Number.isSafeInteger(record.revision) || record.revision < 0) throw refuseRecord('unknown or malformed domain run');
+    return record;
+  };
+  const guard = async (tx, record, lease) => {
+    if (record.jobId !== lease?.jobId) throw refuseRecord('foreign run job');
+    await tx.jobs.assertLease(lease);
+  };
+  const same = (record, identity) => record.workflow === identity.workflow && record.schemaVersion === identity.schemaVersion && record.jobId === identity.jobId;
+  const write = async (tx, record) => {
+    if (!Number.isSafeInteger(record.revision + 1)) throw refuseRecord('run revision exhausted');
+    record.revision++;
+    const event = { id: eventId(record.id, record.revision), runId: record.id, revision: record.revision,
+      status: record.status, summary: record.summary, cancelRequested: record.cancelRequested };
+    if (bytes({ state: 'page', events: [event], cursor: record.revision, revision: record.revision, more: false, status: record.status, summary: record.summary }) > maxBytes) throw refuseRecord('public run summary exceeds byte budget');
+    await runs.put(tx, record);
+    await events.put(tx, event, true);
+    return { record, changes: 1, writes: 2, revisions: 1 };
+  };
+  return Object.freeze({
+    /** Attach without renaming or re-enqueueing an existing domain run.
+     * @param {{ id: string, jobId: string, workflow: string, schemaVersion: string }} identity @param {any} lease */
+    attach(identity, lease) {
+      const frozen = copyRecord(identity);
+      if (['id', 'jobId', 'workflow', 'schemaVersion'].some((name) => typeof frozen[name] !== 'string' || !frozen[name])) throw new TypeError('run identity needs id/jobId/workflow/schemaVersion');
+      return inside(async (tx) => {
+        if (frozen.jobId !== lease?.jobId) throw refuseRecord('foreign run job');
+        await tx.jobs.assertLease(lease);
+        const prior = await runs.get(tx, frozen.id);
+        if (prior) {
+          if (!same(prior, frozen)) throw refuseRecord('incompatible run workflow or schema identity');
+          return { record: prior, ...zero };
+        }
+        return write(tx, { ...frozen, revision: 0, status: statuses.running, summary: null, checkpoint: null, cancelRequested: false });
+      });
+    },
+    /** Verify provenance before exposing any old checkpoint to the engine.
+     * @param {string} id @param {any} identity @param {any} lease */
+    load(id, identity, lease) {
+      return inside(async (tx) => {
+        const record = await requireRun(tx, id);
+        await guard(tx, record, lease);
+        if (!same(record, identity)) throw refuseRecord('incompatible run workflow or schema identity');
+        if (record.cancelRequested) throw refuseRecord('run cancellation stops admission');
+        return record.checkpoint;
+      });
+    },
+    /** Existing workflow CAS, mapped status/event and checkpoint co-commit.
+     * @param {string} id @param {any} snapshot @param {number} expectedGeneration @param {any} lease */
+    save(id, snapshot, expectedGeneration, lease) {
+      const checkpoint = copyRecord(snapshot);
+      return inside(async (tx) => {
+        const record = await requireRun(tx, id);
+        await guard(tx, record, lease);
+        if (record.cancelRequested) throw refuseRecord('run cancellation stops admission');
+        if ((record.checkpoint?.generation ?? 0) !== expectedGeneration) return false;
+        if (checkpoint.runId !== id || checkpoint.generation !== expectedGeneration + 1 || !Object.hasOwn(statuses, checkpoint.status))
+          throw refuseRecord('checkpoint run, generation or status mismatch');
+        record.checkpoint = checkpoint;
+        record.status = statuses[checkpoint.status];
+        record.summary = copyRecord(summary(checkpoint));
+        await write(tx, record);
+        return true;
+      });
+    },
+    /** Trusted read: public authorization belongs to the contract handler.
+     * @param {string} id */
+    get: (id) => inside((tx) => requireRun(tx, id)),
+    /** Bounded revision cursor. Missing history explicitly requires a fresh summary.
+     * @param {string} id @param {{ after?: number, limit?: number }} [options] */
+    page(id, { after = 0, limit = maxPage } = {}) {
+      if (!Number.isSafeInteger(after) || after < 0 || !Number.isSafeInteger(limit) || limit < 1 || limit > maxPage) throw new TypeError('run page needs a revision cursor and bounded limit');
+      return inside(async (tx) => {
+        const record = await requireRun(tx, id);
+        if (after > record.revision) throw refuseRecord('future run cursor');
+        const page = [], end = Math.min(record.revision, after + limit);
+        const envelope = { state: 'page', events: page, cursor: after, revision: record.revision, more: true, status: record.status, summary: record.summary };
+        for (let revision = after + 1; revision <= end; revision++) {
+          const event = await events.get(tx, eventId(id, revision));
+          if (!event) return bounded({ state: 'reset-required', cursor: record.revision, revision: record.revision, events: [], summary: record.summary, status: record.status });
+          if (event.runId !== id || event.revision !== revision) throw refuseRecord('run event identity mismatch');
+          if (bytes({ ...envelope, cursor: revision, events: [...page, event] }) > maxBytes) break;
+          page.push(event);
+        }
+        const cursor = page.at(-1)?.revision ?? after;
+        if (cursor === after && cursor < record.revision) throw refuseRecord('run page exceeds byte budget');
+        return bounded({ state: 'page', events: page, cursor, revision: record.revision, more: cursor < record.revision,
+          status: record.status, summary: record.summary });
+      });
+    },
+    /** Current authority is required in the caller's command; revision rejects stale intent.
+     * @param {string} id @param {number} expectedRevision @param {{ actor: string, reason: string }} evidence */
+    requestCancel(id, expectedRevision, evidence) {
+      if (!evidence?.actor || !evidence.reason) throw refuseRecord('cancellation needs actor and reason');
+      const proof = copyRecord(evidence);
+      return inside(async (tx) => {
+        const record = await requireRun(tx, id);
+        if (record.cancelRequested) return { record, ...zero };
+        if (record.revision !== expectedRevision) throw refuseRecord('stale cancellation revision');
+        if (record.status === statuses.done) throw refuseRecord('completed run cannot be cancelled');
+        record.cancelRequested = true; record.cancellation = proof;
+        return write(tx, record);
+      });
+    },
+    /** Called after workers drain and before resources close.
+     * @param {string} id @param {'cancelled' | 'failed'} state @param {any} lease */
+    finish(id, state, lease) {
+      if (!['cancelled', 'failed'].includes(state)) throw new TypeError('finish state must be cancelled or failed');
+      return inside(async (tx) => {
+        const record = await requireRun(tx, id);
+        await guard(tx, record, lease);
+        if (record.status === statuses[state]) return { record, ...zero };
+        record.status = statuses[state]; record.summary = { status: state };
+        return write(tx, record);
+      });
+    },
+    /** Reset touches only this run checkpoint, never receipts/effects. Host safety
+     * must consult authoritative history in this transaction; default is refusal.
+     * @param {string} id @param {number} expectedRevision @param {any} evidence @param {any} lease */
+    reset(id, expectedRevision, evidence, lease) {
+      if (!evidence?.actor || !evidence.reason || typeof options.canReset !== 'function') throw refuseRecord('reset needs explicit actor/reason and a transactional safety policy');
+      return inside(async (tx) => {
+        const record = await requireRun(tx, id);
+        await guard(tx, record, lease);
+        if (record.revision !== expectedRevision || ![statuses.cancelled, statuses.failed, statuses.waiting].includes(record.status)) throw refuseRecord('reset needs an inactive current revision');
+        if (await options.canReset(tx, copyRecord(record)) !== true) throw refuseRecord('receipt or unresolved effect prevents reset');
+        record.checkpoint = null; record.cancelRequested = false; record.status = statuses.running;
+        record.summary = { status: 'reset' }; record.reset = copyRecord(evidence);
+        return write(tx, record);
+      });
+    },
+  });
+}

package/src/db/search.js

@@ -0,0 +1,86 @@
+//@ts-check
+/** Structural lexical ranges reuse the shared resident range implementation. */
+import { createArrayRangeProvider, rangeBytes, rangeIdentity } from '@jarenjs/core/range';
+import { canonicalizeJson } from '@jarenjs/json/canonical';
+
+/**
+ * Materialize only a credited, complete lexical membership. The source retains
+ * authoritative rows; this adapter owns one bounded range copy and its cursors.
+ * @param {any} source @param {string} text @param {any} [spec] @param {any} [options]
+ * @returns {Promise<any>}
+ */
+export async function createLexicalRangeProvider(source, text, spec = {}, options = {}) {
+  const maxMatches = options.maxMatches ?? 1000, maxSourceBytes = options.maxSourceBytes ?? 1024 * 1024;
+  if (!Number.isSafeInteger(maxMatches) || maxMatches < 1 || !Number.isSafeInteger(maxSourceBytes) || maxSourceBytes < 2)
+    throw new TypeError('Invalid lexical range credits');
+  if (spec.after !== undefined || spec.limit !== undefined) throw new TypeError('Lexical ranges own continuation and result limits');
+  spec = structuredClone(spec);
+  const query = options.query ?? canonicalizeJson({ text, spec, source: options.source ?? null });
+  let disposed = false, dirty = false, epoch = 0, provider = null, refreshing = null;
+  const observers = new Set();
+  const unsubscribe = source.subscribe((event) => {
+    dirty = true; epoch++;
+    for (const observer of observers) { try { observer({ ...event, query, type: 'reset', revision: epoch, snapshot: source.sourceRevision }); }
+      catch { /* Subscribers cannot suppress a sibling's reset. */ } }
+  });
+  const refresh = async () => {
+    if (disposed) throw new Error('Lexical range disposed');
+    if (refreshing) return refreshing;
+    refreshing = (async () => {
+      const result = await source.search(text, { ...spec, limit: maxMatches });
+      if (disposed) throw new Error('Lexical range disposed');
+      if (result.state !== 'complete' || result.hasMore || result.hits.length !== result.total)
+        throw new RangeError(`Lexical range requires complete membership: ${result.reason ?? 'match-credits'}`);
+      const rows = [], snapshot = result.sourceRevision;
+      let bytes = 2;
+      for (const hit of result.hits) {
+        const row = source.row(hit.id, snapshot); bytes += rangeBytes(row) + (rows.length ? 1 : 0);
+        if (bytes > maxSourceBytes) throw new RangeError('Lexical range source byte credits');
+        rows.push(row);
+      }
+      if (provider === null) provider = createArrayRangeProvider(rows, { ...options, query, snapshot });
+      else if (provider.snapshot !== snapshot) provider.replace(rows, snapshot);
+      dirty = false; return { state: 'complete', sourceRevision: snapshot, rows: rows.length, bytes };
+    })().finally(() => { refreshing = null; });
+    return refreshing;
+  };
+  try { await refresh(); }
+  catch (error) { unsubscribe(); throw error; }
+  return {
+    query, get snapshot() { return provider.snapshot; }, capabilities: provider.capabilities, refresh,
+    indexOf: (key) => provider.indexOf(key),
+    subscribe(fn) {
+      if (disposed || typeof fn !== 'function') throw new TypeError('Invalid lexical range subscriber');
+      if (observers.size >= 8) throw new RangeError('Lexical range subscription credits');
+      observers.add(fn); return () => observers.delete(fn);
+    },
+    async request(request, signal) {
+      const refusal = (state, reason) => ({ ...rangeIdentity(request), state, reason, used: { pages: 0, rows: 0, bytes: 0, work: 0 } });
+      if (disposed) return refusal('error', 'disposed');
+      if (signal?.aborted) return refusal('error', 'cancelled');
+      const current = epoch;
+      const ready = await source.refresh();
+      if (disposed) return refusal('error', 'disposed');
+      if (signal?.aborted) return refusal('error', 'cancelled');
+      if (ready.state !== 'complete') return refusal(ready.state === 'budget-exhausted' ? ready.state : 'error', ready.reason);
+      if (dirty || current !== epoch || source.sourceRevision !== provider.snapshot) return refusal('invalidated', 'source-changed');
+      return provider.request(request, signal);
+    },
+    async *export(request, signal) {
+      const ready = await source.refresh();
+      if (ready.state !== 'complete' || dirty || disposed || source.sourceRevision !== provider.snapshot) throw new Error('Incomplete lexical snapshot export');
+      for await (const page of provider.export(request, signal)) {
+        const current = await source.refresh();
+        if (current.state !== 'complete' || dirty || disposed || source.sourceRevision !== provider.snapshot)
+          throw new Error('Incomplete lexical snapshot export');
+        yield page;
+      }
+    },
+    stats: () => ({ ...provider.stats(), refreshing: refreshing ? 1 : 0, subscriptions: observers.size, dirty }),
+    async dispose() {
+      disposed = true; unsubscribe(); observers.clear();
+      await Promise.allSettled([refreshing]); await provider.dispose();
+      if (options.disposeSource) await source.dispose();
+    },
+  };
+}

package/src/errors.js

@@ -15,7 +15,8 @@ import { CodedError } from '@jarenjs/core/errors';
  * this package can raise, proven in sync with QUERY-PEN.md §9's
  * normative table by a test.
  */
-export const LINQ_CODES = Object.freeze({
+// Freezing an unexported literal has no observable effect when the table is unused.
+export const LINQ_CODES = /* @__PURE__ */ Object.freeze({
   JL0001: 'from() received neither an iterable nor a provider',
   JL0002: 'an expression proxy escaped its capture callback',
   JL0003: 'ofType/cast need an injected compileTypeTest',
@@ -38,6 +39,7 @@ export const LINQ_CODES = Object.freeze({
   JL2006: 'a provider answered an element terminal with something other than one array',
   JL2007: 'a ledger settlement named a ref that settles no started record',
   JL2008: 'a federated fetch reached its row or byte budget',
+  JL2009: 'a durable mapped record violated identity, retention or fencing',
 });
 
 /**

package/src/expression.js

@@ -307,8 +307,7 @@ function shiftArgs(record, amount, unit) {
 function literalSpec(spec, method) {
   if (!isPlainJson(spec) || spec === null || typeof spec !== 'object' || Array.isArray(spec)) {
     throw new LinqBuildError('JL0005',
-      `${method}() takes a plain literal spec object; it is read once when the query`
-      + ' compiles, so it cannot be an expression or carry a captured value');
+      `${method}() takes a plain literal spec object, not an expression or captured value`);
   }
   return spec;
 }
@@ -336,6 +335,10 @@ const METHODS = {
   // §8.7 strings
   startsWith: binary('$starts-with'), endsWith: binary('$ends-with'),
   contains: binary('$contains'), matches: binary('$match'),
+  lexical(record, provider, spec = {}) {
+    if (typeof provider !== 'string' || !provider) throw new LinqBuildError('JL0005', 'Lexical name');
+    return makeExpr({ $lexical: [provider, record.doc, literalSpec(spec, 'lexical')] }, record.epoch, false);
+  },
   upper: unary('$upper'), lower: unary('$lower'),
   length: unary('$string-length'),
   concat: binary('$concat'),

package/src/formula/index.js

@@ -0,0 +1,15 @@
+//@ts-check
+/** Formula authoring emits the same JSON document consumed by json/formula. */
+import { formulaDocument } from '@jarenjs/json/formula';
+import { requireJson } from '../json-boundary.js';
+
+/**
+ * Author a saved Query profile; expression is an existing Query document.
+ * @param {string} id
+ * @param {any} expression
+ * @param {object} [options] - Revision, bindings, schema/helper references and result mode.
+ * @returns {any} Frozen JSON, with no executable closures in the document.
+ */
+export function defineFormula(id, expression, options = {}) {
+  return formulaDocument(requireJson({ $formula: '1', revision: '1', ...options, id, expression }, 'defineFormula'));
+}

package/src/model/define.js

@@ -116,6 +116,8 @@ export function defineModel(spec) {
         }
       }
       const entity = { schema: builder.schema };
+      if (builder.state.invariants !== undefined) entity.invariants = builder.state.invariants;
+      if (builder.state.physical !== undefined) entity.physical = builder.state.physical;
       if (builder.state.renamedFrom !== undefined) entity['x-rename'] = builder.state.renamedFrom;
       setObjectMember(emitted, name, entity);
     }

package/src/model/entity.js

@@ -218,6 +218,21 @@ export function withEntity(Base) {
      */
     renamedFrom(name) { return this.with({ renamedFrom: requireName(name, 'renamedFrom()') }); }
 
+    /** Explicit existing columns, lifted onto the entity declaration.
+     * @param {any} layout */
+    physical(layout) {
+      if (this.state.kind !== 'object') throw new LinqBuildError('JL0102', 'physical() belongs on an entity object');
+      return this.with({ physical: requireJson(layout, 'physical()') });
+    }
+
+
+    /** Declare persistence predicates, with explicit writer enforcement.
+     * @param {any[]} rules */
+    invariants(rules) {
+      if (this.state.kind !== 'object') throw new LinqBuildError('JL0102', 'invariants() belongs on an entity object');
+      return this.with({ invariants: requireJson(rules, 'invariants()') });
+    }
+
     /** As in the schema pen, but `x-entity` is owned here. @param {Record<string, any>} annotations */
     meta(annotations) {
       if (annotations !== null && typeof annotations === 'object' && KEYWORD in annotations) {

package/src/project/index.js

@@ -5,24 +5,25 @@ import { LinqBuildError } from '../errors.js';
 
 /** The public project file vocabulary, held equal to Studio's schema by tests. */
 export const FILE_KINDS = Object.freeze(['app', 'jslt', 'query', 'state', 'data', 'schema', 'fsm', 'dag', 'model', 'contract']);
+const FILE_OPTIONS = ['imports', 'input', 'model', 'collection'];
 const LAYOUT_KEYS = ['mode', 'ratio', 'autorun'];
 
 /** One file, preserving the caller's text byte-for-byte. */
-export function file(name, kind, text) {
+export function file(name, kind, text, options = {}) {
   if (typeof name !== 'string' || name.length === 0 || !FILE_KINDS.includes(kind) || typeof text !== 'string')
     throw new LinqBuildError('JL0101', 'file() requires a nonempty name, a declared kind and text');
-  return snapshot({ name, kind, text });
+  return snapshot({ name, kind, text, ...optionsOf(options, FILE_OPTIONS, 'file()') });
 }
 
 /** One file holding a public JSON value; pass another pen's `.schema` explicitly. */
-export function jsonFile(name, kind, document) { return file(name, kind, JSON.stringify(snapshot(document))); }
+export function jsonFile(name, kind, document, options = {}) { return file(name, kind, JSON.stringify(snapshot(document)), options); }
 
 /** Validate the authoring shape, preserving duplicate names for Studio to judge. */
 function filesOf(files) {
   if (!Array.isArray(files)) throw new LinqBuildError('JL0101', 'files() takes an array of project files');
   return files.map((value) => {
-    const f = optionsOf(value, ['name', 'kind', 'text'], 'file');
-    return file(f.name, f.kind, f.text);
+    const { name, kind, text, ...options } = optionsOf(value, ['name', 'kind', 'text', ...FILE_OPTIONS], 'file');
+    return file(name, kind, text, options);
   });
 }
 

package/types/db.d.ts

@@ -145,6 +145,7 @@ export type Continuation<S, M extends EntityMeta> = LoadContinuation & {
 /** A page's options over this graph (the store's `PageOptions`, the
  * continuation typed by the declared ordering). */
 export interface GraphPageOptions<S, M extends EntityMeta> extends EntityCursorOptions {
+  lookahead?: boolean;
   limit?: number;
   after?: Continuation<S, M>;
   maxBytes?: number;
@@ -205,6 +206,7 @@ export interface Graph<E extends MetaMap<E>, M extends EntityMeta, S> {
  * exactly the many-to-many members. */
 export type EntityHandle<E extends MetaMap<E>, M extends EntityMeta> =
   TypedEntitySet<E, M> & ChainStart<M['doc']> & {
+    range(spec: import('@jarenjs/db').LoadSpec, options: DbRangeOptions): Promise<DbRangeProvider<M['doc']>>;
     /** Open a graph: include one relation member with an optional spec. */
     include<K extends keyof M['relations'] & string, const I extends IncludeSpec<E, TargetMeta<E, M, K>> = true>(
       pick: (u: RelationPicker<M>) => Picked<K>, spec?: I | NoInfer<IncludeSpec<E, TargetMeta<E, M, K>>>,
@@ -217,6 +219,40 @@ export type EntityHandle<E extends MetaMap<E>, M extends EntityMeta> =
     live<T = M['doc']>(source?: AsyncSequence<T, any> | object, options?: LiveOptions): Promise<TypedLiveQuery<T>>;
   };
 
+export interface DbRangeOptions {
+  keys: readonly string[];
+  resident?: boolean; seekIndex?: boolean; exactTotal?: boolean;
+  source?: string; query?: string; schemaVersion?: string;
+  profile?: 'safe' | import('@jarenjs/db').ProfileSpec;
+  maxRows?: number; maxBytes?: number; maxPages?: number; maxInFlight?: number; maxSubscriptions?: number;
+  runtime?: Partial<Runtime>;
+}
+export interface DbRangeRequest {
+  generation: number; requestId: string; query: string; snapshot: string;
+  range?: { start: number; end: number }; continuation?: string;
+  credits: { pages: number; rows: number; bytes: number; work: number };
+}
+export interface DbRangeResponse<T = unknown> {
+  generation: number; requestId: string; query: string; snapshot: string;
+  state: 'ready' | 'loading' | 'error' | 'invalidated' | 'budget-exhausted'; reason?: string;
+  rows?: readonly T[]; keys?: readonly string[]; continuation?: string | null;
+  total?: { kind: 'known'; value: number } | { kind: 'unknown' };
+  used: { pages: number; rows: number; bytes: number; work: number };
+}
+export interface DbRangeProvider<T = unknown> {
+  readonly query: string; readonly snapshot: string;
+  readonly capabilities: Readonly<{ seekIndex: boolean; seekKey: false; continuation: true;
+    live: true; exactTotal: boolean; completeExport: false }>;
+  request(request: DbRangeRequest, signal?: AbortSignal): Promise<DbRangeResponse<T>>;
+  subscribe(observer: (event: { type: 'reset'; reason: string; query: string; snapshot: string; revision: number; capture: string }) => void): () => boolean;
+  stats(): { sourceReads: number; sourceRows: number; sourceBytes: number; pending: number;
+    pages: number; rows: number; bytes: number; subscriptions: number; disposed: boolean };
+  dispose(): Promise<void>;
+}
+/** Source capture is required; keyset mode is sequential unless resident is explicit. */
+export declare function createDbRangeProvider<T = unknown>(store: import('@jarenjs/db').Store | TypedStore<any>,
+  entity: string, spec: import('@jarenjs/db').LoadSpec, options: DbRangeOptions): Promise<DbRangeProvider<T>>;
+
 /** Present exactly when the model declares entities, as on the store. */
 export interface EntityClientMembers {
   /** The store's unit of work, flushed. */
@@ -331,6 +367,9 @@ export type TransactionClientOf<E extends MetaMap<E>, C = Record<string, unknown
   /** The scope-bound store — the escape hatch, still inside. It carries
    * no `close`: a transaction never owns the connection's lifetime. */
   readonly store: TransactionStore;
+  readonly sql: TransactionStore['sql'];
+  readonly jobs: TransactionStore['jobs'];
+  readonly sync: TransactionStore['sync'];
   readonly capabilities: StoreCapabilities;
   readonly entities: { readonly [K in keyof E & string]: EntityHandle<E, E[K]> };
   readonly collections: { readonly [K in keyof C & string]: CollectionHandle<C[K]> };
@@ -364,3 +403,65 @@ export function defineReplication(header: Omit<import('@jarenjs/db').Replication
   toDocument(): import('@jarenjs/db').ReplicationEnvelope;
   toJSON(): import('@jarenjs/db').ReplicationEnvelope;
 };
+
+/** A complete lexical membership composed with the common structural range provider. */
+export declare function createLexicalRangeProvider(source: import('@jarenjs/db/search').DbSearch,
+  text: string, request?: Record<string, unknown>, options?: {maxMatches?:number; maxSourceBytes?:number;
+    maxRows?:number; maxBytes?:number; maxPages?:number; maxInFlight?:number; query?:string;
+    source?:string; exactTotal?:boolean; seekIndex?:boolean; disposeSource?:boolean}): Promise<any>;
+
+/** Atomic staging and publication over application-declared collections. */
+export function createDbIngestionStore(client: Client<any> | TransactionClientOf<any>, options: {
+  staging: string; checkpoints: string; publications: string; facts?: string;
+  reconcile?: (existing: any, incoming: any, evidence: any) => any;
+}): {
+  begin(plan: any): Promise<any>;
+  stage(plan: any, partition: string, page: any): Promise<any>;
+  invalidate(plan: any, reason: string): Promise<void>;
+  publish(plan: any, evidence: any, context?: { signal?: AbortSignal }): Promise<any>;
+  current(source: string): Promise<any>;
+  inspect(plan: any): Promise<any>;
+};
+
+/** Lossless canonical-record mapping onto an application-declared collection. */
+export type DurableRecordMapping = string | (({ collection: string; entity?: never } | { entity: string; collection?: never }) & { key?: (id: string) => any; read: (stored: any) => any; write: (record: any) => any });
+export interface CommandIdentity {
+  tenant: string; environment: string; aggregate: string; op: string; key: string; hashVersion: string; hash: string;
+}
+/** Permanent business outcomes and independently expiring execution authority. */
+export function createDbReceipts(client: Client<any> | TransactionClientOf<any>, options: {
+  receipts: DurableRecordMapping; leases?: DurableRecordMapping; runtime?: Partial<import('@jarenjs/core/runtime').Runtime>;
+}): {
+  lookup(identity: CommandIdentity): Promise<any>;
+  execute(identity: CommandIdentity, work: (tx: TransactionClientOf<any>) => Promise<{ outcome: any; references?: any[] }>, context?: { lease?: any }): Promise<any>;
+  claim(identity: CommandIdentity, options: { leaseMs: number }): Promise<any>;
+  release(identity: CommandIdentity, lease: any): Promise<any>;
+  sweep(identities: CommandIdentity[]): Promise<{ changes: number; writes: number; revisions: number }>;
+  migrate(records: any[]): Promise<{ changes: number; writes: number; revisions: number }>;
+  compact(identity: CommandIdentity, policy: { retainReplay: true; retainReferences: true; actor: string; reason: string }): Promise<any>;
+};
+/** Durable preparation, job-fenced sending and explicit reconciliation. */
+export function createDbEffectStore(client: Client<any> | TransactionClientOf<any>, options: {
+  operations: DurableRecordMapping; maxLegs?: number; maxBytes?: number;
+}): {
+  prepare(plan: any, prepare?: (tx: TransactionClientOf<any>) => any): Promise<any>;
+  get(id: string): Promise<any>;
+  begin(id: string, legId: string, revision: number, lease: import('@jarenjs/db').JobLease): Promise<any>;
+  settle(id: string, legId: string, revision: number, lease: import('@jarenjs/db').JobLease, outcome: any): Promise<any>;
+  recover(id: string, revision: number, lease: import('@jarenjs/db').JobLease): Promise<any>;
+  reconcile(id: string, legId: string, revision: number, lease: import('@jarenjs/db').JobLease, decision: any): Promise<any>;
+};
+/** Application run/checkpoint records and bounded public revision pages. */
+export function createDbRunStore(client: Client<any> | TransactionClientOf<any>, options: {
+  runs: DurableRecordMapping; events: DurableRecordMapping; statuses?: Record<string, string>;
+  summary?: (snapshot: any) => any; canReset?: (tx: TransactionClientOf<any>, record: any) => any; maxPage?: number; maxBytes?: number;
+}): {
+  attach(identity: { id: string; jobId: string; workflow: string; schemaVersion: string }, lease: import('@jarenjs/db').JobLease): Promise<any>;
+  load(id: string, identity: any, lease: import('@jarenjs/db').JobLease): Promise<any>;
+  save(id: string, snapshot: any, expectedGeneration: number, lease: import('@jarenjs/db').JobLease): Promise<boolean>;
+  get(id: string): Promise<any>;
+  page(id: string, options?: { after?: number; limit?: number }): Promise<any>;
+  requestCancel(id: string, revision: number, evidence: { actor: string; reason: string }): Promise<any>;
+  finish(id: string, state: 'cancelled' | 'failed', lease: import('@jarenjs/db').JobLease): Promise<any>;
+  reset(id: string, revision: number, evidence: any, lease: import('@jarenjs/db').JobLease): Promise<any>;
+};

package/types/formula.d.ts

@@ -0,0 +1,9 @@
+/** Author a saved JSON Query formula without executing it. */
+export declare function defineFormula(id: string, expression: unknown, options?: {
+  revision?: string;
+  bindings?: Record<string, unknown>;
+  inputSchema?: { id: string; version: string };
+  resultSchema?: { id: string; version: string };
+  helpers?: { name: string; version: string }[];
+  resultMode?: 'value' | 'outcome';
+}): any;

package/types/index.d.ts

@@ -77,6 +77,8 @@ export interface StringExpr extends ExprBase<string>, EqExpr<string>, SpatialMet
   contains(value: string | StringExpr): BoolExpr;
   /** I-Regexp (RFC 9485) full match. */
   matches(pattern: string): BoolExpr;
+  /** Explicit lexical provider request; preserves ranked-result completeness. */
+  lexical(provider: string, request?: Record<string, unknown>): UnknownExpr;
   upper(): StringExpr;
   lower(): StringExpr;
   length(): NumberExpr;
@@ -363,6 +365,8 @@ export interface UnknownExpr
   endsWith(value: unknown): BoolExpr;
   contains(value: unknown): BoolExpr;
   matches(pattern: string): BoolExpr;
+  /** Explicit lexical provider request; preserves ranked-result completeness. */
+  lexical(provider: string, request?: Record<string, unknown>): UnknownExpr;
   upper(): UnknownExpr;
   lower(): UnknownExpr;
   length(): NumberExpr;

package/types/model.d.ts

@@ -61,6 +61,20 @@ export interface EntityBlock {
   };
 }
 
+/** Explicit column-only layout for an existing SQLite object. */
+export interface PhysicalLayout {
+  readonly table: string;
+  readonly kind?: 'table' | 'view';
+  readonly keys?: readonly string[];
+  readonly columns: Readonly<Record<string, {
+    readonly name: string;
+    readonly codec: 'text' | 'integer' | 'number' | 'boolean' | 'json' | 'date' | 'datetime' | 'epoch-ms' | 'bigint' | 'decimal' | 'blob-hex';
+    readonly null: 'null' | 'absent' | 'reject';
+    readonly default?: 'database';
+    readonly generated?: boolean;
+  }>>;
+}
+
 // ————— the entity-aware builders —————
 
 /** The base every untyped kind is built from, plus the vocabulary. */
@@ -203,6 +217,10 @@ export class EntityObjectBuilder<
   P extends Props, Open extends boolean = false, PV = never, PVIn = PV,
   N extends boolean = false, F extends Flag = never,
 > extends ObjectBuilder<P, Open, PV, PVIn, N, F> {
+  physical(layout: PhysicalLayout): this;
+  invariants(rules: readonly { name: string; on: readonly ('insert' | 'update' | 'delete')[];
+    enforcement: 'database' | 'store'; assert: unknown;
+    audit?: { entity: string; values: Readonly<Record<string, unknown>> } }[]): this;
   optional(): EntityObjectBuilder<P, Open, PV, PVIn, N, F | 'optional'>;
   nullable(): EntityObjectBuilder<P, Open, PV, PVIn, true, F>;
   open(): EntityObjectBuilder<P, true, PV, PVIn, N, F>;

package/types/project.d.ts

@@ -7,7 +7,13 @@ export type JsonInput<T> = unknown extends T ? unknown
       : T extends object ? { readonly [K in keyof T]: JsonInput<T[K]> } : never;
 
 export type FileKind = 'app' | 'jslt' | 'query' | 'state' | 'data' | 'schema' | 'fsm' | 'dag' | 'model' | 'contract';
-export interface ProjectFile<Name extends string = string, Kind extends FileKind = FileKind> {
+export interface ProjectFileOptions {
+  readonly imports?: Readonly<Record<string, string>>;
+  readonly input?: string;
+  readonly model?: string;
+  readonly collection?: string;
+}
+export interface ProjectFile<Name extends string = string, Kind extends FileKind = FileKind> extends ProjectFileOptions {
   readonly name: Name;
   readonly kind: Kind;
   readonly text: string;
@@ -24,8 +30,8 @@ export interface ProjectDocument {
   readonly layout?: ProjectLayout;
 }
 export const FILE_KINDS: readonly FileKind[];
-export function file<const N extends string, K extends FileKind>(name: N, kind: K, text: string): ProjectFile<N, K>;
-export function jsonFile<const N extends string, K extends FileKind, const D>(name: N, kind: K, document: D & JsonInput<D>): ProjectFile<N, K>;
+export function file<const N extends string, K extends FileKind>(name: N, kind: K, text: string, options?: ProjectFileOptions): ProjectFile<N, K>;
+export function jsonFile<const N extends string, K extends FileKind, const D>(name: N, kind: K, document: D & JsonInput<D>, options?: ProjectFileOptions): ProjectFile<N, K>;
 /** Names are a phantom; the public document has no extra registry. */
 export class ProjectBuilder<Names extends string = never> {
   protected constructor();