@vibeorm/runtime 1.2.0 → 2.0.0-alpha.1

package/src/coerce.ts

@@ -1,84 +0,0 @@
-/**
- * Scalar value type coercion.
- *
- * Coerce raw DB driver output to the JS types declared in the Prisma schema.
- * Currently handles `BigInt` (pg / bun:sql return PG `bigint` as a string,
- * but the application expects native `BigInt`).
- *
- * Lives in its own module so all relation loaders (query strategy, lateral
- * join strategy, post-write refresh, raw post-processing) can call it without
- * creating circular imports between `client.ts` and the relation loaders.
- *
- * Mutates the records in place — callers rely on this for performance.
- */
-
-import type { ModelMeta, ScalarFieldMeta } from "./types.ts";
-
-/**
- * Per-model cache of names of fields that need BigInt coercion.
- * Empty arrays are cached too, so the `length === 0` fast path costs one
- * `WeakMap.get` after the first call per model.
- *
- * Keyed by the `scalarFields` array reference (the same hot-path cache key
- * used by `getScalarFieldMap`), which is stable for the process lifetime
- * because model metadata is generated once at startup.
- */
-const _bigintFieldsCache = new WeakMap<
-  readonly ScalarFieldMeta[],
-  readonly string[]
->();
-
-function getBigIntFieldNames(modelMeta: ModelMeta): readonly string[] {
-  const sf = modelMeta.scalarFields;
-  let names = _bigintFieldsCache.get(sf);
-  if (names) return names;
-  const arr: string[] = [];
-  for (const f of sf) {
-    if ((f as { type?: string }).type === "BigInt") arr.push(f.name);
-  }
-  names = arr;
-  _bigintFieldsCache.set(sf, names);
-  return names;
-}
-
-/**
- * Coerce scalar field values on the given records to their JS-native types.
- *
- * Today only `BigInt` fields are affected. Driver behaviour:
- *  - `bun:sql` returns PG `bigint` as a JS `string`.
- *  - `node-postgres` returns PG `bigint` as a JS `string` by default too.
- *  - In both cases the Prisma type is `BigInt`, so we coerce.
- *
- * No-op when the model has no `BigInt` fields, or when `records` is empty.
- */
-export function coerceFieldTypes(params: {
-  records: Record<string, unknown>[];
-  modelMeta: ModelMeta;
-}): void {
-  const { records, modelMeta } = params;
-  if (records.length === 0) return;
-
-  const bigintNames = getBigIntFieldNames(modelMeta);
-  if (bigintNames.length === 0) return;
-
-  for (const record of records) {
-    for (const name of bigintNames) {
-      const val = record[name];
-      if (typeof val === "string") {
-        record[name] = BigInt(val);
-      } else if (typeof val === "number") {
-        record[name] = BigInt(val);
-      }
-    }
-  }
-}
-
-/**
- * True iff the model has any `BigInt` fields that require coercion.
- * Cheap O(1) lookup after first call per model. Hot-path callers (lateral-join
- * builder, relation loaders) use this to skip the per-row coercion loop
- * entirely for relations whose related model has no `BigInt` columns.
- */
-export function modelHasBigInt(modelMeta: ModelMeta): boolean {
-  return getBigIntFieldNames(modelMeta).length > 0;
-}

package/src/count-loader.ts

@@ -1,152 +0,0 @@
-/**
- * Shared `_count` resolution + loader, used by both the "query" and "join"
- * relation strategies.
- *
- * `resolveCountSpec` looks at `include._count` / `select._count` and returns
- * the list of list-relation names to count (or `["__all__"]` for `_count: true`,
- * or `null` when not requested).
- *
- * `loadRelationCounts` issues a single grouped `COUNT(*) GROUP BY <fk>` per
- * relation (parallelised across relations) and attaches the result as a
- * `_count` object on each parent record.
- *
- * Lives in its own module so the lateral-join path can call it without
- * pulling in `client.ts` (which would create a circular import).
- */
-
-import type { ModelMeta, ModelMetaMap } from "./types.ts";
-import { getScalarFieldMap, getModelByNameMap, PgArray } from "./types.ts";
-
-type SqlExecutor = (params: {
-  text: string;
-  values: unknown[];
-}) => Promise<Record<string, unknown>[]>;
-
-/**
- * Resolve `_count` specification from `include` or `select` args.
- * Returns the list of relation names to count, `["__all__"]` to count every
- * list relation, or `null` if `_count` was not requested.
- */
-export function resolveCountSpec(params: { args: Record<string, unknown> }): string[] | null {
-  const { args } = params;
-  const include = args.include as Record<string, unknown> | undefined;
-  const select = args.select as Record<string, unknown> | undefined;
-
-  const countArg = include?._count ?? select?._count;
-  if (!countArg) return null;
-
-  if (countArg === true) {
-    // Count all list relations — will be resolved by loadRelationCounts
-    return ["__all__"];
-  }
-
-  if (typeof countArg === "object" && countArg !== null) {
-    const countObj = countArg as Record<string, unknown>;
-    const selectObj = countObj.select as Record<string, boolean> | undefined;
-    if (selectObj) {
-      return Object.entries(selectObj)
-        .filter(([_, enabled]) => enabled)
-        .map(([name]) => name);
-    }
-  }
-
-  return null;
-}
-
-/**
- * Load relation counts and attach a `_count` object to each parent record.
- * Uses one grouped `COUNT(*)` query per relation, executed in parallel.
- *
- * Mutates the parent records in place.
- */
-export async function loadRelationCounts(params: {
-  records: Record<string, unknown>[];
-  modelMeta: ModelMeta;
-  allModelsMeta: ModelMetaMap;
-  countSpec: string[];
-  executor: SqlExecutor;
-}): Promise<void> {
-  const { records, modelMeta, allModelsMeta, countSpec, executor } = params;
-  const modelMap = getModelByNameMap({ allModelsMeta });
-  const parentPk = modelMeta.primaryKey[0];
-  if (!parentPk) return;
-
-  const parentIds = records.map((r) => r[parentPk]).filter((id) => id != null);
-  if (parentIds.length === 0) return;
-
-  // Resolve which relations to count
-  const listRelations = modelMeta.relationFields.filter((r) => r.isList);
-  const relationsToCount = countSpec.includes("__all__")
-    ? listRelations
-    : listRelations.filter((r) => countSpec.includes(r.name));
-
-  // Initialize _count on all records
-  for (const record of records) {
-    const countObj: Record<string, number> = {};
-    for (const rel of relationsToCount) {
-      countObj[rel.name] = 0;
-    }
-    record._count = countObj;
-  }
-
-  // Run all relation COUNT queries in parallel — each hits a different table
-  // so there are no data races on the parent records.
-  await Promise.all(
-    relationsToCount.map(async (rel) => {
-      const relatedModelMeta = modelMap.get(rel.relatedModel);
-      if (!relatedModelMeta) return;
-
-      // M:N relation: count via join table
-      if (rel.type === "manyToMany" && (rel as { joinTable?: string }).joinTable) {
-        const joinTableName = (rel as { joinTable?: string }).joinTable!;
-        const sorted = [modelMeta.name, relatedModelMeta.name].sort();
-        const parentIsA = modelMeta.name === sorted[0];
-        const parentCol = parentIsA ? "A" : "B";
-
-        const text = `SELECT "${joinTableName}"."${parentCol}" AS "__fk", COUNT(*) AS "__count" FROM "${joinTableName}" WHERE "${joinTableName}"."${parentCol}" = ANY($1) GROUP BY "${joinTableName}"."${parentCol}"`;
-        const result = await executor({ text, values: [new PgArray(parentIds)] });
-
-        const countMap = new Map<unknown, number>();
-        for (const row of result) {
-          countMap.set(row.__fk, Number(row.__count ?? 0));
-        }
-
-        for (const record of records) {
-          const pkValue = record[parentPk];
-          const cnt = countMap.get(pkValue) ?? 0;
-          (record._count as Record<string, number>)[rel.name] = cnt;
-        }
-        return;
-      }
-
-      // Find the FK column on the related model (with relationName disambiguation)
-      const reverseRel = relatedModelMeta.relationFields.find(
-        (r) => r.relatedModel === modelMeta.name && r.isForeignKey && r.fields.length > 0 &&
-          (!rel.relationName || r.relationName === rel.relationName)
-      );
-      if (!reverseRel) return;
-
-      const fkField = reverseRel.fields[0]!;
-      const relatedSfMap = getScalarFieldMap({ scalarFields: relatedModelMeta.scalarFields });
-      const fkScalar = relatedSfMap.get(fkField);
-      const fkDbName = fkScalar?.dbName ?? fkField;
-      const relatedTable = `"${relatedModelMeta.dbName}"`;
-
-      // SELECT "fk" AS "__fk", COUNT(*) AS "__count" FROM "related" WHERE "fk" = ANY($1) GROUP BY "fk"
-      const text = `SELECT ${relatedTable}."${fkDbName}" AS "__fk", COUNT(*) AS "__count" FROM ${relatedTable} WHERE ${relatedTable}."${fkDbName}" = ANY($1) GROUP BY ${relatedTable}."${fkDbName}"`;
-      const result = await executor({ text, values: [new PgArray(parentIds)] });
-
-      // Map counts back to parent records
-      const countMap = new Map<unknown, number>();
-      for (const row of result) {
-        countMap.set(row.__fk, Number(row.__count ?? 0));
-      }
-
-      for (const record of records) {
-        const pkValue = record[parentPk];
-        const cnt = countMap.get(pkValue) ?? 0;
-        (record._count as Record<string, number>)[rel.name] = cnt;
-      }
-    })
-  );
-}

package/src/errors.ts

@@ -1,460 +0,0 @@
-/**
- * VibeORM Error Hierarchy
- *
- * All VibeORM errors extend the abstract VibeError base class, split into
- * two concrete branches:
- *
- * - VibeRequestError — deterministic failures caused by invalid data or
- *   violated constraints. Running the same operation again will produce
- *   the same error. Includes: unique constraint, FK violation, not-null,
- *   check constraint, not-found, and validation errors.
- *
- * - VibeTransientError — transient infrastructure failures where retrying
- *   the same operation may succeed. Includes: connection errors, deadlocks,
- *   serialization failures, statement timeouts, and pool exhaustion.
- *
- * VibeValidationError (Zod validation) is a subclass of VibeRequestError,
- * so `instanceof VibeRequestError` catches both constraint violations AND
- * validation errors. Use `instanceof VibeValidationError` to narrow.
- *
- * @example
- * ```ts
- * import { VibeRequestError, VibeTransientError, VibeError } from "@vibeorm/runtime";
- *
- * try {
- *   await db.user.create({ data: { email: "taken@example.com" } });
- * } catch (error) {
- *   if (error instanceof VibeRequestError) {
- *     if (error.code === "UNIQUE_CONSTRAINT") {
- *       console.log(error.meta.constraint); // "User_email_key"
- *       console.log(error.meta.detail);     // 'Key (email)=(taken@example.com) already exists.'
- *       return { error: "Email already taken" };
- *     }
- *   }
- *   if (error instanceof VibeTransientError) {
- *     // error.retryable is always true
- *     return retry(() => db.user.create({ ... }));
- *   }
- *   throw error;
- * }
- * ```
- */
-
-// ─── Error Codes ─────────────────────────────────────────────────
-
-/**
- * Error codes for deterministic request failures.
- * The operation itself is invalid — changing the data would fix it.
- */
-export type VibeRequestErrorCode =
-  | "UNIQUE_CONSTRAINT"
-  | "FOREIGN_KEY_VIOLATION"
-  | "NOT_NULL_VIOLATION"
-  | "CHECK_CONSTRAINT"
-  | "NOT_FOUND"
-  | "VALIDATION_ERROR"
-  | "UNKNOWN_REQUEST_ERROR";
-
-/**
- * Error codes for transient infrastructure failures.
- * The operation is valid but the infrastructure failed — retrying may fix it.
- */
-export type VibeTransientErrorCode =
-  | "CONNECTION_ERROR"
-  | "DEADLOCK"
-  | "SERIALIZATION_FAILURE"
-  | "STATEMENT_TIMEOUT"
-  | "TOO_MANY_CONNECTIONS"
-  | "UNKNOWN_TRANSIENT_ERROR";
-
-/** Union of all VibeORM error codes. */
-export type VibeErrorCode = VibeRequestErrorCode | VibeTransientErrorCode;
-
-// ─── Error Meta ──────────────────────────────────────────────────
-
-/**
- * Structured metadata attached to every VibeORM error.
- * Fields are populated when available from the PostgreSQL error protocol
- * or from the application-level context (model name, operation, etc.).
- */
-export type VibeErrorMeta = {
-  /** VibeORM model name (e.g. "User", "Post"). Set for app-level errors. */
-  model?: string;
-  /** The field that caused the error (extracted from PG detail when possible). */
-  field?: string;
-  /** PostgreSQL constraint name (e.g. "User_email_key"). */
-  constraint?: string;
-  /** PostgreSQL table name from the error (e.g. "User"). */
-  table?: string;
-  /** PostgreSQL column name from the error. */
-  column?: string;
-  /** PostgreSQL schema name from the error (e.g. "public"). */
-  schema?: string;
-  /** Human-readable detail from PostgreSQL (e.g. 'Key (email)=(x@y.com) already exists.'). */
-  detail?: string;
-  /** The VibeORM operation that triggered this error (e.g. "create", "update"). */
-  operation?: string;
-  /** Validation direction — only set on VibeValidationError. */
-  direction?: "input" | "output";
-  /** Raw Zod error object — only set on VibeValidationError. */
-  zodError?: unknown;
-};
-
-// ─── Base Class ──────────────────────────────────────────────────
-
-/**
- * Abstract base class for all VibeORM errors.
- * Use `instanceof VibeError` to catch any error originating from VibeORM.
- */
-export abstract class VibeError extends Error {
-  abstract readonly code: VibeErrorCode;
-  readonly meta: VibeErrorMeta;
-
-  constructor(params: { message: string; meta?: VibeErrorMeta; cause?: Error }) {
-    super(params.message, { cause: params.cause });
-    this.name = "VibeError";
-    this.meta = params.meta ?? {};
-  }
-}
-
-// ─── Request Error (deterministic) ──────────────────────────────
-
-/**
- * Deterministic request error — the operation itself is invalid.
- * Same input will always produce the same failure.
- *
- * Covers: constraint violations, not-found, validation, and
- * unrecognized database errors that aren't transient.
- *
- * Use `error.code` to narrow the specific failure type.
- */
-export class VibeRequestError extends VibeError {
-  readonly code: VibeRequestErrorCode;
-
-  constructor(params: {
-    code: VibeRequestErrorCode;
-    message: string;
-    meta?: VibeErrorMeta;
-    cause?: Error;
-  }) {
-    super({ message: params.message, meta: params.meta, cause: params.cause });
-    this.name = "VibeRequestError";
-    this.code = params.code;
-  }
-}
-
-// ─── Validation Error (subclass of Request) ─────────────────────
-
-/**
- * Zod validation error — thrown when input or output data fails schema validation.
- *
- * Subclass of VibeRequestError, so `instanceof VibeRequestError` catches it.
- * Use `instanceof VibeValidationError` to narrow specifically to validation failures.
- *
- * Preserves backward-compatible fields: model, operation, direction, zodError.
- */
-export class VibeValidationError extends VibeRequestError {
-  readonly model: string;
-  readonly operation: string;
-  readonly direction: "input" | "output";
-  readonly zodError: unknown;
-
-  constructor(params: {
-    model: string;
-    operation: string;
-    direction: "input" | "output";
-    zodError: unknown;
-  }) {
-    const { model, operation, direction, zodError } = params;
-    const msg = `Validation failed for ${model}.${operation} (${direction}): ${formatZodError({ error: zodError })}`;
-    super({
-      code: "VALIDATION_ERROR",
-      message: msg,
-      meta: { model, operation, direction, zodError },
-    });
-    this.name = "VibeValidationError";
-    this.model = model;
-    this.operation = operation;
-    this.direction = direction;
-    this.zodError = zodError;
-  }
-}
-
-// ─── Transient Error (retryable) ────────────────────────────────
-
-/**
- * Transient infrastructure error — the operation is valid but the
- * infrastructure failed. Retrying the same operation may succeed.
- *
- * Covers: connection errors, deadlocks, serialization failures,
- * statement timeouts, and pool exhaustion.
- *
- * `retryable` is always `true` on this class.
- */
-export class VibeTransientError extends VibeError {
-  readonly code: VibeTransientErrorCode;
-  readonly retryable = true as const;
-
-  constructor(params: {
-    code: VibeTransientErrorCode;
-    message: string;
-    meta?: VibeErrorMeta;
-    cause?: Error;
-  }) {
-    super({ message: params.message, meta: params.meta, cause: params.cause });
-    this.name = "VibeTransientError";
-    this.code = params.code;
-  }
-}
-
-// ─── SQLSTATE → VibeError Mapping ───────────────────────────────
-
-/**
- * SQLSTATE code ranges for transient (retryable) errors.
- * Class 08 = connection, Class 40 = transaction rollback,
- * 57014 = query_canceled (statement_timeout), 53300 = too_many_connections.
- */
-const TRANSIENT_CODE_MAP: Record<string, VibeTransientErrorCode> = {
-  "08000": "CONNECTION_ERROR",
-  "08001": "CONNECTION_ERROR",
-  "08003": "CONNECTION_ERROR",
-  "08004": "CONNECTION_ERROR",
-  "08006": "CONNECTION_ERROR",
-  "08007": "CONNECTION_ERROR",
-  "08P01": "CONNECTION_ERROR",
-  "40P01": "DEADLOCK",
-  "40001": "SERIALIZATION_FAILURE",
-  "57014": "STATEMENT_TIMEOUT",
-  "53300": "TOO_MANY_CONNECTIONS",
-};
-
-/**
- * SQLSTATE codes for constraint violation errors (Class 23).
- */
-const CONSTRAINT_CODE_MAP: Record<string, VibeRequestErrorCode> = {
-  "23505": "UNIQUE_CONSTRAINT",
-  "23503": "FOREIGN_KEY_VIOLATION",
-  "23502": "NOT_NULL_VIOLATION",
-  "23514": "CHECK_CONSTRAINT",
-};
-
-/**
- * Extract a field name from a PostgreSQL detail string.
- *
- * Examples:
- * - 'Key (email)=(x@y.com) already exists.' → "email"
- * - 'Failing row contains (1, null, ...).' → undefined
- * - 'Key (author_id)=(999) is not present in table "User".' → "author_id"
- */
-function extractFieldFromDetail(params: { detail: string }): string | undefined {
-  const match = params.detail.match(/Key \(([^)]+)\)/);
-  return match ? match[1] : undefined;
-}
-
-/**
- * Shape of a PostgreSQL protocol error as exposed by both bun:sql and node-postgres.
- *
- * Note: bun:sql puts the SQLSTATE code in `errno` (e.g. "23505") while `code`
- * contains a Node.js-style string (e.g. "ERR_POSTGRES_SERVER_ERROR").
- * node-postgres puts the SQLSTATE code in `code` directly.
- */
-type PgProtocolError = {
-  code: string;
-  errno?: string;
-  message: string;
-  detail?: string;
-  hint?: string;
-  constraint?: string;
-  table?: string;
-  column?: string | number;
-  schema?: string;
-  severity?: string;
-};
-
-/**
- * Check whether a raw error object looks like a PostgreSQL protocol error.
- * Both bun:sql (PostgresError) and node-postgres (DatabaseError) expose
- * error fields from the PostgreSQL wire protocol. The SQLSTATE code is in
- * `errno` (bun:sql) or `code` (node-postgres).
- */
-function isPgError(error: unknown): error is PgProtocolError {
-  if (error === null || typeof error !== "object" || !("message" in error)) return false;
-  const e = error as Record<string, unknown>;
-  // node-postgres: has `code` as a 5-char SQLSTATE string
-  // bun:sql: has `errno` as a SQLSTATE string + `severity`
-  return (
-    (typeof e.code === "string" && /^[0-9A-Z]{5}$/.test(e.code)) ||
-    (typeof e.errno === "string" && typeof e.severity === "string")
-  );
-}
-
-/**
- * Extract the SQLSTATE code from a PgProtocolError.
- * bun:sql stores it in `errno`, node-postgres stores it in `code`.
- */
-function getSqlStateCode(error: PgProtocolError): string {
-  // bun:sql: errno contains the actual SQLSTATE code (e.g. "23505")
-  if (error.errno && /^[0-9A-Z]{5}$/.test(error.errno)) {
-    return error.errno;
-  }
-  // node-postgres: code contains the SQLSTATE code
-  if (/^[0-9A-Z]{5}$/.test(error.code)) {
-    return error.code;
-  }
-  return error.code;
-}
-
-/**
- * Check whether a raw error looks like a client-side connection error
- * (e.g. ECONNREFUSED, ENOTFOUND, ETIMEDOUT) that doesn't have a SQLSTATE code.
- */
-function isConnectionError(err: unknown): boolean {
-  if (err === null || typeof err !== "object") return false;
-  const anyErr = err as Record<string, unknown>;
-
-  // Node.js system errors from net/dns
-  if (typeof anyErr.code === "string") {
-    const code = anyErr.code;
-    if (
-      code === "ECONNREFUSED" ||
-      code === "ECONNRESET" ||
-      code === "ENOTFOUND" ||
-      code === "ETIMEDOUT" ||
-      code === "EPIPE"
-    ) {
-      return true;
-    }
-  }
-
-  // bun:sql connection-level errors often have specific message patterns
-  const msg = typeof anyErr.message === "string" ? anyErr.message : "";
-  if (
-    msg.includes("connection refused") ||
-    msg.includes("Connection terminated") ||
-    msg.includes("Connection lost") ||
-    msg.includes("connect ECONNREFUSED") ||
-    msg.includes("the database system is starting up")
-  ) {
-    return true;
-  }
-
-  return false;
-}
-
-/**
- * Normalize a raw database error into a structured VibeORM error.
- *
- * Both bun:sql and node-postgres expose the PostgreSQL ErrorResponse fields
- * (code, detail, constraint, table, column, schema, severity), so this
- * function is adapter-agnostic.
- *
- * If the error is already a VibeError, it is returned as-is.
- *
- * @param error - The raw error from the database driver.
- * @param model - Optional VibeORM model name for context.
- * @param operation - Optional operation name for context.
- */
-export function normalizeError(params: {
-  error: unknown;
-  model?: string;
-  operation?: string;
-}): VibeRequestError | VibeTransientError {
-  const { error, model, operation } = params;
-
-  // Already a VibeError — return as-is (don't double-wrap)
-  if (error instanceof VibeError) {
-    return error as VibeRequestError | VibeTransientError;
-  }
-
-  const cause = error instanceof Error ? error : new Error(String(error));
-
-  // ─── PostgreSQL protocol error (has SQLSTATE code) ───────────
-  if (isPgError(error)) {
-    const pgErr = error;
-    const pgCode = getSqlStateCode(pgErr);
-    const meta: VibeErrorMeta = {
-      model,
-      operation,
-      constraint: pgErr.constraint,
-      table: pgErr.table,
-      column: typeof pgErr.column === "string" ? pgErr.column : undefined,
-      schema: pgErr.schema,
-      detail: pgErr.detail,
-    };
-
-    // Extract field name from detail when available
-    if (pgErr.detail) {
-      const field = extractFieldFromDetail({ detail: pgErr.detail });
-      if (field) meta.field = field;
-    }
-
-    // Check transient errors first (Class 08, 40, 57014, 53300)
-    const transientCode = TRANSIENT_CODE_MAP[pgCode];
-    if (transientCode) {
-      return new VibeTransientError({
-        code: transientCode,
-        message: pgErr.message,
-        meta,
-        cause,
-      });
-    }
-
-    // Check constraint violations (Class 23)
-    const constraintCode = CONSTRAINT_CODE_MAP[pgCode];
-    if (constraintCode) {
-      return new VibeRequestError({
-        code: constraintCode,
-        message: pgErr.message,
-        meta,
-        cause,
-      });
-    }
-
-    // Check transient by SQLSTATE class prefix
-    if (pgCode.startsWith("08") || pgCode.startsWith("40")) {
-      return new VibeTransientError({
-        code: pgCode.startsWith("08") ? "CONNECTION_ERROR" : "UNKNOWN_TRANSIENT_ERROR",
-        message: pgErr.message,
-        meta,
-        cause,
-      });
-    }
-
-    // Unrecognized SQLSTATE — treat as request error
-    return new VibeRequestError({
-      code: "UNKNOWN_REQUEST_ERROR",
-      message: pgErr.message,
-      meta,
-      cause,
-    });
-  }
-
-  // ─── Client-side connection error (no SQLSTATE) ──────────────
-  if (isConnectionError(error)) {
-    return new VibeTransientError({
-      code: "CONNECTION_ERROR",
-      message: cause.message,
-      meta: { model, operation },
-      cause,
-    });
-  }
-
-  // ─── Unknown error — treat as request error ──────────────────
-  return new VibeRequestError({
-    code: "UNKNOWN_REQUEST_ERROR",
-    message: cause.message,
-    meta: { model, operation },
-    cause,
-  });
-}
-
-// ─── Helpers ─────────────────────────────────────────────────────
-
-function formatZodError(params: { error: unknown }): string {
-  const { error } = params;
-  if (error && typeof error === "object" && "issues" in error) {
-    const issues = (error as { issues: Array<{ path: (string | number)[]; message: string }> }).issues;
-    return issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ");
-  }
-  return String(error);
-}