okmodel 0.5.1 → 0.7.0

package/dist/runtime/aggregate.d.ts

@@ -7,8 +7,14 @@
  * every aggregate exactly as they apply to a `find`. This module loads on the
  * first `aggregate()`.
  *
- * Not here: `having`, `bucket`, and ordering by an aggregate. A hidden column
- * cannot be grouped or aggregated, so an aggregate never shows what a read hides.
+ * Not here: `having`, ordering by an aggregate, and the time-zone date helpers
+ * (tool 5). A hidden column cannot be grouped or aggregated, so an aggregate
+ * never shows what a read hides.
+ *
+ * `bucket()` is a tagged helper. Its validation and SQL load in their own
+ * chunk, and only when `groupBy` contains one. A request object cannot create
+ * one. A NULL timestamp is one group: the result key is present and the value
+ * is null.
  */
 import { type Mods, type Session } from "./client.js";
 import { type ArchiveView } from "./plan.js";

package/dist/runtime/batch.d.ts

@@ -12,7 +12,7 @@ import { type Session } from "./client.js";
  * Runs write handles as one atomic unit.
  *
  * @param session - Client session
- * @param ops - Write handles: `insert`, `update`, `delete`, `archive`. A `restore`, or a write with `expect`, is OKM1121 (D183)
+ * @param ops - Write handles: `insert`, `update`, `delete`, `archive`. A `restore`, a write with `expect`, or `refresh()` is OKM1121 (D183, D239)
  * @param options - `signal` and `timeout` for the whole batch
  * @param replica - Set by `.replica()`. A batch needs the primary (OKM1840)
  * @returns One result per operation, in order

package/dist/runtime/bucket-group.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Time buckets inside `aggregate` `groupBy` (spec §10, §13 tool 4).
+ *
+ * This module loads on the first `aggregate()` whose `groupBy` contains a
+ * `bucket()`. A plain aggregate does not import it. A NULL timestamp is one
+ * group: the `as` key is present and the value is null.
+ */
+import type { ColumnModel } from "../dialects/pg/model.js";
+import { type BucketUnit } from "../dialects/pg/ops/bucket.js";
+import { type Built, type Indexed, type Sink } from "./plan.js";
+/** One bucket in a group list. */
+export type BucketGroup = {
+    readonly kind: "bucket";
+    readonly column: ColumnModel;
+    readonly unit: BucketUnit;
+    readonly tz: string | undefined;
+    readonly as: string;
+    readonly shift: 0 | 1 | 2;
+    readonly clock: boolean;
+};
+/**
+ * What the aggregate chunk calls after this module loads.
+ *
+ * The aggregate chunk does not import this file. It receives the functions
+ * from `import()`.
+ */
+export type BucketChunk = {
+    readBucket(table: Indexed, value: unknown, fields: ReadonlySet<string>, aliases: Set<string>): BucketGroup;
+    writeBucket(sink: Sink, outputs: Built | undefined, wrote: {
+        at: number;
+    }, group: BucketGroup): void;
+    writeGrouped(sink: Sink, names: readonly string[], orderBy: unknown): void;
+};
+/**
+ * Reads one `bucket()` group.
+ *
+ * Refuses a bad unit, zone, week start, or result name before any SQL.
+ * `__proto__`, `constructor`, `toString`, and `hasOwnProperty` are refused.
+ * `timestamptz` needs an IANA `tz`. `date` refuses `tz`. `timestamp` without
+ * a zone is refused.
+ *
+ * @param table - The grouped table
+ * @param value - One `groupBy` entry
+ * @param fields - Plain group fields already seen
+ * @param aliases - Bucket result names already seen
+ * @returns The group the statement writes
+ */
+export declare function readBucket(table: Indexed, value: unknown, fields: ReadonlySet<string>, aliases: Set<string>): BucketGroup;
+/**
+ * Writes one bucket expression into the select list.
+ *
+ * @param sink - Statement buffer
+ * @param outputs - Decode plan, absent while only marking
+ * @param wrote - How many select items are already written
+ * @param group - The bucket
+ */
+export declare function writeBucket(sink: Sink, outputs: Built | undefined, wrote: {
+    at: number;
+}, group: BucketGroup): void;
+/**
+ * Groups and orders by select-list ordinals.
+ *
+ * The bucket expression is written once, in the select list. A second copy
+ * would bind a new `$n`, and Postgres treats that as a different expression.
+ *
+ * @param sink - Statement buffer
+ * @param names - Group names, in select order
+ * @param orderBy - Caller order, or the default group order
+ */
+export declare function writeGrouped(sink: Sink, names: readonly string[], orderBy: unknown): void;

package/dist/runtime/conflict.d.ts

@@ -18,23 +18,41 @@ export type ConflictPlan = {
  * @param table - Target table
  * @param value - The option the caller passed
  * @param allow - Guarded fields this write may set
- * @param tenantKey - The tenant key on a tenant schema, which every unique includes
+ * @param tenantKey - The tenant key, or every tenant key when the schema has several. A unique that includes them matches when `on` names the other columns. The target keeps the keys, in the unique's order. Naming a key is OKM1104.
  * @returns The plan, or `undefined` for the default `"error"`
  */
-export declare function readConflict(table: Indexed, value: unknown, allow?: ReadonlySet<string>, tenantKey?: string): ConflictPlan | undefined;
+export declare function readConflict(table: Indexed, value: unknown, allow?: ReadonlySet<string>, tenantKey?: string | readonly string[]): ConflictPlan | undefined;
 /**
- * Appends the conflict clause, or wraps a first-or-create insert.
+ * Appends the conflict clause.
+ *
+ * First-or-create is `on conflict do nothing`. It does not read the existing
+ * row here: that lookup is a later statement, so it sees a row another
+ * transaction committed while this insert waited (D246).
  *
  * @param head - `insert into … values …` without `returning`
  * @param returning - ` returning …`, including the leading space
  * @param params - Insert parameters
  * @param plan - Conflict plan
  * @param table - Target table
- * @param returningColumns - Columns in `returning`
- * @param keys - Encoded conflict-key tuples, one per inserted row. Used by `return`
  * @returns Statement text and parameters
  */
-export declare function finishInsert(head: string, returning: string, params: readonly (string | null)[], plan: ConflictPlan, table: Indexed, returningColumns: readonly ColumnModel[], keys: readonly (readonly (string | null)[])[]): {
+export declare function finishInsert(head: string, returning: string, params: readonly (string | null)[], plan: ConflictPlan, table: Indexed): {
+    readonly text: string;
+    readonly params: (string | null)[];
+};
+/**
+ * Reads rows a first-or-create insert did not return.
+ *
+ * The conflict target is the same unique, including the tenant key. A partial
+ * unique on an archivable table only matches the active row.
+ *
+ * @param table - Target table
+ * @param keys - Conflict columns, in constraint order
+ * @param returningColumns - Columns the insert returns, in that order
+ * @param keyRows - Encoded conflict-key tuples that the insert did not return
+ * @returns One select
+ */
+export declare function lookupExisting(table: Indexed, keys: readonly ColumnModel[], returningColumns: readonly ColumnModel[], keyRows: readonly (readonly (string | null)[])[]): {
     readonly text: string;
     readonly params: (string | null)[];
 };

package/dist/runtime/drift.d.ts

@@ -29,3 +29,12 @@ export declare function assertCompatible(pool: DriverPool, schema: QuerySchema,
     readonly catalog?: CatalogArtifact;
     readonly catalogDir?: string;
 }, options: ExecuteOptions | undefined): Promise<void>;
+/**
+ * Directory of `catalog.hash` and `catalog.json`.
+ *
+ * A trailing `/` or `\` is removed so the joined file name is one path.
+ *
+ * @param catalogDir - Directory the caller passed, or the default `.okm`
+ * @returns The directory, without a trailing slash
+ */
+export declare function artifactDir(catalogDir: string | undefined): string;

package/dist/runtime/include.d.ts

@@ -2,14 +2,6 @@
  * LATERAL include planner. Loaded on the first include.
  */
 import { type IncludeHooks, type Plan } from "./plan.js";
-/**
- * Decodes a result that has includes.
- *
- * @param plan - Compiled plan
- * @param rows - Wire rows
- * @param table - Table the call named
- * @returns The call's value
- */
 export declare function decodeIncluded(plan: Plan, rows: readonly (readonly (string | null)[])[], table: string): unknown;
 /** Hooks the read planner calls after this module has loaded. */
 export declare const includeHooks: IncludeHooks;

package/dist/runtime/inflight.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Refuses a positive timeout on a driver that cannot cancel.
+ *
+ * `tx({ timeout })` and `batch({ timeout })` load this with the call. The
+ * connect graph does not. The OKM1120 text loads with the lazy error module.
+ */
+import type { DriverPool } from "../contracts/driver.js";
+/**
+ * Throws OKM1120 when `timeout` is positive and the driver cannot cancel.
+ *
+ * @param pool - Driver the call will use
+ * @param timeout - Milliseconds, when the caller passed one
+ */
+export declare function refuseUncancellableTimeout(pool: DriverPool, timeout: number | undefined): Promise<void>;

package/dist/runtime/page.d.ts

@@ -20,6 +20,9 @@ import { type ArchiveView } from "./plan.js";
  * @param options - `where`, `select`, `orderBy`, `limit`, `include`, and `after`
  * @param mods - Signal and timeout
  * @param view - Archive visibility
+ * @param pin - Endpoint a stream already chose. Absent for `page()`
  * @returns A handle that resolves to `{ items, next }`
  */
-export declare function build(session: Session, table: string, options: object, mods: Mods, view: ArchiveView | undefined): Promise<unknown> & Record<string, unknown>;
+export declare function build(session: Session, table: string, options: object, mods: Mods, view: ArchiveView | undefined, pin?: {
+    name?: string;
+}): Promise<unknown> & Record<string, unknown>;

package/dist/runtime/pg/bun.js

@@ -1,22 +1,27 @@
 import {
   DriverError2
-} from "../../shared/31vm914h.js";
+} from "../../shared/cm3w0ywp.js";
 import {
+  markClientPool,
   open5
-} from "../../shared/k8v5v5wj.js";
+} from "../../shared/x933k9a3.js";
 import {
   BUNSQL_CAPABILITIES,
   readCapability2,
   hasCapability2
-} from "../../shared/cgbamx3e.js";
+} from "../../shared/kb2sdhfb.js";
 import {
   createClient
-} from "../../shared/hf22e0wt.js";
+} from "../../shared/tbrvgw6z.js";
 
 // src/runtime/pg/bun.ts
 function connect(target, options) {
   if (typeof target === "object" && !isPool(target)) {
-    return import("../../shared/nxdp2ze3.js").then((mod) => mod.default(target, options, open5));
+    return import("../../shared/mtaszv5a.js").then((mod) => mod.default(target, options, (config) => {
+      const pool = open5(config);
+      markClientPool(pool);
+      return pool;
+    }));
   }
   const owned = !isPool(target);
   const pool = isPool(target) ? target : open5({
@@ -27,6 +32,8 @@ function connect(target, options) {
     ...options.searchPath !== undefined ? { searchPath: options.searchPath } : {},
     ...options.ssl !== undefined ? { ssl: options.ssl } : {}
   });
+  if (!isPool(target))
+    markClientPool(pool);
   return createClient(options.schema, pool, {
     ownsPool: owned,
     http: options.errors?.http,

package/dist/runtime/pg/pg.js

@@ -1,22 +1,22 @@
 import {
   DriverError2
-} from "../../shared/31vm914h.js";
+} from "../../shared/cm3w0ywp.js";
 import {
   open4
-} from "../../shared/96qcj21c.js";
+} from "../../shared/w79hsckn.js";
 import {
   NODE_POSTGRES_CAPABILITIES,
   readCapability2,
   hasCapability2
-} from "../../shared/cgbamx3e.js";
+} from "../../shared/kb2sdhfb.js";
 import {
   createClient
-} from "../../shared/hf22e0wt.js";
+} from "../../shared/tbrvgw6z.js";
 
 // src/runtime/pg/pg.ts
 function connect(target, options) {
   if (typeof target === "object" && !isPool(target)) {
-    return import("../../shared/nxdp2ze3.js").then((mod) => mod.default(target, options, open4));
+    return import("../../shared/mtaszv5a.js").then((mod) => mod.default(target, options, open4));
   }
   const owned = !isPool(target);
   const pool = isPool(target) ? target : open4({

package/dist/runtime/pg/pglite.d.ts

@@ -2,6 +2,7 @@
  * `connect` for PGlite (`okmodel/pg/pglite`).
  *
  * Opening a database is async. An existing pool is reused and not closed.
+ * Closing that client marks the client closed.
  * A `{ primary, replicas }` object loads the topology module. A replica URL is
  * that endpoint's data directory.
  */

package/dist/runtime/pg/pglite.js

@@ -1,29 +1,30 @@
 import {
   DriverError2
-} from "../../shared/31vm914h.js";
+} from "../../shared/cm3w0ywp.js";
 import {
-  open3
-} from "../../shared/87jvvhnt.js";
+  open3,
+  seal2
+} from "../../shared/81ebdx9p.js";
 import {
   PGLITE_CAPABILITIES,
   readCapability2,
   hasCapability2
-} from "../../shared/cgbamx3e.js";
+} from "../../shared/kb2sdhfb.js";
 import {
   createClient
-} from "../../shared/hf22e0wt.js";
+} from "../../shared/tbrvgw6z.js";
 
 // src/runtime/pg/pglite.ts
 async function connect(target, options) {
   if (typeof target === "object" && !isPool(target)) {
-    return import("../../shared/nxdp2ze3.js").then((mod) => mod.default(target, options, open3));
+    return import("../../shared/mtaszv5a.js").then((mod) => mod.default(target, options, open3));
   }
-  const pool = isPool(target) ? target : await open3({
+  const pool = isPool(target) ? seal2(target) : await open3({
     ...target !== undefined ? { dataDir: target } : {},
     ...options.timeouts !== undefined ? { timeouts: options.timeouts } : {}
   });
   return createClient(options.schema, pool, {
-    ownsPool: !isPool(target),
+    ownsPool: true,
     http: options.errors?.http,
     includeValues: options.errors?.includeValues,
     logger: options.logger,

package/dist/runtime/pg/postgresjs.js

@@ -1,22 +1,22 @@
 import {
   DriverError2
-} from "../../shared/31vm914h.js";
+} from "../../shared/cm3w0ywp.js";
 import {
   open2
-} from "../../shared/krxx77g0.js";
+} from "../../shared/14vx95q4.js";
 import {
   POSTGRESJS_CAPABILITIES,
   readCapability2,
   hasCapability2
-} from "../../shared/cgbamx3e.js";
+} from "../../shared/kb2sdhfb.js";
 import {
   createClient
-} from "../../shared/hf22e0wt.js";
+} from "../../shared/tbrvgw6z.js";
 
 // src/runtime/pg/postgresjs.ts
 function connect(target, options) {
   if (typeof target === "object" && !isPool(target)) {
-    return import("../../shared/nxdp2ze3.js").then((mod) => mod.default(target, options, open2));
+    return import("../../shared/mtaszv5a.js").then((mod) => mod.default(target, options, open2));
   }
   const owned = !isPool(target);
   const pool = isPool(target) ? target : open2({

package/dist/runtime/plan.d.ts

@@ -8,7 +8,7 @@ import { type QueryCode } from "../contracts/error.js";
 import { type OperatorName } from "../dialects/pg/operators.js";
 import { type ColumnModel, type QuerySchema, type RelationModel, type TableModel } from "../dialects/pg/model.js";
 /** A read the caller asked for. */
-export type ReadOp = "find" | "one" | "count" | "exists" | "aggregate";
+export type ReadOp = "find" | "one" | "count" | "exists" | "aggregate" | "descendants" | "ancestors";
 /** Routing constraint chosen before execute. */
 export type RouteConstraint = "auto" | "primary" | "replica";
 /**
@@ -18,13 +18,14 @@ export type RouteConstraint = "auto" | "primary" | "replica";
  */
 export type CallScope = {
     readonly value: string;
+    readonly values?: Readonly<Record<string, string>>;
 } | {
     readonly unscoped: string;
 };
 /** Writes one more `where` condition after the tenant and active-set predicates. */
 export type Keyset = (sink: Sink, alias: string) => void;
 /** Writes the whole statement of a read the planner does not know. */
-export type ReadBuild = (schema: QuerySchema, table: Indexed, sink: Sink, outputs: Built | undefined, call: ReadCall) => void;
+export type ReadBuild = (schema: QuerySchema, table: Indexed, sink: Sink, outputs: Built | undefined, call: ReadCall, hooks?: IncludeHooks) => void;
 /** One read call. `all` is the `.all(reason)` escape for an unbounded read. */
 export type ReadCall = {
     readonly op: ReadOp;
@@ -34,6 +35,8 @@ export type ReadCall = {
     readonly orderBy?: unknown;
     readonly limit?: unknown;
     readonly include?: unknown;
+    /** `find` and `count`. Rewritten to `matches` and `relevance` before SQL. */
+    readonly search?: unknown;
     readonly all?: string;
     /** The `after` cursor of a `page`. The condition joins the others with `and`. */
     readonly after?: Keyset;
@@ -46,6 +49,15 @@ export type ReadCall = {
     readonly timeout?: number;
     /** `"primary"` or `"replica"`. Absent means the router classifies the statement. */
     readonly route?: "primary" | "replica";
+    /**
+     * Endpoint a `.stream()` already chose.
+     *
+     * The first batch leaves `name` empty and the router fills it. Later batches
+     * pass the same object so they stay on that endpoint.
+     */
+    readonly pin?: {
+        name?: string;
+    };
     /** Set by `for()` or `unscoped()`. Absent on a schema with no tenancy. */
     readonly scope?: CallScope;
     /** Inspect lines from the tenancy object. Absent when the schema has no tenancy. */
@@ -94,6 +106,11 @@ export type ScalarOut = {
     readonly at: number;
     readonly decode: ((wire: string) => unknown) | undefined;
 };
+/** One target inside a morph include's JSON value. */
+export type MorphOut = {
+    readonly type: string;
+    readonly fields: readonly ScalarOut[];
+};
 /** A nested include. `at` is a root column for `one` and the JSON column for `many`. */
 export type IncludeOut = {
     readonly name: string;
@@ -101,6 +118,15 @@ export type IncludeOut = {
     readonly at: number;
     readonly fields: readonly ScalarOut[];
     readonly nested: readonly IncludeOut[];
+    /**
+     * Set when the include is a morph.
+     *
+     * The column at `at` is one JSON array, `[type, ...fields]`, or null.
+     */
+    readonly morph?: {
+        readonly typeKey: string;
+        readonly targets: readonly MorphOut[];
+    };
 };
 /** Columns and includes in statement order. */
 export type Outputs = {
@@ -113,6 +139,13 @@ export type IncludeHooks = {
     read(schema: QuerySchema, table: Indexed, include: unknown, all: string | undefined): readonly ParsedInclude[];
     select(include: ParsedInclude, alias: string, sink: Sink, outputs: Built | undefined, column: number): number;
     join(schema: QuerySchema, include: ParsedInclude, sink: Sink, parentAlias: string, alias: string, depth: number): void;
+    /**
+     * Reports whether an include's `where` or `orderBy` needs the operator compiler.
+     *
+     * The root check does not walk includes. This does, and only after the
+     * include planner has loaded.
+     */
+    needsOperator(schema: QuerySchema, call: ReadCall): boolean;
 };
 export type Built = {
     fields: ScalarOut[];
@@ -156,8 +189,13 @@ export type Sink = {
  * @returns Names in a stable order
  */
 export declare function readOptionNames(op: ReadOp): readonly string[];
-/** 0.2 operator SQL. Absent until that module has been imported. */
-type OperatorEmit = (column: ColumnModel, ref: string, name: OperatorName, value: unknown, sink: Sink) => void;
+/**
+ * 0.2 operator SQL. Absent until that module has been imported.
+ *
+ * `order` is set when the operator is an `orderBy` value. `relevance` writes
+ * its direction there; the same operator in `where` is refused by that module.
+ */
+type OperatorEmit = (column: ColumnModel, ref: string, name: OperatorName, value: unknown, sink: Sink, order?: true) => void;
 /**
  * Installs the 0.2 operator compiler.
  *
@@ -176,6 +214,16 @@ export declare function installOperatorSql(emit: OperatorEmit): void;
  * @returns `true` when {@link installOperatorSql} has not run and the read needs it
  */
 export declare function readNeedsOperatorSql(schema: QuerySchema, call: ReadCall): boolean;
+/**
+ * Reports whether `orderBy` holds a `relevance` value.
+ *
+ * Called before the operator compiler has loaded. The include planner uses it
+ * for a related table.
+ *
+ * @param orderBy - The caller's order
+ * @returns `true` when a value is `relevance`
+ */
+export declare function orderHasRelevance(orderBy: unknown): boolean;
 /**
  * Writes `<table> <alias> where <link to parent>` for a to-many relation.
  *
@@ -183,6 +231,18 @@ export declare function readNeedsOperatorSql(schema: QuerySchema, call: ReadCall
  * The caller adds the related table's own predicates after it.
  */
 export declare function emitRelationFrom(schema: QuerySchema, relation: RelationModel, child: Indexed, sink: Sink, parent: string, alias: string, depth: number): void;
+/**
+ * Reports whether a filter needs the operator compiler.
+ *
+ * Equality and text patterns do not. The include planner calls this for a
+ * related table.
+ *
+ * @param table - The table the filter reads
+ * @param value - A `where` value
+ * @param key - The field, when `value` is that field's operand
+ * @returns `true` when the operator compiler has to load
+ */
+export declare function needsOperatorSql(table: Indexed, value: unknown, key?: string): boolean;
 /**
  * Runs registered safety rules before planning.
  *
@@ -249,6 +309,24 @@ export declare function emitJoin(sink: Sink, parent: string, child: string, rela
 export declare function emitWhere(schema: QuerySchema, table: Indexed, where: unknown, sink: Sink, alias: string, depth: number, appended?: boolean, extra?: Keyset): void;
 export declare function emitOrder(table: Indexed, orderBy: unknown, sink: Sink, alias: string): void;
 export declare function emitPrimaryOrder(table: Indexed, sink: Sink, alias: string): void;
+/**
+ * Refuses a hidden field in `where` or `orderBy`.
+ *
+ * `"filter"` is `hidden({ filterable: true })` and is allowed here.
+ * Aggregate loads this on its first call and applies it before the groupBy rule.
+ *
+ * @param column - The field the caller named
+ */
+export declare function refuseHidden(column: ColumnModel): void;
+export declare function emitLimit(call: ReadCall, sink: Sink): void;
+/** One target branch of a morph include. */
+export type ParsedMorphTarget = {
+    readonly type: string;
+    readonly table: string;
+    readonly sql: string;
+    readonly keySql: string;
+    readonly columns: readonly ColumnModel[];
+};
 export type ParsedInclude = {
     readonly name: string;
     readonly relation: RelationModel;
@@ -260,13 +338,35 @@ export type ParsedInclude = {
     /** Index in the projected list that is null when the related row is missing. */
     readonly anchor: number;
     readonly nested: readonly ParsedInclude[];
+    /**
+     * Set when the include is a morph.
+     *
+     * Absent on every other include, so a normal include does not carry it.
+     */
+    readonly morphTo?: {
+        readonly typeKey: string;
+        readonly typeSql: string;
+        readonly idSql: string;
+        readonly targets: readonly ParsedMorphTarget[];
+    };
 };
 export declare function selectedColumns(table: Indexed, select: unknown): readonly ColumnModel[];
 export declare function parseOrder(field: string, value: unknown): {
     readonly dir: "asc" | "desc";
     readonly nulls: "first" | "last";
 };
-export declare function rejectKeys(value: Readonly<Record<string, unknown>>, accepted: readonly string[], where: string): void;
+/**
+ * Refuses a key that `accepted` does not list.
+ *
+ * A read passes `search`. `one` and `exists` then say to use `find` or
+ * `count`, instead of the generic option list.
+ *
+ * @param value - Caller options
+ * @param accepted - Names this call allows
+ * @param where - The call, named in the error
+ * @param search - When set, a rejected `search` key uses the read message
+ */
+export declare function rejectKeys(value: Readonly<Record<string, unknown>>, accepted: readonly string[], where: string, search?: true): void;
 export declare function readLimit(value: unknown): number;
 /**
  * Lets an object through only when the column's codec takes it (OKM1121).
@@ -289,18 +389,15 @@ export declare function quote(name: string): string;
 export declare function list(names: readonly string[]): string;
 export declare function isRecord(value: unknown): value is Record<string, unknown>;
 /**
- * Whether `where` constrains a row.
+ * Throws OKM1121 for an `or()` that is not an array, or for an empty branch.
  *
- * A field value is a leaf. Anything other than `undefined` counts, including
- * `null`, objects, arrays, and operators. The walk does not enter a field value.
- * It enters the where object's own keys, `and`, `or`, and `not` when `not` is
- * the where itself. An `or()` branch with no predicate is OKM1121. `or([])`
- * matches nothing.
+ * The write and archive predicate walk uses the same throw. It lives here
+ * because the read planner throws it too, and that planner stays in this module.
  *
- * @param where - Caller filter, or one `and` / `or` / `not` operand
- * @returns `false` when the filter matches every row
+ * @param empty - `true` when a branch has no predicate
+ * @returns Never
  */
-export declare function effectivePredicate(where: unknown): boolean;
+export declare function orFail(empty: boolean): never;
 /**
  * Records the fix text for a code thrown from a chunk that loads on first use.
  *
@@ -316,6 +413,7 @@ export declare function registerFailFix(code: QueryCode, summary: string): void;
  *
  * @param code - Spec code
  * @param message - What failed
+ * @param fix - Fix sentence for this call. Omitted, the sentence registered for `code` is used
  */
-export declare function fail(code: QueryCode, message: string): never;
+export declare function fail(code: QueryCode, message: string, fix?: string): never;
 export {};

package/dist/runtime/predicate.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Whether a `where` constrains a row.
+ *
+ * Write and archive load this module. A read does not. The walk is the same
+ * one those paths used when it lived in the planner.
+ */
+/**
+ * Whether `where` constrains a row.
+ *
+ * A field value is a leaf. Anything other than `undefined` counts, including
+ * `null`, objects, arrays, and operators. The walk does not enter a field value.
+ * It enters the where object's own keys, `and`, `or`, and `not` when `not` is
+ * the where itself. An `or()` branch with no predicate is OKM1121. `or([])`
+ * matches nothing.
+ *
+ * @param where - Caller filter, or one `and` / `or` / `not` operand
+ * @returns `false` when the filter matches every row
+ */
+export declare function effectivePredicate(where: unknown): boolean;

package/dist/runtime/read-stream.d.ts

@@ -1,26 +1,23 @@
 /**
- * Server-side read cursor.
+ * Keyset batches for `.stream()` (spec §10).
  *
  * Loaded the first time `.stream()` is iterated. A find that is only awaited
- * does not load it.
+ * does not load it. Each batch is one finished `page` query: fetch, yield,
+ * then fetch the next. A `break` does not hold a connection. A server cursor
+ * is not used, so the driver `stream` flag is not read.
  */
-import type { DriverPool } from "../contracts/driver.js";
-import { OkmError, type ErrorStatuses } from "../contracts/error.js";
-import { type Plan, type ReadCall } from "./plan.js";
+import { OkmError } from "../contracts/error.js";
+import { type Mods, type Session } from "./client.js";
+import { type ArchiveView, type ReadCall } from "./plan.js";
 /**
- * Yields decoded rows from the driver's stream.
+ * Yields decoded rows, one keyset batch at a time.
  *
  * @param session - Connected pool and HTTP statuses
- * @param call - The read being streamed
- * @param prepare - Compiles the statement on first use
+ * @param call - The find being streamed
+ * @param mods - `.all` reason and presets
+ * @param view - Archive visibility
+ * @param batchOptions - `{ batch }`, or omitted for {@link DEFAULT_BATCH}
  * @param log - Attaches the session logger and returns the error
  * @returns One row at a time
  */
-export declare function streamRows(session: {
-    readonly connected: Promise<void>;
-    readonly pool: DriverPool;
-    readonly http: ErrorStatuses | undefined;
-}, call: ReadCall, prepare: () => Promise<{
-    readonly plan: Plan;
-    readonly params: readonly (string | null)[];
-}>, log: (error: OkmError) => OkmError): AsyncIterable<unknown>;
+export declare function streamRows(session: Session, call: ReadCall, mods: Mods, view: ArchiveView | undefined, batchOptions: object | undefined, log: (error: OkmError) => OkmError): AsyncIterable<unknown>;