@vibeorm/runtime 1.3.0 → 2.0.0-alpha.10

package/dist/keyset-iterator.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Bounded-memory export: a sequential async iterator over keyset pages.
+ *
+ * One page is held at a time and the next one is fetched only when the
+ * consumer asks for a row the buffer cannot serve. There is no prefetch, no
+ * look-ahead and no unbounded accumulation — `pagesFetched()` is the receipt.
+ *
+ * What this deliberately is NOT:
+ *   - **not a snapshot.** No transaction is opened, so the traversal is a LIVE
+ *     view: concurrent inserts, deletes and sort-key updates change what a
+ *     later page sees. A row that moves behind the position is missed; one
+ *     that moves ahead of it is seen twice. A consistent export means running
+ *     the whole iteration inside `$transaction` at an explicit isolation
+ *     level, paying its connection and deadline cost — never a secretly
+ *     long-lived transaction.
+ *   - **not exactly-once.** `checkpoint()` records the last row the consumer
+ *     came BACK for, so a `break` or an exception leaves the in-flight row
+ *     uncheckpointed and resuming re-delivers it. At-least-once. The consumer
+ *     owns acknowledgement and de-duplication; this is not a durable job
+ *     engine.
+ *   - **not statement cancellation.** Aborting the signal stops FUTURE page
+ *     fetches. A page query already in flight keeps running: per EPIC 6 only
+ *     `adapter-pg` / `adapter-bun` can cancel a running statement, and only
+ *     inside a transaction carrying a deadline — which this iterator does not
+ *     open.
+ */
+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. */
+export type KeysetPageSource = {
+    readonly findMany: (args: Record<string, unknown>) => Promise<Record<string, unknown>[]>;
+};
+export type KeysetIterateOptions = {
+    readonly source: KeysetPageSource;
+    readonly meta: RuntimeMeta;
+    readonly dialect: SqlDialect;
+    readonly model: string;
+    readonly orderBy: unknown;
+    /** Bounded and required, 1…{@link KEYSET_MAX_PAGE_SIZE}. There is no unbounded default. */
+    readonly pageSize: number;
+    readonly where?: Record<string, unknown>;
+    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. */
+    readonly after?: string;
+    /** Consumer cancellation: stops future page fetches; ends iteration cleanly. */
+    readonly signal?: AbortSignal;
+    readonly timestampPrecision?: KeysetTimestampPrecision;
+};
+export type KeysetIterator = AsyncIterableIterator<Record<string, unknown>> & {
+    /** Always present: `break` and an exception both have to be able to release the traversal. */
+    readonly return: (value?: unknown) => Promise<IteratorResult<Record<string, unknown>>>;
+    readonly throw: (error?: unknown) => Promise<IteratorResult<Record<string, unknown>>>;
+    /** Token for the last SUCCESSFULLY CONSUMED row; `null` before the first one settles. */
+    readonly checkpoint: () => string | null;
+    /** Pages fetched so far — the bounded-fetch receipt. */
+    readonly pagesFetched: () => number;
+    /** True when the signal aborted the traversal. */
+    readonly cancelled: () => boolean;
+};
+/**
+ * Iterate a model in keyset order, one bounded page at a time.
+ *
+ * @example
+ * const rows = iterateKeyset({ source: db.$models.product, meta, dialect,
+ *   model: "Product", orderBy: [{ price: "asc" }, { id: "asc" }], pageSize: 500 });
+ * for await (const row of rows) { … }
+ * const resumeFrom = rows.checkpoint();
+ */
+export declare function iterateKeyset(options: KeysetIterateOptions): KeysetIterator;
+//# sourceMappingURL=keyset-iterator.d.ts.map

package/dist/keyset-iterator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyset-iterator.d.ts","sourceRoot":"","sources":["../src/keyset-iterator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAS/C,OAAO,KAAK,EAAmB,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAE7E,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAKnD,0EAA0E;AAC1E,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;CAC1F,CAAC;AAEF,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,2FAA2F;IAC3F,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC1C,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACxC,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC3C,gFAAgF;IAChF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,gFAAgF;IAChF,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,kBAAkB,CAAC,EAAE,wBAAwB,CAAC;CACxD,CAAC;AAEF,MAAM,MAAM,cAAc,GAAG,qBAAqB,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG;IAC5E,8FAA8F;IAC9F,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,cAAc,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACvF,QAAQ,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,EAAE,OAAO,KAAK,OAAO,CAAC,cAAc,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IACtF,yFAAyF;IACzF,QAAQ,CAAC,UAAU,EAAE,MAAM,MAAM,GAAG,IAAI,CAAC;IACzC,wDAAwD;IACxD,QAAQ,CAAC,YAAY,EAAE,MAAM,MAAM,CAAC;IACpC,kDAAkD;IAClD,QAAQ,CAAC,SAAS,EAAE,MAAM,OAAO,CAAC;CACnC,CAAC;AAuCF;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,cAAc,CA2I3E"}

package/dist/keyset.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Sort-aware keyset pagination — the order plan and the opaque position token.
+ *
+ * A keyset position describes ORDERING VALUES plus a unique tie-breaker, not
+ * the identity of one row: the row a token was minted from may since have been
+ * deleted or had its sort key changed, and traversal still continues from the
+ * 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:
+ *   - 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'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.
+ */
+import type { SqlDialect } from "@vibeorm/sql";
+import type { FieldMeta, ModelMeta } from "./model-meta.ts";
+export type KeysetDirection = "asc" | "desc";
+export type KeysetNulls = "first" | "last";
+/**
+ * The caller's assertion that every `DateTime` ordering column holds
+ * millisecond-exact values. See {@link compileKeysetOrderPlan}.
+ */
+export type KeysetTimestampPrecision = "milliseconds";
+/** One order term, already resolved by the query builder. */
+export type KeysetOrderInput = {
+    readonly field: FieldMeta;
+    readonly direction: KeysetDirection;
+    /** Resolved NULL placement: the explicit request, else the dialect's native one. */
+    readonly nulls: KeysetNulls;
+};
+/** One key of the effective keyset order. */
+export type KeysetOrderKey = {
+    readonly field: FieldMeta;
+    readonly direction: KeysetDirection;
+    readonly nulls: KeysetNulls;
+    readonly tag: KeysetValueTag;
+};
+/** The effective order a token is bound to. */
+export type KeysetOrderPlan = {
+    readonly model: string;
+    readonly keys: readonly KeysetOrderKey[];
+    /** Plain-text order signature carried inside the token. */
+    readonly signature: string;
+};
+/** 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. */
+export declare const KEYSET_TOKEN_VERSION: number;
+/** Token prefix — `vk` for "vibe keyset", then the version. */
+export declare const KEYSET_TOKEN_PREFIX: string;
+/** Upper bound on an iterator page — memory is bounded by construction, not by hope. */
+export declare const KEYSET_MAX_PAGE_SIZE: number;
+/**
+ * Compile and VALIDATE the effective keyset order.
+ *
+ * Refuses, at build time and before any statement runs: list/Json/Bytes order
+ * keys, an order with no unique tie-breaker, and a `DateTime` key on a dialect
+ * that may store sub-millisecond values unless the caller passes
+ * `timestampPrecision: "milliseconds"` — the caller's explicit assertion that
+ * the column is millisecond-exact. That assertion is NOT safe for a
+ * `@default(now())` column on postgres, which is microsecond-precise: a
+ * truncated cursor value re-admits rows already delivered in that same
+ * millisecond, i.e. duplicates.
+ */
+export declare function compileKeysetOrderPlan(params: {
+    model: ModelMeta;
+    dialect: SqlDialect;
+    terms: readonly KeysetOrderInput[];
+    timestampPrecision?: KeysetTimestampPrecision;
+}): KeysetOrderPlan;
+/**
+ * Is `row` strictly after `position` in this ordering? `null` means the
+ * comparison is inconclusive in JavaScript (a collated string key), never
+ * "yes".
+ *
+ * Used as a LIVENESS guard, not as a filter: the SQL bound does the real work,
+ * and this only catches a traversal that fails to advance — which happens when
+ * an ordering is not actually total, or when a cursor value was lossy (a
+ * truncated sub-millisecond timestamp being the case this codebase can
+ * demonstrate). Without it that situation is an infinite page loop.
+ */
+export declare function keysetRowIsAfter(params: {
+    keys: readonly KeysetOrderKey[];
+    row: readonly unknown[];
+    position: readonly unknown[];
+}): boolean | null;
+/** Read a row's ordering values in plan order. */
+export declare function keysetRowValues(params: {
+    plan: KeysetOrderPlan;
+    row: Readonly<Record<string, unknown>>;
+}): readonly unknown[];
+/**
+ * Mint a continuation token from a row that carries every ordering value.
+ *
+ * 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
+ * sequence. Callers that project a subset (`select`) fetch the ordering
+ * columns HIDDEN and strip them from the payload; see `keyset-iterator.ts`.
+ */
+export declare function encodeKeysetToken(params: {
+    plan: KeysetOrderPlan;
+    row: Readonly<Record<string, unknown>>;
+}): 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.
+ */
+export declare function decodeKeysetToken(params: {
+    plan: KeysetOrderPlan;
+    token: string;
+}): readonly unknown[];
+//# sourceMappingURL=keyset.d.ts.map

package/dist/keyset.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyset.d.ts","sourceRoot":"","sources":["../src/keyset.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC/C,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAI5D,MAAM,MAAM,eAAe,GAAG,KAAK,GAAG,MAAM,CAAC;AAC7C,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,MAAM,CAAC;AAE3C;;;GAGG;AACH,MAAM,MAAM,wBAAwB,GAAG,cAAc,CAAC;AAEtD,6DAA6D;AAC7D,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC,oFAAoF;IACpF,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;CAC7B,CAAC;AAEF,6CAA6C;AAC7C,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,eAAe,CAAC;IACpC,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,GAAG,EAAE,cAAc,CAAC;CAC9B,CAAC;AAEF,+CAA+C;AAC/C,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,IAAI,EAAE,SAAS,cAAc,EAAE,CAAC;IACzC,2DAA2D;IAC3D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEF,4DAA4D;AAC5D,MAAM,MAAM,cAAc,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;AAI3E,gFAAgF;AAChF,eAAO,MAAM,oBAAoB,EAAE,MAAU,CAAC;AAE9C,+DAA+D;AAC/D,eAAO,MAAM,mBAAmB,EAAE,MAAe,CAAC;AAElD,wFAAwF;AACxF,eAAO,MAAM,oBAAoB,EAAE,MAAe,CAAC;AAuHnD;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE;IAC7C,KAAK,EAAE,SAAS,CAAC;IACjB,OAAO,EAAE,UAAU,CAAC;IACpB,KAAK,EAAE,SAAS,gBAAgB,EAAE,CAAC;IACnC,kBAAkB,CAAC,EAAE,wBAAwB,CAAC;CAC/C,GAAG,eAAe,CA+ClB;AA0ID;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE;IACvC,IAAI,EAAE,SAAS,cAAc,EAAE,CAAC;IAChC,GAAG,EAAE,SAAS,OAAO,EAAE,CAAC;IACxB,QAAQ,EAAE,SAAS,OAAO,EAAE,CAAC;CAC9B,GAAG,OAAO,GAAG,IAAI,CAmBjB;AAED,kDAAkD;AAClD,wBAAgB,eAAe,CAAC,MAAM,EAAE;IACtC,IAAI,EAAE,eAAe,CAAC;IACtB,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACxC,GAAG,SAAS,OAAO,EAAE,CAGrB;AAID;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IACxC,IAAI,EAAE,eAAe,CAAC;IACtB,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;CACxC,GAAG,MAAM,CAcT;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,eAAe,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,OAAO,EAAE,CA8EtG"}

package/dist/model-meta.d.ts

@@ -0,0 +1,200 @@
+/**
+ * Runtime model metadata: the pre-resolved view of the Schema IR the query
+ * builder and client run on.
+ *
+ * Built once per client (`buildRuntimeMeta`), then read-only. Everything the
+ * hot path needs is precomputed here — column names, field lookup maps, primary
+ * keys — so no query ever walks the IR. Relations are carried verbatim: the P2
+ * core slice does not load them, P3 does.
+ *
+ * Also the home of app-side default generation (uuid/cuid/nanoid/ulid/now),
+ * which is dialect-free by design: the id exists before the INSERT, which is
+ * what lets dialects without RETURNING re-select the row they just wrote.
+ */
+import type { ComputedConfig, DefaultValueIR, EnumStorage, FieldType, RelationIR, ScalarType, SchemaIR } from "@vibeorm/schema";
+import type { ScalarCodec, SqlExpr } from "@vibeorm/sql";
+/** Where a field's default value is produced. */
+export type DefaultOrigin = "app" | "database" | "none";
+/** A scalar or enum column, resolved for the runtime. */
+export type FieldMeta = {
+    /** Client-facing field name. */
+    readonly name: string;
+    /** Database column name (`dbName ?? name`). */
+    readonly columnName: string;
+    /** Explicit column collation (@collation, board #36) — mysql insensitive-filter rendering reads it. */
+    readonly collation?: string;
+    /**
+     * The declared `@db.*` native column type, verbatim as Prisma writes it
+     * (`Uuid`, `VarChar(191)`, `Char(10)`, `Decimal(10, 2)`), or `undefined`
+     * when the field takes the dialect's canonical mapping.
+     *
+     * Carried because the physical type decides value equality on its own,
+     * before any collation: `char(n)` pads, `uuid` folds case, `timestamp(0)`
+     * truncates, `real` narrows a Float. `upsertMany`'s duplicate rule reads it
+     * (`conflictKeyComparisonOf` in bulk-upsert.ts). It is a schema claim, not a
+     * reading of the live column.
+     */
+    readonly nativeType?: string;
+    readonly type: FieldType;
+    /** The scalar type, or `null` when the field is an enum reference. */
+    readonly scalarType: ScalarType | null;
+    /** The enum name, or `null` when the field is a scalar. */
+    readonly enumName: string | null;
+    /** Physical enum storage, or `null` for ordinary scalar fields. */
+    readonly enumStorage: EnumStorage | null;
+    /** Precomputed membership codec for string-backed enums only. */
+    readonly enumCodec: ScalarCodec | null;
+    readonly isList: boolean;
+    readonly isOptional: boolean;
+    readonly isId: boolean;
+    readonly isUnique: boolean;
+    readonly isUpdatedAt: boolean;
+    readonly default: DefaultValueIR | null;
+    /**
+     * `"app"` — the runtime generates the value and sends it (uuid/cuid/nanoid/
+     * ulid/now). `"database"` — the column's DEFAULT clause applies and the field
+     * is omitted from INSERTs (autoincrement, dbgenerated, literal, enum value).
+     */
+    readonly defaultOrigin: DefaultOrigin;
+};
+/** One computed field, resolved for the runtime (config-declared, see @vibeorm/schema computed.ts). */
+export type ComputedFieldMeta = {
+    readonly name: string;
+    /** The declared TypeScript type (informational at runtime; the generator wrote it into the .d.ts). */
+    readonly type: string;
+    /** Scalar fields the compute reads — fetched with the computed field, stripped unless selected. */
+    readonly needs: readonly string[];
+    readonly compute: (row: Record<string, unknown>) => unknown;
+};
+/** A model, resolved for the runtime. */
+export type ModelMeta = {
+    /** IR model name, e.g. `"User"`. */
+    readonly name: string;
+    /** Delegate key on the client, e.g. `"user"`. */
+    readonly clientName: string;
+    /** Table name (`dbName ?? name`). */
+    readonly tableName: string;
+    readonly fields: readonly FieldMeta[];
+    readonly fieldByName: ReadonlyMap<string, FieldMeta>;
+    /** Reverse map for row materialization (driver rows are keyed by column). */
+    readonly fieldByColumn: ReadonlyMap<string, FieldMeta>;
+    /** Primary-key fields: the single `@id` field, or the `@@id` fields in order. */
+    readonly primaryKey: readonly FieldMeta[];
+    /** Fields that identify a row on their own (`@id` or `@unique`). */
+    readonly uniqueFields: readonly FieldMeta[];
+    /**
+     * COMPOSITE ways to address one row, keyed exactly like the generated
+     * `…WhereUniqueInput` property — the declared client selector name
+     * (`@@unique`/`@@id` `name:`) when present, else member field names joined
+     * with `_` (`projectId_userId`). The composite `@@id` comes first, then
+     * every multi-field `@@unique`, in schema order. Empty for models without
+     * one.
+     */
+    readonly compoundUniques: ReadonlyMap<string, UniqueGroupMeta>;
+    /**
+     * Single-field unique INDEXES that are addressable but not folded into
+     * `field.isUnique` (today: NULLS NOT DISTINCT singles) — mirrors the
+     * generator's WhereUniqueInput surface.
+     */
+    readonly singleIndexUniques: readonly UniqueGroupMeta[];
+    /** Carried verbatim from the IR — consumed by relation loading in P3. */
+    readonly relations: readonly RelationIR[];
+    readonly relationByName: ReadonlyMap<string, RelationIR>;
+    readonly isView: boolean;
+    /** Row-scoping policy (@@policy) — the client fails closed on it ($withPolicy). */
+    readonly policy?: {
+        readonly field: string;
+        readonly context: string;
+    };
+    /** Computed fields configured for this model, or `null` (the common case). */
+    readonly computed: ReadonlyMap<string, ComputedFieldMeta> | null;
+};
+/**
+ * A pre-bound extension where-operator: compiles one use (`{ similarTo: … }`)
+ * into a SqlExpr fragment. Built by `buildExtensionOperatorMap` in
+ * extensions.ts with dialect/provider/options already curried in.
+ */
+export type ExtensionOperatorFn = (params: {
+    /** Identifier path of the column (qualified when inside a subquery). */
+    readonly column: readonly string[];
+    readonly operand: unknown;
+    readonly model: string;
+    readonly field: string;
+}) => SqlExpr;
+/**
+ * One addressable unique group beyond the flat `@id`/`@unique` fields: a
+ * composite `@@id`/`@@unique`, or a single-field unique INDEX that does not
+ * fold into `field.isUnique` (today: `nullsNotDistinct` uniques). Under
+ * NULLS NOT DISTINCT the database keeps at most one row per key INCLUDING
+ * null dimensions, so a `null` member addresses exactly one row — those
+ * groups accept `null` where members; default (nulls-distinct) groups never
+ * do.
+ */
+export type UniqueGroupMeta = {
+    readonly fields: readonly FieldMeta[];
+    readonly nullsNotDistinct: boolean;
+};
+/** All runtime metadata for one schema. */
+export type RuntimeMeta = {
+    readonly models: readonly ModelMeta[];
+    /** Keyed by BOTH camelCase client name (`user`) and model name (`User`). */
+    readonly modelByName: ReadonlyMap<string, ModelMeta>;
+    /** Enum name → its values, for validation and codec decisions. */
+    readonly enums: ReadonlyMap<string, readonly string[]>;
+    /**
+     * Extension where-operators (extension sql plane), keyed by operator name.
+     * Rides on the meta so the WHERE compiler reaches it at every site without
+     * threading a parameter through the hot path.
+     */
+    readonly extensionOperators?: ReadonlyMap<string, ExtensionOperatorFn>;
+};
+/**
+ * Delegate key for a model name: the first character lowercased, nothing else
+ * (the Prisma convention — `User` → `user`, `URLMap` → `uRLMap`). Keeping the
+ * rest untouched makes the mapping unambiguous and reversible.
+ */
+export declare function toClientName(params: {
+    name: string;
+}): string;
+/** RFC 4122 v4 UUID. */
+export declare function generateUuid(): string;
+/**
+ * Collision-resistant, sortable-ish id in the CUID spirit: `"c"` + a base-36
+ * millisecond timestamp + 16 random base-36 characters. Starts with a letter so
+ * it is safe as an HTML id and in every database identifier context.
+ */
+export declare function generateCuid(): string;
+/** 21-character NanoID over the standard URL-safe alphabet (64 chars, unbiased 6-bit mask). */
+export declare function generateNanoid(): string;
+/**
+ * ULID: 10 characters of millisecond timestamp + 16 of randomness, Crockford
+ * base32, lexicographically sortable by creation time. 256 % 32 === 0, so the
+ * byte-to-symbol fold is unbiased.
+ */
+export declare function generateUlid(): string;
+/**
+ * The value the runtime sends for an app-side default, or `undefined` when the
+ * database owns it (autoincrement, dbgenerated, literal, enum value — those
+ * ride the column's DEFAULT clause so the database stays the single source of
+ * truth for them).
+ */
+export declare function generateDefaultValue(params: {
+    spec: DefaultValueIR;
+}): unknown;
+/** Resolve a whole schema into the runtime's read-only metadata. */
+export declare function buildRuntimeMeta(params: {
+    schema: SchemaIR;
+    computed?: ComputedConfig;
+}): RuntimeMeta;
+/** Look a model up by client name or model name; unknown names are a caller error. */
+export declare function getModelMeta(params: {
+    meta: RuntimeMeta;
+    model: string;
+}): ModelMeta;
+/** Look a field up on a model; unknown names are a caller error naming the field. */
+export declare function getFieldMeta(params: {
+    model: ModelMeta;
+    field: string;
+    context: string;
+}): FieldMeta;
+//# sourceMappingURL=model-meta.d.ts.map

package/dist/model-meta.d.ts.map

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

package/dist/nested-writes.d.ts

@@ -0,0 +1,67 @@
+import type { SqlDialect, SqlStatement } from "@vibeorm/sql";
+import type { ModelMeta, RuntimeMeta } from "./model-meta.ts";
+import type { QueryMethod } from "./query-builder.ts";
+export type ClientRowLike = Record<string, unknown>;
+/**
+ * Executes ORM statements against ONE adapter (plain or transactional).
+ * `single` runs a single-row mutation with the client's full RETURNING /
+ * re-select machinery (mysql-safe); `statement` runs a raw AST statement
+ * (join-table work has no model).
+ */
+export type StatementRunner = {
+    readonly single: (params: {
+        model: string;
+        method: QueryMethod;
+        args: Record<string, unknown>;
+    }) => Promise<ClientRowLike>;
+    readonly rows: (params: {
+        model: string;
+        method: QueryMethod;
+        args: Record<string, unknown>;
+    }) => Promise<ClientRowLike[]>;
+    readonly affected: (params: {
+        model: string;
+        method: QueryMethod;
+        args: Record<string, unknown>;
+    }) => Promise<number>;
+    readonly statement: (params: {
+        statement: SqlStatement;
+        model: string;
+        method: string;
+    }) => Promise<ClientRowLike[]>;
+};
+/** What the client hands the nested-write orchestrator. */
+export type WriteContext = {
+    readonly meta: RuntimeMeta;
+    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. */
+    readonly transactional: <T>(fn: (run: StatementRunner) => Promise<T>) => Promise<T>;
+};
+/** Does this `data` object carry nested relation operations? */
+export declare function hasNestedWrites(params: {
+    model: ModelMeta;
+    data: 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).
+ */
+export declare function createWithNested(params: {
+    ctx: WriteContext;
+    model: ModelMeta;
+    data: Record<string, unknown>;
+}): Promise<ClientRowLike>;
+/**
+ * `update` with nested relation operations. Always transactional (the flow is
+ * multi-statement by construction). Returns the parent row after its UPDATE
+ * (or the pre-read row when only children changed).
+ */
+export declare function updateWithNested(params: {
+    ctx: WriteContext;
+    model: ModelMeta;
+    where: Record<string, unknown>;
+    data: Record<string, unknown>;
+}): Promise<ClientRowLike>;
+//# sourceMappingURL=nested-writes.d.ts.map

package/dist/nested-writes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nested-writes.d.ts","sourceRoot":"","sources":["../src/nested-writes.ts"],"names":[],"mappings":"AAqCA,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE7D,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAgFtD,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEpD;;;;;GAKG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE;QACxB,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,WAAW,CAAC;QACpB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAC/B,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,CAAC,MAAM,EAAE;QACtB,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,WAAW,CAAC;QACpB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAC/B,KAAK,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;IAC/B,QAAQ,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE;QAC1B,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,WAAW,CAAC;QACpB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAC/B,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACtB,QAAQ,CAAC,SAAS,EAAE,CAAC,MAAM,EAAE;QAC3B,SAAS,EAAE,YAAY,CAAC;QACxB,KAAK,EAAE,MAAM,CAAC;QACd,MAAM,EAAE,MAAM,CAAC;KAChB,KAAK,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;CAChC,CAAC;AAEF,2DAA2D;AAC3D,MAAM,MAAM,YAAY,GAAG;IACzB,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,UAAU,CAAC;IAC7B,6EAA6E;IAC7E,QAAQ,CAAC,GAAG,EAAE,eAAe,CAAC;IAC9B,+DAA+D;IAC/D,QAAQ,CAAC,aAAa,EAAE,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,EAAE,eAAe,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;CACrF,CAAC;AAmCF,gEAAgE;AAChE,wBAAgB,eAAe,CAAC,MAAM,EAAE;IAAE,KAAK,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG,OAAO,CAQpF;AA4eD;;;GAGG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE;IAC7C,GAAG,EAAE,YAAY,CAAC;IAClB,KAAK,EAAE,SAAS,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B,GAAG,OAAO,CAAC,aAAa,CAAC,CAOzB;AA0hBD;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,MAAM,EAAE;IAC7C,GAAG,EAAE,YAAY,CAAC;IAClB,KAAK,EAAE,SAAS,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B,GAAG,OAAO,CAAC,aAAa,CAAC,CAqCzB"}

package/dist/policy-operation.d.ts

@@ -0,0 +1,14 @@
+import type { DynamicClient } from "./client.ts";
+type PolicyOperationFactory = <T>(run: (client: DynamicClient) => Promise<T>) => Promise<T>;
+/** Register the engine-owned deferred-operation factory without exposing it on clients. */
+export declare function registerPolicyOperations(params: {
+    client: DynamicClient;
+    factory: PolicyOperationFactory;
+}): void;
+/** Defer the whole policy flow; its client is selected by the ordinary array-transaction runner. */
+export declare function deferPolicyOperation<T>(params: {
+    client: DynamicClient;
+    run: (client: DynamicClient) => Promise<T>;
+}): Promise<T>;
+export {};
+//# sourceMappingURL=policy-operation.d.ts.map

package/dist/policy-operation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy-operation.d.ts","sourceRoot":"","sources":["../src/policy-operation.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEjD,KAAK,sBAAsB,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,OAAO,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC;AAG5F,2FAA2F;AAC3F,wBAAgB,wBAAwB,CAAC,MAAM,EAAE;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,OAAO,EAAE,sBAAsB,CAAA;CAAE,GAAG,IAAI,CAEjH;AAED,oGAAoG;AACpG,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,MAAM,EAAE;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,GAAG,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,OAAO,CAAC,CAAC,CAAC,CAAA;CAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAIjI"}

package/dist/policy.d.ts

@@ -0,0 +1,17 @@
+import type { RuntimeMeta } from "./model-meta.ts";
+import type { DynamicClient, ModelDelegate } from "./client.ts";
+/** Values a policy context may bind — the scoping column's scalar shape. */
+export type PolicyContextValue = string | number | bigint;
+/**
+ * Attach `$withPolicy`/`$bypassPolicy` and fail-close the base delegates of
+ * policied models. No-op on schemas without @@policy.
+ */
+export declare function attachPolicy(params: {
+    client: DynamicClient;
+    meta: RuntimeMeta;
+    wrapDelegate?: (params: {
+        model: string;
+        delegate: ModelDelegate;
+    }) => ModelDelegate;
+}): void;
+//# sourceMappingURL=policy.d.ts.map

package/dist/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../src/policy.ts"],"names":[],"mappings":"AAgCA,OAAO,KAAK,EAAa,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9D,OAAO,KAAK,EAA0B,aAAa,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGxF,4EAA4E;AAC5E,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,CAAC;AAkrB1D;;;GAGG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,IAAI,EAAE,WAAW,CAAC;IAAC,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,aAAa,CAAA;KAAE,KAAK,aAAa,CAAC;CAAE,GAAG,IAAI,CAmK9K"}