@vibeorm/runtime 1.3.0 → 2.0.0-alpha.10

package/dist/query-builder.d.ts

@@ -0,0 +1,271 @@
+/**
+ * The query builder: `{ model, method, args }` → a SQL AST statement, purely.
+ *
+ * Nothing here touches a database, a clock-free input always produces the same
+ * statement, and every branch is reachable from the query catalog
+ * (`tests/query-catalog/`) — which pins the rendered SQL for all three dialects
+ * and exports it to the reviewable root `sql-catalog.md`.
+ *
+ * Division of labour:
+ *   - shapes and SQL text live in @vibeorm/sql (this file never writes SQL),
+ *   - value transport lives in codecs.ts (this file never coerces),
+ *   - dialect gaps become VIBE_UNSUPPORTED_CAPABILITY here, at build time,
+ *     which is the earliest knowable moment for a query-level feature,
+ *   - bad input becomes VIBE_VALIDATION naming the model, field and operator.
+ */
+import type { OrderByColumn, SqlDialect, SqlExpr, SqlStatement } from "@vibeorm/sql";
+import type { KeysetOrderInput } from "./keyset.ts";
+import type { ModelMeta, RuntimeMeta } from "./model-meta.ts";
+import type { RelationSelection, RelationTreeNode } from "./relation-plan.ts";
+/** Every ORM method the query builder builds SQL for. */
+export type QueryMethod = "findMany" | "findFirst" | "findUnique" | "create" | "createMany" | "createManyAndReturn" | "update" | "updateMany" | "updateManyAndReturn" | "upsert" | "upsertMany" | "delete" | "deleteMany" | "count" | "aggregate" | "groupBy";
+/** Client-level options that shape SQL (subset of ClientOptions the builder needs). */
+export type BuilderClientOptions = {
+    /** Append the primary key to ORDER BY when no explicit orderBy was given (default false). */
+    readonly defaultOrderByPk?: boolean;
+    /** Append the primary key as a `distinct` tie-breaker for determinism (default true). */
+    readonly distinctOrderByPk?: boolean;
+};
+/** The five aggregate selector keys, in the deterministic order they project. */
+export type AggregateKey = "_count" | "_avg" | "_sum" | "_min" | "_max";
+/**
+ * One projected aggregate. `field: null` is `_all` (COUNT(*)). The alias is the
+ * deterministic `<key>__<selector>` scheme (`_count___all`, `_avg__score`) —
+ * results are read back by construction from these aliases, never parsed.
+ */
+export type AggregateSelection = {
+    readonly key: AggregateKey;
+    readonly field: string | null;
+    readonly alias: string;
+};
+/** Everything the client needs to decode an aggregate/groupBy/count-select row. */
+export type AggregateSpec = {
+    readonly selections: readonly AggregateSelection[];
+    /** `_count: true` — the result's `_count` is a bare number, not an object. */
+    readonly countShorthand: boolean;
+};
+/** How included relations are fetched. */
+export type RelationStrategy = "query" | "join";
+/**
+ * A built query plus everything the client needs after execution. The plan is
+ * data only: the client decides how to run it.
+ */
+export type QueryPlan = {
+    readonly method: QueryMethod;
+    readonly model: ModelMeta;
+    readonly statement: SqlStatement;
+    /**
+     * Field names the statement projects, in order, or `null` when it projects
+     * every scalar field. Mutations RETURNING extra primary-key columns are
+     * narrowed back down to this list by the client.
+     */
+    readonly selectedFields: readonly string[] | null;
+    /**
+     * What the CALLER should see: the user's scalar select plus relation names
+     * and `_count`, or `null` for "all scalars (plus attached relations)".
+     * Differs from `selectedFields` when stitching keys were added to the SQL
+     * projection — the client narrows back down to this after relation loading.
+     */
+    readonly resultFields: readonly string[] | null;
+    /**
+     * Computed fields to attach to result rows (config-declared), resolved from
+     * select/omit — always a concrete name list, `null` when none apply. Their
+     * `needs` ride `selectedFields` like stitch keys and are narrowed away by
+     * `resultFields` unless selected themselves.
+     */
+    readonly computed: readonly string[] | null;
+    /** Relations to load after the base rows, or `null` when none were asked for. */
+    readonly relations: RelationSelection | null;
+    /**
+     * 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).
+     */
+    readonly relationStrategy: RelationStrategy;
+    /** True when `take` produced a LIMIT. */
+    readonly takeApplied: boolean;
+    /** Alias the COUNT(*) value is projected under (`count` only). */
+    readonly countAlias: string | null;
+    /**
+     * Unique WHERE identifying the affected row, for the re-select a dialect
+     * without RETURNING needs. `null` when the row cannot be identified before
+     * the write (an autoincrement key the database assigns).
+     */
+    readonly refetchWhere: Readonly<Record<string, unknown>> | null;
+    /**
+     * Upsert only: the unique where WITHOUT the update-arm overlay. The INSERT
+     * arm's row answers this key (its create row binds the conflict target — the
+     * B1 native-eligibility gate), so the mysql read-back tries the overlaid
+     * `refetchWhere` first, then this. `null` on every other method.
+     */
+    readonly refetchWhereBase: Readonly<Record<string, unknown>> | null;
+    /**
+     * createMany/createManyAndReturn only: when the call compiles to MORE than
+     * one statement (sqlite's heterogeneous column-set groups — M4 — or the M7
+     * parameter-budget chunks), every statement in order (`statement` is the
+     * first). The client executes them in ONE transaction, summing counts /
+     * concatenating returned rows. Absent for single-statement calls.
+     */
+    readonly batch?: readonly SqlStatement[];
+    /**
+     * upsertMany only (EPIC 10): the number of rows this plan submits, summed
+     * across chunks. It IS the operation's affected count under the one
+     * cross-dialect definition — every submitted row is inserted or updated —
+     * and it is computed here because the drivers do not agree: mysql's ON
+     * DUPLICATE KEY scores an insert 1, a changed update 2 and an unchanged
+     * update 0, so its number is not a row count at all.
+     */
+    readonly upsertRowCount?: number;
+    /** 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. */
+    readonly aggregateSpec: AggregateSpec | null;
+    /** groupBy's `by` field names, for row assembly; `null` elsewhere. */
+    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;
+/**
+ * Compile a Prisma-shaped where object; `undefined` when it constrains nothing.
+ *
+ * `qualify` table-qualifies every column reference (used inside lateral and
+ * EXISTS subqueries); `aliasSeq` threads the statement-wide subquery-alias
+ * counter so nested relation filters never collide.
+ */
+export declare function compileWhere(params: {
+    dialect: SqlDialect;
+    meta: RuntimeMeta;
+    model: ModelMeta;
+    where: Record<string, unknown>;
+    qualify?: string;
+    aliasSeq?: {
+        n: number;
+    };
+}): SqlExpr | undefined;
+/** Compile `orderBy` (a single object or an array of them) into order terms. */
+export declare function compileOrderBy(params: {
+    model: ModelMeta;
+    orderBy: unknown;
+    qualify?: string;
+    /** When given, B4's sqlite Decimal ordering cast applies (`CAST … AS REAL`). */
+    dialect?: SqlDialect;
+}): OrderByColumn[];
+/**
+ * Compile `select` into scalar field names, projecting EXACTLY what was asked
+ * — the primary key is not smuggled in. Relation keys and `_count` are the
+ * relation resolver's business (`relation-plan.ts`) and are skipped here;
+ * `allowEmpty` permits a select of ONLY relations (the stitching key is added
+ * separately and stripped from the result).
+ */
+export declare function compileSelect(params: {
+    model: ModelMeta;
+    select: unknown;
+    allowEmpty?: boolean;
+}): string[];
+/**
+ * Whether `upsert({ where, create, update })` can ride ONE native
+ * `INSERT … ON CONFLICT`/`ON DUPLICATE KEY` statement — Prisma's own
+ * criterion: the create data must bind every conflict-target column with the
+ * SAME value the where names. Otherwise the conflict can never fire on the
+ * addressed row (postgres/sqlite would silently insert instead of update;
+ * mysql's ODKU could update an unrelated row — SQL review B1) and the client
+ * must run the transactional find-then-write fallback instead.
+ */
+/**
+ * Whether `upsert({ where, create, update })` can ride ONE native
+ * `INSERT … ON CONFLICT`/`ON DUPLICATE KEY` statement — Prisma's own
+ * criterion, two halves:
+ *   1. the create data binds every conflict-target column with the SAME value
+ *      the where names (otherwise the conflict can never fire on the
+ *      addressed row — postgres/sqlite would silently insert instead of
+ *      update; mysql's ODKU could update an unrelated row — SQL review B1);
+ *   2. the where carries NO fields beyond the conflict target (PG-2): a guard
+ *      field (`where: { email, active: true }`) is invisible to ON CONFLICT —
+ *      the update arm would fire even when the guard fails, where update()
+ *      honors the same guard.
+ * Ineligible shapes run the client's transactional find-then-write fallback,
+ * whose probe honors the FULL where.
+ */
+export declare function upsertUsesNativeStatement(params: {
+    model: ModelMeta;
+    args: Record<string, unknown>;
+}): boolean;
+/**
+ * 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
+ * never drift from the ordering the statement carries.
+ */
+export declare function compileKeysetOrderInputs(params: {
+    dialect: SqlDialect;
+    meta: RuntimeMeta;
+    model: ModelMeta;
+    orderBy: unknown;
+}): KeysetOrderInput[];
+/** The column a relation's JSON payload is exposed under in the outer row. */
+export declare function lateralColumnAlias(params: {
+    relation: string;
+}): string;
+/**
+ * PG-3 (SQL review round 2): order fields the lateral subselect must project
+ * HIDDEN — the aggregate's explicit `ORDER BY "__sub".…` (N2) can only
+ * reference projected columns, and a per-relation orderBy on a field outside
+ * the child select otherwise left the aggregate relying on "usually preserves
+ * subquery order". The loader deletes these after parsing (the stitch-key
+ * pattern). Empty when the projection is full or no orderBy was given.
+ */
+export declare function lateralHiddenOrderFields(params: {
+    node: RelationTreeNode;
+}): string[];
+/**
+ * The relation selection + caller-visible field list for one call, WITHOUT
+ * building a statement — the nested-write path orchestrates its own
+ * statements but still needs the validated result shape for relation loading
+ * and projection.
+ */
+export declare function resolveResultShape(params: {
+    meta: RuntimeMeta;
+    model: ModelMeta;
+    method: QueryMethod;
+    args: Record<string, unknown>;
+}): {
+    relations: RelationSelection | null;
+    resultFields: readonly string[] | null;
+    computed: readonly string[] | null;
+};
+/**
+ * Build the SQL plan for one ORM call. Pure: same inputs, same statement —
+ * except for app-generated defaults (uuid/cuid/nanoid/ulid/now), which are by
+ * definition fresh per call.
+ *
+ * `defaultRelationStrategy` is the client-level option; a per-query
+ * `relationStrategy` argument (find methods only) overrides it.
+ */
+export declare function buildQuery(params: {
+    meta: RuntimeMeta;
+    dialect: SqlDialect;
+    model: string;
+    method: QueryMethod;
+    args?: Record<string, unknown>;
+    defaultRelationStrategy?: RelationStrategy;
+    clientOptions?: BuilderClientOptions;
+}): QueryPlan;
+//# sourceMappingURL=query-builder.d.ts.map

package/dist/query-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-builder.d.ts","sourceRoot":"","sources":["../src/query-builder.ts"],"names":[],"mappings":"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"}

package/dist/relation-key.d.ts

@@ -0,0 +1,23 @@
+/** Compare decoded relation keys by value, including DateTime milliseconds and binary bytes. */
+export declare function relationValueKey(params: {
+    value: unknown;
+}): unknown;
+/**
+ * A collision-safe Map key for an ORDERED key tuple, or `null` when the tuple
+ * is INCOMPLETE (any member null/undefined) — an incomplete foreign key must
+ * never attach a parent, so it gets no key at all rather than a key that could
+ * collide with another incomplete tuple.
+ *
+ * The encoding is `JSON.stringify` over the per-member {@link relationValueKey}
+ * tags, NOT a separator join: JSON string escaping is injective, so a member
+ * containing the separator of a naive `a + "\u0000" + b` scheme (or `","`, or
+ * `"|"`) cannot forge another tuple's key.
+ *
+ * A member whose equality cannot be implemented faithfully — any object that is
+ * neither `Date` nor `Uint8Array`, where `String(value)` would be a lossy stand-in
+ * — is refused rather than silently mis-grouped.
+ */
+export declare function relationTupleKey(params: {
+    values: readonly unknown[];
+}): string | null;
+//# sourceMappingURL=relation-key.d.ts.map

package/dist/relation-key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relation-key.d.ts","sourceRoot":"","sources":["../src/relation-key.ts"],"names":[],"mappings":"AAEA,gGAAgG;AAChG,wBAAgB,gBAAgB,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAqBpE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE;IAAE,MAAM,EAAE,SAAS,OAAO,EAAE,CAAA;CAAE,GAAG,MAAM,GAAG,IAAI,CAgBtF"}

package/dist/relation-loader.d.ts

@@ -0,0 +1,46 @@
+import type { SelectStatement, SqlDialect, WireFidelity } from "@vibeorm/sql";
+import type { ModelMeta, RuntimeMeta } from "./model-meta.ts";
+import type { RelationSelection } from "./relation-plan.ts";
+/** A materialized row relations are stitched onto. */
+export type LoadedRow = Record<string, unknown>;
+/**
+ * Executes one SELECT and returns RAW driver rows — the loader decodes them
+ * itself (the child model's codecs, at every materialization point). The
+ * client provides this bound to its adapter + onQuery reporting.
+ */
+export type RelationExecutor = (params: {
+    statement: SelectStatement;
+    model: string;
+    method: string;
+}) => Promise<Record<string, unknown>[]>;
+/**
+ * "query"-strategy loading: batched statements per relation, in declaration
+ * order, recursively. Mutates `rows` in place (relations become properties).
+ */
+export declare function attachRelations(params: {
+    dialect: SqlDialect;
+    meta: RuntimeMeta;
+    model: ModelMeta;
+    rows: LoadedRow[];
+    selection: RelationSelection;
+    execute: RelationExecutor;
+    /** The executing adapter's wire declaration (board #30). */
+    wire?: WireFidelity;
+}): Promise<void>;
+/**
+ * "join"-strategy post-processing: parse each row's `__rel_<name>` JSON
+ * column, decode the children through the child model's codecs, stitch, then
+ * recurse deeper levels through the query strategy (v1 semantics) and load
+ * `_count` separately.
+ */
+export declare function attachLateralRelations(params: {
+    dialect: SqlDialect;
+    meta: RuntimeMeta;
+    model: ModelMeta;
+    rows: LoadedRow[];
+    selection: RelationSelection;
+    execute: RelationExecutor;
+    /** The executing adapter's wire declaration (board #30 — deeper levels recurse through the query strategy). */
+    wire?: WireFidelity;
+}): Promise<void>;
+//# sourceMappingURL=relation-loader.d.ts.map

package/dist/relation-loader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relation-loader.d.ts","sourceRoot":"","sources":["../src/relation-loader.ts"],"names":[],"mappings":"AAiCA,OAAO,KAAK,EAAU,eAAe,EAAE,UAAU,EAAW,YAAY,EAAE,MAAM,cAAc,CAAC;AAG/F,OAAO,KAAK,EAAa,SAAS,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAGzE,OAAO,KAAK,EAAmC,iBAAiB,EAAoB,MAAM,oBAAoB,CAAC;AAI/G,sDAAsD;AACtD,MAAM,MAAM,SAAS,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEhD;;;;GAIG;AACH,MAAM,MAAM,gBAAgB,GAAG,CAAC,MAAM,EAAE;IACtC,SAAS,EAAE,eAAe,CAAC;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;AA6wBzC;;;GAGG;AACH,wBAAsB,eAAe,CAAC,MAAM,EAAE;IAC5C,OAAO,EAAE,UAAU,CAAC;IACpB,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,EAAE,SAAS,CAAC;IACjB,IAAI,EAAE,SAAS,EAAE,CAAC;IAClB,SAAS,EAAE,iBAAiB,CAAC;IAC7B,OAAO,EAAE,gBAAgB,CAAC;IAC1B,4DAA4D;IAC5D,IAAI,CAAC,EAAE,YAAY,CAAC;CACrB,GAAG,OAAO,CAAC,IAAI,CAAC,CAShB;AAED;;;;;GAKG;AACH,wBAAsB,sBAAsB,CAAC,MAAM,EAAE;IACnD,OAAO,EAAE,UAAU,CAAC;IACpB,IAAI,EAAE,WAAW,CAAC;IAClB,KAAK,EAAE,SAAS,CAAC;IACjB,IAAI,EAAE,SAAS,EAAE,CAAC;IAClB,SAAS,EAAE,iBAAiB,CAAC;IAC7B,OAAO,EAAE,gBAAgB,CAAC;IAC1B,+GAA+G;IAC/G,IAAI,CAAC,EAAE,YAAY,CAAC;CACrB,GAAG,OAAO,CAAC,IAAI,CAAC,CA4DhB"}

package/dist/relation-plan.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Relation RESOLUTION: `select`/`include` args → a validated relation tree,
+ * plus the structural link (FK fields, join table) each relation loads through.
+ *
+ * Pure structure — no SQL, no execution. The query builder consumes this to
+ * gate strategies and augment projections at build time (the earliest knowable
+ * moment); the relation loader consumes it to run and stitch.
+ *
+ * v1 semantics carried:
+ * - `select: { rel: … }` and `include: { rel: … }` both load; `include` wins
+ *   when both name the same relation.
+ * - `_count` uses the v1 shape: `include._count: true | { select: { rel: true } }`
+ *   (or under `select`) and counts LIST relations only. A count entry may also
+ *   be `{ where: … }` (EPIC 4): the filter is carried on the resolved node and
+ *   compiled by the loader through the ordinary where compiler.
+ * - Implicit many-to-many resolves through the ONE shared join-table rule
+ *   (`implicitJoinTable` in @vibeorm/schema) — never re-derived here.
+ */
+import type { RelationIR } from "@vibeorm/schema";
+import type { FieldMeta, ModelMeta, RuntimeMeta } from "./model-meta.ts";
+/** How a relation is physically wired. */
+export type RelationKind = 
+/** Children hold the FK (`oneToMany`) — batch `WHERE fk IN (parents)`. */
+"toManyFk"
+/** THIS model holds the FK (`manyToOne` / owning `oneToOne`). */
+ | "toOneOwner"
+/** The other side holds the FK (non-owning `oneToOne`). */
+ | "toOneInverse"
+/** Implicit join table (`manyToMany`). */
+ | "manyToMany";
+/** The resolved physical link for one relation. */
+export type RelationLink = {
+    readonly kind: RelationKind;
+    readonly relation: RelationIR;
+    readonly target: ModelMeta;
+    /**
+     * ORDERED parent-side correlation fields — index `i` pairs with
+     * `childKeys[i]`. A composite foreign key carries every column here; there is
+     * deliberately no singular accessor, so no call site can truncate a tuple to
+     * its first member.
+     */
+    readonly parentKeys: readonly FieldMeta[];
+    /** ORDERED child-side correlation fields, positionally paired with {@link parentKeys}. */
+    readonly childKeys: readonly FieldMeta[];
+    /** Join-table wiring; `null` unless kind is `manyToMany`. */
+    readonly join: {
+        readonly tableName: string;
+        readonly parentColumn: "A" | "B";
+        readonly childColumn: "A" | "B";
+    } | null;
+};
+/** Nested args for one relation to load, validated. */
+export type RelationArgs = {
+    readonly where: Record<string, unknown> | undefined;
+    readonly orderBy: unknown;
+    readonly take: number | undefined;
+    readonly skip: number | undefined;
+    /** Child scalar fields the CALLER asked for, or `null` for all scalars. */
+    readonly select: readonly string[] | null;
+    /** SQL projection: `select` plus stitching keys — what the child statement fetches. */
+    readonly projected: readonly string[] | null;
+    /** Fields in `projected` the caller did NOT ask for — deleted after stitching. */
+    readonly strip: readonly string[];
+    /** Computed fields to attach to loaded children, or `null` — resolved like the top level. */
+    readonly computed: readonly string[] | null;
+    /** Deeper relation levels under this one. */
+    readonly nested: RelationSelection | null;
+};
+export type RelationTreeNode = {
+    /** Relation field name on the parent (`posts`). */
+    readonly name: string;
+    readonly link: RelationLink;
+    readonly args: RelationArgs;
+};
+/**
+ * One relation counted into `_count`, with the filter that narrows it.
+ *
+ * The link is resolved HERE, once, so no later consumer has to re-derive a
+ * relation's ordered key tuples just to count through them.
+ */
+export type RelationCountNode = {
+    /** List-relation field name on the parent (`posts`). */
+    readonly name: string;
+    /** Structural link the count correlates and groups on. */
+    readonly link: RelationLink;
+    /**
+     * Validated `where` narrowing the counted children, or `undefined` for
+     * "count every child". The loader compiles it with `compileWhere` — the same
+     * centralized compiler and codecs an ordinary query where goes through.
+     */
+    readonly where: Record<string, unknown> | undefined;
+};
+/** Everything relation-shaped one query level asked for. */
+export type RelationSelection = {
+    readonly relations: readonly RelationTreeNode[];
+    /** List relations to count into `_count`, each with its own filter. */
+    readonly counts: readonly RelationCountNode[];
+};
+/**
+ * The ONE correlation pair of an arity-1 link, for the paths that are single-key
+ * by construction (implicit many-to-many, whose join table has one column per
+ * side). Refuses a composite link with a typed capability error BEFORE any
+ * statement runs — never truncates.
+ */
+export declare function singleKeyPair(params: {
+    link: RelationLink;
+    what: string;
+}): {
+    readonly parent: FieldMeta;
+    readonly child: FieldMeta;
+};
+/** Resolve how one relation is physically wired. */
+export declare function resolveRelationLink(params: {
+    meta: RuntimeMeta;
+    model: ModelMeta;
+    relation: RelationIR;
+}): RelationLink;
+/**
+ * The parent-side fields a selection needs for stitching: each relation's
+ * `parentKey`, and each counted relation's `parentKey`.
+ */
+export declare function requiredParentFields(params: {
+    meta: RuntimeMeta;
+    model: ModelMeta;
+    selection: RelationSelection;
+}): string[];
+/**
+ * Resolve everything relation-shaped in one level's `select`/`include`.
+ * Returns `null` when neither names a relation or `_count`.
+ *
+ * Scalar keys in `select` are ignored here (the query builder projects them);
+ * every key in `include` must be a relation or `_count` — anything else is a
+ * loud validation error.
+ */
+export declare function resolveRelationSelection(params: {
+    meta: RuntimeMeta;
+    model: ModelMeta;
+    select: unknown;
+    include: unknown;
+}): RelationSelection | null;
+//# sourceMappingURL=relation-plan.d.ts.map

package/dist/relation-plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relation-plan.d.ts","sourceRoot":"","sources":["../src/relation-plan.ts"],"names":[],"mappings":"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"}

package/dist/render-cache.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The compiled-query cache — §9's "query-shape cache (structural hash → SQL
+ * skeleton)", constitution rule 8 (perf) under rule 3's constraint: the SQL
+ * text is ALWAYS the renderer's, byte-identical — this module never builds SQL.
+ *
+ * How it works: a statement AST is walked ONCE, producing (a) a structural key
+ * covering everything that affects the rendered text — kinds, identifiers,
+ * operators, flags, literal LIMIT/OFFSET, arity where a dialect expands
+ * placeholders per element — and (b) the parameter values in exactly the
+ * renderer's collection order. A key hit reuses the cached text with the fresh
+ * values; a miss renders for real and caches the text.
+ *
+ * SAFETY: the walk mirrors @vibeorm/sql's render traversal. Two guards keep a
+ * divergence from ever mis-binding parameters:
+ *   1. every MISS cross-checks the walked values against the renderer's
+ *      collected values (element-wise); a mismatch poisons the key so that
+ *      shape renders uncached forever, and
+ *   2. constructs with dialect-conditional value branching that is not worth
+ *      mirroring (jsonFilter) are declared uncacheable outright.
+ * The cache is invalidation-free by construction: the key IS the shape, and
+ * equal shapes render equal text (shape-purity). Statement ASTs are treated as
+ * immutable by the whole runtime, so cached texts can never go stale.
+ */
+import type { RenderedQuery, SqlDialect, SqlStatement } from "@vibeorm/sql";
+type CachedText = {
+    readonly text: string;
+    readonly returning: "native" | "omitted" | "none";
+};
+/** `null` = poisoned: this shape verified unsafe once — never cache it. */
+type CacheSlot = CachedText | null;
+/** One per client (dialect-stable); shared across its transaction clients. */
+export declare class StatementRenderCache {
+    private readonly entries;
+    get(key: string): CacheSlot | undefined;
+    set(key: string, slot: CacheSlot): void;
+}
+/**
+ * Render through the shape cache: hit = cached text + freshly walked values;
+ * miss = real render, cross-checked against the walk before caching. Anything
+ * uncacheable (or a verification failure — poisoned) renders directly.
+ */
+export declare function renderStatementCached(params: {
+    dialect: SqlDialect;
+    statement: SqlStatement;
+    cache: StatementRenderCache;
+}): RenderedQuery;
+export {};
+//# sourceMappingURL=render-cache.d.ts.map

package/dist/render-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-cache.d.ts","sourceRoot":"","sources":["../src/render-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAWH,OAAO,KAAK,EAMV,aAAa,EAEb,UAAU,EAEV,YAAY,EAGb,MAAM,cAAc,CAAC;AAItB,KAAK,UAAU,GAAG;IAChB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,QAAQ,GAAG,SAAS,GAAG,MAAM,CAAC;CACnD,CAAC;AAEF,2EAA2E;AAC3E,KAAK,SAAS,GAAG,UAAU,GAAG,IAAI,CAAC;AAInC,8EAA8E;AAC9E,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqC;IAE7D,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAEtC;IAED,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,GAAG,IAAI,CAKtC;CACF;AA0fD;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE;IAC5C,OAAO,EAAE,UAAU,CAAC;IACpB,SAAS,EAAE,YAAY,CAAC;IACxB,KAAK,EAAE,oBAAoB,CAAC;CAC7B,GAAG,aAAa,CAoBhB"}

package/dist/rls-context.d.ts

@@ -0,0 +1,14 @@
+import type { SchemaIR } from "@vibeorm/schema";
+import type { SqlDialect } from "@vibeorm/sql";
+/** Private, copied identity and its total transaction-settings transport. */
+export type BoundRlsContext = {
+    readonly values: Readonly<Record<string, unknown>>;
+    readonly settings: Readonly<Record<string, string | null>>;
+};
+/** Validate before serialization; missing nullable slots are still missing keys. */
+export declare function bindRlsContext(params: {
+    schema: SchemaIR;
+    dialect: SqlDialect;
+    context: unknown;
+}): BoundRlsContext;
+//# sourceMappingURL=rls-context.d.ts.map

package/dist/rls-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rls-context.d.ts","sourceRoot":"","sources":["../src/rls-context.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAoB,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAElE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAG/C,6EAA6E;AAC7E,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IACnD,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC;CAC5D,CAAC;AA0BF,oFAAoF;AACpF,wBAAgB,cAAc,CAAC,MAAM,EAAE;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,OAAO,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GAAG,eAAe,CA6CnH"}