@vibeorm/runtime 1.1.3 → 1.1.5

package/README.md

@@ -59,6 +59,54 @@ Per-operation `countStrategy` takes precedence over the client default.
 
 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.
+
+```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 },
+);
+```
+
+**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`
 
 Custom error class thrown when Zod validation fails on input or output data.
@@ -86,7 +134,7 @@ type DatabaseAdapter = {
 
 ### Exported Types
 
-`DatabaseAdapter`, `QueryResult`, `SqlExecutor`, `VibeClientOptions`, `ModelMeta`, `ModelMetaMap`, `ModelSchemas`, `ValidationSchema`, `QueryProfile`, `RelationProfile`, `ScalarFieldMeta`, `RelationFieldMeta`, `SqlQuery`, `Operation`.
+`DatabaseAdapter`, `QueryResult`, `SqlExecutor`, `VibeClientOptions`, `ModelMeta`, `ModelMetaMap`, `ModelSchemas`, `ValidationSchema`, `QueryProfile`, `RelationProfile`, `ScalarFieldMeta`, `RelationFieldMeta`, `SqlQuery`, `Operation`, `RetryOptions`.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibeorm/runtime",
-  "version": "1.1.3",
+  "version": "1.1.5",
   "description": "Driver-agnostic query engine and client runtime for VibeORM",
   "license": "MIT",
   "keywords": [

package/src/client.ts

@@ -36,6 +36,8 @@ import {
   executeLateralJoinQuery,
 } from "./lateral-join-builder.ts";
 import { generateDefault } from "./id-generators.ts";
+import { createView } from "./view.ts";
+import type { ViewDefinition } from "./view.ts";
 
 /**
  * Creates a VibeORM client instance.
@@ -1218,6 +1220,20 @@ export function createClient(params: {
     await adapter.disconnect();
   };
 
+  // defineView — create a read-only scoped client restricted to specific fields per model.
+  client.defineView = function (viewParams: {
+    name: string;
+    definition: ViewDefinition;
+  }): Record<string, unknown> {
+    return createView({
+      client,
+      name: viewParams.name,
+      definition: viewParams.definition,
+      allModelsMeta,
+      schemas: params.schemas,
+    });
+  };
+
   // Eager connection: warm up the pool immediately on client creation.
   // This runs in the background — it won't block client construction,
   // but will ensure connections are ready before the first real query.

package/src/index.ts

@@ -20,6 +20,10 @@ export {
   executeLateralJoinQuery,
 } from "./lateral-join-builder.ts";
 export { toSqlExecutor } from "./adapter.ts";
+export { withRetry } from "./retry.ts";
+export { ViewResult, createView } from "./view.ts";
+export type { ViewDefinition } from "./view.ts";
+export type { RetryOptions } from "./retry.ts";
 
 export type {
   DatabaseAdapter,

package/src/retry.ts

@@ -0,0 +1,183 @@
+/**
+ * Retry utility with exponential backoff and jitter.
+ *
+ * Only retries on transient errors (VibeTransientError) — connection failures,
+ * deadlocks, serialization failures, statement timeouts, and pool exhaustion.
+ * Deterministic errors (VibeRequestError) are never retried.
+ *
+ * @example
+ * ```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 },
+ * );
+ *
+ * // With abort signal
+ * const controller = new AbortController();
+ * const result = await withRetry(
+ *   () => db.user.findFirst({ where: { id: 1 } }),
+ *   { signal: controller.signal },
+ * );
+ *
+ * // Retry only specific error codes
+ * const result = await withRetry(
+ *   () => db.$transaction(async (tx) => { ... }, { isolationLevel: "Serializable" }),
+ *   { retryOn: ["SERIALIZATION_FAILURE", "DEADLOCK"] },
+ * );
+ * ```
+ */
+
+import { VibeTransientError } from "./errors.ts";
+import type { VibeTransientErrorCode } from "./errors.ts";
+
+// ─── Types ───────────────────────────────────────────────────────
+
+/**
+ * Options for configuring retry behavior.
+ */
+export type RetryOptions = {
+  /**
+   * Maximum number of retry attempts (default: 3).
+   * The first execution is not counted as a retry, so the operation
+   * may execute up to `maxRetries + 1` times total.
+   */
+  maxRetries?: number;
+  /**
+   * Base delay in milliseconds for exponential backoff (default: 50).
+   * Actual delay = min(baseDelay * 2^attempt + jitter, maxDelay).
+   */
+  baseDelay?: number;
+  /**
+   * Maximum delay in milliseconds between retries (default: 5000).
+   * Caps the exponential growth to prevent excessively long waits.
+   */
+  maxDelay?: number;
+  /**
+   * Maximum jitter in milliseconds added to each delay (default: 50).
+   * Randomized per retry to prevent thundering herd effects when
+   * many clients retry simultaneously after a shared failure.
+   */
+  maxJitter?: number;
+  /**
+   * Optional AbortSignal to cancel pending retries.
+   * When aborted, the last error is thrown immediately without
+   * further retry attempts.
+   */
+  signal?: AbortSignal;
+  /**
+   * Optional filter to retry only specific transient error codes.
+   * When provided, only errors with matching codes are retried;
+   * other transient errors are thrown immediately.
+   *
+   * When not provided, all transient errors are retried.
+   */
+  retryOn?: VibeTransientErrorCode[];
+  /**
+   * Optional callback invoked before each retry attempt.
+   * Useful for logging or metrics.
+   */
+  onRetry?: (params: { error: VibeTransientError; attempt: number; delay: number }) => void;
+};
+
+// ─── Implementation ──────────────────────────────────────────────
+
+/**
+ * Compute the delay for a retry attempt using exponential backoff with jitter.
+ * Formula: min(baseDelay * 2^attempt + random(0, maxJitter), maxDelay)
+ */
+function computeDelay(params: {
+  attempt: number;
+  baseDelay: number;
+  maxDelay: number;
+  maxJitter: number;
+}): number {
+  const { attempt, baseDelay, maxDelay, maxJitter } = params;
+  const exponential = baseDelay * Math.pow(2, attempt);
+  const jitter = Math.random() * maxJitter;
+  return Math.min(exponential + jitter, maxDelay);
+}
+
+/**
+ * Sleep for a given number of milliseconds.
+ * Resolves immediately if the signal is already aborted.
+ */
+function sleep(params: { ms: number; signal?: AbortSignal }): Promise<void> {
+  const { ms, signal } = params;
+  if (signal?.aborted) return Promise.resolve();
+  return new Promise((resolve) => {
+    const timer = setTimeout(resolve, ms);
+    signal?.addEventListener("abort", () => {
+      clearTimeout(timer);
+      resolve();
+    }, { once: true });
+  });
+}
+
+/**
+ * Execute a function with automatic retry on transient errors.
+ *
+ * Uses exponential backoff with jitter to space out retries and
+ * prevent thundering herd effects. Only retries `VibeTransientError`
+ * instances — deterministic errors (constraint violations, validation
+ * errors, etc.) are thrown immediately.
+ *
+ * @param fn - The async operation to execute and potentially retry.
+ * @param options - Optional retry configuration.
+ * @returns The result of the first successful execution.
+ * @throws The last error if all retries are exhausted.
+ */
+export async function withRetry<T>(
+  fn: () => Promise<T>,
+  options?: RetryOptions,
+): Promise<T> {
+  const maxRetries = options?.maxRetries ?? 3;
+  const baseDelay = options?.baseDelay ?? 50;
+  const maxDelay = options?.maxDelay ?? 5000;
+  const maxJitter = options?.maxJitter ?? 50;
+  const signal = options?.signal;
+  const retryOn = options?.retryOn;
+  const onRetry = options?.onRetry;
+
+  let lastError: unknown;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (err) {
+      lastError = err;
+
+      // Only retry transient errors
+      if (!(err instanceof VibeTransientError)) throw err;
+
+      // If retryOn filter is set, only retry matching codes
+      if (retryOn && !retryOn.includes(err.code)) throw err;
+
+      // Don't retry if we've exhausted attempts
+      if (attempt >= maxRetries) throw err;
+
+      // Don't retry if aborted
+      if (signal?.aborted) throw err;
+
+      const delay = computeDelay({ attempt, baseDelay, maxDelay, maxJitter });
+
+      // Notify before sleeping
+      onRetry?.({ error: err, attempt: attempt + 1, delay });
+
+      await sleep({ ms: delay, signal });
+
+      // Check abort again after sleep
+      if (signal?.aborted) throw err;
+    }
+  }
+
+  // Should never reach here, but TypeScript needs it
+  throw lastError;
+}

package/src/view.ts

@@ -0,0 +1,629 @@
+/**
+ * VibeORM Views — Read-only scoped client with field-level restrictions.
+ *
+ * Views restrict which fields are returned by default, provide a `reveal`
+ * keyword for explicit opt-in to extra fields, and enforce serialization
+ * safety via toJSON() that excludes revealed fields.
+ */
+
+import type {
+  ModelMeta,
+  ModelMetaMap,
+  ModelSchemas,
+  ValidationSchema,
+} from "./types.ts";
+import { getModelByNameMap } from "./types.ts";
+
+// ─── Types ────────────────────────────────────────────────────────
+
+/**
+ * View definition: maps camelCase model keys to sets of allowed field names.
+ * Example: { user: { id: true, name: true }, post: { id: true, title: true } }
+ */
+export type ViewDefinition = Record<string, Record<string, true>>;
+
+// ─── ViewResult Class ─────────────────────────────────────────────
+
+/**
+ * Wraps a query result record with serialization safety.
+ *
+ * - All fields (view + revealed) are accessible as direct properties.
+ * - `toJSON()` excludes revealed fields (called by JSON.stringify).
+ * - `$unsafe()` returns a plain object with ALL fields.
+ *
+ * Internal tracking (`_revealedFields`, `$unsafe`, `toJSON`) is non-enumerable
+ * so it doesn't appear in Object.keys(), for...in, or spread.
+ */
+export class ViewResult {
+  /** Allow dynamic property access for view/revealed fields. */
+  [key: string]: unknown;
+
+  /** @internal — set of field names that were revealed (non-enumerable). */
+  declare readonly _revealedFields: ReadonlySet<string>;
+  /** @internal — set of field names that are relation fields (non-enumerable). */
+  declare readonly _relationFields: ReadonlySet<string>;
+
+  constructor(params: {
+    record: Record<string, unknown>;
+    viewFields: Record<string, true>;
+    revealedFields: Record<string, true>;
+    relationFields?: Set<string>;
+  }) {
+    const { record, viewFields, revealedFields, relationFields } = params;
+
+    // Track which fields are revealed
+    const revealedSet = new Set(Object.keys(revealedFields));
+    Object.defineProperty(this, "_revealedFields", {
+      value: revealedSet,
+      enumerable: false,
+      writable: false,
+      configurable: false,
+    });
+
+    // Track relation field names
+    Object.defineProperty(this, "_relationFields", {
+      value: relationFields ?? new Set<string>(),
+      enumerable: false,
+      writable: false,
+      configurable: false,
+    });
+
+    // Assign all view + revealed fields as enumerable properties
+    const allowedFields = new Set([
+      ...Object.keys(viewFields),
+      ...Object.keys(revealedFields),
+    ]);
+
+    for (const key of allowedFields) {
+      if (key in record) {
+        (this as Record<string, unknown>)[key] = record[key];
+      }
+    }
+
+    // Also assign relation fields that may be present
+    if (relationFields) {
+      for (const relName of relationFields) {
+        if (relName in record) {
+          (this as Record<string, unknown>)[relName] = record[relName];
+        }
+      }
+    }
+  }
+
+  /**
+   * Returns a plain object with only view fields (excludes revealed fields).
+   * Called automatically by JSON.stringify().
+   */
+  toJSON(): Record<string, unknown> {
+    const obj: Record<string, unknown> = {};
+    for (const key of Object.keys(this)) {
+      if (this._revealedFields.has(key)) continue;
+      const value = (this as Record<string, unknown>)[key];
+      if (value instanceof ViewResult) {
+        obj[key] = value.toJSON();
+      } else if (Array.isArray(value)) {
+        obj[key] = value.map((item) =>
+          item instanceof ViewResult ? item.toJSON() : item
+        );
+      } else {
+        obj[key] = value;
+      }
+    }
+    return obj;
+  }
+
+  /**
+   * Returns a plain object with ALL fields (view + revealed).
+   * Use this as an escape hatch when you need the full data.
+   */
+  $unsafe(): Record<string, unknown> {
+    const obj: Record<string, unknown> = {};
+    for (const key of Object.keys(this)) {
+      const value = (this as Record<string, unknown>)[key];
+      if (value instanceof ViewResult) {
+        obj[key] = value.$unsafe();
+      } else if (Array.isArray(value)) {
+        obj[key] = value.map((item) =>
+          item instanceof ViewResult ? item.$unsafe() : item
+        );
+      } else {
+        obj[key] = value;
+      }
+    }
+    return obj;
+  }
+}
+
+// Make $unsafe non-enumerable on prototype (toJSON is already non-enumerable by default on prototype)
+Object.defineProperty(ViewResult.prototype, "$unsafe", {
+  ...Object.getOwnPropertyDescriptor(ViewResult.prototype, "$unsafe"),
+  enumerable: false,
+});
+
+Object.defineProperty(ViewResult.prototype, "toJSON", {
+  ...Object.getOwnPropertyDescriptor(ViewResult.prototype, "toJSON"),
+  enumerable: false,
+});
+
+// ─── Result Wrapping ──────────────────────────────────────────────
+
+/**
+ * Wrap raw query result records into ViewResult instances.
+ */
+export function wrapResultsWithView(params: {
+  records: Record<string, unknown>[];
+  viewFields: Record<string, true>;
+  revealedFields: Record<string, true>;
+  viewDefinition: ViewDefinition;
+  modelMeta: ModelMeta;
+  allModelsMeta: ModelMetaMap;
+}): ViewResult[] {
+  const { records, viewFields, revealedFields, viewDefinition, modelMeta, allModelsMeta } = params;
+  const modelMap = getModelByNameMap({ allModelsMeta });
+
+  // Build set of relation field names present on this model
+  const relationFieldSet = new Set<string>();
+  for (const rel of modelMeta.relationFields) {
+    relationFieldSet.add(rel.name);
+  }
+
+  return records.map((record) => {
+    // Recursively wrap relation fields
+    const wrappedRecord: Record<string, unknown> = { ...record };
+
+    for (const rel of modelMeta.relationFields) {
+      const relValue = record[rel.name];
+      if (relValue === undefined || relValue === null) continue;
+
+      // Find the related model's camelCase key in allModelsMeta
+      const relatedModelMeta = modelMap.get(rel.relatedModel);
+      if (!relatedModelMeta) continue;
+
+      // Find the camelCase key for this related model in the view definition
+      const relatedViewKey = findModelKeyInMeta({
+        modelName: rel.relatedModel,
+        allModelsMeta,
+      });
+      const relatedViewFields = relatedViewKey
+        ? viewDefinition[relatedViewKey]
+        : undefined;
+
+      if (relatedViewFields) {
+        // Relation is in view definition — restrict its fields
+        if (Array.isArray(relValue)) {
+          wrappedRecord[rel.name] = wrapResultsWithView({
+            records: relValue as Record<string, unknown>[],
+            viewFields: relatedViewFields,
+            revealedFields: extractNestedReveal({ args: {}, relationName: rel.name }),
+            viewDefinition,
+            modelMeta: relatedModelMeta,
+            allModelsMeta,
+          });
+        } else if (typeof relValue === "object") {
+          const wrapped = wrapResultsWithView({
+            records: [relValue as Record<string, unknown>],
+            viewFields: relatedViewFields,
+            revealedFields: extractNestedReveal({ args: {}, relationName: rel.name }),
+            viewDefinition,
+            modelMeta: relatedModelMeta,
+            allModelsMeta,
+          });
+          wrappedRecord[rel.name] = wrapped[0] ?? null;
+        }
+      }
+      // If relation is NOT in view definition, leave as-is (no restriction)
+    }
+
+    return new ViewResult({
+      record: wrappedRecord,
+      viewFields,
+      revealedFields,
+      relationFields: relationFieldSet,
+    });
+  });
+}
+
+/**
+ * Extract the nested reveal fields for a specific relation from the args.
+ * For now returns empty — reveal handling is done at args merging time.
+ */
+function extractNestedReveal(_params: {
+  args: Record<string, unknown>;
+  relationName: string;
+}): Record<string, true> {
+  return {};
+}
+
+/**
+ * Find the camelCase key for a PascalCase model name in allModelsMeta.
+ */
+function findModelKeyInMeta(params: {
+  modelName: string;
+  allModelsMeta: ModelMetaMap;
+}): string | undefined {
+  for (const [key, meta] of Object.entries(params.allModelsMeta)) {
+    if (meta.name === params.modelName) return key;
+  }
+  return undefined;
+}
+
+// ─── Args Merging ─────────────────────────────────────────────────
+
+/**
+ * Merge view field definitions with user-provided args.
+ *
+ * This injects the view's field set as a `select`, handles `reveal`
+ * by merging extra fields into the SQL select, and recursively
+ * restricts relation includes.
+ */
+export function mergeViewArgs(params: {
+  args: Record<string, unknown>;
+  viewFields: Record<string, true>;
+  viewDefinition: ViewDefinition;
+  modelMeta: ModelMeta;
+  allModelsMeta: ModelMetaMap;
+}): {
+  mergedArgs: Record<string, unknown>;
+  revealedFields: Record<string, true>;
+} {
+  const { args, viewFields, viewDefinition, modelMeta, allModelsMeta } = params;
+  const modelMap = getModelByNameMap({ allModelsMeta });
+
+  // Extract reveal from args
+  const reveal = (args.reveal ?? {}) as Record<string, boolean>;
+  const revealedFields: Record<string, true> = {};
+  for (const [key, val] of Object.entries(reveal)) {
+    if (val === true) {
+      revealedFields[key] = true;
+    }
+  }
+
+  // Build the effective select
+  let effectiveSelect: Record<string, true>;
+
+  const userSelect = args.select as Record<string, boolean> | undefined;
+  if (userSelect) {
+    // User select narrows within view fields — only allow keys in viewFields
+    effectiveSelect = {};
+    for (const [key, val] of Object.entries(userSelect)) {
+      if (val === true && key in viewFields) {
+        effectiveSelect[key] = true;
+      }
+    }
+  } else {
+    // Default: use all view fields
+    effectiveSelect = { ...viewFields };
+  }
+
+  // Merge revealed fields into effective select (they go to SQL but are tracked separately)
+  for (const key of Object.keys(revealedFields)) {
+    effectiveSelect[key] = true;
+  }
+
+  // Process includes — restrict relation fields by view definition
+  const include = args.include as Record<string, unknown> | undefined;
+  let mergedInclude: Record<string, unknown> | undefined;
+
+  if (include) {
+    mergedInclude = {};
+    for (const [relName, relArgs] of Object.entries(include)) {
+      if (relName === "_count") {
+        // Pass through _count unchanged
+        mergedInclude[relName] = relArgs;
+        continue;
+      }
+
+      // Find the relation's model
+      const relField = modelMeta.relationFields.find((r) => r.name === relName);
+      if (!relField) {
+        mergedInclude[relName] = relArgs;
+        continue;
+      }
+
+      const relatedModelMeta = modelMap.get(relField.relatedModel);
+      if (!relatedModelMeta) {
+        mergedInclude[relName] = relArgs;
+        continue;
+      }
+
+      // Find view fields for the related model
+      const relatedViewKey = findModelKeyInMeta({
+        modelName: relField.relatedModel,
+        allModelsMeta,
+      });
+      const relatedViewFields = relatedViewKey
+        ? viewDefinition[relatedViewKey]
+        : undefined;
+
+      if (!relatedViewFields) {
+        // Relation not in view definition — pass through unchanged
+        mergedInclude[relName] = relArgs;
+        continue;
+      }
+
+      if (relArgs === true) {
+        // include: { posts: true } → include: { posts: { select: <viewFields> } }
+        mergedInclude[relName] = { select: { ...relatedViewFields } };
+      } else if (typeof relArgs === "object" && relArgs !== null) {
+        const nestedArgs = relArgs as Record<string, unknown>;
+        const nestedReveal = (nestedArgs.reveal ?? {}) as Record<string, boolean>;
+        const nestedRevealedFields: Record<string, true> = {};
+        for (const [key, val] of Object.entries(nestedReveal)) {
+          if (val === true) {
+            nestedRevealedFields[key] = true;
+          }
+        }
+
+        // Build nested select from view fields + nested reveal
+        const nestedSelect: Record<string, true> = { ...relatedViewFields };
+        for (const key of Object.keys(nestedRevealedFields)) {
+          nestedSelect[key] = true;
+        }
+
+        // Preserve other nested args (where, orderBy, take, skip, etc.)
+        const preservedArgs: Record<string, unknown> = {};
+        for (const [key, val] of Object.entries(nestedArgs)) {
+          if (key !== "reveal" && key !== "select") {
+            preservedArgs[key] = val;
+          }
+        }
+
+        // Handle nested includes recursively
+        if (nestedArgs.include) {
+          const nestedInclude = mergeViewArgs({
+            args: { include: nestedArgs.include },
+            viewFields: relatedViewFields,
+            viewDefinition,
+            modelMeta: relatedModelMeta,
+            allModelsMeta,
+          });
+          preservedArgs.include = (nestedInclude.mergedArgs as Record<string, unknown>).include;
+          // When there's a nested include, DON'T use select — use include + omit approach
+          // Actually, select and include conflict. If there's a nested include,
+          // we need to let include handle it and not use select
+          mergedInclude[relName] = {
+            ...preservedArgs,
+          };
+          continue;
+        }
+
+        mergedInclude[relName] = {
+          select: nestedSelect,
+          ...preservedArgs,
+        };
+      }
+    }
+  }
+
+  // Build the merged args
+  const mergedArgs: Record<string, unknown> = {};
+
+  // Copy through non-view-specific args
+  for (const [key, val] of Object.entries(args)) {
+    if (key !== "select" && key !== "reveal" && key !== "include" && key !== "omit") {
+      mergedArgs[key] = val;
+    }
+  }
+
+  // Set the effective select
+  mergedArgs.select = effectiveSelect;
+
+  // Set include if present
+  if (mergedInclude && Object.keys(mergedInclude).length > 0) {
+    // When we have both select and include, we need to also include relation
+    // keys in the select so they don't get filtered out
+    for (const relName of Object.keys(mergedInclude)) {
+      (mergedArgs.select as Record<string, unknown>)[relName] = mergedInclude[relName];
+    }
+  }
+
+  return { mergedArgs, revealedFields };
+}
+
+// ─── Zod Safety Net ───────────────────────────────────────────────
+
+/**
+ * Build a picked Zod schema that only allows the specified fields.
+ * Uses Zod v4's .pick() method via duck-typing.
+ */
+export function buildPickedSchema(params: {
+  schema: ValidationSchema;
+  fields: Record<string, true>;
+}): ValidationSchema | undefined {
+  const { schema, fields } = params;
+
+  // Duck-type check: does the schema have .pick()?
+  const schemaWithPick = schema as unknown as {
+    pick?: (fields: Record<string, true>) => ValidationSchema;
+  };
+
+  if (typeof schemaWithPick.pick === "function") {
+    try {
+      return schemaWithPick.pick(fields);
+    } catch {
+      // If .pick() fails (e.g., invalid fields), fall back to no safety net
+      return undefined;
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Validate records through the view's picked schema.
+ * Returns parsed data (with extra fields stripped) on success.
+ * On failure, returns the original records (defense-in-depth, not critical path).
+ */
+export function applyViewSchemaFilter(params: {
+  records: Record<string, unknown>[];
+  viewSchema: ValidationSchema | undefined;
+}): Record<string, unknown>[] {
+  const { records, viewSchema } = params;
+  if (!viewSchema) return records;
+
+  return records.map((record) => {
+    const result = viewSchema.safeParse(record);
+    if (result.success) {
+      return result.data as Record<string, unknown>;
+    }
+    // Safety net failed — return original record (the ViewResult wrapper
+    // will still restrict what's visible)
+    return record;
+  });
+}
+
+// ─── View Delegate Creation ───────────────────────────────────────
+
+/** Read operations exposed on view delegates. */
+const VIEW_READ_OPS = [
+  "findMany",
+  "findFirst",
+  "findUnique",
+  "findUniqueOrThrow",
+  "findFirstOrThrow",
+  "count",
+  "aggregate",
+  "groupBy",
+] as const;
+
+/**
+ * Create a view delegate that wraps an existing model delegate.
+ * Only read operations are exposed; writes are omitted.
+ */
+export function createViewDelegate(params: {
+  delegate: Record<string, Function>;
+  modelMeta: ModelMeta;
+  viewFields: Record<string, true>;
+  viewDefinition: ViewDefinition;
+  allModelsMeta: ModelMetaMap;
+  modelSchema?: ValidationSchema;
+}): Record<string, Function> {
+  const { delegate, modelMeta, viewFields, viewDefinition, allModelsMeta, modelSchema } = params;
+
+  // Build the picked schema eagerly (once per view, not per query)
+  const viewSchema = modelSchema
+    ? buildPickedSchema({ schema: modelSchema, fields: viewFields })
+    : undefined;
+
+  const viewDelegate: Record<string, Function> = {};
+
+  // count, aggregate, groupBy — pass through unchanged
+  for (const op of ["count", "aggregate", "groupBy"] as const) {
+    if (typeof delegate[op] === "function") {
+      viewDelegate[op] = delegate[op]!.bind(delegate);
+    }
+  }
+
+  // Read operations that return model instances — wrap with view logic
+  for (const op of ["findMany", "findFirst", "findUnique", "findUniqueOrThrow", "findFirstOrThrow"] as const) {
+    const originalFn = delegate[op];
+    if (typeof originalFn !== "function") continue;
+
+    viewDelegate[op] = async function (args: Record<string, unknown> = {}): Promise<unknown> {
+      // Merge view fields + reveal into args
+      const { mergedArgs, revealedFields } = mergeViewArgs({
+        args,
+        viewFields,
+        viewDefinition,
+        modelMeta,
+        allModelsMeta,
+      });
+
+      // Call the original delegate method with merged args
+      const rawResult = await originalFn.call(delegate, mergedArgs);
+
+      // Handle null/undefined (findFirst, findUnique)
+      if (rawResult === null || rawResult === undefined) {
+        return rawResult;
+      }
+
+      // Build the query-specific schema (view fields + revealed fields)
+      let querySchema = viewSchema;
+      if (Object.keys(revealedFields).length > 0 && modelSchema) {
+        const allFields = { ...viewFields, ...revealedFields };
+        querySchema = buildPickedSchema({ schema: modelSchema, fields: allFields }) ?? viewSchema;
+      }
+
+      // Wrap results
+      if (Array.isArray(rawResult)) {
+        // Apply Zod safety net first
+        const filtered = applyViewSchemaFilter({
+          records: rawResult as Record<string, unknown>[],
+          viewSchema: querySchema,
+        });
+        return wrapResultsWithView({
+          records: filtered,
+          viewFields,
+          revealedFields,
+          viewDefinition,
+          modelMeta,
+          allModelsMeta,
+        });
+      } else {
+        // Single result (findUniqueOrThrow, findFirstOrThrow)
+        const filtered = applyViewSchemaFilter({
+          records: [rawResult as Record<string, unknown>],
+          viewSchema: querySchema,
+        });
+        const wrapped = wrapResultsWithView({
+          records: filtered,
+          viewFields,
+          revealedFields,
+          viewDefinition,
+          modelMeta,
+          allModelsMeta,
+        });
+        return wrapped[0] ?? null;
+      }
+    };
+  }
+
+  return viewDelegate;
+}
+
+// ─── View Client Creation ─────────────────────────────────────────
+
+/**
+ * Create a view client from an existing client and a view definition.
+ * Returns an object with only the models specified in the definition,
+ * each with read-only delegates restricted to view fields.
+ */
+export function createView(params: {
+  client: Record<string, unknown>;
+  name: string;
+  definition: ViewDefinition;
+  allModelsMeta: ModelMetaMap;
+  schemas?: Record<string, ModelSchemas>;
+}): Record<string, unknown> {
+  const { client, name, definition, allModelsMeta, schemas } = params;
+
+  const viewClient: Record<string, unknown> = {};
+
+  for (const [modelKey, viewFields] of Object.entries(definition)) {
+    const delegate = client[modelKey] as Record<string, Function> | undefined;
+    if (!delegate || typeof delegate !== "object") {
+      throw new Error(
+        `[vibeorm] View "${name}": model "${modelKey}" not found on the client. ` +
+        `Available models: ${Object.keys(allModelsMeta).join(", ")}`
+      );
+    }
+
+    const modelMeta = allModelsMeta[modelKey];
+    if (!modelMeta) {
+      throw new Error(
+        `[vibeorm] View "${name}": no metadata found for model "${modelKey}".`
+      );
+    }
+
+    viewClient[modelKey] = createViewDelegate({
+      delegate,
+      modelMeta,
+      viewFields,
+      viewDefinition: definition,
+      allModelsMeta,
+      modelSchema: schemas?.[modelKey]?.model,
+    });
+  }
+
+  return viewClient;
+}