@happyvertical/smrt-core 0.40.69 → 0.41.0

package/dist/config.d.ts

@@ -2,6 +2,7 @@ import { LoggerConfig } from '@happyvertical/logger';
 import { AiUsageHandler, SignalAdapter } from '@happyvertical/smrt-types';
 import { SignalBus } from './signals/bus.js';
 import { SanitizationConfig } from './signals/sanitizer.js';
+import { RetentionPolicy } from './system/retention.js';
 /**
  * Metrics adapter configuration
  */
@@ -88,6 +89,15 @@ export interface GlobalSignalConfig {
      * Set to false to disable sanitization
      */
     sanitization?: SanitizationConfig | false;
+    /**
+     * System-table retention policy (#2375).
+     *
+     * Consumed by `smrt db:prune` and by the jobs `TaskRunner`'s periodic
+     * sweep. Defaults come from `DEFAULT_RETENTION_POLICY`; set
+     * `retention: { enabled: false }` to opt a deployment out entirely, or an
+     * individual table to `false` to keep only that one unbounded.
+     */
+    retention?: RetentionPolicy;
     /** Custom signal configuration */
     signals?: {
         /** Shared signal bus instance */

package/dist/config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC/E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAEjE;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,8BAA8B;IAC9B,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,kCAAkC;IAClC,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,0DAA0D;IAC1D,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB,yDAAyD;IACzD,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAE9D,gCAAgC;IAChC,QAAQ,CAAC,EAAE,cAAc,EAAE,CAAC;CAC7B;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,qEAAqE;IACrE,OAAO,CAAC,EAAE,YAAY,CAAC;IAEvB,0DAA0D;IAC1D,OAAO,CAAC,EAAE,aAAa,CAAC;IAExB,0DAA0D;IAC1D,MAAM,CAAC,EAAE,YAAY,CAAC;IAEtB;;;OAGG;IACH,EAAE,CAAC,EAAE,QAAQ,CAAC;IAEd;;OAEG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC;IAEtB;;;OAGG;IACH,YAAY,CAAC,EAAE,kBAAkB,GAAG,KAAK,CAAC;IAE1C,kCAAkC;IAClC,OAAO,CAAC,EAAE;QACR,iCAAiC;QACjC,GAAG,CAAC,EAAE,SAAS,CAAC;QAChB,iCAAiC;QACjC,QAAQ,CAAC,EAAE,aAAa,EAAE,CAAC;KAC5B,CAAC;CACH;AAmDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,iBAAS,MAAM,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI,CAEjD;kBAFQ,MAAM;qBAOI,IAAI;sBAUH,kBAAkB;wBAQhB,MAAM;;AAI5B,OAAO,EACL,KAAK,aAAa,EAClB,WAAW,EACX,aAAa,EACb,WAAW,EACX,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,MAAM,EAAE,CAAC"}
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAC;AAC/E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AACjE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAE7D;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,8BAA8B;IAC9B,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,kCAAkC;IAClC,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAElB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;OAEG;IACH,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,0DAA0D;IAC1D,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,OAAO,CAAC;IAElB,yDAAyD;IACzD,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB,2CAA2C;IAC3C,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAE9D,gCAAgC;IAChC,QAAQ,CAAC,EAAE,cAAc,EAAE,CAAC;CAC7B;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,qEAAqE;IACrE,OAAO,CAAC,EAAE,YAAY,CAAC;IAEvB,0DAA0D;IAC1D,OAAO,CAAC,EAAE,aAAa,CAAC;IAExB,0DAA0D;IAC1D,MAAM,CAAC,EAAE,YAAY,CAAC;IAEtB;;;OAGG;IACH,EAAE,CAAC,EAAE,QAAQ,CAAC;IAEd;;OAEG;IACH,KAAK,CAAC,EAAE,aAAa,CAAC;IAEtB;;;OAGG;IACH,YAAY,CAAC,EAAE,kBAAkB,GAAG,KAAK,CAAC;IAE1C;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,eAAe,CAAC;IAE5B,kCAAkC;IAClC,OAAO,CAAC,EAAE;QACR,iCAAiC;QACjC,GAAG,CAAC,EAAE,SAAS,CAAC;QAChB,iCAAiC;QACjC,QAAQ,CAAC,EAAE,aAAa,EAAE,CAAC;KAC5B,CAAC;CACH;AAmDD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,iBAAS,MAAM,CAAC,OAAO,EAAE,kBAAkB,GAAG,IAAI,CAEjD;kBAFQ,MAAM;qBAOI,IAAI;sBAUH,kBAAkB;wBAQhB,MAAM;;AAI5B,OAAO,EACL,KAAK,aAAa,EAClB,WAAW,EACX,aAAa,EACb,WAAW,EACX,oBAAoB,GACrB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,MAAM,EAAE,CAAC"}

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","names":[],"sources":["../src/config.ts"],"sourcesContent":["/**\n * Global SMRT configuration system\n *\n * Provides application-level defaults for signal adapters.\n * Configuration follows a three-tier pattern:\n * 1. Global defaults (via smrt.configure())\n * 2. Per-instance overrides (via SmrtClassOptions)\n * 3. Runtime behavior (from merged config)\n */\n\nimport type { LoggerConfig } from '@happyvertical/logger';\nimport type { AiUsageHandler, SignalAdapter } from '@happyvertical/smrt-types';\nimport type { SignalBus } from './signals/bus.js';\nimport type { SanitizationConfig } from './signals/sanitizer.js';\n\n/**\n * Metrics adapter configuration\n */\nexport interface MetricsConfig {\n  /** Enable metrics tracking */\n  enabled: boolean;\n}\n\n/**\n * Pub/Sub adapter configuration\n */\nexport interface PubSubConfig {\n  /** Enable pub/sub broadcasting */\n  enabled: boolean;\n}\n\n/**\n * AI provider configuration\n *\n * Global defaults for AI client initialization.\n * Provides fallback values when AI options are not specified per-instance.\n */\nexport interface AIConfig {\n  /**\n   * Default AI provider to use\n   * Examples: 'openai', 'anthropic', 'claude-cli', 'gemini', etc.\n   */\n  provider?: string;\n\n  /**\n   * Default model to use with the provider\n   * Examples: 'gpt-4', 'claude-3-opus', 'sonnet', etc.\n   */\n  model?: string;\n\n  /**\n   * Default API key for the provider\n   * Can be overridden by environment variables or instance options\n   */\n  apiKey?: string;\n\n  /**\n   * Additional provider-specific options\n   */\n  [key: string]: unknown;\n}\n\n/**\n * AI usage tracking configuration\n */\nexport interface AiUsageConfig {\n  /** Enable normalized AI usage tracking (default: true) */\n  enabled?: boolean;\n\n  /** Enable persistence to _smrt_ai_usage when a DB exists (default: true) */\n  persist?: boolean;\n\n  /** Enable best-effort cost estimation (default: true) */\n  estimateCosts?: boolean;\n\n  /** Override USD-per-1K-token cost rates */\n  costRates?: Record<string, { input: number; output: number }>;\n\n  /** Additional usage handlers */\n  handlers?: AiUsageHandler[];\n}\n\n/**\n * Global signal configuration\n *\n * Application-level defaults for signal adapters.\n * These can be overridden per-instance via SmrtClassOptions.\n */\nexport interface GlobalSignalConfig {\n  /** Logging configuration (default: true with console, info level) */\n  logging?: LoggerConfig;\n\n  /** Metrics configuration (default: undefined/disabled) */\n  metrics?: MetricsConfig;\n\n  /** Pub/Sub configuration (default: undefined/disabled) */\n  pubsub?: PubSubConfig;\n\n  /**\n   * AI provider configuration (default: undefined)\n   * Provides global defaults for AI client initialization\n   */\n  ai?: AIConfig;\n\n  /**\n   * AI usage tracking configuration (default: enabled)\n   */\n  usage?: AiUsageConfig;\n\n  /**\n   * Signal sanitization configuration (default: enabled with standard redactions)\n   * Set to false to disable sanitization\n   */\n  sanitization?: SanitizationConfig | false;\n\n  /** Custom signal configuration */\n  signals?: {\n    /** Shared signal bus instance */\n    bus?: SignalBus;\n    /** Additional custom adapters */\n    adapters?: SignalAdapter[];\n  };\n}\n\n/**\n * Singleton configuration manager\n *\n * Manages global SMRT configuration with sensible defaults.\n */\nclass SmrtConfig {\n  private static instance: SmrtConfig;\n  private config: GlobalSignalConfig = {\n    logging: true, // Default: console logging at info level\n  };\n\n  private constructor() {}\n\n  /**\n   * Get singleton instance\n   */\n  static getInstance(): SmrtConfig {\n    if (!SmrtConfig.instance) {\n      SmrtConfig.instance = new SmrtConfig();\n    }\n    return SmrtConfig.instance;\n  }\n\n  /**\n   * Configure global defaults\n   *\n   * @param config - Configuration to apply\n   */\n  configure(config: GlobalSignalConfig): void {\n    this.config = { ...this.config, ...config };\n  }\n\n  /**\n   * Get current configuration\n   *\n   * @returns Current global configuration\n   */\n  getConfig(): GlobalSignalConfig {\n    return { ...this.config };\n  }\n\n  /**\n   * Reset to default configuration\n   */\n  reset(): void {\n    this.config = { logging: true };\n  }\n}\n\n/**\n * Global configuration API\n *\n * Callable function with attached methods for managing SMRT configuration.\n *\n * @example\n * ```typescript\n * import { config } from '@happyvertical/smrt-core';\n *\n * // Set application-level defaults\n * config({\n *   logging: { level: 'debug' },\n *   metrics: { enabled: true },\n *   pubsub: { enabled: false },\n *   ai: {\n *     provider: 'claude-cli',\n *     model: 'sonnet'\n *   }\n * });\n *\n * // Reset to defaults\n * config.reset();\n *\n * // Get current configuration\n * const current = config.toJSON();\n *\n * // Auto-convert to string\n * console.log(`Config: ${config}`);\n *\n * // Auto-convert to JSON\n * JSON.stringify(config);\n *\n * // All SmrtClass instances now use these defaults\n * const product = new Product({ name: 'Widget' });\n * await product.initialize();\n * // product has logging at debug level, metrics enabled, and uses claude-cli by default\n * ```\n */\nfunction config(options: GlobalSignalConfig): void {\n  SmrtConfig.getInstance().configure(options);\n}\n\n/**\n * Reset configuration to defaults\n */\nconfig.reset = (): void => {\n  SmrtConfig.getInstance().reset();\n};\n\n/**\n * Get current configuration as object\n * Called automatically by JSON.stringify()\n *\n * @returns Current global configuration\n */\nconfig.toJSON = (): GlobalSignalConfig => SmrtConfig.getInstance().getConfig();\n\n/**\n * Convert configuration to string\n * Called automatically in string contexts\n *\n * @returns JSON string representation of configuration\n */\nconfig.toString = (): string =>\n  JSON.stringify(SmrtConfig.getInstance().getConfig(), null, 2);\n\n// Re-export env-config utilities from @happyvertical/utils\nexport {\n  type ConfigOptions,\n  convertType,\n  loadEnvConfig,\n  toCamelCase,\n  toScreamingSnakeCase,\n} from '@happyvertical/utils';\nexport { config };\n"],"mappings":";;;;;;;AAiIA,IAAM,aAAN,MAAM,WAAW;CACf,OAAe;CACf,SAAqC,EACnC,SAAS,KACX;CAEA,cAAsB,CAAC;;;;CAKvB,OAAO,cAA0B;EAC/B,IAAI,CAAC,WAAW,UACd,WAAW,WAAW,IAAI,WAAW;EAEvC,OAAO,WAAW;CACpB;;;;;;CAOA,UAAU,QAAkC;EAC1C,KAAK,SAAS;GAAE,GAAG,KAAK;GAAQ,GAAG;EAAO;CAC5C;;;;;;CAOA,YAAgC;EAC9B,OAAO,EAAE,GAAG,KAAK,OAAO;CAC1B;;;;CAKA,QAAc;EACZ,KAAK,SAAS,EAAE,SAAS,KAAK;CAChC;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,SAAS,OAAO,SAAmC;CACjD,WAAW,YAAY,CAAC,CAAC,UAAU,OAAO;AAC5C;;;;AAKA,OAAO,cAAoB;CACzB,WAAW,YAAY,CAAC,CAAC,MAAM;AACjC;;;;;;;AAQA,OAAO,eAAmC,WAAW,YAAY,CAAC,CAAC,UAAU;;;;;;;AAQ7E,OAAO,iBACL,KAAK,UAAU,WAAW,YAAY,CAAC,CAAC,UAAU,GAAG,MAAM,CAAC"}
+{"version":3,"file":"config.js","names":[],"sources":["../src/config.ts"],"sourcesContent":["/**\n * Global SMRT configuration system\n *\n * Provides application-level defaults for signal adapters.\n * Configuration follows a three-tier pattern:\n * 1. Global defaults (via smrt.configure())\n * 2. Per-instance overrides (via SmrtClassOptions)\n * 3. Runtime behavior (from merged config)\n */\n\nimport type { LoggerConfig } from '@happyvertical/logger';\nimport type { AiUsageHandler, SignalAdapter } from '@happyvertical/smrt-types';\nimport type { SignalBus } from './signals/bus.js';\nimport type { SanitizationConfig } from './signals/sanitizer.js';\nimport type { RetentionPolicy } from './system/retention.js';\n\n/**\n * Metrics adapter configuration\n */\nexport interface MetricsConfig {\n  /** Enable metrics tracking */\n  enabled: boolean;\n}\n\n/**\n * Pub/Sub adapter configuration\n */\nexport interface PubSubConfig {\n  /** Enable pub/sub broadcasting */\n  enabled: boolean;\n}\n\n/**\n * AI provider configuration\n *\n * Global defaults for AI client initialization.\n * Provides fallback values when AI options are not specified per-instance.\n */\nexport interface AIConfig {\n  /**\n   * Default AI provider to use\n   * Examples: 'openai', 'anthropic', 'claude-cli', 'gemini', etc.\n   */\n  provider?: string;\n\n  /**\n   * Default model to use with the provider\n   * Examples: 'gpt-4', 'claude-3-opus', 'sonnet', etc.\n   */\n  model?: string;\n\n  /**\n   * Default API key for the provider\n   * Can be overridden by environment variables or instance options\n   */\n  apiKey?: string;\n\n  /**\n   * Additional provider-specific options\n   */\n  [key: string]: unknown;\n}\n\n/**\n * AI usage tracking configuration\n */\nexport interface AiUsageConfig {\n  /** Enable normalized AI usage tracking (default: true) */\n  enabled?: boolean;\n\n  /** Enable persistence to _smrt_ai_usage when a DB exists (default: true) */\n  persist?: boolean;\n\n  /** Enable best-effort cost estimation (default: true) */\n  estimateCosts?: boolean;\n\n  /** Override USD-per-1K-token cost rates */\n  costRates?: Record<string, { input: number; output: number }>;\n\n  /** Additional usage handlers */\n  handlers?: AiUsageHandler[];\n}\n\n/**\n * Global signal configuration\n *\n * Application-level defaults for signal adapters.\n * These can be overridden per-instance via SmrtClassOptions.\n */\nexport interface GlobalSignalConfig {\n  /** Logging configuration (default: true with console, info level) */\n  logging?: LoggerConfig;\n\n  /** Metrics configuration (default: undefined/disabled) */\n  metrics?: MetricsConfig;\n\n  /** Pub/Sub configuration (default: undefined/disabled) */\n  pubsub?: PubSubConfig;\n\n  /**\n   * AI provider configuration (default: undefined)\n   * Provides global defaults for AI client initialization\n   */\n  ai?: AIConfig;\n\n  /**\n   * AI usage tracking configuration (default: enabled)\n   */\n  usage?: AiUsageConfig;\n\n  /**\n   * Signal sanitization configuration (default: enabled with standard redactions)\n   * Set to false to disable sanitization\n   */\n  sanitization?: SanitizationConfig | false;\n\n  /**\n   * System-table retention policy (#2375).\n   *\n   * Consumed by `smrt db:prune` and by the jobs `TaskRunner`'s periodic\n   * sweep. Defaults come from `DEFAULT_RETENTION_POLICY`; set\n   * `retention: { enabled: false }` to opt a deployment out entirely, or an\n   * individual table to `false` to keep only that one unbounded.\n   */\n  retention?: RetentionPolicy;\n\n  /** Custom signal configuration */\n  signals?: {\n    /** Shared signal bus instance */\n    bus?: SignalBus;\n    /** Additional custom adapters */\n    adapters?: SignalAdapter[];\n  };\n}\n\n/**\n * Singleton configuration manager\n *\n * Manages global SMRT configuration with sensible defaults.\n */\nclass SmrtConfig {\n  private static instance: SmrtConfig;\n  private config: GlobalSignalConfig = {\n    logging: true, // Default: console logging at info level\n  };\n\n  private constructor() {}\n\n  /**\n   * Get singleton instance\n   */\n  static getInstance(): SmrtConfig {\n    if (!SmrtConfig.instance) {\n      SmrtConfig.instance = new SmrtConfig();\n    }\n    return SmrtConfig.instance;\n  }\n\n  /**\n   * Configure global defaults\n   *\n   * @param config - Configuration to apply\n   */\n  configure(config: GlobalSignalConfig): void {\n    this.config = { ...this.config, ...config };\n  }\n\n  /**\n   * Get current configuration\n   *\n   * @returns Current global configuration\n   */\n  getConfig(): GlobalSignalConfig {\n    return { ...this.config };\n  }\n\n  /**\n   * Reset to default configuration\n   */\n  reset(): void {\n    this.config = { logging: true };\n  }\n}\n\n/**\n * Global configuration API\n *\n * Callable function with attached methods for managing SMRT configuration.\n *\n * @example\n * ```typescript\n * import { config } from '@happyvertical/smrt-core';\n *\n * // Set application-level defaults\n * config({\n *   logging: { level: 'debug' },\n *   metrics: { enabled: true },\n *   pubsub: { enabled: false },\n *   ai: {\n *     provider: 'claude-cli',\n *     model: 'sonnet'\n *   }\n * });\n *\n * // Reset to defaults\n * config.reset();\n *\n * // Get current configuration\n * const current = config.toJSON();\n *\n * // Auto-convert to string\n * console.log(`Config: ${config}`);\n *\n * // Auto-convert to JSON\n * JSON.stringify(config);\n *\n * // All SmrtClass instances now use these defaults\n * const product = new Product({ name: 'Widget' });\n * await product.initialize();\n * // product has logging at debug level, metrics enabled, and uses claude-cli by default\n * ```\n */\nfunction config(options: GlobalSignalConfig): void {\n  SmrtConfig.getInstance().configure(options);\n}\n\n/**\n * Reset configuration to defaults\n */\nconfig.reset = (): void => {\n  SmrtConfig.getInstance().reset();\n};\n\n/**\n * Get current configuration as object\n * Called automatically by JSON.stringify()\n *\n * @returns Current global configuration\n */\nconfig.toJSON = (): GlobalSignalConfig => SmrtConfig.getInstance().getConfig();\n\n/**\n * Convert configuration to string\n * Called automatically in string contexts\n *\n * @returns JSON string representation of configuration\n */\nconfig.toString = (): string =>\n  JSON.stringify(SmrtConfig.getInstance().getConfig(), null, 2);\n\n// Re-export env-config utilities from @happyvertical/utils\nexport {\n  type ConfigOptions,\n  convertType,\n  loadEnvConfig,\n  toCamelCase,\n  toScreamingSnakeCase,\n} from '@happyvertical/utils';\nexport { config };\n"],"mappings":";;;;;;;AA4IA,IAAM,aAAN,MAAM,WAAW;CACf,OAAe;CACf,SAAqC,EACnC,SAAS,KACX;CAEA,cAAsB,CAAC;;;;CAKvB,OAAO,cAA0B;EAC/B,IAAI,CAAC,WAAW,UACd,WAAW,WAAW,IAAI,WAAW;EAEvC,OAAO,WAAW;CACpB;;;;;;CAOA,UAAU,QAAkC;EAC1C,KAAK,SAAS;GAAE,GAAG,KAAK;GAAQ,GAAG;EAAO;CAC5C;;;;;;CAOA,YAAgC;EAC9B,OAAO,EAAE,GAAG,KAAK,OAAO;CAC1B;;;;CAKA,QAAc;EACZ,KAAK,SAAS,EAAE,SAAS,KAAK;CAChC;AACF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,SAAS,OAAO,SAAmC;CACjD,WAAW,YAAY,CAAC,CAAC,UAAU,OAAO;AAC5C;;;;AAKA,OAAO,cAAoB;CACzB,WAAW,YAAY,CAAC,CAAC,MAAM;AACjC;;;;;;;AAQA,OAAO,eAAmC,WAAW,YAAY,CAAC,CAAC,UAAU;;;;;;;AAQ7E,OAAO,iBACL,KAAK,UAAU,WAAW,YAAY,CAAC,CAAC,UAAU,GAAG,MAAM,CAAC"}

package/dist/database.d.ts

@@ -1,4 +1,5 @@
 import { DatabaseInterface, SchemasOption } from '@happyvertical/sql';
+import { PostgresTimeoutConfig } from './postgres-timeouts.js';
 /**
  * Unified type for all database configuration formats
  *
@@ -28,6 +29,13 @@ export type DatabaseConfig = string | {
     url?: string;
     type?: 'sqlite' | 'postgres' | 'duckdb' | 'json';
     authToken?: string;
+    /**
+     * Runtime PostgreSQL timeouts for this connection (#2377). Ignored by
+     * every other engine.
+     *
+     * @see {@link PostgresTimeoutConfig}
+     */
+    timeouts?: PostgresTimeoutConfig;
     [key: string]: unknown;
 } | DatabaseInterface;
 /**

package/dist/database.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../src/database.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAG3E;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,MAAM,cAAc,GACtB,MAAM,GACN;IACE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,QAAQ,GAAG,UAAU,GAAG,QAAQ,GAAG,MAAM,CAAC;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,GACD,iBAAiB,CAAC;AAEtB;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,CAAC,MAAM,CAAC;IAEb,IAAI,8BAA8B,EAC9B,CAAC,MAAM,cAAc,GAAG,SAAS,CAAC,GAClC,SAAS,CAAC;CACf;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,iBAAiB,CAO5B;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;;;OAKG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,cAAc,EACtB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,iBAAiB,CAAC,CAkC5B"}
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../src/database.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAE3E,OAAO,EAEL,KAAK,qBAAqB,EAC3B,MAAM,wBAAwB,CAAC;AAEhC;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,MAAM,cAAc,GACtB,MAAM,GACN;IACE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,QAAQ,GAAG,UAAU,GAAG,QAAQ,GAAG,MAAM,CAAC;IACjD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,qBAAqB,CAAC;IACjC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB,GACD,iBAAiB,CAAC;AAEtB;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,CAAC,MAAM,CAAC;IAEb,IAAI,8BAA8B,EAC9B,CAAC,MAAM,cAAc,GAAG,SAAS,CAAC,GAClC,SAAS,CAAC;CACf;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,OAAO,GACb,KAAK,IAAI,iBAAiB,CAO5B;AAED;;GAEG;AACH,MAAM,WAAW,sBAAsB;IACrC;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd;;;;;OAKG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAsB,eAAe,CACnC,MAAM,EAAE,cAAc,EACtB,OAAO,GAAE,sBAA2B,GACnC,OAAO,CAAC,iBAAiB,CAAC,CAqC5B"}

package/dist/database.js

@@ -1,3 +1,4 @@
+import { applyPostgresRuntimeTimeouts } from "./postgres-timeouts.js";
 import { getDatabase } from "@happyvertical/sql";
 //#region src/database.ts
 /**
@@ -49,19 +50,26 @@ function isDatabaseInterface(value) {
 async function resolveDatabase(config, options = {}) {
 	const { dbid, schemas } = options;
 	if (isDatabaseInterface(config)) return config;
-	if (typeof config === "string") return getDatabase({
-		url: config,
-		schemas,
-		...config === ":memory:" ? {} : { dbid: dbid ?? `smrt:${config}` }
-	});
+	if (typeof config === "string") {
+		const isMemoryDb = config === ":memory:";
+		const bounded = applyPostgresRuntimeTimeouts({ url: config });
+		return getDatabase({
+			...bounded,
+			schemas,
+			...isMemoryDb ? {} : { dbid: dbid ?? `smrt:${bounded.url}` }
+		});
+	}
 	const canUseMemory = !config.type || config.type === "sqlite";
 	const dbUrl = config.url || (canUseMemory ? ":memory:" : "");
 	const isMemoryDb = dbUrl === ":memory:";
-	return getDatabase({
+	const bounded = applyPostgresRuntimeTimeouts({
 		...config,
-		url: dbUrl,
+		url: dbUrl
+	});
+	return getDatabase({
+		...bounded,
 		schemas,
-		...isMemoryDb ? {} : { dbid: dbid ?? `smrt:${dbUrl}` }
+		...isMemoryDb ? {} : { dbid: dbid ?? `smrt:${bounded.url}` }
 	});
 }
 //#endregion

package/dist/database.js.map

@@ -1 +1 @@
-{"version":3,"file":"database.js","names":[],"sources":["../src/database.ts"],"sourcesContent":["/**\n * Database configuration and resolution utilities\n *\n * This module provides a unified type for database configuration options\n * and a utility function to resolve any config format to a DatabaseInterface.\n *\n * @module\n */\n\nimport type { DatabaseInterface, SchemasOption } from '@happyvertical/sql';\nimport { getDatabase } from '@happyvertical/sql';\n\n/**\n * Unified type for all database configuration formats\n *\n * Supports three formats:\n * - **String**: Connection URL (e.g., 'products.db', ':memory:', 'postgres://...')\n * - **Config object**: Full configuration with type, url, and options\n * - **DatabaseInterface**: Pre-initialized database instance\n *\n * @example\n * ```typescript\n * // String shortcut\n * const config: DatabaseConfig = 'products.db';\n *\n * // Config object\n * const config: DatabaseConfig = {\n *   type: 'sqlite',\n *   url: 'products.db',\n *   authToken: 'token'\n * };\n *\n * // Pre-initialized instance\n * const db = await getDatabase({ type: 'sqlite', url: ':memory:' });\n * const config: DatabaseConfig = db;\n * ```\n */\nexport type DatabaseConfig =\n  | string\n  | {\n      url?: string;\n      type?: 'sqlite' | 'postgres' | 'duckdb' | 'json';\n      authToken?: string;\n      [key: string]: unknown;\n    }\n  | DatabaseInterface;\n\n/**\n * Canonical declaration of the request-scoped database global.\n *\n * The value is installed by whichever package owns request scoping (today\n * `@happyvertical/smrt-users`, via its session permission context) and is read\n * by the SvelteKit runtime config that `smrt-core`'s vite plugin generates into\n * consumer apps. Both sides used to `declare global` this name independently\n * with different types — `DatabaseConfig` here, a package-private\n * `QueryableDatabase` there — and TypeScript requires merged `var` declarations\n * to be *identical*, not merely compatible. Consumers whose program contained\n * both then failed to type-check (#2342).\n *\n * `smrt-core` owns the declaration because it is the base package every other\n * SMRT package and consumer already depends on. Writers should keep assigning a\n * live `DatabaseInterface`; it satisfies `DatabaseConfig` through that arm of\n * the union. Never redeclare this global elsewhere.\n */\ndeclare global {\n  // eslint-disable-next-line no-var\n  var __smrtGetRequestScopedDatabase:\n    | (() => DatabaseConfig | undefined)\n    | undefined;\n}\n\n/**\n * Type guard to check if a value is a DatabaseInterface instance\n *\n * @param value - Value to check\n * @returns True if value has query() and close() methods\n *\n * @example\n * ```typescript\n * if (isDatabaseInterface(config)) {\n *   // config is DatabaseInterface\n *   await config.query('SELECT 1');\n * }\n * ```\n */\nexport function isDatabaseInterface(\n  value: unknown,\n): value is DatabaseInterface {\n  return (\n    value !== null &&\n    typeof value === 'object' &&\n    'query' in value &&\n    typeof (value as { query: unknown }).query === 'function'\n  );\n}\n\n/**\n * Options for resolving a database configuration\n */\nexport interface ResolveDatabaseOptions {\n  /**\n   * Cache key for connection pooling.\n   * If provided, the same dbid returns the same cached connection.\n   */\n  dbid?: string;\n\n  /**\n   * Optional pre-generated schemas to pass to the database adapter.\n   *\n   * Intended for explicit tooling and test utilities that bootstrap schema\n   * ahead of runtime. Core runtime no longer passes these automatically.\n   */\n  schemas?: SchemasOption;\n}\n\n/**\n * Resolve any DatabaseConfig format to a DatabaseInterface instance\n *\n * This utility function normalizes the three config formats:\n * 1. **String URL**: Passed to getDatabase() with auto-detected type\n * 2. **Config object**: Passed to getDatabase() directly\n * 3. **DatabaseInterface**: Returned as-is\n *\n * @param config - Database configuration in any supported format\n * @param options - Resolution options (dbid for caching, optional explicit schemas)\n * @returns Promise resolving to a DatabaseInterface instance\n *\n * @example\n * ```typescript\n * // String URL\n * const db = await resolveDatabase('products.db');\n *\n * // Config object\n * const db = await resolveDatabase({\n *   type: 'postgres',\n *   url: 'postgres://localhost/mydb'\n * });\n *\n * // Pre-initialized instance (returned as-is)\n * const existingDb = await getDatabase({ url: ':memory:' });\n * const db = await resolveDatabase(existingDb);\n * console.log(db === existingDb); // true\n * ```\n */\nexport async function resolveDatabase(\n  config: DatabaseConfig,\n  options: ResolveDatabaseOptions = {},\n): Promise<DatabaseInterface> {\n  const { dbid, schemas } = options;\n\n  // Already a DatabaseInterface instance - return as-is\n  if (isDatabaseInterface(config)) {\n    return config;\n  }\n\n  // String URL shortcut\n  if (typeof config === 'string') {\n    const isMemoryDb = config === ':memory:';\n    return getDatabase({\n      url: config,\n      schemas,\n      ...(isMemoryDb ? {} : { dbid: dbid ?? `smrt:${config}` }),\n    });\n  }\n\n  // Config object\n  // Only default to :memory: for SQLite (or unspecified type which defaults to SQLite)\n  // Other adapters (json, postgres, duckdb) require explicit URLs\n  const canUseMemory = !config.type || config.type === 'sqlite';\n  const dbUrl = config.url || (canUseMemory ? ':memory:' : '');\n  const isMemoryDb = dbUrl === ':memory:';\n  // `config` is the loosely-typed config-object variant of `DatabaseConfig`\n  // (it carries an open `[key: string]: unknown` index for adapter-specific\n  // options). Cast the merged options to `getDatabase`'s own parameter type at\n  // this boundary; the adapter validates the concrete shape at runtime.\n  return getDatabase({\n    ...config,\n    url: dbUrl,\n    schemas,\n    ...(isMemoryDb ? {} : { dbid: dbid ?? `smrt:${dbUrl}` }),\n  } as Parameters<typeof getDatabase>[0]);\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAqFA,SAAgB,oBACd,OAC4B;CAC5B,OACE,UAAU,QACV,OAAO,UAAU,YACjB,WAAW,SACX,OAAQ,MAA6B,UAAU;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkDA,eAAsB,gBACpB,QACA,UAAkC,CAAC,GACP;CAC5B,MAAM,EAAE,MAAM,YAAY;CAG1B,IAAI,oBAAoB,MAAM,GAC5B,OAAO;CAIT,IAAI,OAAO,WAAW,UAEpB,OAAO,YAAY;EACjB,KAAK;EACL;EACA,GAJiB,WAAW,aAIX,CAAC,IAAI,EAAE,MAAM,QAAQ,QAAQ,SAAS;CACzD,CAAC;CAMH,MAAM,eAAe,CAAC,OAAO,QAAQ,OAAO,SAAS;CACrD,MAAM,QAAQ,OAAO,QAAQ,eAAe,aAAa;CACzD,MAAM,aAAa,UAAU;CAK7B,OAAO,YAAY;EACjB,GAAG;EACH,KAAK;EACL;EACA,GAAI,aAAa,CAAC,IAAI,EAAE,MAAM,QAAQ,QAAQ,QAAQ;CACxD,CAAsC;AACxC"}
+{"version":3,"file":"database.js","names":[],"sources":["../src/database.ts"],"sourcesContent":["/**\n * Database configuration and resolution utilities\n *\n * This module provides a unified type for database configuration options\n * and a utility function to resolve any config format to a DatabaseInterface.\n *\n * @module\n */\n\nimport type { DatabaseInterface, SchemasOption } from '@happyvertical/sql';\nimport { getDatabase } from '@happyvertical/sql';\nimport {\n  applyPostgresRuntimeTimeouts,\n  type PostgresTimeoutConfig,\n} from './postgres-timeouts.js';\n\n/**\n * Unified type for all database configuration formats\n *\n * Supports three formats:\n * - **String**: Connection URL (e.g., 'products.db', ':memory:', 'postgres://...')\n * - **Config object**: Full configuration with type, url, and options\n * - **DatabaseInterface**: Pre-initialized database instance\n *\n * @example\n * ```typescript\n * // String shortcut\n * const config: DatabaseConfig = 'products.db';\n *\n * // Config object\n * const config: DatabaseConfig = {\n *   type: 'sqlite',\n *   url: 'products.db',\n *   authToken: 'token'\n * };\n *\n * // Pre-initialized instance\n * const db = await getDatabase({ type: 'sqlite', url: ':memory:' });\n * const config: DatabaseConfig = db;\n * ```\n */\nexport type DatabaseConfig =\n  | string\n  | {\n      url?: string;\n      type?: 'sqlite' | 'postgres' | 'duckdb' | 'json';\n      authToken?: string;\n      /**\n       * Runtime PostgreSQL timeouts for this connection (#2377). Ignored by\n       * every other engine.\n       *\n       * @see {@link PostgresTimeoutConfig}\n       */\n      timeouts?: PostgresTimeoutConfig;\n      [key: string]: unknown;\n    }\n  | DatabaseInterface;\n\n/**\n * Canonical declaration of the request-scoped database global.\n *\n * The value is installed by whichever package owns request scoping (today\n * `@happyvertical/smrt-users`, via its session permission context) and is read\n * by the SvelteKit runtime config that `smrt-core`'s vite plugin generates into\n * consumer apps. Both sides used to `declare global` this name independently\n * with different types — `DatabaseConfig` here, a package-private\n * `QueryableDatabase` there — and TypeScript requires merged `var` declarations\n * to be *identical*, not merely compatible. Consumers whose program contained\n * both then failed to type-check (#2342).\n *\n * `smrt-core` owns the declaration because it is the base package every other\n * SMRT package and consumer already depends on. Writers should keep assigning a\n * live `DatabaseInterface`; it satisfies `DatabaseConfig` through that arm of\n * the union. Never redeclare this global elsewhere.\n */\ndeclare global {\n  // eslint-disable-next-line no-var\n  var __smrtGetRequestScopedDatabase:\n    | (() => DatabaseConfig | undefined)\n    | undefined;\n}\n\n/**\n * Type guard to check if a value is a DatabaseInterface instance\n *\n * @param value - Value to check\n * @returns True if value has query() and close() methods\n *\n * @example\n * ```typescript\n * if (isDatabaseInterface(config)) {\n *   // config is DatabaseInterface\n *   await config.query('SELECT 1');\n * }\n * ```\n */\nexport function isDatabaseInterface(\n  value: unknown,\n): value is DatabaseInterface {\n  return (\n    value !== null &&\n    typeof value === 'object' &&\n    'query' in value &&\n    typeof (value as { query: unknown }).query === 'function'\n  );\n}\n\n/**\n * Options for resolving a database configuration\n */\nexport interface ResolveDatabaseOptions {\n  /**\n   * Cache key for connection pooling.\n   * If provided, the same dbid returns the same cached connection.\n   */\n  dbid?: string;\n\n  /**\n   * Optional pre-generated schemas to pass to the database adapter.\n   *\n   * Intended for explicit tooling and test utilities that bootstrap schema\n   * ahead of runtime. Core runtime no longer passes these automatically.\n   */\n  schemas?: SchemasOption;\n}\n\n/**\n * Resolve any DatabaseConfig format to a DatabaseInterface instance\n *\n * This utility function normalizes the three config formats:\n * 1. **String URL**: Passed to getDatabase() with auto-detected type\n * 2. **Config object**: Passed to getDatabase() directly\n * 3. **DatabaseInterface**: Returned as-is\n *\n * @param config - Database configuration in any supported format\n * @param options - Resolution options (dbid for caching, optional explicit schemas)\n * @returns Promise resolving to a DatabaseInterface instance\n *\n * @example\n * ```typescript\n * // String URL\n * const db = await resolveDatabase('products.db');\n *\n * // Config object\n * const db = await resolveDatabase({\n *   type: 'postgres',\n *   url: 'postgres://localhost/mydb'\n * });\n *\n * // Pre-initialized instance (returned as-is)\n * const existingDb = await getDatabase({ url: ':memory:' });\n * const db = await resolveDatabase(existingDb);\n * console.log(db === existingDb); // true\n * ```\n */\nexport async function resolveDatabase(\n  config: DatabaseConfig,\n  options: ResolveDatabaseOptions = {},\n): Promise<DatabaseInterface> {\n  const { dbid, schemas } = options;\n\n  // Already a DatabaseInterface instance - return as-is\n  if (isDatabaseInterface(config)) {\n    return config;\n  }\n\n  // String URL shortcut\n  if (typeof config === 'string') {\n    const isMemoryDb = config === ':memory:';\n    // The dbid is derived from the *bounded* URL so two configurations that\n    // differ only in their PostgreSQL timeouts cannot share one pool (#2377).\n    const bounded = applyPostgresRuntimeTimeouts({ url: config });\n    return getDatabase({\n      ...bounded,\n      schemas,\n      ...(isMemoryDb ? {} : { dbid: dbid ?? `smrt:${bounded.url}` }),\n    } as Parameters<typeof getDatabase>[0]);\n  }\n\n  // Config object\n  // Only default to :memory: for SQLite (or unspecified type which defaults to SQLite)\n  // Other adapters (json, postgres, duckdb) require explicit URLs\n  const canUseMemory = !config.type || config.type === 'sqlite';\n  const dbUrl = config.url || (canUseMemory ? ':memory:' : '');\n  const isMemoryDb = dbUrl === ':memory:';\n  const bounded = applyPostgresRuntimeTimeouts({ ...config, url: dbUrl });\n  // `config` is the loosely-typed config-object variant of `DatabaseConfig`\n  // (it carries an open `[key: string]: unknown` index for adapter-specific\n  // options). Cast the merged options to `getDatabase`'s own parameter type at\n  // this boundary; the adapter validates the concrete shape at runtime.\n  return getDatabase({\n    ...bounded,\n    schemas,\n    ...(isMemoryDb ? {} : { dbid: dbid ?? `smrt:${bounded.url}` }),\n  } as Parameters<typeof getDatabase>[0]);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAgGA,SAAgB,oBACd,OAC4B;CAC5B,OACE,UAAU,QACV,OAAO,UAAU,YACjB,WAAW,SACX,OAAQ,MAA6B,UAAU;AAEnD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAkDA,eAAsB,gBACpB,QACA,UAAkC,CAAC,GACP;CAC5B,MAAM,EAAE,MAAM,YAAY;CAG1B,IAAI,oBAAoB,MAAM,GAC5B,OAAO;CAIT,IAAI,OAAO,WAAW,UAAU;EAC9B,MAAM,aAAa,WAAW;EAG9B,MAAM,UAAU,6BAA6B,EAAE,KAAK,OAAO,CAAC;EAC5D,OAAO,YAAY;GACjB,GAAG;GACH;GACA,GAAI,aAAa,CAAC,IAAI,EAAE,MAAM,QAAQ,QAAQ,QAAQ,MAAM;EAC9D,CAAsC;CACxC;CAKA,MAAM,eAAe,CAAC,OAAO,QAAQ,OAAO,SAAS;CACrD,MAAM,QAAQ,OAAO,QAAQ,eAAe,aAAa;CACzD,MAAM,aAAa,UAAU;CAC7B,MAAM,UAAU,6BAA6B;EAAE,GAAG;EAAQ,KAAK;CAAM,CAAC;CAKtE,OAAO,YAAY;EACjB,GAAG;EACH;EACA,GAAI,aAAa,CAAC,IAAI,EAAE,MAAM,QAAQ,QAAQ,QAAQ,MAAM;CAC9D,CAAsC;AACxC"}

package/dist/db-errors.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Driver-error classification for the persistence path (#2366).
+ *
+ * `@happyvertical/sql` does not normalize driver errors: every adapter catches
+ * the driver failure and rethrows
+ * `DatabaseError('Failed to upsert record into table', { …, originalError })`,
+ * where `originalError` is the **string** produced by the SDK's `formatDbError`
+ * (`"<driver message>, code=<driver code>, detail=…, hint=…"`). The typed
+ * message therefore carries none of the constraint wording, which is why
+ * matching on `error.message` alone silently stopped recognizing constraint
+ * violations and let {@link ErrorUtils.withRetry} retry them.
+ *
+ * This module walks the whole causal chain — `cause`, `context.originalError`
+ * (Error *or* formatted string), `originalError`, `details.causeMessages`, and
+ * `AggregateError.errors` — collecting every driver code and message it finds,
+ * then classifies on the codes first (PostgreSQL SQLSTATE, SQLite result
+ * codes, Node network errno) and only falls back to dialect wording for DuckDB,
+ * which reports no machine-readable code.
+ *
+ * The classification separates two independent questions:
+ * - `deterministic` — a retry cannot change the outcome (constraint violation,
+ *   bad input syntax, aborted transaction, missing table). Fail fast.
+ * - `retryable` — a retry plausibly can succeed (serialization failure,
+ *   deadlock, lock timeout, connection loss, `SQLITE_BUSY`).
+ *
+ * They are not complements: `kind: 'unknown'` means "no opinion", leaving the
+ * caller's own default policy in charge.
+ *
+ * @module
+ */
+/** Coarse classification of a database driver failure. */
+export type DatabaseErrorKind = 'unique_violation' | 'not_null_violation' | 'foreign_key_violation' | 'check_violation' | 'exclusion_violation' | 'invalid_input' | 'aborted_transaction' | 'undefined_object' | 'insufficient_privilege' | 'syntax_error' | 'transient' | 'unknown';
+/** Structured result of {@link classifyDatabaseError}. */
+export interface DatabaseErrorClassification {
+    /** What kind of failure this is, or `'unknown'` when nothing matched. */
+    kind: DatabaseErrorKind;
+    /** True when retrying cannot change the outcome. */
+    deterministic: boolean;
+    /** True when retrying plausibly can succeed. */
+    retryable: boolean;
+    /** PostgreSQL SQLSTATE recovered from the chain, when present. */
+    sqlstate?: string;
+    /** Raw driver code that produced the classification, when present. */
+    driverCode?: string;
+    /** Every driver code found anywhere in the chain, in discovery order. */
+    driverCodes: readonly string[];
+    /**
+     * Every message found anywhere in the chain, in discovery order. Includes
+     * the SDK's formatted `originalError` strings and the driver's own
+     * `detail`/`hint` fields, which carry the PostgreSQL
+     * `Key (col)=(value) already exists.` line used for column recovery.
+     */
+    driverMessages: readonly string[];
+    /**
+     * Column named directly by the driver (`node-postgres` sets `error.column`
+     * on a `23502`), when one was reported. More reliable than parsing it back
+     * out of the message.
+     */
+    column?: string;
+    /** Constraint named directly by the driver (`error.constraint`). */
+    constraint?: string;
+}
+/**
+ * Classifies a raw dialect message. Exposed so
+ * `SmrtObject.classifyConstraintError()` and this module share one set of
+ * regexes rather than drifting apart.
+ */
+export declare function classifyDialectMessage(message: string): DatabaseErrorKind;
+/**
+ * Classifies a database failure by walking its causal chain.
+ *
+ * Codes win over wording: a PostgreSQL SQLSTATE or SQLite result code is
+ * authoritative, and dialect message matching only runs when no code in the
+ * chain was recognized (DuckDB, or an error already flattened to a string).
+ *
+ * Constraint violations are reported ahead of `aborted_transaction` so a chain
+ * carrying both surfaces the root cause rather than the downstream symptom;
+ * both are deterministic, so retry behavior is identical either way.
+ *
+ * @param error - Any thrown value. Non-database errors classify as `'unknown'`.
+ * @returns The structured classification; never throws.
+ */
+export declare function classifyDatabaseError(error: unknown): DatabaseErrorClassification;
+/**
+ * True when retrying the statement cannot change the outcome.
+ *
+ * Used by {@link ErrorUtils.withRetry} to fail fast instead of burning the
+ * full 500 + 1000 + 2000 ms backoff on a constraint violation.
+ */
+export declare function isDeterministicDatabaseError(error: unknown): boolean;
+/** True when the failure is contention or availability and may clear. */
+export declare function isTransientDatabaseError(error: unknown): boolean;
+/** True when a unique or primary-key constraint was violated. */
+export declare function isUniqueViolationError(error: unknown): boolean;
+/** True when a NOT NULL constraint was violated. */
+export declare function isNotNullViolationError(error: unknown): boolean;
+/**
+ * True when the failure came from running inside an already-aborted
+ * PostgreSQL transaction (SQLSTATE `25P02`).
+ *
+ * Detected independently of {@link DatabaseErrorKind} so a chain that also
+ * carries the root constraint code still answers `true` here.
+ */
+export declare function isAbortedTransactionError(error: unknown): boolean;
+//# sourceMappingURL=db-errors.d.ts.map

package/dist/db-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"db-errors.d.ts","sourceRoot":"","sources":["../src/db-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAEH,0DAA0D;AAC1D,MAAM,MAAM,iBAAiB,GACzB,kBAAkB,GAClB,oBAAoB,GACpB,uBAAuB,GACvB,iBAAiB,GACjB,qBAAqB,GACrB,eAAe,GACf,qBAAqB,GACrB,kBAAkB,GAClB,wBAAwB,GACxB,cAAc,GACd,WAAW,GACX,SAAS,CAAC;AAEd,0DAA0D;AAC1D,MAAM,WAAW,2BAA2B;IAC1C,yEAAyE;IACzE,IAAI,EAAE,iBAAiB,CAAC;IACxB,oDAAoD;IACpD,aAAa,EAAE,OAAO,CAAC;IACvB,gDAAgD;IAChD,SAAS,EAAE,OAAO,CAAC;IACnB,kEAAkE;IAClE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sEAAsE;IACtE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,yEAAyE;IACzE,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;IAC/B;;;;;OAKG;IACH,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,oEAAoE;IACpE,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAgWD;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,MAAM,GAAG,iBAAiB,CAMzE;AAMD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,OAAO,GACb,2BAA2B,CA6G7B;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEpE;AAED,yEAAyE;AACzE,wBAAgB,wBAAwB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAEhE;AAED,iEAAiE;AACjE,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE9D;AAED,oDAAoD;AACpD,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAE/D;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAWjE"}