@vibeorm/runtime 1.3.0 → 2.0.0-alpha.2

package/README.md

@@ -1,141 +1,84 @@
 # @vibeorm/runtime
 
-Driver-agnostic query engine and client runtime for VibeORM. This package contains the SQL query builder, WHERE clause compiler, relation loading strategies, and client factory. It does **not** include any database driver — use an adapter package to connect to PostgreSQL.
+> Part of **[VibeORM](https://github.com/vibeorm/vibeorm)** — a type-safe TypeScript ORM for Bun and Node. Prisma-schema or TypeScript-DSL input, a canonical schema IR, a generated client, and a dialect-aware SQL layer over PostgreSQL, PGlite, SQLite and MySQL.
 
-## Installation
+The query engine behind the generated client: it turns delegate calls into SQL statements, loads relations, runs nested writes and moves values across the wire through the codec table. It is its own package because it is driver-agnostic — it talks to databases only through the `DatabaseAdapter` contract, so adapters and the generator can depend on it without depending on each other.
 
 ```bash
-bun add @vibeorm/runtime
+bun add @vibeorm/runtime@alpha
 ```
 
-You also need an adapter:
+> **Pre-release.** `2.0.0-alpha.x`, published under the `alpha` dist-tag. `npm i vibeorm` still resolves to the stable v1 line.
 
-```bash
-bun add @vibeorm/adapter-bun    # for bun:sql
-# or
-bun add @vibeorm/adapter-pg pg  # for node-postgres
-```
+Most users never install this directly — it ships as a dependency of [`vibeorm`](https://www.npmjs.com/package/vibeorm) and of the generated client. Reach for it when you are writing an adapter or tooling against the runtime.
 
-## Usage
+## What it does
 
-This package is consumed by the generated client. You typically don't import from it directly — the generated `index.ts` calls `createClient()` internally.
+`createClient({ schema, adapter, options })` builds a `DynamicClient` from the Schema IR at runtime: model delegates keyed by both camelCase client name and model name (`$models`), plus `$transaction`, `$queryRaw`, `$executeRaw`, `$queryRawUnsafe`, `$executeRawUnsafe`, `$on`, `$connect` and `$disconnect`. The delegates are deliberately broad here (`ClientRow` in, `ClientRow` out); the generated `.d.ts` declares the precise per-model types on top.
 
-```ts
-// The generated client wires everything together:
-import { VibeClient } from "./generated/vibeorm/index.ts";
-
-const db = VibeClient({
-  relationStrategy: "query",
-  log: false,
-});
-```
+Each `ModelDelegate` implements 16 methods:
 
-## API
+| Group | Methods |
+|---|---|
+| Read | `findMany` · `findFirst` · `findFirstOrThrow` · `findUnique` · `findUniqueOrThrow` |
+| Create | `create` · `createMany` · `createManyAndReturn` |
+| Update | `update` · `updateMany` · `upsert` |
+| Delete | `delete` · `deleteMany` |
+| Aggregate | `count` · `aggregate` · `groupBy` |
 
-### `createClient({ options, modelMeta, schemas? })`
+The statement-building pieces are exported too, for tooling that needs SQL without executing it: `buildQuery`, `compileWhere`, `compileSelect`, `compileOrderBy`, `resolveResultShape`, and the runtime metadata builders `buildRuntimeMeta`, `getModelMeta`, `getFieldMeta`.
 
-Creates a VibeORM client instance. Called by generated code — takes model metadata, optional Zod schemas, and client options.
+## The adapter contract
 
-`countStrategy` can be set globally in client options and overridden per count call:
+`DatabaseAdapter` is frozen. Implement it and any driver works with the whole ORM:
 
 ```ts
-await db.user.count({
-  where: { isActive: true },
-  countStrategy: "subquery",
-});
+import type { DatabaseAdapter, QueryResult, TransactionOptions } from "@vibeorm/runtime";
+
+const adapter: DatabaseAdapter = {
+  dialect: "postgres",
+  provider: "postgresql",
+  async execute(params: { text: string; values: unknown[] }): Promise<Record<string, unknown>[]> { /* … */ },
+  async executeUnsafe(params: { text: string; values?: unknown[] }): Promise<QueryResult> { /* … */ },
+  async transaction<T>(fn: (tx: DatabaseAdapter) => Promise<T>, options?: TransactionOptions): Promise<T> { /* … */ },
+  async connect(): Promise<void> { /* … */ },
+  async disconnect(): Promise<void> { /* … */ },
+  formatArrayParam(values: unknown[]): unknown { /* … */ },
+};
 ```
 
-Per-operation `countStrategy` takes precedence over the client default.
-
-### Mutation RETURNING behavior
-
-`create`, `update`, `delete`, and `upsert` now narrow SQL `RETURNING` columns when `select` is provided, reducing row payload size.
-
-- Default behavior: full scalar row is returned (same as before)
-- With `select`: only selected scalar columns are returned (plus internal keys when needed)
-- With `returning: true`: force full scalar `RETURNING` payload even when `select` is present
+- `execute` is the ORM hot path (row-returning, statement-cached by the adapter). `executeUnsafe` is the raw/DDL path and is the only place `affectedRows` surfaces.
+- `transaction` nests: an inner call creates a savepoint. `isolationLevel` and `timeout` are top-level only — a nested call must refuse both with `VIBE_VALIDATION`.
+- Adapters never let raw driver errors escape. Each maps its driver's failures to `VibeError` codes (`VIBE_UNIQUE_VIOLATION`, `VIBE_FK_VIOLATION`, `VIBE_TRANSACTION`, `VIBE_ADAPTER`) through a per-driver table, with the driver error as `cause`.
+- `formatArrayParam` converts a JS array into the driver's preferred scalar-array representation; the ORM path binds arrays through it, the raw path does not.
+- The optional `wire` declaration (`WireFidelity`) tells the runtime what the driver already delivers for non-list scalars, so provably no-op decoders can be skipped.
 
-### `toSqlExecutor({ adapter })`
+`toSqlExecutor({ adapter })` bridges an adapter to the `SqlExecutor` shape `@vibeorm/migrate` runs on.
 
-Bridges a `DatabaseAdapter` to a `SqlExecutor` for use with the migrate package.
-
-### `withRetry(fn, options?)`
-
-Retry utility with exponential backoff and jitter. Only retries `VibeTransientError` instances (connection failures, deadlocks, serialization conflicts, statement timeouts, pool exhaustion). Deterministic errors (`VibeRequestError`) are never retried.
+## Relation strategies
 
 ```ts
-import { withRetry } from "@vibeorm/runtime";
-
-// Basic — 3 retries, exponential backoff with jitter
-const users = await withRetry(() =>
-  db.user.findMany({ where: { active: true } })
-);
-
-// Custom options
-const user = await withRetry(
-  () => db.user.create({ data: { email: "new@example.com" } }),
-  { maxRetries: 5, baseDelay: 100, maxDelay: 10000 },
-);
-
-// Retry only specific error codes
-const result = await withRetry(
-  () => db.$transaction(async (tx) => {
-    /* ... */
-  }, { isolationLevel: "Serializable" }),
-  { retryOn: ["SERIALIZATION_FAILURE", "DEADLOCK"] },
-);
-
-// With abort signal
-const controller = new AbortController();
-const result = await withRetry(
-  () => db.user.findFirst({ where: { id: 1 } }),
-  { signal: controller.signal },
-);
+const db = createClient({ schema, adapter, options: { relationStrategy: "join" } });
 ```
 
-**Options (`RetryOptions`):**
-
-| Option | Default | Description |
-|--------|---------|-------------|
-| `maxRetries` | `3` | Max retry attempts (total executions = maxRetries + 1) |
-| `baseDelay` | `50` | Base delay in ms for exponential backoff |
-| `maxDelay` | `5000` | Maximum delay cap in ms |
-| `maxJitter` | `50` | Random jitter added per retry to prevent thundering herd |
-| `signal` | — | `AbortSignal` to cancel pending retries |
-| `retryOn` | — | Filter to retry only specific `VibeTransientErrorCode`s |
-| `onRetry` | — | Callback `({ error, attempt, delay }) => void` for logging/metrics |
-
-Backoff formula: `min(baseDelay * 2^attempt + random(0, maxJitter), maxDelay)`
-
-### `VibeValidationError`
+- `"query"` (default): one query per relation, batched with `WHERE ... IN`. Works on every dialect.
+- `"join"`: a single statement using `LEFT JOIN LATERAL` with JSON aggregation. PostgreSQL and PGlite only; other dialects throw `VibeError` with code `VIBE_UNSUPPORTED_CAPABILITY`.
 
-Custom error class thrown when Zod validation fails on input or output data.
+A `relationStrategy` argument on a find overrides the client default. Relation trees are resolved by `resolveRelationSelection` / `resolveRelationLink` and attached by `attachRelations` (query strategy) or `attachLateralRelations` (join strategy).
 
-### `DatabaseAdapter` interface
+## Codecs
 
-The contract that adapter packages implement:
+Value encoding and decoding lives in one table per dialect: `POSTGRES_CODECS`, `SQLITE_CODECS`, `MYSQL_CODECS`, indexed by `DIALECT_CODECS` and reachable through `getCodec({ dialect, type })`. Nothing else in the codebase coerces values — scattered coercion is what produced v1's BigInt, enum-array and timestamp bugs.
 
 ```ts
-type DatabaseAdapter = {
-  execute(params: { text: string; values: unknown[] }): Promise<Record<string, unknown>[]>;
-  executeRaw(params: { text: string; values: unknown[] }): Promise<QueryResult>;
-  transaction<T>(params: { fn: (adapter: DatabaseAdapter) => Promise<T> }): Promise<T>;
-  connect(): Promise<void>;
-  disconnect(): Promise<void>;
-};
+import { decodeRows, encodeValue, getCodec } from "@vibeorm/runtime";
 ```
 
-### Relation Loading Strategies
-
-| Strategy | Method | Best for |
-|----------|--------|----------|
-| `"query"` | Parent query + batched `WHERE IN` queries | Deep/nested includes |
-| `"join"` | `LEFT JOIN LATERAL` + JSON aggregation | Flat includes, fewer round-trips |
-
-### Exported Types
-
-`DatabaseAdapter`, `QueryResult`, `SqlExecutor`, `VibeClientOptions`, `ModelMeta`, `ModelMetaMap`, `ModelSchemas`, `ValidationSchema`, `QueryProfile`, `RelationProfile`, `ScalarFieldMeta`, `RelationFieldMeta`, `SqlQuery`, `Operation`, `RetryOptions`.
+`encodeValue` runs on every parameter, `decodeValue` / `decodeRow` / `decodeRows` on every row materialization point — including relation children and join-strategy rows, not only top-level parents. `decodeAggregateValue` handles aggregate columns, whose result type differs from the underlying field's.
 
-## License
+## Links
 
-[MIT](../../LICENSE)
+- [Documentation](https://github.com/vibeorm/vibeorm/tree/master/docs)
+- [Query API](https://github.com/vibeorm/vibeorm/blob/master/docs/queries.md)
+- [Repository and issues](https://github.com/vibeorm/vibeorm)
+- MIT licensed

package/dist/adapter.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Database adapter contract for VibeORM v2. FROZEN INTERFACE — the runtime is
+ * driver-agnostic and talks to databases exclusively through this type;
+ * adapter packages (adapter-bun, adapter-pg, adapter-pglite, adapter-sqlite,
+ * adapter-mysql) implement it.
+ *
+ * ERROR CONTRACT: adapters never let raw driver errors escape. Every failure
+ * is mapped to a VibeError with a stable code via a per-driver table
+ * (unique violation → VIBE_UNIQUE_VIOLATION, FK violation → VIBE_FK_VIOLATION,
+ * serialization/deadlock → VIBE_TRANSACTION, connection/other → VIBE_ADAPTER),
+ * with the driver error attached as `cause`.
+ */
+import type { Dialect, Provider } from "@vibeorm/schema";
+import type { WireFidelity } from "@vibeorm/sql";
+/** Transaction isolation levels (mapped per dialect by the adapter). */
+export type IsolationLevel = "ReadCommitted" | "RepeatableRead" | "Serializable";
+/**
+ * Options for `$transaction` / `adapter.transaction`.
+ *
+ * `timeout` is milliseconds, enforced database-side where the engine can
+ * genuinely cancel a running statement (postgres servers via `SET LOCAL
+ * statement_timeout`, mysql's SELECT-only `MAX_EXECUTION_TIME`). Dialect
+ * honesty: an adapter whose engine CANNOT enforce it refuses loudly instead
+ * of no-opping — sqlite adapters throw `VIBE_VALIDATION` (busy_timeout only
+ * bounds lock acquisition), pglite throws `VIBE_UNSUPPORTED_CAPABILITY` (the
+ * WASM build accepts statement_timeout but never fires it).
+ *
+ * Options are TOP-LEVEL only: a nested `transaction()` call (a savepoint)
+ * refuses BOTH fields with `VIBE_VALIDATION` on every adapter — a savepoint
+ * cannot change the isolation level of the transaction it joins, and a
+ * nested timeout is not enforceable.
+ */
+export type TransactionOptions = {
+    isolationLevel?: IsolationLevel;
+    timeout?: number;
+};
+/** Result of an unsafe/raw execution: rows plus affected-row count. */
+export type QueryResult = {
+    rows: Record<string, unknown>[];
+    affectedRows: number;
+};
+/**
+ * The primary interface every database adapter implements. Adapters own
+ * connection management, statement caching, transactions (including nested →
+ * savepoints), driver-specific parameter formatting and driver-error mapping.
+ */
+export type DatabaseAdapter = {
+    /** SQL dialect this adapter's database speaks (selects the @vibeorm/sql dialect). */
+    readonly dialect: Dialect;
+    /** Concrete provider (pglite and postgresql both speak `postgres`). */
+    readonly provider: Provider;
+    /**
+     * What this DRIVER actually delivers for non-list scalar columns on the
+     * result path (board #30) — lets the runtime's decode plans skip decoders
+     * that are provably no-ops for this driver (e.g. node-postgres already hands
+     * `Date` for timestamptz and parsed values for jsonb). OPTIONAL and purely
+     * an optimization contract: an adapter that declares nothing gets the full
+     * idempotency-guarded decode path. Declare only what the driver verifiably
+     * does; transactional adapters must carry the same declaration.
+     */
+    readonly wire?: WireFidelity;
+    /**
+     * Execute a parameterized query on the ORM hot path and return rows.
+     * The adapter owns prepared-statement caching and ORM-path parameter
+     * serialization (e.g. tagged scalar-list params vs JSON values).
+     */
+    execute(params: {
+        text: string;
+        values: unknown[];
+    }): Promise<Record<string, unknown>[]>;
+    /**
+     * Execute a raw query (`$queryRaw*`, `$executeRaw*`, DDL). No statement
+     * caching; raw-path parameter serialization (arrays pass through to the
+     * driver where it supports them — see LEARNINGS: raw vs ORM paths differ).
+     *
+     * OMITTING `values` changes semantics on the sqlite adapters (board #31):
+     * `adapter-sqlite` and `adapter-better-sqlite3` route no-`values` text
+     * through the driver's multi-statement script mode (`db.run`/`exec` — the
+     * shape @vibeorm/migrate emits for DDL/PRAGMA batches), which CANNOT return
+     * rows: a parameterless SELECT yields `rows: []` there, while pg/pglite/
+     * mysql/bun return its result set either way. Callers that want rows from a
+     * single parameterless statement must pass `values: []` — the client's
+     * `$queryRawUnsafe` always does. Rule of thumb: `values` present (even
+     * empty) = one prepared statement with rows; `values` absent = script mode,
+     * rows not guaranteed.
+     */
+    executeUnsafe(params: {
+        text: string;
+        values?: unknown[];
+    }): Promise<QueryResult>;
+    /**
+     * Run `fn` inside a transaction; the callback receives a transactional
+     * adapter with this same interface. Nested calls create savepoints. Throwing
+     * rolls back (the savepoint or the whole transaction) and rethrows.
+     *
+     * `options` is honored on TOP-LEVEL calls only. A NESTED call refuses any
+     * `isolationLevel` or `timeout` with `VIBE_VALIDATION` (`meta.nested:
+     * true`), identically on every adapter: a savepoint cannot change the
+     * isolation level of the transaction it joins, and a nested timeout is not
+     * enforceable. Silently dropping the option was the pre-#3 behaviour of the
+     * pg/pglite/mysql/bun adapters and is forbidden by constitution rule 4.
+     */
+    transaction<T>(fn: (txAdapter: DatabaseAdapter) => Promise<T>, options?: TransactionOptions): Promise<T>;
+    /** Eagerly open/verify connectivity (pool warm-up or first connection). */
+    connect(): Promise<void>;
+    /** Gracefully close all connections. */
+    disconnect(): Promise<void>;
+    /**
+     * Convert a JS array into the driver's preferred representation for a
+     * scalar-array parameter (postgres `= ANY($n)`): PG array literal string for
+     * drivers that send strings, the raw array for drivers with native support.
+     */
+    formatArrayParam(values: unknown[]): unknown;
+};
+/** Minimal SQL execution interface used by @vibeorm/migrate. */
+export type SqlExecutor = (params: {
+    text: string;
+    values?: unknown[];
+}) => Promise<Record<string, unknown>[]>;
+/** Bridge a DatabaseAdapter to the migrate package's SqlExecutor shape. */
+export declare function toSqlExecutor(params: {
+    adapter: DatabaseAdapter;
+}): SqlExecutor;
+//# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAIjD,wEAAwE;AACxE,MAAM,MAAM,cAAc,GAAG,eAAe,GAAG,gBAAgB,GAAG,cAAc,CAAC;AAEjF;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,kBAAkB,GAAG;IAC/B,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAIF,uEAAuE;AACvE,MAAM,MAAM,WAAW,GAAG;IACxB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IAChC,YAAY,EAAE,MAAM,CAAC;CACtB,CAAC;AAIF;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,qFAAqF;IACrF,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAE5B;;;;;;;;OAQG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,YAAY,CAAC;IAE7B;;;;OAIG;IACH,OAAO,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,OAAO,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;IAEzF;;;;;;;;;;;;;;;OAeG;IACH,aAAa,CAAC,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,EAAE,CAAA;KAAE,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAElF;;;;;;;;;;;OAWG;IACH,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,SAAS,EAAE,eAAe,KAAK,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAEzG,2EAA2E;IAC3E,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEzB,wCAAwC;IACxC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5B;;;;OAIG;IACH,gBAAgB,CAAC,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,CAAC;CAC9C,CAAC;AAIF,gEAAgE;AAChE,MAAM,MAAM,WAAW,GAAG,CAAC,MAAM,EAAE;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,OAAO,EAAE,CAAC;CACpB,KAAK,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC;AAEzC,2EAA2E;AAC3E,wBAAgB,aAAa,CAAC,MAAM,EAAE;IAAE,OAAO,EAAE,eAAe,CAAA;CAAE,GAAG,WAAW,CAS/E"}

package/dist/client.d.ts

@@ -0,0 +1,152 @@
+/**
+ * The dynamic client: model delegates over a `DatabaseAdapter`, built from the
+ * Schema IR at runtime.
+ *
+ * This is the engine the generated client wraps in P2 proper. It is deliberately
+ * untyped-per-model — the generator emits a `.d.ts` that declares each delegate
+ * with precise argument and result types, and casts to it. Nothing about the
+ * shape of a query lives here: `query-builder.ts` builds statements,
+ * `@vibeorm/sql` renders them, `codecs.ts` moves values across the wire,
+ * `relation-loader.ts` attaches included relations, `nested-writes.ts`
+ * orchestrates relation verbs inside create/update data.
+ *
+ * Execution split:
+ *   - row-returning statements use `adapter.execute` (the cached hot path),
+ *   - count-returning mutations (createMany/updateMany/deleteMany) use
+ *     `adapter.executeUnsafe`, the only place the frozen adapter contract
+ *     surfaces `affectedRows`.
+ */
+import type { SchemaIR } from "@vibeorm/schema";
+import type { DatabaseAdapter, TransactionOptions } from "./adapter.ts";
+import type { RelationStrategy } from "./query-builder.ts";
+import type { ClientComputedOptions } from "./computed.ts";
+import type { ClientExtensionsOptions } from "./extensions.ts";
+import type { DefineViewFn } from "./views.ts";
+/** One executed statement, reported to `ClientOptions.onQuery`. */
+export type QueryEvent = {
+    /** Model name, or `null` for raw queries. */
+    readonly model: string | null;
+    /** ORM method, or `"$queryRaw"` / `"$executeRaw"`. */
+    readonly method: string;
+    readonly text: string;
+    readonly values: readonly unknown[];
+    readonly durationMs: number;
+};
+export type ClientOptions = {
+    /** Called after every statement — logging, tracing, test assertions. */
+    readonly onQuery?: (event: QueryEvent) => void;
+    /**
+     * Default relation-loading strategy: `"query"` (batched WHERE-IN, portable,
+     * the default) or `"join"` (LATERAL + JSON aggregation, postgres/pglite
+     * only). A per-query `relationStrategy` argument overrides it.
+     */
+    readonly relationStrategy?: RelationStrategy;
+    /**
+     * Append the primary key to ORDER BY when a find has no explicit orderBy
+     * (default false) — deterministic row order at the cost of a sort. v1 parity.
+     */
+    readonly defaultOrderByPk?: boolean;
+    /**
+     * Append the primary key as a tie-breaker to `distinct` ordering (default
+     * TRUE) — without it, WHICH row represents each distinct key is unspecified.
+     * v1 parity.
+     */
+    readonly distinctOrderByPk?: boolean;
+};
+/** Rows are plain objects keyed by field name; the generated client narrows them. */
+export type ClientRow = Record<string, unknown>;
+/** Result of the count-returning batch methods. */
+export type BatchResult = {
+    readonly count: number;
+};
+/**
+ * A model's methods. Arguments and results are intentionally broad here — the
+ * generated `.d.ts` replaces this surface with precise per-model types, and
+ * keeping the runtime free of inference is what holds the type-cost budget
+ * (constitution rule 2).
+ */
+export type ModelDelegate = {
+    readonly findMany: (args?: ClientRow) => Promise<ClientRow[]>;
+    readonly findFirst: (args?: ClientRow) => Promise<ClientRow | null>;
+    readonly findFirstOrThrow: (args?: ClientRow) => Promise<ClientRow>;
+    readonly findUnique: (args: ClientRow) => Promise<ClientRow | null>;
+    readonly findUniqueOrThrow: (args: ClientRow) => Promise<ClientRow>;
+    readonly create: (args: ClientRow) => Promise<ClientRow>;
+    readonly createMany: (args: ClientRow) => Promise<BatchResult>;
+    readonly createManyAndReturn: (args: ClientRow) => Promise<ClientRow[]>;
+    readonly update: (args: ClientRow) => Promise<ClientRow>;
+    readonly updateMany: (args: ClientRow) => Promise<BatchResult>;
+    readonly upsert: (args: ClientRow) => Promise<ClientRow>;
+    readonly delete: (args: ClientRow) => Promise<ClientRow>;
+    readonly deleteMany: (args?: ClientRow) => Promise<BatchResult>;
+    /** Plain form returns a number; `{ select: { _all, field } }` returns per-key counts. */
+    readonly count: (args?: ClientRow) => Promise<number | Record<string, number>>;
+    readonly aggregate: (args: ClientRow) => Promise<ClientRow>;
+    readonly groupBy: (args: ClientRow) => Promise<ClientRow[]>;
+};
+/**
+ * The client. Delegates are also attached as own properties under their
+ * camelCase names (`client.user.findMany()`); the type surfaces them through
+ * `$models` because a plain index signature would erase the `$`-methods.
+ * Model names can never collide with those: every reserved client name is
+ * `$`-prefixed (see `RESERVED_CLIENT_NAMES` in @vibeorm/schema).
+ */
+export type DynamicClient = {
+    /** Delegates keyed by BOTH camelCase client name and model name. */
+    readonly $models: Readonly<Record<string, ModelDelegate>>;
+    /**
+     * Subscribe to client events (`"query"` fires after every statement, with
+     * the same payload as `ClientOptions.onQuery` — both fire). Returns an
+     * unsubscribe function. Transaction clients share the parent's listeners.
+     */
+    readonly $on: (event: "query", listener: (event: QueryEvent) => void) => () => void;
+    /**
+     * Run work in ONE transaction. Callback form: `fn` receives a transaction
+     * client; everything it runs rides the same BEGIN/COMMIT and a throw rolls
+     * back. Array form (Prisma parity): UN-AWAITED delegate calls — delegate
+     * methods return LAZY query promises that only dispatch on await — run
+     * SEQUENTIALLY inside one transaction, results returned positionally.
+     */
+    readonly $transaction: {
+        <T>(fn: (tx: DynamicClient) => Promise<T>, options?: TransactionOptions): Promise<T>;
+        <T extends readonly unknown[]>(operations: readonly [...T], options?: TransactionOptions): Promise<{
+            -readonly [K in keyof T]: Awaited<T[K]>;
+        }>;
+    };
+    /** Tagged template — interpolations become bound parameters, never text. */
+    readonly $queryRaw: (strings: TemplateStringsArray, ...values: unknown[]) => Promise<ClientRow[]>;
+    /** Tagged template returning the affected-row count. */
+    readonly $executeRaw: (strings: TemplateStringsArray, ...values: unknown[]) => Promise<number>;
+    readonly $queryRawUnsafe: (text: string, ...values: unknown[]) => Promise<ClientRow[]>;
+    readonly $executeRawUnsafe: (text: string, ...values: unknown[]) => Promise<number>;
+    readonly $connect: () => Promise<void>;
+    readonly $disconnect: () => Promise<void>;
+    /**
+     * Field-masking views (v1 `defineView` parity, board #11) — a read-only
+     * scoped client restricted to the definition's models and fields. Attached
+     * by `attachDefineView` after construction (hence optional in the type);
+     * it is always present on a built client, transaction clients included.
+     */
+    readonly $defineView?: DefineViewFn;
+};
+/**
+ * Build a client for a schema over an adapter.
+ *
+ * The adapter chooses the dialect: the same IR runs on postgres, sqlite or
+ * mysql, and every dialect difference is resolved by `@vibeorm/sql` and the
+ * codec table rather than by branching here.
+ *
+ * @example
+ * const db = createClient({ schema, adapter });
+ * const users = await db.$models.user.findMany({ where: { active: true } });
+ */
+export declare function createClient(params: {
+    schema: SchemaIR;
+    adapter: DatabaseAdapter;
+    options?: ClientOptions;
+    /** Extension wiring — baked mounts + manifest from the generated client, live instances from the caller. */
+    extensions?: ClientExtensionsOptions;
+    /** Computed-field wiring — baked manifest from the generated client, live specs from the caller. */
+    computed?: ClientComputedOptions;
+}): DynamicClient;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

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

package/dist/codecs.d.ts

@@ -0,0 +1,170 @@
+/**
+ * The codec entry points — constitution rule 6.
+ *
+ * The PURE per-dialect tables (dialect × scalar type) live in @vibeorm/sql
+ * (`codecs.ts` there) and are re-exported here so consumers keep one import
+ * site. This module owns the FieldMeta-aware entry points: list handling,
+ * enum-to-String routing and row materialization.
+ *
+ * The two rules that make it work:
+ *   - EVERY parameter bound by the query builder passes through `encodeValue`.
+ *   - EVERY row materialized by the client passes through `decodeRow`/
+ *     `decodeRows` — including every relation-loaded child row, at every
+ *     materialization point (the v1 lesson: BigInt-as-string and enum-array
+ *     bugs came from children skipping coercion).
+ */
+import type { Dialect, FieldType } from "@vibeorm/schema";
+import type { ScalarCodec, WireFidelity } from "@vibeorm/sql";
+import type { FieldMeta, ModelMeta } from "./model-meta.ts";
+export { DIALECT_CODECS, MYSQL_CODECS, POSTGRES_CODECS, SQLITE_CODECS, decodeIsNoop, } from "@vibeorm/sql";
+export type { CodecTable, ScalarCodec, WireFidelity } from "@vibeorm/sql";
+/** The codec for a field type on a dialect. Enum references use the String codec. */
+export declare function getCodec(params: {
+    dialect: Dialect;
+    type: FieldType;
+}): ScalarCodec;
+/**
+ * Encode one value for parameter binding. `null`/`undefined` pass through
+ * untouched (SQL NULL). List fields encode element-wise; the adapter's
+ * `formatArrayParam` then owns the array's wire representation — except for
+ * postgres ENUM arrays, which become an array literal here (no driver can
+ * serialize them, see {@link isPostgresEnumList}).
+ */
+export declare function encodeValue(params: {
+    dialect: Dialect;
+    field: FieldMeta;
+    value: unknown;
+}): unknown;
+/**
+ * Decode one driver value. List fields decode element-wise.
+ *
+ * postgres returns ENUM arrays as a raw array literal string, because no driver
+ * knows a user-defined enum's array OID (LEARNINGS.md) — that literal is parsed
+ * here, next to the other coercion rules.
+ */
+export declare function decodeValue(params: {
+    dialect: Dialect;
+    field: FieldMeta;
+    value: unknown;
+}): unknown;
+/**
+ * Encode one COMPARISON operand (WHERE / cursor bounds). Identical to
+ * {@link encodeValue} everywhere except sqlite Decimal (SQL review B4):
+ * Decimal STORES as exact TEXT there, but text comparison is lexicographic —
+ * so every compare site casts the column (`CAST(col AS REAL)`) and binds the
+ * operand as a NUMBER. Comparison precision is float64-bounded on sqlite
+ * (docs/dialects.md); storage and read-back stay exact.
+ */
+export declare function encodeFilterValue(params: {
+    dialect: Dialect;
+    field: FieldMeta;
+    value: unknown;
+}): unknown;
+/**
+ * Encode one AGGREGATE-predicate operand (HAVING). On sqlite an aggregate
+ * expression has NO column affinity, so a TEXT operand never converts and the
+ * predicate is constant-false (SQL review M5, live-proven) — operands bind in
+ * raw numeric form there: Decimal as a number (the aggregate is over
+ * `CAST(col AS REAL)`), BigInt as a bigint (bun:sqlite binds int64 natively).
+ * Other dialects keep the field codec's wire form.
+ */
+export declare function encodeAggregateOperand(params: {
+    dialect: Dialect;
+    field: FieldMeta;
+    value: unknown;
+}): unknown;
+/** Decode one non-null driver value (list handling prebound). */
+type RowDecoder = (value: unknown) => unknown;
+/**
+ * The prebound encoder for one field on one dialect, or `null` when its codec
+ * encode is the identity. Mirrors `encodeValue` exactly (see `fieldDecoder`).
+ */
+export declare function fieldEncoder(params: {
+    dialect: Dialect;
+    field: FieldMeta;
+}): RowDecoder | null;
+/**
+ * The prebound decoder for one field on one dialect, or `null` when its codec
+ * decode is the identity (nothing to do). Mirrors `decodeValue` exactly:
+ * elements of a list decode element-wise (null elements pass), a non-array
+ * value on a list field goes through the element decoder as-is.
+ *
+ * With a `wire` declaration (board #30 — the ADAPTER's promise about what its
+ * driver delivers), decoders that are provably no-ops for that wire are pruned
+ * too ({@link decodeIsNoop}): non-list DateTime/Json/Int/Float columns on
+ * drivers that already deliver native forms. Without a declaration the full
+ * idempotency-guarded decoder set applies — exactly the pre-#30 behaviour.
+ */
+export declare function fieldDecoder(params: {
+    dialect: Dialect;
+    field: FieldMeta;
+    wire?: WireFidelity;
+}): RowDecoder | null;
+/**
+ * Materialize one driver row: column names become field names, values pass
+ * through their codecs. Columns the model does not know (aggregate aliases, raw
+ * extras) are carried over verbatim.
+ */
+export declare function decodeRow(params: {
+    dialect: Dialect;
+    model: ModelMeta;
+    row: Record<string, unknown>;
+    /** The executing adapter's wire declaration — prunes provably-no-op decoders (board #30). */
+    wire?: WireFidelity;
+}): Record<string, unknown>;
+/** `decodeRow` over a result set. */
+export declare function decodeRows(params: {
+    dialect: Dialect;
+    model: ModelMeta;
+    rows: readonly Record<string, unknown>[];
+    /** The executing adapter's wire declaration — prunes provably-no-op decoders (board #30). */
+    wire?: WireFidelity;
+}): Record<string, unknown>[];
+/**
+ * `decodeRows` for rows the caller OWNS (fresh driver output): when no column
+ * is renamed the rows are decoded in place — only columns whose codec does
+ * something are touched — and the same array returns. With renames it falls
+ * back to rebuilding rows. Every decoder is idempotent (each checks its input
+ * type), so re-materializing an already-decoded row is harmless.
+ *
+ * Internal to the runtime (client + relation loader) — the exported
+ * `decodeRow`/`decodeRows` keep their copy semantics.
+ */
+export declare function materializeRows(params: {
+    dialect: Dialect;
+    model: ModelMeta;
+    rows: Record<string, unknown>[];
+    /** The executing adapter's wire declaration — prunes provably-no-op decoders (board #30). */
+    wire?: WireFidelity;
+}): Record<string, unknown>[];
+/**
+ * `materializeRows` for JSON-transport rows — the join strategy's child rows
+ * after `JSON.parse`. Postgres-only by construction (lateral joins are).
+ */
+export declare function materializeJsonRows(params: {
+    model: ModelMeta;
+    rows: Record<string, unknown>[];
+}): Record<string, unknown>[];
+/**
+ * Normalize one aggregate value — the contract, tested live on PGlite:
+ *
+ * | aggregate | field type      | JS result                     |
+ * |-----------|-----------------|-------------------------------|
+ * | `_count`  | any / `_all`    | `number` (0 over an empty set)|
+ * | `_avg`    | Int/BigInt/Float| `number` (pg numeric → Number)|
+ * | `_avg`    | Decimal         | `string` (no float rounding)  |
+ * | `_sum`    | Int / Float     | `number`                      |
+ * | `_sum`    | BigInt          | `bigint`                      |
+ * | `_sum`    | Decimal         | `string`                      |
+ * | `_min/_max`| any            | the field's own codec type    |
+ *
+ * Every non-`_count` aggregate over an empty set is `null` (SQL semantics,
+ * kept deliberately — 0 would be a lie for MIN/AVG).
+ */
+export declare function decodeAggregateValue(params: {
+    dialect: Dialect;
+    key: "_count" | "_avg" | "_sum" | "_min" | "_max";
+    field: FieldMeta | null;
+    value: unknown;
+}): unknown;
+//# sourceMappingURL=codecs.d.ts.map