@vibeorm/runtime 2.6.0 → 3.0.0

package/dist/keyset-iterator.d.ts

@@ -27,7 +27,12 @@
 import type { SqlDialect } from "@vibeorm/sql";
 import type { KeysetTimestampPrecision } from "./keyset.ts";
 import type { RuntimeMeta } from "./model-meta.ts";
-/** The one method this iterator needs — a model delegate satisfies it. */
+/**
+ * The one method this iterator needs — a model delegate satisfies it. A
+ * wrapper that adds filters to `where` must return the delegate's result array
+ * itself: that array carries the query binding the engine checks, and a copy
+ * (`rows.map(…)`) loses it, so the next page is refused (`keyset-token-query`).
+ */
 export type KeysetPageSource = {
     readonly findMany: (args: Record<string, unknown>) => Promise<Record<string, unknown>[]>;
 };
@@ -43,11 +48,16 @@ export type KeysetIterateOptions = {
     readonly select?: Record<string, unknown>;
     readonly omit?: Record<string, unknown>;
     readonly include?: Record<string, unknown>;
-    /** Resume from a checkpoint minted by a previous run over the SAME ordering. */
+    /**
+     * Resume from a checkpoint minted by a previous run over the SAME ordering,
+     * filters and scope — a checkpoint from another `where` or `scope` is refused.
+     */
     readonly after?: string;
     /** Consumer cancellation: stops future page fetches; ends iteration cleanly. */
     readonly signal?: AbortSignal;
     readonly timestampPrecision?: KeysetTimestampPrecision;
+    /** The caller's owner key (a user or tenant id) the checkpoints are bound to. */
+    readonly scope?: string;
 };
 export type KeysetIterator = AsyncIterableIterator<Record<string, unknown>> & {
     /** Always present: `break` and an exception both have to be able to release the traversal. */

package/dist/keyset.d.ts

@@ -7,17 +7,23 @@
  * right place. That is the whole difference from the legacy `cursor`, which
  * addresses a row by a unique key and is left untouched by this module.
  *
- * Two rules this module exists to enforce:
+ * Three rules this module exists to enforce:
  *   - a position is only meaningful against ONE effective ordering, so the
  *     token carries that ordering's signature and a mismatch is refused loudly
  *     rather than silently paginating the wrong sequence;
+ *   - a position is only meaningful for the QUERY it came from, so the token
+ *     also carries a digest of the normalized `where` (including the filters
+ *     `$scoped` / `$withPolicy` add) and of the caller's optional
+ *     `keyset.scope`, and a mismatch is refused the same way;
  *   - a position's values are encoded LOSSLESSLY per scalar type — never
  *     through a float64 detour and never from a rounded display value.
  *
- * The token is ENCODED, not encrypted: anyone holding it can read the ordering
- * values inside. It is also NOT an authorization credential — it selects a
- * position, never a row; every query consuming one still compiles the caller's
- * own `where` and keeps its `$scoped` / `$withPolicy` / RLS filters.
+ * The token is ENCODED, not encrypted: anyone holding it can read the model,
+ * the ordering and the ordering values inside, and can confirm a guessed
+ * filter or scope against the digest. It is also NOT an authorization
+ * credential — it selects a position, never a row; every query consuming one
+ * still compiles the caller's own `where` and keeps its `$scoped` /
+ * `$withPolicy` / RLS filters.
  */
 import type { SqlDialect } from "@vibeorm/sql";
 import type { FieldMeta, ModelMeta } from "./model-meta.ts";
@@ -28,6 +34,11 @@ export type KeysetNulls = "first" | "last";
  * millisecond-exact values. See {@link compileKeysetOrderPlan}.
  */
 export type KeysetTimestampPrecision = "milliseconds";
+/**
+ * The query a token is bound to: a digest of the normalized `where` and the
+ * caller's optional `keyset.scope`. See {@link keysetQueryBinding}.
+ */
+export type KeysetQueryBinding = string;
 /** One order term, already resolved by the query builder. */
 export type KeysetOrderInput = {
     readonly field: FieldMeta;
@@ -51,7 +62,11 @@ export type KeysetOrderPlan = {
 };
 /** Per-scalar lossless encoding tag stored in the token. */
 export type KeysetValueTag = "s" | "i" | "b" | "f" | "c" | "t" | "o" | "y";
-/** Token version. A token from another version is refused, never guessed at. */
+/**
+ * Token version. A token from another version is refused, never guessed at —
+ * including version 1, minted before tokens were bound to their query: it
+ * cannot prove which filters it came from.
+ */
 export declare const KEYSET_TOKEN_VERSION: number;
 /** Token prefix — `vk` for "vibe keyset", then the version. */
 export declare const KEYSET_TOKEN_PREFIX: string;
@@ -97,8 +112,44 @@ export declare function keysetRowValues(params: {
     plan: KeysetOrderPlan;
     row: Readonly<Record<string, unknown>>;
 }): readonly unknown[];
+/**
+ * The query a keyset token is bound to: the first 128 bits (hex) of a SHA-256
+ * over the canonical `where` and the caller's optional scope.
+ *
+ * `where` is the filter the ENGINE compiles — including the predicates
+ * `$scoped` and `$withPolicy` merge into it — so a token minted in one tenant's
+ * handle is refused in another's without any caller scope. `scope` is the
+ * caller's own owner key (a user or tenant id) for cases the filters do not
+ * show, e.g. native RLS context. A digest is not a secret: a holder can
+ * confirm a guessed filter value or scope against it.
+ *
+ * @example
+ * keysetQueryBinding({ where: { status: "OPEN" }, scope: userId })
+ */
+export declare function keysetQueryBinding(params: {
+    where: unknown;
+    scope?: string;
+}): KeysetQueryBinding;
+/**
+ * Hidden channel on a `findMany` result that carried keyset arguments: the
+ * binding the ENGINE computed for it. The iterator mints its checkpoints with
+ * it, so a source that merges filters into `where` (`$scoped`, `$withPolicy`)
+ * yields checkpoints that source accepts. Non-enumerable, never serialized.
+ */
+export declare const KEYSET_RESULT_BINDING: unique symbol;
+/** Attach the engine's binding to a result array (see {@link KEYSET_RESULT_BINDING}). */
+export declare function attachKeysetBinding<T extends object>(params: {
+    rows: T;
+    binding: KeysetQueryBinding;
+}): T;
+/** The engine's binding a result array carries, if any. */
+export declare function keysetBindingOf(params: {
+    rows: unknown;
+}): KeysetQueryBinding | undefined;
 /**
  * Mint a continuation token from a row that carries every ordering value.
+ * `binding` is the query it continues ({@link keysetQueryBinding}); omitted,
+ * it is the unfiltered, unscoped query.
  *
  * The row must contain each ordering field — a missing one is refused rather
  * than encoded as a null, because a silently null position paginates the wrong
@@ -108,15 +159,19 @@ export declare function keysetRowValues(params: {
 export declare function encodeKeysetToken(params: {
     plan: KeysetOrderPlan;
     row: Readonly<Record<string, unknown>>;
+    binding?: KeysetQueryBinding;
 }): string;
 /**
- * Read a token back into ordering values, validating version, model and the
- * effective order. A token minted under a different ordering (or for another
- * model, or by a future version) is refused with a precise, non-guessing
- * error — never used to paginate a sequence it does not describe.
+ * Read a token back into ordering values, validating version, model, the
+ * effective order and the query binding. A token minted under a different
+ * ordering, for different filters or another scope (or for another model, or
+ * by another version) is refused with a precise, non-guessing error — never
+ * used to paginate a sequence it does not describe. `binding` is the query
+ * presenting it; omitted, the unfiltered, unscoped query.
  */
 export declare function decodeKeysetToken(params: {
     plan: KeysetOrderPlan;
     token: string;
+    binding?: KeysetQueryBinding;
 }): readonly unknown[];
 //# sourceMappingURL=keyset.d.ts.map

package/dist/lateral-projection.d.ts

@@ -1,5 +1,6 @@
 import type { ColRef } from "@vibeorm/sql";
-import type { RelationTreeNode } from "./relation-plan.ts";
+import type { FieldMeta } from "./model-meta.ts";
+import type { RelationSelection, RelationTreeNode } from "./relation-plan.ts";
 /** Child table qualifier, scoped independently inside each lateral. */
 export declare const LATERAL_CHILD_ALIAS: string;
 /** Shared SQL/decode descriptor. Its order is the resolved physical projection, never model order. */
@@ -11,6 +12,35 @@ export type LateralProjection = {
 export declare function lateralProjection(params: {
     node: RelationTreeNode;
 }): LateralProjection;
+/**
+ * B3 (SQL review): a list column of BigInt/Decimal/Bytes has no faithful JSON
+ * wire form, so the lateral projection refuses it. ONE predicate, read by the
+ * refusal ({@link lateralProjection}) and by the R-02 nesting rule
+ * ({@link nestedLateralSelection}), so a level that would refuse never nests.
+ */
+export declare function lateralRefusesField(params: {
+    field: FieldMeta;
+}): boolean;
+/**
+ * R-02 (round-trip campaign): the deeper level of a `"join"` relation node that
+ * rides INSIDE its lateral — each child carries one more positional slot per
+ * nested relation (`__rel_<name>`, its own nested lateral's JSON) — or `null`
+ * when that level keeps today's batched `"query"` loads. The builder (nesting
+ * the SQL) and the loader (decoding the slots) both read THIS function, so
+ * the payload and its decoder can never disagree. Cached per node.
+ *
+ * A level nests only in the shapes the campaign measured (EPIC 1 spike, EPIC 5
+ * A/B): foreign-key links (to-many FK, to-one either side), plain column
+ * orders, no `_count` at that level. Implicit many-to-many children and counts
+ * below level 1 keep the query strategy (with R-03a's derived counts) —
+ * unmeasured, so unchanged. (An include's orderBy is validated to scalars
+ * upstream; the order check here is defensive.) A level whose projection the
+ * lateral would refuse ({@link lateralRefusesField}, e.g. a `BigInt[]` column)
+ * keeps the query strategy too — before R-02 it loaded through it (RV4 B1).
+ */
+export declare function nestedLateralSelection(params: {
+    node: RelationTreeNode;
+}): RelationSelection | null;
 /**
  * PG-3 (SQL review round 2): order fields the lateral subselect must project
  * HIDDEN — the aggregate's explicit `ORDER BY "__sub".…` (N2) can only

package/dist/model-meta.d.ts

@@ -152,6 +152,18 @@ export type RuntimeMeta = {
      */
     readonly extensionOperators?: ReadonlyMap<string, ExtensionOperatorFn>;
 };
+/**
+ * The postgres type of a Json field's column (of its elements, for a list):
+ * `json` for `@db.Json` in any letter case — `.prisma` files say `@db.Json`,
+ * `db pull` writes `@db.json` and migrate accepts both — else `jsonb`. The
+ * ONE rule for every json/jsonb decision in the runtime: filters, list
+ * operands, order/distinct casts, write cells and the nested-write fold.
+ * Migrate normalizes the same annotation case-insensitively on its own
+ * (`normalizeNativeType`). Meaningful on postgres only.
+ */
+export declare function jsonStorageOf(params: {
+    field: FieldMeta;
+}): "json" | "jsonb";
 /**
  * Delegate key for a model name: the first character lowercased, nothing else
  * (the Prisma convention — `User` → `user`, `URLMap` → `uRLMap`). Keeping the

package/dist/nested-fold.d.ts

@@ -0,0 +1,98 @@
+/**
+ * A nested write as ONE statement (round-trip campaign EPIC F, narrow scope).
+ *
+ * A top-level `create`, or an `update` with scalar data, whose ONLY nested
+ * operation is ONE homogeneous FK-side list of scalar children (`create: [...]`
+ * or `createMany`) runs today as parent statement + child statement inside a
+ * transaction (BEGIN · parent · children · COMMIT; a savepoint inside a
+ * caller's transaction). On a dialect with a statement-chain strategy
+ * (postgres: pg, bun, pglite) it is one statement instead:
+ *
+ * ```sql
+ * WITH "__vibe_parent" AS (INSERT … RETURNING … | UPDATE … WHERE <full where> RETURNING …),
+ *      "__vibe_children" AS (INSERT INTO child (cols…, fk) SELECT src.cols…, "__vibe_parent".key
+ *                            FROM "__vibe_parent" CROSS JOIN (<typed VALUES rows>) AS src RETURNING …)
+ * SELECT parent row, CASE WHEN <a step returned nothing> THEN <fail> ELSE <rows changed> END
+ * ```
+ *
+ * Every child takes the parent key FROM the parent step, so an empty parent
+ * writes no child and a child BEFORE trigger sees the parent (review O-07).
+ * The in-statement veto (shape gate, `report-epic-f.md` §1) makes the
+ * STATEMENT fail when the parent step is empty (an UPDATE that matched
+ * nothing, a write a trigger suppressed) or, for a `create` list, when the
+ * child step returned fewer rows than items (EPIC W: one item → no row; N
+ * items → fewer than N, the `minRows` veto) — exactly where today's flow raises
+ * not-found. The database then undoes every effect, trigger writes included,
+ * so the statement needs no transaction at top level and no savepoint inside
+ * one (decision D1). The runtime turns the veto back into today's error.
+ *
+ * `createMany` carries no child veto: it never checks its row count (a
+ * trigger-suppressed child is silently skipped, like the top-level
+ * createMany's count).
+ *
+ * This module only BUILDS the statement (pure). Eligibility is a closed
+ * allowlist; anything else returns `null` and the whole call keeps today's
+ * path. Engine-level exclusions (native RLS, `@@policy` schemas) are the
+ * caller's.
+ */
+import { VibeError } from "@vibeorm/schema";
+import type { ChainStatement, SqlDialect, SqlStatement } from "@vibeorm/sql";
+import type { ModelMeta, RuntimeMeta } from "./model-meta.ts";
+import type { QueryMethod } from "./query-builder.ts";
+/** Step names and the row-source alias. Models whose table starts with `__vibe_` never fold. */
+export declare const NESTED_FOLD_NAMES: {
+    readonly parent: string;
+    readonly children: string;
+    readonly source: string;
+};
+/** The folded statement plus what the runtime needs to read its result or its veto. */
+export type NestedFold = {
+    readonly statement: ChainStatement;
+    /** Model whose row the statement returns (the parent). */
+    readonly model: ModelMeta;
+    /** Veto token → today's error for that outcome. */
+    readonly vetoes: ReadonlyMap<string, () => VibeError>;
+    /** The per-call nonce every veto marker carries (a user value cannot know it). */
+    readonly nonce: string;
+};
+/**
+ * Fold the call into one statement, or return `null` (today's path). Builds
+ * the same plans today's flow builds (`plan`), so validation, defaults and
+ * codecs are unchanged; plan-time refusals raise today's errors (a child's now
+ * before any SQL, see below).
+ *
+ * Allowlist: statement-chain dialect with RETURNING; exactly ONE nested op, an
+ * FK-side to-many list (`toManyFk`) on a different table, not `__vibe_`
+ * prefixed; one verb — `create` (one or more items) or `createMany` without
+ * `skipDuplicates`; at least one item, none with nested writes, all defining
+ * the same fields; at most {@link RUNTIME_CONFIG}`.nestedFoldMaxChildren`
+ * items; no protected write scope on the verbs; an update must carry scalar
+ * data; one child statement (no parameter-budget chunks), no DEFAULT cell, no
+ * Json cell on a non-`jsonb` column, no column mixing `dbNow()` with values,
+ * `dbNow()` only on a timestamptz/timestamp/date column; no raw SQL fragment
+ * anywhere.
+ *
+ * The child plan is compiled BEFORE any SQL is sent (EPIC F decision 1): a
+ * child that validation refuses throws here, so it now outranks a parent
+ * database error (today's path compiled it after the parent statement ran).
+ */
+export declare function buildNestedFold(params: {
+    dialect: SqlDialect;
+    meta: RuntimeMeta;
+    model: ModelMeta;
+    method: "create" | "update";
+    data: Record<string, unknown>;
+    where?: Record<string, unknown>;
+    skipUpdatedAt?: boolean;
+    /** Per-call random nonce bound into every veto marker (review RV3 MN-3). */
+    nonce: string;
+    plan: (params: {
+        model: string;
+        method: QueryMethod;
+        args: Record<string, unknown>;
+    }) => {
+        statement: SqlStatement;
+        batch?: readonly SqlStatement[];
+    };
+}): NestedFold | null;
+//# sourceMappingURL=nested-fold.d.ts.map

package/dist/nested-update-data.d.ts

@@ -0,0 +1,11 @@
+import type { ModelMeta } from "./model-meta.ts";
+/** Resolve only a nested update's body, consistently across execution and argument walkers. */
+export declare function resolveNestedUpdateData(params: {
+    model: ModelMeta;
+    isList: boolean;
+    operand: Record<string, unknown>;
+}): {
+    readonly data: Record<string, unknown>;
+    readonly wrapped: boolean;
+};
+//# sourceMappingURL=nested-update-data.d.ts.map

package/dist/nested-writes.d.ts

@@ -1,6 +1,7 @@
 import type { SqlDialect, SqlStatement } from "@vibeorm/sql";
 import type { ModelMeta, RuntimeMeta } from "./model-meta.ts";
 import type { QueryMethod } from "./query-builder.ts";
+import type { RelationLink } from "./relation-plan.ts";
 export type ClientRowLike = Record<string, unknown>;
 /**
  * Executes ORM statements against ONE adapter (plain or transactional).
@@ -14,6 +15,12 @@ export type StatementRunner = {
         method: QueryMethod;
         args: Record<string, unknown>;
     }) => Promise<ClientRowLike>;
+    /** `single`, but `null` when the where matched no row — the caller raises its own not-found. */
+    readonly singleOrNull: (params: {
+        model: string;
+        method: QueryMethod;
+        args: Record<string, unknown>;
+    }) => Promise<ClientRowLike | null>;
     readonly rows: (params: {
         model: string;
         method: QueryMethod;
@@ -36,7 +43,10 @@ export type WriteContext = {
     readonly dialect: SqlDialect;
     /** Runner on the client's current adapter (may already be transactional). */
     readonly run: StatementRunner;
-    /** Runs `fn` with a runner bound to a (nested) transaction. */
+    /**
+     * Runs `fn` with a runner bound to a (nested) transaction — or, inside a
+     * transaction an array batch or the ORM call already owns, on that one.
+     */
     readonly transactional: <T>(fn: (run: StatementRunner) => Promise<T>) => Promise<T>;
 };
 /** Does this `data` object carry nested relation operations? */
@@ -44,6 +54,31 @@ export declare function hasNestedWrites(params: {
     model: ModelMeta;
     data: unknown;
 }): boolean;
+/** One relation's nested-write verbs, as `partitionData` found them. */
+export type NestedOp = {
+    readonly name: string;
+    readonly link: RelationLink;
+    readonly verbs: Record<string, unknown>;
+};
+/** Split write data into scalar columns and nested relation ops (validating verb names). */
+export declare function partitionData(params: {
+    meta: RuntimeMeta;
+    model: ModelMeta;
+    data: Record<string, unknown>;
+    phase: "create" | "update";
+}): {
+    scalars: Record<string, unknown>;
+    ops: NestedOp[];
+};
+/** A verb's operand as its list of object items (refusing an array on a to-one relation). */
+export declare function toItems(params: {
+    op: NestedOp;
+    verb: string;
+    operand: unknown;
+}): Record<string, unknown>[];
+/** Every row defines the same key set — the batching precondition (see below). */
+/** Whether every row defines the same keys (an undefined value counts as absent). */
+export declare function sameDefinedKeys(rows: readonly Record<string, unknown>[]): boolean;
 /**
  * `create` with nested relation operations. Returns the parent row as the
  * INSERT produced it (relation loading/projection are the client's follow-up).
@@ -63,5 +98,7 @@ export declare function updateWithNested(params: {
     model: ModelMeta;
     where: Record<string, unknown>;
     data: Record<string, unknown>;
+    /** Suppress only the parent's automatic timestamp, never the child's. */
+    skipUpdatedAt?: boolean;
 }): Promise<ClientRowLike>;
 //# sourceMappingURL=nested-writes.d.ts.map

package/dist/query-builder.d.ts

@@ -32,6 +32,17 @@ export type AggregateSpec = {
 };
 /** How included relations are fetched. */
 export type RelationStrategy = "query" | "join";
+/**
+ * R-03b: one level-1 `_count` entry the root find statement projects as a
+ * correlated `COUNT(*)` column, so the loader reads it off the row instead of
+ * sending its grouped count statement.
+ */
+export type EmbeddedCount = {
+    /** The counted relation (`posts`) — the `_count` key. */
+    readonly name: string;
+    /** The root row's column carrying the count (`__vibe_count_0`), deleted after reading. */
+    readonly column: string;
+};
 /**
  * A built query plus everything the client needs after execution. The plan is
  * data only: the client decides how to run it.
@@ -65,7 +76,9 @@ export type QueryPlan = {
     /**
      * How relations load. With `"join"` on a find method the base statement IS
      * the lateral statement (level-1 relations ride along as JSON columns);
-     * deeper levels always fall back to `"query"` batches (v1 semantics).
+     * deeper levels nest inside them where {@link nestedLateralSelection}
+     * admits (R-02, `nestedLaterals`) and otherwise fall back to `"query"`
+     * batches (v1 semantics).
      */
     readonly relationStrategy: RelationStrategy;
     /** True when `take` produced a LIMIT. */
@@ -102,6 +115,18 @@ export type QueryPlan = {
      * update 0, so its number is not a row count at all.
      */
     readonly upsertRowCount?: number;
+    /**
+     * find methods under the `"query"` strategy only (R-03b): the level-1
+     * `_count` entries this statement already projects. Absent when none.
+     */
+    readonly embeddedCounts?: readonly EmbeddedCount[];
+    /**
+     * find methods under `"join"` only (R-02): the lateral statement nests the
+     * deeper relation levels {@link nestedLateralSelection} admits inside the
+     * depth-1 laterals, so the loader decodes them from the payload instead of
+     * querying them. Absent when the statement nests nothing.
+     */
+    readonly nestedLaterals?: boolean;
     /** The caller's `select`, replayed on that re-select. */
     readonly selectArg: Readonly<Record<string, unknown>> | null;
     /** How to decode aggregate/groupBy/count-select rows; `null` elsewhere. */
@@ -110,26 +135,20 @@ export type QueryPlan = {
     readonly groupByFields: readonly string[] | null;
     /** Negative `take`: the SQL ordering was flipped; re-reverse rows after fetch. */
     readonly reverseRows: boolean;
-    /**
-     * `distinct` + an explicit user orderBy (N1, board #22): the arrangement
-     * DISTINCT ON needs demotes the user's order behind the distinct fields, so
-     * the client re-sorts the FINAL rows by these keys — Prisma's presentation
-     * order, on every dialect. `nulls` is resolved at build time to the
-     * dialect's own NULL placement so the re-sort mirrors what the SQL order
-     * would have produced. `null` when no re-sort is needed.
-     */
-    readonly resortBy: readonly ResortKey[] | null;
-};
-/** One client-side re-sort key (see QueryPlan.resortBy). */
-export type ResortKey = {
-    readonly field: string;
-    readonly direction: "asc" | "desc";
-    readonly nulls: "first" | "last";
-    /** B4 mirror: Decimal ranks numerically — the SQL side ordered a number. */
-    readonly decimal: boolean;
 };
 /** Column alias for COUNT(*) — postgres and sqlite/mysql name it differently otherwise. */
 export declare const COUNT_ALIAS: string;
+/**
+ * A model's full row projection as SQL text, every column qualified by
+ * `qualify` and read in the form `findMany` reads it ({@link projectionRef}:
+ * postgres `Float[]`/`Json[]` as `::text`). For statements built outside the
+ * query builder — extension SQL — whose rows decode through the model's plan.
+ */
+export declare function compileProjection(params: {
+    dialect: SqlDialect;
+    model: ModelMeta;
+    qualify: string;
+}): string;
 /**
  * Compile a Prisma-shaped where object; `undefined` when it constrains nothing.
  *
@@ -167,6 +186,19 @@ export declare function compileSelect(params: {
     select: unknown;
     allowEmpty?: boolean;
 }): string[];
+/**
+ * Expand the compound-key sugar the GENERATED `…WhereUniqueInput` emits:
+ * `{ projectId_userId: { projectId, userId } }` becomes
+ * `{ projectId: …, userId: … }`, so a composite `@@id`/`@@unique` compiles
+ * exactly like the flat form. Models without a composite key (the common case)
+ * return their where object untouched, allocation-free.
+ */
+export declare function expandCompoundWhere(params: {
+    model: ModelMeta;
+    where: Record<string, unknown>;
+    /** Argument label for errors — `"where"` (default) or `"cursor"` (#4). */
+    what?: string;
+}): Record<string, unknown>;
 /**
  * Does this (already compound-expanded) where address at most one row? The
  * predicate `assertUniqueWhere` enforces, exported so a batch that stands in
@@ -206,6 +238,22 @@ export declare function upsertUsesNativeStatement(params: {
     model: ModelMeta;
     args: Record<string, unknown>;
 }): boolean;
+/**
+ * The rows split into the runs `createMany` inserts as one column group each,
+ * in INPUT order — or `null` when grouping would reorder them. A dialect with
+ * the per-row DEFAULT keyword keeps every row in one VALUES list (one run). On
+ * sqlite rows group by their COMPILED column set in first-appearance order
+ * ({@link compileCreateRows}), so item order survives only when every group is
+ * one contiguous run of items; otherwise autoincrement ids would be handed out
+ * of item order. Compiles each row exactly as the plan will (app defaults and
+ * `@updatedAt` included), so a row that cannot compile throws the plan's own
+ * error here.
+ */
+export declare function createManyRowRuns<T>(params: {
+    dialect: SqlDialect;
+    model: ModelMeta;
+    data: readonly T[];
+}): readonly (readonly T[])[] | null;
 /**
  * Compile a raw `orderBy` argument into keyset order inputs — the ONE parsing
  * path the iterator and the `after` bound share, so a token's signature can
@@ -217,12 +265,17 @@ export declare function compileKeysetOrderInputs(params: {
     model: ModelMeta;
     orderBy: unknown;
 }): KeysetOrderInput[];
-/** The `keyset: { … }` per-query options bag. */
+/**
+ * The `keyset: { … }` per-query options bag: `timestampPrecision` (the
+ * millisecond assertion) and `scope` (the caller's owner key, mixed into the
+ * token's query binding).
+ */
 export declare function parseKeysetOptions(params: {
     model: ModelMeta;
     value: unknown;
 }): {
     timestampPrecision?: KeysetTimestampPrecision;
+    scope?: string;
 };
 /** The column a relation's JSON payload is exposed under in the outer row. */
 export declare function lateralColumnAlias(params: {
@@ -264,5 +317,11 @@ export declare function buildQuery(params: {
     args?: Record<string, unknown>;
     defaultRelationStrategy?: RelationStrategy;
     clientOptions?: BuilderClientOptions;
+    /**
+     * R-03b: `false` keeps level-1 counts out of the statement. A write's
+     * read-back (dialects without RETURNING) plans a find whose counts the
+     * write's own finalize loads with the grouped statement (RV4 m1).
+     */
+    embedCounts?: boolean;
 }): QueryPlan;
 //# sourceMappingURL=query-builder.d.ts.map

package/dist/read-only.d.ts

@@ -105,6 +105,11 @@ export type LazyOperationBridge = {
         reason: unknown;
     }) => void;
 };
+/** @internal Inherit authentic classifier provenance without exposing a marker property. */
+export declare function inheritReadOnlyReceiver(params: {
+    source: unknown;
+    target?: object;
+}): boolean;
 /**
  * Attach `$readOnly` to a built client. Called once per client build; the
  * facade itself is built lazily on the first call, so it always sees the FINAL

package/dist/relation-key.d.ts

@@ -1,3 +1,5 @@
+import type { KeyTableMember, SqlDialect } from "@vibeorm/sql";
+import type { FieldMeta } from "./model-meta.ts";
 /** Compare decoded relation keys by value, including DateTime milliseconds and binary bytes. */
 export declare function relationValueKey(params: {
     value: unknown;
@@ -20,4 +22,52 @@ export declare function relationValueKey(params: {
 export declare function relationTupleKey(params: {
     values: readonly unknown[];
 }): string | null;
+/** EPIC R: alias of the key table (a `KeyTableJoin` from `@vibeorm/sql`). */
+export declare const KEY_TABLE_ALIAS: string;
+/** EPIC R: the key table's ordinal column — the index of the key row the database paired. */
+export declare const KEY_ORDINAL_ALIAS: string;
+/**
+ * Must the DATABASE decide which keys are equal?
+ *
+ * Comparing decoded keys in JavaScript is exact bytes. That is the database's
+ * own equality only where text compares bytes: postgres and sqlite
+ * (`conflictKeyEquality.textIsBinaryByDefault`). Mysql's default
+ * `utf8mb4_0900_ai_ci` equates `acme`/`Acme`/`ACME` and `cafe`/`Café`, and its
+ * PAD SPACE collations equate `x ` and `x` — the foreign key, the join table and
+ * every `IN` accept such a key, so an exact JavaScript comparison disagrees
+ * with the database (EPIC R for includes, release 3.0 D4 for nested writes).
+ *
+ * Any text (`String`) member switches the WHOLE tuple to the key table. A
+ * declared `@collation` does not opt out: it is the schema's claim, and
+ * migrate never alters an existing column's collation, so the physical column
+ * can still fold. Non-text keys (Int, BigInt, DateTime, Bytes, …) read back
+ * canonically on both sides and keep the exact comparison.
+ *
+ * Postgres (release 3.0 lane n, review "Fixes 2" and "Fixes 3"): a `citext`
+ * key member switches the tuple too — citext compares case-insensitively, and
+ * a citext foreign key or join column stores `acme` under the key `Acme`.
+ * Every other postgres key, and every sqlite key, compares by value, and its
+ * SQL is byte-identical to before.
+ */
+export declare function associatesInDatabase(params: {
+    dialect: SqlDialect;
+    fields: readonly FieldMeta[];
+}): boolean;
+/**
+ * How a key member binds in the key table, on the dialect that runs it
+ * ({@link associatesInDatabase}): postgres in {@link postgresKeyTableMember},
+ * mysql below.
+ */
+export declare function keyTableMember(params: {
+    dialect: SqlDialect;
+    field: FieldMeta;
+}): KeyTableMember;
+/**
+ * The key-table ordinal a row carries, or `null` when it is not one. The
+ * ordinals are integer literals: they arrive as numbers or, under mysql's
+ * `bigNumberStrings`, as digit strings.
+ */
+export declare function keyOrdinalOf(params: {
+    raw: unknown;
+}): number | null;
 //# sourceMappingURL=relation-key.d.ts.map