pipework 0.292.0 → 0.294.0

package/src/data/migrate/invalid-indexes.ts

@@ -0,0 +1,296 @@
+import postgres, { type Sql } from 'postgres'
+import { stripComments } from './statements.js'
+import { parseCreateIndex, readMigrations } from './apply.js'
+
+/**
+ * What migrate does with an INVALID index met in a database it migrated.
+ * Issue #1005.
+ *
+ * - `a`: an index a migration owns. Dropped and rebuilt with the migration's
+ *   own CREATE statement.
+ * - `b`: a `_ccnew` / `_ccold` leftover of an owned index whose counterpart is
+ *   VALID. Dropped.
+ * - `c`: anything else. Nothing is touched; the statements to run are printed.
+ */
+export interface InvalidIndex {
+  case: 'a' | 'b' | 'c'
+  /** Schema-qualified, quoted. */
+  index: string
+  /** Schema-qualified, quoted. */
+  table: string
+  /** What migrate did: rebuilt (a), dropped the leftover (b), or nothing (c). */
+  action: 'rebuilt' | 'dropped' | 'none'
+  outcome: 'repaired' | 'failed' | 'warned'
+  /** For (a): the tag of the migration whose CREATE was rerun. */
+  tag?: string
+  /** For (a): the statement rerun. */
+  statement?: string
+  /** For (c) and a failed (a): the statements its owner can run. */
+  printed: string[]
+  /** Why migrate left it alone, or what failed. */
+  reason?: string
+}
+
+export interface InvalidIndexReport {
+  indexes: InvalidIndex[]
+  /** Set when the catalog read failed; nothing was checked. */
+  readError: string | null
+}
+
+export class InvalidIndexRepairError extends Error {
+  override readonly name = 'InvalidIndexRepairError'
+  constructor(
+    public readonly indexes: InvalidIndex[],
+    message: string,
+  ) {
+    super(message)
+  }
+}
+
+export interface RepairOptions {
+  migrationsFolder: string
+  migrationsTable: string
+  connectionUrl: string
+}
+
+const LOCK_TIMEOUT = '30s'
+const LEFTOVER_RE = /_cc(?:new|old)\d*$/
+const IDENT = String.raw`"(?:[^"]|"")+"|[A-Za-z_][A-Za-z0-9_$]*`
+const DROP_INDEX_RE = new RegExp(
+  String.raw`^\s*DROP\s+INDEX\s+(?:CONCURRENTLY\s+)?(?:IF\s+EXISTS\s+)?((?:(?:${IDENT})(?:\s*\.\s*(?:${IDENT}))?\s*,?\s*)+)`,
+  'i',
+)
+
+interface Row {
+  oid: string
+  tableOid: string
+  schema: string
+  name: string
+  tableSchema: string
+  table: string
+  def: string
+}
+
+interface Owner {
+  tag: string
+  statement: string
+}
+
+function quoteIdent(name: string): string {
+  return `"${name.replace(/"/g, '""')}"`
+}
+
+function unquoteIdent(token: string): string {
+  return token.startsWith('"') ? token.slice(1, -1).replace(/""/g, '"') : token.toLowerCase()
+}
+
+/** The (schema?, name) pairs a DROP INDEX statement names; empty for any other statement. */
+function parseDropIndex(statement: string): { schema: string | null; name: string }[] {
+  const match = DROP_INDEX_RE.exec(stripComments(statement))
+  if (match === null) return []
+  const tokens = match[1]!.match(new RegExp(`(?:${IDENT})(?:\\s*\\.\\s*(?:${IDENT}))?`, 'g')) ?? []
+  return tokens.map((token) => {
+    const parts = token.match(new RegExp(IDENT, 'g'))!
+    return parts.length === 2
+      ? { schema: unquoteIdent(parts[0]!), name: unquoteIdent(parts[1]!) }
+      : { schema: null, name: unquoteIdent(parts[0]!) }
+  })
+}
+
+/** An index definition with its own name removed, so a leftover compares equal to its counterpart. */
+function nameless(def: string): string {
+  return def.replace(/^(CREATE (?:UNIQUE )?INDEX )(?:"(?:[^"]|"")+"|\S+)( ON )/, '$1$2')
+}
+
+const INVALID_INDEXES = `
+  SELECT i.indexrelid::text AS oid, i.indrelid::text AS "tableOid", n.nspname AS schema, c.relname AS name,
+         tn.nspname AS "tableSchema", t.relname AS "table", pg_get_indexdef(i.indexrelid) AS def
+    FROM pg_index i
+    JOIN pg_class c ON c.oid = i.indexrelid
+    JOIN pg_namespace n ON n.oid = c.relnamespace
+    JOIN pg_class t ON t.oid = i.indrelid
+    JOIN pg_namespace tn ON tn.oid = t.relnamespace
+   WHERE NOT i.indisvalid
+     AND c.relkind = 'i'
+     AND n.nspname <> 'information_schema' AND n.nspname NOT LIKE 'pg\\_%'
+     AND NOT EXISTS (SELECT 1 FROM pg_depend d
+                      WHERE d.classid = 'pg_class'::regclass AND d.objid = i.indexrelid AND d.deptype = 'e')
+     AND NOT EXISTS (SELECT 1 FROM pg_stat_progress_create_index p WHERE p.relid = i.indrelid)
+   ORDER BY n.nspname, c.relname`
+
+async function building(client: Sql, tableOid: string): Promise<boolean> {
+  const rows = await client.unsafe(
+    `SELECT 1 FROM pg_stat_progress_create_index WHERE relid = $1::oid`,
+    [tableOid],
+  )
+  return rows.length > 0
+}
+
+/** The applied migrations' CREATE INDEX statements that still stand, keyed by table oid and index name. */
+async function ownedIndexes(client: Sql, options: RepairOptions): Promise<Map<string, Owner>> {
+  const applied = new Set(
+    (await client.unsafe<{ tag: string }[]>(
+      `SELECT tag FROM ${quoteIdent(options.migrationsTable)} WHERE tag IS NOT NULL`,
+    )).map((r) => r.tag),
+  )
+  const owned = new Map<string, Owner & { schema: string }>()
+  for (const migration of readMigrations(options)) {
+    if (!applied.has(migration.tag)) continue
+    for (const statement of migration.statements) {
+      const create = parseCreateIndex(statement)
+      if (create !== null) {
+        const [table] = await client.unsafe<{ oid: string; schema: string }[]>(
+          `SELECT c.oid::text AS oid, n.nspname AS schema FROM pg_class c
+             JOIN pg_namespace n ON n.oid = c.relnamespace WHERE c.oid = to_regclass($1)`,
+          [create.table],
+        )
+        if (table !== undefined) owned.set(`${table.oid}:${create.index}`, { tag: migration.tag, statement, schema: table.schema })
+        continue
+      }
+      for (const dropped of parseDropIndex(statement)) {
+        for (const [key, owner] of owned) {
+          if (key.endsWith(`:${dropped.name}`) && (dropped.schema === null || dropped.schema === owner.schema)) {
+            owned.delete(key)
+          }
+        }
+      }
+    }
+  }
+  return owned
+}
+
+/**
+ * Repair the INVALID indexes the applied migrations made, and report the rest.
+ * Called once per database after `applyMigrations` finished without error,
+ * while the run's advisory lock is held. Throws `InvalidIndexRepairError` when
+ * an owned index cannot be made VALID. Issue #1005.
+ */
+export async function repairInvalidIndexes(options: RepairOptions): Promise<InvalidIndexReport> {
+  const client = postgres(options.connectionUrl, { max: 1, onnotice: () => {} })
+  try {
+    let rows: Row[]
+    let owned: Map<string, Owner>
+    try {
+      rows = await client.unsafe<Row[]>(INVALID_INDEXES)
+      owned = rows.length === 0 ? new Map() : await ownedIndexes(client, options)
+    } catch (err) {
+      return { indexes: [], readError: err instanceof Error ? err.message : String(err) }
+    }
+
+    const qualified = (schema: string, name: string): string => `${quoteIdent(schema)}.${quoteIdent(name)}`
+    const results: InvalidIndex[] = []
+    const failures: string[] = []
+    const ownedKey = (r: Row): string => `${r.tableOid}:${r.name}`
+    const printed = (r: Row, rebuild: boolean): string[] => [
+      ...(rebuild ? [`REINDEX INDEX CONCURRENTLY ${qualified(r.schema, r.name)}`] : []),
+      `DROP INDEX CONCURRENTLY ${qualified(r.schema, r.name)}`,
+    ]
+
+    // (a) owned: drop and rerun the migration's own CREATE.
+    const leftovers: Row[] = []
+    for (const row of rows) {
+      const owner = owned.get(ownedKey(row))
+      if (owner === undefined) {
+        if (LEFTOVER_RE.test(row.name)) leftovers.push(row)
+        else {
+          results.push({
+            case: 'c', index: qualified(row.schema, row.name), table: qualified(row.tableSchema, row.table),
+            action: 'none', outcome: 'warned', printed: printed(row, true),
+            reason: 'no applied migration owns this index',
+          })
+        }
+        continue
+      }
+      // Another session may have started a build on the table since the read.
+      if (await building(client, row.tableOid)) continue
+      const entry: InvalidIndex = {
+        case: 'a', index: qualified(row.schema, row.name), table: qualified(row.tableSchema, row.table),
+        action: 'rebuilt', outcome: 'repaired', tag: owner.tag, statement: owner.statement, printed: [],
+      }
+      try {
+        await client.unsafe(`SET lock_timeout = '${LOCK_TIMEOUT}'`)
+        try {
+          await client.unsafe(`DROP INDEX CONCURRENTLY IF EXISTS ${entry.index}`)
+        } finally {
+          await client.unsafe('RESET lock_timeout')
+        }
+        await client.unsafe(owner.statement)
+      } catch (err) {
+        const detail = err instanceof Error ? err.message : String(err)
+        const extra = (err as { detail?: unknown }).detail
+        entry.outcome = 'failed'
+        entry.reason = typeof extra === 'string' ? `${detail} (${extra})` : detail
+        entry.printed = printed(row, true)
+        failures.push(`${entry.index} (rerunning "${owner.tag}"): ${entry.reason}`)
+      }
+      results.push(entry)
+    }
+
+    // (b) / (c) leftovers, classified against the table's indexes as they stand after (a).
+    const byTable = new Map<string, { name: string; schema: string; valid: boolean; def: string }[]>()
+    for (const row of leftovers) {
+      if (!byTable.has(row.tableOid)) {
+        byTable.set(row.tableOid, await client.unsafe(
+          `SELECT c.relname AS name, n.nspname AS schema, i.indisvalid AS valid, pg_get_indexdef(i.indexrelid) AS def
+             FROM pg_index i JOIN pg_class c ON c.oid = i.indexrelid
+             JOIN pg_namespace n ON n.oid = c.relnamespace WHERE i.indrelid = $1::oid`,
+          [row.tableOid],
+        ))
+      }
+    }
+    for (const row of leftovers) {
+      const own = nameless(row.def)
+      const matches = byTable.get(row.tableOid)!.filter((o) => o.name !== row.name && nameless(o.def) === own)
+      const counterpart = matches.length === 1 ? matches[0]! : undefined
+      const base = { index: qualified(row.schema, row.name), table: qualified(row.tableSchema, row.table) }
+      if (counterpart === undefined) {
+        results.push({
+          case: 'c', ...base, action: 'none', outcome: 'warned', printed: printed(row, true),
+          reason: matches.length === 0
+            ? 'a leftover of an index build or rebuild, and no index on the table matches it'
+            : 'a leftover of an index build or rebuild, and more than one index on the table matches it',
+        })
+        continue
+      }
+      const counterpartOwned = owned.has(`${row.tableOid}:${counterpart.name}`)
+      if (!counterpartOwned || !counterpart.valid) {
+        results.push({
+          case: 'c', ...base, action: 'none', outcome: 'warned', printed: printed(row, !counterpart.valid),
+          reason: counterpartOwned
+            ? `a leftover of ${qualified(counterpart.schema, counterpart.name)}, which is not valid`
+            : `a leftover of ${qualified(counterpart.schema, counterpart.name)}, which no applied migration owns`,
+        })
+        continue
+      }
+      if (await building(client, row.tableOid)) continue
+      const entry: InvalidIndex = { case: 'b', ...base, action: 'dropped', outcome: 'repaired', printed: [],
+        reason: `a leftover of ${qualified(counterpart.schema, counterpart.name)}, which stays in use` }
+      try {
+        await client.unsafe(`SET lock_timeout = '${LOCK_TIMEOUT}'`)
+        try {
+          await client.unsafe(`DROP INDEX CONCURRENTLY IF EXISTS ${base.index}`)
+        } finally {
+          await client.unsafe('RESET lock_timeout')
+        }
+      } catch (err) {
+        entry.outcome = 'failed'
+        entry.action = 'none'
+        entry.reason = err instanceof Error ? err.message : String(err)
+        entry.printed = printed(row, false)
+      }
+      results.push(entry)
+    }
+
+    if (failures.length > 0) {
+      throw new InvalidIndexRepairError(
+        results,
+        `migrate could not make ${failures.length} INVALID ${failures.length === 1 ? 'index' : 'indexes'} ` +
+          `its migrations built valid:\n  ${failures.join('\n  ')}\n` +
+          `The next run drops each and builds it again; fix the cause first (for a UNIQUE index, the duplicate rows).`,
+      )
+    }
+    return { indexes: results, readError: null }
+  } finally {
+    await client.end()
+  }
+}

package/src/data/migrate/run.ts

@@ -1,3 +1,4 @@
+import postgres from 'postgres'
 import { sql } from '../query/index.js'
 import type { Manifold } from '../../core/pipework.js'
 import type { ResolvedDatabase } from '../../core/config/index.js'
@@ -6,6 +7,7 @@ import { OWNER_LABEL_MIGRATE } from '../db/owner-labels.js'
 import { checkMigrations, type MigrationCheckResult } from './check.js'
 import { readAppliedState } from './applied.js'
 import { applyMigrations, type MigrationNotice } from './apply.js'
+import { repairInvalidIndexes, InvalidIndexRepairError, type InvalidIndex } from './invalid-indexes.js'
 import { provisionFrameworkTables, type FrameworkTablesResult } from './provision-framework.js'
 
 // Deliberately empty of hazard switches. Authorization for a hazardous
@@ -24,8 +26,16 @@ export interface MigrateResult {
   safetyCheck: MigrationCheckResult
   /** No-transaction files picked up half applied and finished. Issue #378. */
   resumed: ResumedMigration[]
-  /** INVALID indexes a cut CREATE INDEX CONCURRENTLY left, dropped before the resumed statement reran. Issue #1003. */
+  /** INVALID indexes a cut CREATE INDEX CONCURRENTLY left, dropped before the statement that builds them reran. Issues #1003, #1005. */
   droppedInvalidIndexes: DroppedInvalidIndex[]
+  /**
+   * Every INVALID index this run met, with its case, what was done or must be
+   * done, and the outcome: (a) an owned index rebuilt, (b) a leftover of an owned
+   * index dropped, (c) anything else, untouched. Issue #1005.
+   */
+  invalidIndexes: InvalidIndex[]
+  /** Set when the catalog read for INVALID indexes failed, so none were checked. Issue #1005. */
+  invalidIndexReadError: string | null
   /** Notices and warnings raised by migration statements, in arrival order. Issue #970. */
   notices: MigrateNotice[]
   /** Trace/audit tables, columns and day partitions this run provisioned. */
@@ -54,6 +64,8 @@ export interface MigrateNotice extends MigrationNotice {
   statements: number
 }
 
+export { InvalidIndexRepairError, type InvalidIndex }
+
 export class UnsafeMigrationError extends Error {
   override readonly name = 'UnsafeMigrationError'
   constructor(
@@ -76,7 +88,34 @@ export async function migrateAll(instance: Manifold, options: MigrateOptions = {
   return results
 }
 
+/** One key per database: advisory locks are scoped to the database they are taken in. */
+const MIGRATE_LOCK_KEY = `hashtextextended('pipework.migrate', 0)`
+
+/**
+ * The connection that holds the run lock. It must live as long as the run: the
+ * default `max_lifetime` would close it mid-run and release the lock, so both
+ * timeouts are off, as in src/test/setup.ts.
+ */
+export function openRunLock(url: string): ReturnType<typeof postgres> {
+  return postgres(url, { max: 1, idle_timeout: 0, max_lifetime: 0, onnotice: () => {} })
+}
+
+/**
+ * Runs one database's migrations and index repairs under a session advisory
+ * lock held for the whole run. A second run at once waits for it, then finds
+ * nothing to apply. The lock dies with its connection. Issue #1005.
+ */
 export async function migrateOne(instance: Manifold, dbConfig: ResolvedDatabase, options: MigrateOptions = {}): Promise<MigrateResult> {
+  const lock = openRunLock(dbConfig.url)
+  try {
+    await lock.unsafe(`SELECT pg_advisory_lock(${MIGRATE_LOCK_KEY})`)
+    return await migrateLocked(instance, dbConfig, options)
+  } finally {
+    await lock.end()
+  }
+}
+
+async function migrateLocked(instance: Manifold, dbConfig: ResolvedDatabase, options: MigrateOptions): Promise<MigrateResult> {
   const conn = instance.pool.getOrCreate(dbConfig, 'owner', OWNER_LABEL_MIGRATE)
 
   // Scope the safety gate to pending migrations only — hazards in already-applied
@@ -124,6 +163,15 @@ export async function migrateOne(instance: Manifold, dbConfig: ResolvedDatabase,
     },
   })
 
+  // After a run that finished without error only; a failing migration throws
+  // above and its rerun resumes and checks then. Throws when an owned index
+  // cannot be made valid.
+  const repaired = await repairInvalidIndexes({
+    migrationsFolder: dbConfig.migrations!,
+    migrationsTable: dbConfig.migrationTable,
+    connectionUrl: dbConfig.url,
+  })
+
   // Trace and audit storage rides the default database; their partitioned
   // tables are kept out of generated migrations (#313), so migrate provisions them.
   const frameworkTables = await provisionFrameworkTables(
@@ -146,6 +194,8 @@ export async function migrateOne(instance: Manifold, dbConfig: ResolvedDatabase,
     safetyCheck,
     resumed,
     droppedInvalidIndexes,
+    invalidIndexes: repaired.indexes,
+    invalidIndexReadError: repaired.readError,
     notices,
     frameworkTables,
   }

package/src/data/schema/parse.ts

@@ -1,5 +1,5 @@
 import type { z } from 'zod/v4'
-import { ValidationError, type ValidationSource } from '../../core/errors/index.js'
+import { ValidationError, OutputValidationError, type ValidationSource } from '../../core/errors/index.js'
 
 export function parse<T extends z.ZodType>(schema: T, data: unknown, source?: ValidationSource): z.infer<T> {
   const result = schema.safeParse(data)
@@ -16,7 +16,42 @@ export function parse<T extends z.ZodType>(schema: T, data: unknown, source?: Va
 
   throw source === undefined
     ? new ValidationError(fieldErrors)
-    : new ValidationError(fieldErrors, undefined, { source, paths: result.error.issues.map(i => ({ path: i.path.map(String), message: i.message })) })
+    : new ValidationError(fieldErrors, undefined, { source, paths: issuesOf(result.error.issues, false) })
+}
+
+/** Parses a handler's reply against its declared output schema; a failure is the server's (500), carrying paths and messages, never the value. */
+export function parseOutput<T extends z.ZodType>(schema: T, data: unknown): z.infer<T> {
+  const result = schema.safeParse(data)
+  if (result.success) return result.data
+  throw new OutputValidationError(issuesOf(result.error.issues, true).map(i => ({ source: null, ...i })))
+}
+
+type FlatIssue = { path: string[]; message: string }
+
+/**
+ * The one mapping from zod issues to `{ path, message }` (never the value). With `flattenUnions`, a union
+ * failure (one issue at the union's own path) is replaced by its branches' issues (nested `errors`), each with
+ * the union's path prefixed, and exact duplicates (same path and message) are dropped, first seen kept.
+ */
+function issuesOf(issues: ReadonlyArray<z.core.$ZodIssue>, flattenUnions: boolean, prefix: readonly string[] = []): FlatIssue[] {
+  if (!flattenUnions) return issues.map(i => ({ path: i.path.map(String), message: i.message }))
+  const seen = new Set<string>()
+  return flattenBranches(issues, prefix).filter(i => {
+    const key = `${i.path.join('.')}\u0000${i.message}`
+    if (seen.has(key)) return false
+    seen.add(key)
+    return true
+  })
+}
+
+function flattenBranches(issues: ReadonlyArray<z.core.$ZodIssue>, prefix: readonly string[]): FlatIssue[] {
+  return issues.flatMap(i => {
+    const path = [...prefix, ...i.path.map(String)]
+    if (i.code === 'invalid_union' && i.errors.some(branch => branch.length > 0)) {
+      return i.errors.flatMap(branch => flattenBranches(branch, path))
+    }
+    return [{ path, message: i.message }]
+  })
 }
 
 export function tryParse<T extends z.ZodType>(

package/src/index.ts

@@ -213,7 +213,7 @@ export type { Surface, SurfaceKind, SurfaceHandle, SurfaceManifest, SurfaceConte
 
 export { errors } from './core/errors/namespace.js'
 export { PipeworkError, isPipeworkError, NotFoundError, UnauthorizedError, ForbiddenError, CrossSiteRequestError,
-  ValidationError, ConflictError, TooManyRequestsError, PayloadTooLargeError, UnsupportedMediaTypeError, MalformedMultipartError } from './core/errors/index.js'
+  ValidationError, OutputValidationError, ConflictError, TooManyRequestsError, PayloadTooLargeError, UnsupportedMediaTypeError, MalformedMultipartError } from './core/errors/index.js'
 
 export { config } from './core/config/namespace.js'
 export type { ResolvedConfig, ResolvedDatabase, ResolvedObservability, Blueprint, DatabaseConfig,

package/src/request/di/resolve.ts

@@ -10,7 +10,7 @@ import type { HttpRequest, HttpResponse } from '../http/types.js'
 import { requireContext } from '../context/store.js'
 import { verifyTransactionBinding } from '../context/guard.js'
 import { UnauthorizedError, ValidationError } from '../../core/errors/index.js'
-import { parse } from '../../data/schema/parse.js'
+import { parse, parseOutput } from '../../data/schema/parse.js'
 import { unboundDb } from '../../data/db/unbound.js'
 import { createScopedDb, createTenantGuardDb } from '../../auth/tenant/scoped-db.js'
 
@@ -203,13 +203,13 @@ export async function resolveAndExecute<TDeps extends Record<string, unknown>, T
       const response = result as { status: number; body?: unknown }
       const bodySchema = handler.meta.outputSchemas.get(response.status)
       if (bodySchema) {
-        return { status: response.status, body: parse(bodySchema as Schema, response.body, 'response') } as TReturn
+        return { status: response.status, body: parseOutput(bodySchema as Schema, response.body) } as TReturn
       }
       return result
     }
     const defaultSchema = handler.meta.outputSchemas.get(200)
     if (defaultSchema) {
-      return parse(defaultSchema as Schema, result, 'response') as TReturn
+      return parseOutput(defaultSchema as Schema, result) as TReturn
     }
   }
 

package/src/request/http/server.ts

@@ -20,7 +20,7 @@ import { recordErrorStep } from './error-step.js'
 import type { Flow } from '../context/index.js'
 import type { ErrorResponse } from './types.js'
 import { buildErrorResponse, buildInternalErrorResponse, buildClientErrorResponse, sendError } from './response.js'
-import { isPipeworkError } from '../../core/errors/index.js'
+import { isPipeworkError, OutputValidationError } from '../../core/errors/index.js'
 import { checkUploadHeaders, uploadBodyLimit, startUpload, settleUpload, isUploadRefusal, newUploadTrack, type UploadTrack, MULTIPART_FIELD_LIMIT } from './upload.js'
 import type { BinaryUpload, MultipartUpload, UploadConfig, UploadRefusal, RouteRefusal, RouteRefusedHook, HandlerMeta } from '../di/types.js'
 import { __flowStep } from '../../trace/runtime/flow-step.js'
@@ -596,6 +596,16 @@ export function createServer(instance: Manifold, config: ServerConfig = {}): Pip
           return send(500, { error: { code: 'FILE_RESPONSE_INVALID', message: error.message } })
         }
 
+        if (error instanceof OutputValidationError) {
+          await failWith(500, 'OUTPUT_VALIDATION_ERROR')
+          const issues = error.issues.map(i => ({ path: i.path.join('.'), message: i.message }))
+          req.log.error({ route: `${method} ${path}`, requestId: String(req.id), issues }, 'Handler reply failed its output schema')
+          await reportInternalError(req, error, handler)
+          const body = buildErrorResponse(error)
+          if (config.exposeErrorDetails === true) body.error.details = { issues }
+          return send(500, body)
+        }
+
         if (isPipeworkError(error)) {
           const response = buildErrorResponse(error)
           const isClient = error.httpStatus >= 400 && error.httpStatus < 500

package/src/request/http/types.ts

@@ -248,6 +248,6 @@ export interface ErrorResponse {
     fields?: Record<string, readonly string[]>
     /** On a 429: whole seconds to wait; the same number as the Retry-After header. */
     retryAfterSeconds?: number
-    details?: { name: string; message: string }
+    details?: { name: string; message: string } | { issues: Array<{ path: string; message: string }> }
   }
 }