@jarenjs/linq 0.73.0 → 0.83.2

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;
@@ -795,15 +799,18 @@ export interface FederatedSide {
   readonly document: unknown;
   /** Whether this side is pulled row by row, or answered whole. */
   readonly streaming: 'row' | 'buffered';
+  readonly children?: readonly FederatedSide[];
 }
 
 /** What a federated document will do, without doing any of it (§12.1). */
 export interface FederationPlan {
   readonly strategy: 'hash';
   readonly budget: { readonly maxRows: number; readonly maxBytes: number };
+  readonly combinedBudget: { readonly maxTotalRows: number; readonly maxTotalBytes: number };
+  readonly order: readonly FederatedSide[];
   readonly build: FederatedSide;
   readonly probe: FederatedSide;
-  /** The join itself is the engine's, over the two reduced sides. */
+  /** The engine evaluates the original binding order over the reduced sets. */
   readonly resident: { readonly document: unknown };
 }
 
@@ -822,13 +829,18 @@ export interface FederatedSource<T = unknown> extends AsyncProvider<T> {
  * out of that, by naming the sources and the bounds together: each
  * side's own filters and projection run at its source, the smaller side
  * fills a bounded hash table, the other is probed against it, and the
- * caller's own document decides over the two reduced sets. A side that
+ * caller's own document decides over the reduced sets. Connected N-way
+ * graphs and nested fluent joins share cumulative admission credits. A side that
  * reaches `maxRows` or `maxBytes` raises `JL2008` at the row that would
  * have broken the bound. */
 export function federate(spec: {
   sources: Record<string, AsyncProvider | { provider: AsyncProvider; estimatedRows?: number }>;
   maxRows: number;
   maxBytes: number;
+  /** Shared admission credits across source reads and intermediate sets; defaults to 2 * maxRows. */
+  maxTotalRows?: number;
+  /** Defaults to 2 * maxBytes. Buffered providers/intermediates are checked after production. */
+  maxTotalBytes?: number;
   strategy?: 'hash';
 }): {
   source<T = unknown>(name: string): FederatedSource<T>;

package/types/message-vocabulary.d.ts

@@ -1,7 +1,7 @@
 // Derived from the English catalogs by scripts/generate-message-pen.js.
 export interface CatalogIds {
   validate: "type" | "required" | "minimum" | "maximum" | "exclusiveMinimum" | "exclusiveMaximum" | "multipleOf" | "minLength" | "maxLength" | "pattern" | "additionalProperties" | "minProperties" | "maxProperties" | "minItems" | "maxItems" | "uniqueItems" | "contains" | "items" | "allOf" | "anyOf" | "oneOf" | "not" | "format" | "if" | "then" | "else" | "false schema" | "$query" | "JQ2001" | "JQ2003";
-  forms: "form/required" | "form/type" | "form/const" | "form/enum" | "form/minLength" | "form/maxLength" | "form/pattern" | "form/format" | "form/minimum" | "form/maximum" | "form/exclusiveMinimum" | "form/exclusiveMaximum" | "form/multipleOf" | "form/minItems" | "form/maxItems" | "form/uniqueItems" | "form/minProperties" | "form/maxProperties" | "x-form/assert" | "form/addItem" | "form/removeItem";
+  forms: "form/required" | "form/type" | "form/const" | "form/enum" | "form/minLength" | "form/maxLength" | "form/pattern" | "form/format" | "form/minimum" | "form/maximum" | "form/exclusiveMinimum" | "form/exclusiveMaximum" | "form/multipleOf" | "form/minItems" | "form/maxItems" | "form/uniqueItems" | "form/minProperties" | "form/maxProperties" | "x-form/assert" | "form/addItem" | "form/removeItem" | "form/jsonPlaceholder";
   contract: "contract/not-found" | "contract/method-not-allowed" | "contract/body-too-large" | "contract/unsupported-media" | "contract/malformed-json" | "contract/invalid-input" | "contract/idempotency-key-required" | "contract/handler-failed" | "contract/idempotency-conflict" | "contract/invalid-output" | "contract/malformed-path" | "contract/malformed-query" | "contract/not-implemented" | "contract/precondition-failed" | "contract/invalid-header" | "contract/handler-error" | "contract/client-invalid-input" | "contract/network" | "contract/cancelled" | "contract/invalid-response" | "contract/key-storage-failed" | "contract/undeclared-response" | "contract/not-a-contract" | "contract/incompatible" | "contract/host-failed" | "contract/local-handler-failed" | "contract/unknown-operation" | "contract/port-timeout" | "contract/malformed-frame" | "contract/channel-closed" | "contract/not-a-stream" | "contract/invalid-snapshot" | "contract/seq-regression" | "contract/stream-error" | "contract/heartbeat-missed" | "contract/slow-consumer" | "contract/reconnect-exhausted";
 }
 export interface MessageParameters {
@@ -56,6 +56,7 @@ export interface MessageParameters {
   "x-form/assert": never;
   "form/addItem": never;
   "form/removeItem": never;
+  "form/jsonPlaceholder": never;
   "contract/not-found": never;
   "contract/method-not-allowed": "allow";
   "contract/body-too-large": "limit" | "op";

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();