@fulmenhq/tsfulmen 0.3.2 → 0.4.0

package/dist/chunk-CW4CSNVF.js

@@ -0,0 +1,410 @@
+import { compileSchemaById } from './chunk-7SVYOPJ3.js';
+import { randomUUID } from 'crypto';
+
+var UUID_V4_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+function generateCorrelationId() {
+  return randomUUID();
+}
+function isValidCorrelationId(id) {
+  return UUID_V4_PATTERN.test(id);
+}
+function normalizeCorrelationId(id) {
+  return id.trim().toLowerCase();
+}
+function isCorrelationId(value) {
+  return typeof value === "string" && isValidCorrelationId(value);
+}
+
+// src/errors/severity.ts
+var Severity = {
+  INFO: "info",
+  LOW: "low",
+  MEDIUM: "medium",
+  HIGH: "high",
+  CRITICAL: "critical"
+};
+var SEVERITY_LEVELS = {
+  info: 0,
+  low: 1,
+  medium: 2,
+  high: 3,
+  critical: 4
+};
+var LEVEL_TO_SEVERITY = {
+  0: "info",
+  1: "low",
+  2: "medium",
+  3: "high",
+  4: "critical"
+};
+function severityToLevel(name) {
+  if (!isSeverityName(name)) {
+    throw new Error(
+      `Invalid severity name: "${name}". Must be one of: ${Object.values(Severity).join(", ")}`
+    );
+  }
+  return SEVERITY_LEVELS[name];
+}
+function levelToSeverity(level) {
+  if (!isSeverityLevel(level)) {
+    throw new Error(`Invalid severity level: ${level}. Must be 0-4`);
+  }
+  return LEVEL_TO_SEVERITY[level];
+}
+function isSeverityName(value) {
+  return typeof value === "string" && Object.values(Severity).includes(value);
+}
+function isSeverityLevel(value) {
+  return typeof value === "number" && value >= 0 && value <= 4 && Number.isInteger(value);
+}
+function getDefaultSeverity() {
+  return {
+    name: Severity.MEDIUM,
+    level: 2
+  };
+}
+function compareSeverity(a, b) {
+  const levelA = typeof a === "string" ? severityToLevel(a) : a;
+  const levelB = typeof b === "string" ? severityToLevel(b) : b;
+  return levelA - levelB;
+}
+
+// src/errors/serialization.ts
+function serializeError(error, code = "UNKNOWN_ERROR", severity = Severity.MEDIUM) {
+  if (error instanceof Error) {
+    return {
+      code,
+      message: error.message,
+      severity,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      context: {
+        name: error.name,
+        stack: error.stack
+      },
+      original: error.stack || error.message
+    };
+  }
+  if (isErrorLike(error)) {
+    return {
+      code,
+      message: error.message,
+      severity,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      details: error.details,
+      context: error.context,
+      original: JSON.stringify(error)
+    };
+  }
+  if (typeof error === "string") {
+    return {
+      code,
+      message: error,
+      severity,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    };
+  }
+  return {
+    code,
+    message: String(error),
+    severity,
+    timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+    original: typeof error === "object" ? JSON.stringify(error) : String(error)
+  };
+}
+function extractErrorMessage(error) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  if (isErrorLike(error)) {
+    return error.message;
+  }
+  if (typeof error === "string") {
+    return error;
+  }
+  return String(error);
+}
+function extractStackTrace(error) {
+  if (error instanceof Error) {
+    return error.stack;
+  }
+  if (isErrorLike(error) && typeof error.stack === "string") {
+    return error.stack;
+  }
+  return void 0;
+}
+function isErrorLike(value) {
+  return typeof value === "object" && value !== null && "message" in value && typeof value.message === "string";
+}
+
+// src/errors/validators.ts
+var ErrorValidator = class _ErrorValidator {
+  static instance;
+  validateFn = null;
+  initPromise = null;
+  initError = null;
+  constructor() {
+  }
+  /**
+   * Get singleton instance
+   */
+  static getInstance() {
+    if (!_ErrorValidator.instance) {
+      _ErrorValidator.instance = new _ErrorValidator();
+    }
+    return _ErrorValidator.instance;
+  }
+  /**
+   * Initialize validator (lazy load, async)
+   */
+  async init() {
+    if (this.validateFn !== null || this.initError !== null) {
+      return;
+    }
+    if (this.initPromise) {
+      return this.initPromise;
+    }
+    this.initPromise = (async () => {
+      try {
+        await compileSchemaById("pathfinder/v1.0.0/error-response");
+        await compileSchemaById("assessment/v1.0.0/severity-definitions");
+        this.validateFn = await compileSchemaById("error-handling/v1.0.0/error-response");
+      } catch (err) {
+        this.initError = err instanceof Error ? err : new Error(String(err));
+        throw new Error(`Failed to initialize error validator: ${this.initError.message}`);
+      }
+    })();
+    return this.initPromise;
+  }
+  /**
+   * Validate error data against schema
+   *
+   * @param data - Data to validate
+   * @returns Promise resolving to true if valid, false otherwise
+   * @throws {Error} If validator failed to initialize
+   */
+  async validate(data) {
+    if (this.validateFn === null) {
+      await this.init();
+    }
+    if (this.initError) {
+      throw this.initError;
+    }
+    if (!this.validateFn) {
+      throw new Error("Validator not initialized");
+    }
+    return this.validateFn(data);
+  }
+  /**
+   * Get validation errors from last validation
+   *
+   * @returns Validation errors or null
+   */
+  getErrors() {
+    if (!this.validateFn) {
+      return null;
+    }
+    return this.validateFn.errors;
+  }
+  /**
+   * Reset validator state (for testing)
+   * @internal
+   */
+  static _reset() {
+    _ErrorValidator.instance = new _ErrorValidator();
+  }
+};
+async function validateErrorData(data) {
+  return ErrorValidator.getInstance().validate(data);
+}
+function getValidationErrors() {
+  return ErrorValidator.getInstance().getErrors();
+}
+function formatValidationErrors(errors) {
+  return errors.map((err) => {
+    const path = err.instancePath || "(root)";
+    const message = err.message || "validation failed";
+    return `${path}: ${message}`;
+  }).join("; ");
+}
+async function assertValidErrorData(data) {
+  if (!await validateErrorData(data)) {
+    const errors = getValidationErrors();
+    const message = errors ? formatValidationErrors(errors) : "Error data validation failed";
+    throw new Error(`Invalid error data: ${message}`);
+  }
+}
+
+// src/errors/fulmen-error.ts
+var FulmenError = class _FulmenError extends Error {
+  data;
+  constructor(data) {
+    super(data.message);
+    this.name = "FulmenError";
+    this.data = Object.freeze({ ...data });
+    Error.captureStackTrace(this, _FulmenError);
+  }
+  /**
+   * Serialize to JSON (schema-compliant)
+   */
+  toJSON() {
+    return this.data;
+  }
+  /**
+   * Check equality with another FulmenError
+   */
+  equals(other) {
+    return JSON.stringify(this.data) === JSON.stringify(other.data);
+  }
+  /**
+   * Get severity level for comparison
+   */
+  getSeverityLevel() {
+    return this.data.severity_level ?? SEVERITY_LEVELS[this.data.severity ?? "medium"];
+  }
+  /**
+   * Wrap an existing error with FulmenError structure
+   *
+   * @param error - Error to wrap (Error instance or FulmenErrorData)
+   * @param options - Additional error options
+   * @returns New FulmenError instance
+   *
+   * @example
+   * ```typescript
+   * try {
+   *   throw new Error('Config invalid');
+   * } catch (err) {
+   *   const fulmenErr = FulmenError.wrap(err, {
+   *     code: 'CONFIG_INVALID',
+   *     severity: 'high',
+   *     exit_code: 2
+   *   });
+   *   throw fulmenErr;
+   * }
+   * ```
+   */
+  static wrap(error, options = {}) {
+    if (error instanceof _FulmenError) {
+      const effectiveSeverity = options.severity ?? error.data.severity ?? Severity.MEDIUM;
+      const effectiveSeverityLevel = SEVERITY_LEVELS[effectiveSeverity];
+      const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+      return new _FulmenError({
+        ...error.data,
+        ...options,
+        code: options.code ?? error.data.code,
+        message: error.data.message,
+        severity: effectiveSeverity,
+        // Consistent severity
+        severity_level: effectiveSeverityLevel,
+        // Recomputed level
+        timestamp
+        // Updated timestamp
+      });
+    }
+    if (isFulmenErrorData(error)) {
+      const defaultSeverity = getDefaultSeverity();
+      const effectiveSeverity = options.severity ?? error.severity ?? defaultSeverity.name;
+      const effectiveSeverityLevel = SEVERITY_LEVELS[effectiveSeverity];
+      return new _FulmenError({
+        ...error,
+        ...options,
+        severity: effectiveSeverity,
+        severity_level: effectiveSeverityLevel,
+        // Recomputed, not from error.severity_level
+        timestamp: error.timestamp ?? (/* @__PURE__ */ new Date()).toISOString()
+      });
+    }
+    return _FulmenError.fromError(error, options);
+  }
+  /**
+   * Create FulmenError from native Error object
+   *
+   * @param err - Native Error instance
+   * @param options - Error options
+   * @returns New FulmenError instance
+   *
+   * @example
+   * ```typescript
+   * const err = new TypeError('Invalid type');
+   * const fulmenErr = FulmenError.fromError(err, {
+   *   code: 'TYPE_ERROR',
+   *   severity: 'medium'
+   * });
+   * ```
+   */
+  static fromError(err, options = {}) {
+    const code = options.code ?? "UNKNOWN_ERROR";
+    const severity = options.severity ?? Severity.MEDIUM;
+    const severityLevel = SEVERITY_LEVELS[severity];
+    const message = extractErrorMessage(err);
+    const stack = extractStackTrace(err);
+    const data = {
+      code,
+      message,
+      severity,
+      severity_level: severityLevel,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+      ...options,
+      context: {
+        ...options.context,
+        originalName: err instanceof Error ? err.name : typeof err,
+        stack
+      },
+      original: stack || message
+    };
+    return new _FulmenError(data);
+  }
+  /**
+   * Validate error data against schema
+   *
+   * @param data - Error data to validate
+   * @returns Promise resolving to true if valid
+   *
+   * @example
+   * ```typescript
+   * const data = { code: 'TEST', message: 'Test error' };
+   * if (await FulmenError.validate(data)) {
+   *   const err = new FulmenError(data);
+   * }
+   * ```
+   */
+  static async validate(data) {
+    return validateErrorData(data);
+  }
+  /**
+   * Exit process with structured error
+   *
+   * Logs error as JSON and exits with specified exit code.
+   * Mockable for testing (override process.exit).
+   *
+   * @param error - FulmenError instance
+   * @param options - Exit options
+   *
+   * @example
+   * ```typescript
+   * const err = FulmenError.fromError(new Error('Fatal'), {
+   *   code: 'FATAL_ERROR',
+   *   exit_code: 1
+   * });
+   * FulmenError.exitWithError(err); // Exits with code 1
+   * ```
+   */
+  static exitWithError(error, options = {}) {
+    const logger = options.logger ?? console.error;
+    const exitCode = error.data.exit_code ?? 1;
+    logger(JSON.stringify(error.toJSON(), null, 2));
+    process.exit(exitCode);
+  }
+};
+function isFulmenError(value) {
+  return value instanceof FulmenError;
+}
+function isFulmenErrorData(value) {
+  return typeof value === "object" && value !== null && "code" in value && typeof value.code === "string" && "message" in value && typeof value.message === "string";
+}
+
+// src/errors/index.ts
+var VERSION = "0.2.0";
+
+export { FulmenError, LEVEL_TO_SEVERITY, SEVERITY_LEVELS, Severity, VERSION, assertValidErrorData, compareSeverity, extractErrorMessage, extractStackTrace, formatValidationErrors, generateCorrelationId, getDefaultSeverity, getValidationErrors, isCorrelationId, isFulmenError, isFulmenErrorData, isSeverityLevel, isSeverityName, isValidCorrelationId, levelToSeverity, normalizeCorrelationId, serializeError, severityToLevel, validateErrorData };
+//# sourceMappingURL=chunk-CW4CSNVF.js.map
+//# sourceMappingURL=chunk-CW4CSNVF.js.map

package/dist/chunk-CW4CSNVF.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors/correlation.ts","../src/errors/severity.ts","../src/errors/serialization.ts","../src/errors/validators.ts","../src/errors/fulmen-error.ts","../src/errors/index.ts"],"names":[],"mappings":"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","file":"chunk-CW4CSNVF.js","sourcesContent":["/**\n * Correlation ID generation and validation for error tracking\n *\n * Provides UUID v4 generation for correlation IDs used in observability\n * and distributed tracing scenarios.\n */\n\nimport { randomUUID } from \"node:crypto\";\n\n/**\n * UUID v4 regex pattern for validation\n */\nconst UUID_V4_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;\n\n/**\n * Generate a new correlation ID (UUID v4)\n *\n * Uses Node.js crypto.randomUUID() for cryptographically strong random values.\n *\n * @returns UUID v4 string (e.g., \"550e8400-e29b-41d4-a716-446655440000\")\n *\n * @example\n * ```typescript\n * const correlationId = generateCorrelationId();\n * // \"550e8400-e29b-41d4-a716-446655440000\"\n * ```\n */\nexport function generateCorrelationId(): string {\n  return randomUUID();\n}\n\n/**\n * Validate if a string is a valid UUID v4 correlation ID\n *\n * Checks format: xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx\n * where y is one of [8, 9, a, b]\n *\n * @param id - String to validate\n * @returns True if valid UUID v4 format\n *\n * @example\n * ```typescript\n * isValidCorrelationId('550e8400-e29b-41d4-a716-446655440000') // true\n * isValidCorrelationId('not-a-uuid') // false\n * isValidCorrelationId('550e8400-e29b-31d4-a716-446655440000') // false (version 3, not 4)\n * ```\n */\nexport function isValidCorrelationId(id: string): boolean {\n  return UUID_V4_PATTERN.test(id);\n}\n\n/**\n * Normalize a correlation ID (lowercase, trim whitespace)\n *\n * @param id - Correlation ID to normalize\n * @returns Normalized correlation ID\n *\n * @example\n * ```typescript\n * normalizeCorrelationId('  550E8400-E29B-41D4-A716-446655440000  ')\n * // \"550e8400-e29b-41d4-a716-446655440000\"\n * ```\n */\nexport function normalizeCorrelationId(id: string): string {\n  return id.trim().toLowerCase();\n}\n\n/**\n * Type guard to check if a value is a valid correlation ID\n *\n * @param value - Value to check\n * @returns True if value is a string and valid UUID v4\n *\n * @example\n * ```typescript\n * if (isCorrelationId(value)) {\n *   // TypeScript knows value is string here\n *   const normalized = normalizeCorrelationId(value);\n * }\n * ```\n */\nexport function isCorrelationId(value: unknown): value is string {\n  return typeof value === \"string\" && isValidCorrelationId(value);\n}\n","/**\n * Severity mappings for error handling\n *\n * Implements severity levels from assessment/v1.0.0/severity-definitions schema\n * Provides bidirectional mapping between severity names and numeric levels\n */\n\n/**\n * Severity names aligned with assessment taxonomy\n */\nexport const Severity = {\n  INFO: \"info\",\n  LOW: \"low\",\n  MEDIUM: \"medium\",\n  HIGH: \"high\",\n  CRITICAL: \"critical\",\n} as const;\n\n/**\n * Severity name type (string literal union)\n */\nexport type SeverityName = (typeof Severity)[keyof typeof Severity];\n\n/**\n * Numeric severity level for sorting and comparison\n * info=0, low=1, medium=2, high=3, critical=4\n */\nexport type SeverityLevel = 0 | 1 | 2 | 3 | 4;\n\n/**\n * Canonical severity level mapping (name → level)\n * Aligned with schemas/crucible-ts/assessment/v1.0.0/severity-definitions.schema.json\n */\nexport const SEVERITY_LEVELS: Record<SeverityName, SeverityLevel> = {\n  info: 0,\n  low: 1,\n  medium: 2,\n  high: 3,\n  critical: 4,\n};\n\n/**\n * Reverse mapping (level → name)\n */\nexport const LEVEL_TO_SEVERITY: Record<SeverityLevel, SeverityName> = {\n  0: \"info\",\n  1: \"low\",\n  2: \"medium\",\n  3: \"high\",\n  4: \"critical\",\n};\n\n/**\n * Convert severity name to numeric level\n *\n * @param name - Severity name (info, low, medium, high, critical)\n * @returns Numeric severity level (0-4)\n * @throws {Error} If severity name is invalid\n *\n * @example\n * ```typescript\n * severityToLevel('high') // returns 3\n * severityToLevel('info') // returns 0\n * ```\n */\nexport function severityToLevel(name: string): SeverityLevel {\n  if (!isSeverityName(name)) {\n    throw new Error(\n      `Invalid severity name: \"${name}\". Must be one of: ${Object.values(Severity).join(\", \")}`,\n    );\n  }\n  return SEVERITY_LEVELS[name];\n}\n\n/**\n * Convert numeric level to severity name\n *\n * @param level - Numeric severity level (0-4)\n * @returns Severity name\n * @throws {Error} If level is invalid\n *\n * @example\n * ```typescript\n * levelToSeverity(3) // returns 'high'\n * levelToSeverity(0) // returns 'info'\n * ```\n */\nexport function levelToSeverity(level: number): SeverityName {\n  if (!isSeverityLevel(level)) {\n    throw new Error(`Invalid severity level: ${level}. Must be 0-4`);\n  }\n  return LEVEL_TO_SEVERITY[level];\n}\n\n/**\n * Type guard to check if a value is a valid severity name\n *\n * @param value - Value to check\n * @returns True if value is a valid SeverityName\n *\n * @example\n * ```typescript\n * if (isSeverityName(value)) {\n *   const level = severityToLevel(value); // Type-safe\n * }\n * ```\n */\nexport function isSeverityName(value: unknown): value is SeverityName {\n  return typeof value === \"string\" && Object.values(Severity).includes(value as SeverityName);\n}\n\n/**\n * Type guard to check if a value is a valid severity level\n *\n * @param value - Value to check\n * @returns True if value is a valid SeverityLevel\n *\n * @example\n * ```typescript\n * if (isSeverityLevel(value)) {\n *   const name = levelToSeverity(value); // Type-safe\n * }\n * ```\n */\nexport function isSeverityLevel(value: unknown): value is SeverityLevel {\n  return typeof value === \"number\" && value >= 0 && value <= 4 && Number.isInteger(value);\n}\n\n/**\n * Get default severity (medium/2) when not specified\n *\n * @returns Default severity name and level\n */\nexport function getDefaultSeverity(): {\n  name: SeverityName;\n  level: SeverityLevel;\n} {\n  return {\n    name: Severity.MEDIUM,\n    level: 2,\n  };\n}\n\n/**\n * Compare two severity levels\n *\n * @param a - First severity (name or level)\n * @param b - Second severity (name or level)\n * @returns Negative if a < b, positive if a > b, zero if equal\n *\n * @example\n * ```typescript\n * compareSeverity('high', 'low') // returns positive (high > low)\n * compareSeverity(2, 'critical') // returns negative (medium < critical)\n * ```\n */\nexport function compareSeverity(\n  a: SeverityName | SeverityLevel,\n  b: SeverityName | SeverityLevel,\n): number {\n  const levelA = typeof a === \"string\" ? severityToLevel(a) : a;\n  const levelB = typeof b === \"string\" ? severityToLevel(b) : b;\n  return levelA - levelB;\n}\n","/**\n * Error serialization utilities\n *\n * Provides safe serialization of Error objects and unknown errors to structured data\n */\n\nimport { Severity, type SeverityLevel, type SeverityName } from \"./severity.js\";\n\n/**\n * FulmenError data structure (for serialization)\n * Defined here to avoid circular dependency\n */\nexport interface FulmenErrorData {\n  readonly code: string;\n  readonly message: string;\n  readonly details?: Record<string, unknown>;\n  readonly path?: string;\n  readonly timestamp?: string;\n  readonly severity?: SeverityName;\n  readonly severity_level?: SeverityLevel;\n  readonly correlation_id?: string;\n  readonly trace_id?: string;\n  readonly exit_code?: number;\n  readonly context?: Record<string, unknown>;\n  readonly original?: string | object;\n}\n\n/**\n * Safely serialize any error-like value to FulmenErrorData structure\n *\n * Handles native Error objects, plain objects, strings, and unknown types.\n *\n * @param error - Error value to serialize\n * @param code - Optional error code (defaults to 'UNKNOWN_ERROR')\n * @param severity - Optional severity (defaults to 'medium')\n * @returns Structured error data\n *\n * @example\n * ```typescript\n * try {\n *   throw new Error('Something failed');\n * } catch (err) {\n *   const data = serializeError(err, 'OPERATION_FAILED', 'high');\n *   console.log(JSON.stringify(data));\n * }\n * ```\n */\nexport function serializeError(\n  error: unknown,\n  code = \"UNKNOWN_ERROR\",\n  severity: SeverityName = Severity.MEDIUM,\n): FulmenErrorData {\n  // Handle Error instances\n  if (error instanceof Error) {\n    return {\n      code,\n      message: error.message,\n      severity,\n      timestamp: new Date().toISOString(),\n      context: {\n        name: error.name,\n        stack: error.stack,\n      },\n      original: error.stack || error.message,\n    };\n  }\n\n  // Handle plain objects with message\n  if (isErrorLike(error)) {\n    return {\n      code,\n      message: error.message,\n      severity,\n      timestamp: new Date().toISOString(),\n      details: error.details,\n      context: error.context,\n      original: JSON.stringify(error),\n    };\n  }\n\n  // Handle strings\n  if (typeof error === \"string\") {\n    return {\n      code,\n      message: error,\n      severity,\n      timestamp: new Date().toISOString(),\n    };\n  }\n\n  // Handle everything else\n  return {\n    code,\n    message: String(error),\n    severity,\n    timestamp: new Date().toISOString(),\n    original: typeof error === \"object\" ? JSON.stringify(error) : String(error),\n  };\n}\n\n/**\n * Extract error message from unknown error value\n *\n * @param error - Error value\n * @returns Error message string\n */\nexport function extractErrorMessage(error: unknown): string {\n  if (error instanceof Error) {\n    return error.message;\n  }\n  if (isErrorLike(error)) {\n    return error.message;\n  }\n  if (typeof error === \"string\") {\n    return error;\n  }\n  return String(error);\n}\n\n/**\n * Extract stack trace from error if available\n *\n * @param error - Error value\n * @returns Stack trace string or undefined\n */\nexport function extractStackTrace(error: unknown): string | undefined {\n  if (error instanceof Error) {\n    return error.stack;\n  }\n  if (isErrorLike(error) && typeof error.stack === \"string\") {\n    return error.stack;\n  }\n  return undefined;\n}\n\n/**\n * Type guard for error-like objects\n */\nfunction isErrorLike(value: unknown): value is {\n  message: string;\n  stack?: string;\n  details?: Record<string, unknown>;\n  context?: Record<string, unknown>;\n} {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    \"message\" in value &&\n    typeof (value as { message: unknown }).message === \"string\"\n  );\n}\n","/**\n * Schema validation for FulmenError data\n *\n * Provides singleton validator that pre-compiles error-response schema\n * using existing src/schema infrastructure. Performance target: <1ms per validation.\n */\n\nimport { compileSchemaById } from \"../schema/index.js\";\nimport type { CompiledValidator } from \"../schema/types.js\";\n\n/**\n * Singleton validator for FulmenError data\n *\n * Pre-compiles the error-response schema at first access for optimal performance.\n * Reuses existing AJV setup from src/schema module.\n */\nclass ErrorValidator {\n  private static instance: ErrorValidator;\n  private validateFn: CompiledValidator | null = null;\n  private initPromise: Promise<void> | null = null;\n  private initError: Error | null = null;\n\n  private constructor() {\n    // Private constructor for singleton\n  }\n\n  /**\n   * Get singleton instance\n   */\n  static getInstance(): ErrorValidator {\n    if (!ErrorValidator.instance) {\n      ErrorValidator.instance = new ErrorValidator();\n    }\n    return ErrorValidator.instance;\n  }\n\n  /**\n   * Initialize validator (lazy load, async)\n   */\n  private async init(): Promise<void> {\n    if (this.validateFn !== null || this.initError !== null) {\n      return; // Already initialized\n    }\n\n    if (this.initPromise) {\n      return this.initPromise; // Already initializing\n    }\n\n    this.initPromise = (async () => {\n      try {\n        // Ensure dependency schemas are registered before compiling error-response\n        // Error handling schema references pathfinder error-response relatively.\n        await compileSchemaById(\"pathfinder/v1.0.0/error-response\");\n        await compileSchemaById(\"assessment/v1.0.0/severity-definitions\");\n\n        // Compile schema using existing schema infrastructure\n        // Schema ID for error-response extends pathfinder error-response\n        this.validateFn = await compileSchemaById(\"error-handling/v1.0.0/error-response\");\n      } catch (err) {\n        this.initError = err instanceof Error ? err : new Error(String(err));\n        throw new Error(`Failed to initialize error validator: ${this.initError.message}`);\n      }\n    })();\n\n    return this.initPromise;\n  }\n\n  /**\n   * Validate error data against schema\n   *\n   * @param data - Data to validate\n   * @returns Promise resolving to true if valid, false otherwise\n   * @throws {Error} If validator failed to initialize\n   */\n  async validate(data: unknown): Promise<boolean> {\n    if (this.validateFn === null) {\n      await this.init();\n    }\n\n    if (this.initError) {\n      throw this.initError;\n    }\n\n    if (!this.validateFn) {\n      throw new Error(\"Validator not initialized\");\n    }\n\n    return this.validateFn(data);\n  }\n\n  /**\n   * Get validation errors from last validation\n   *\n   * @returns Validation errors or null\n   */\n  getErrors() {\n    if (!this.validateFn) {\n      return null;\n    }\n    return this.validateFn.errors;\n  }\n\n  /**\n   * Reset validator state (for testing)\n   * @internal\n   */\n  static _reset(): void {\n    ErrorValidator.instance = new ErrorValidator();\n  }\n}\n\n/**\n * Validate FulmenError data against error-response schema\n *\n * Uses pre-compiled validator singleton for optimal performance (<1ms target).\n *\n * @param data - Error data to validate\n * @returns Promise resolving to true if valid, false otherwise\n *\n * @example\n * ```typescript\n * const data = {\n *   code: 'CONFIG_INVALID',\n *   message: 'Configuration validation failed'\n * };\n *\n * if (await validateErrorData(data)) {\n *   // Data is schema-compliant\n * } else {\n *   const errors = await getValidationErrors();\n *   console.error('Validation failed:', errors);\n * }\n * ```\n */\nexport async function validateErrorData(data: unknown): Promise<boolean> {\n  return ErrorValidator.getInstance().validate(data);\n}\n\n/**\n * Get validation errors from last validation\n *\n * @returns Validation errors or null\n *\n * @example\n * ```typescript\n * if (!(await validateErrorData(data))) {\n *   const errors = getValidationErrors();\n *   errors?.forEach(err => {\n *     console.error(`${err.instancePath}: ${err.message}`);\n *   });\n * }\n * ```\n */\nexport function getValidationErrors() {\n  return ErrorValidator.getInstance().getErrors();\n}\n\n/**\n * Format validation errors as human-readable string\n *\n * @param errors - Validation error objects\n * @returns Formatted error message\n *\n * @example\n * ```typescript\n * const errors = getValidationErrors();\n * if (errors) {\n *   throw new Error(formatValidationErrors(errors));\n * }\n * ```\n */\nexport function formatValidationErrors(\n  errors: Array<{ instancePath?: string; message?: string }>,\n): string {\n  return errors\n    .map((err) => {\n      const path = err.instancePath || \"(root)\";\n      const message = err.message || \"validation failed\";\n      return `${path}: ${message}`;\n    })\n    .join(\"; \");\n}\n\n/**\n * Validate and throw if invalid\n *\n * @param data - Error data to validate\n * @throws {Error} If validation fails\n *\n * @example\n * ```typescript\n * await assertValidErrorData(data); // Throws if invalid\n * // Safe to use data here\n * ```\n */\nexport async function assertValidErrorData(data: unknown): Promise<void> {\n  if (!(await validateErrorData(data))) {\n    const errors = getValidationErrors();\n    const message = errors ? formatValidationErrors(errors) : \"Error data validation failed\";\n    throw new Error(`Invalid error data: ${message}`);\n  }\n}\n\n// Export for testing\nexport { ErrorValidator };\n","/**\n * FulmenError - Structured error data model for observability\n *\n * Implements ADR-0006 error data model extending Pathfinder error-response\n * with optional telemetry metadata (severity, correlation_id, trace_id, etc.)\n */\n\nimport { extractErrorMessage, extractStackTrace, type FulmenErrorData } from \"./serialization.js\";\nimport type { SeverityLevel, SeverityName } from \"./severity.js\";\nimport { getDefaultSeverity, SEVERITY_LEVELS, Severity } from \"./severity.js\";\nimport { validateErrorData } from \"./validators.js\";\n\n// Re-export FulmenErrorData from serialization\nexport type { FulmenErrorData } from \"./serialization.js\";\n\n/**\n * Options for creating/wrapping FulmenError\n */\nexport interface FulmenErrorOptions {\n  code?: string;\n  severity?: SeverityName;\n  correlation_id?: string;\n  trace_id?: string;\n  exit_code?: number;\n  context?: Record<string, unknown>;\n  details?: Record<string, unknown>;\n  path?: string;\n}\n\n/**\n * FulmenError class - wraps structured error data with helper methods\n *\n * Implements ADR-0006 canonical data model pattern:\n * - Data stored in immutable FulmenErrorData interface\n * - Class provides ergonomic API and methods\n * - Extends native Error for stack traces and instanceof checks\n */\nexport class FulmenError extends Error {\n  readonly data: FulmenErrorData;\n\n  constructor(data: FulmenErrorData) {\n    super(data.message);\n    this.name = \"FulmenError\";\n\n    // Freeze data for immutability\n    this.data = Object.freeze({ ...data });\n\n    // Capture stack trace\n    Error.captureStackTrace(this, FulmenError);\n  }\n\n  /**\n   * Serialize to JSON (schema-compliant)\n   */\n  toJSON(): FulmenErrorData {\n    return this.data;\n  }\n\n  /**\n   * Check equality with another FulmenError\n   */\n  equals(other: FulmenError): boolean {\n    return JSON.stringify(this.data) === JSON.stringify(other.data);\n  }\n\n  /**\n   * Get severity level for comparison\n   */\n  getSeverityLevel(): SeverityLevel {\n    return this.data.severity_level ?? SEVERITY_LEVELS[this.data.severity ?? \"medium\"];\n  }\n\n  /**\n   * Wrap an existing error with FulmenError structure\n   *\n   * @param error - Error to wrap (Error instance or FulmenErrorData)\n   * @param options - Additional error options\n   * @returns New FulmenError instance\n   *\n   * @example\n   * ```typescript\n   * try {\n   *   throw new Error('Config invalid');\n   * } catch (err) {\n   *   const fulmenErr = FulmenError.wrap(err, {\n   *     code: 'CONFIG_INVALID',\n   *     severity: 'high',\n   *     exit_code: 2\n   *   });\n   *   throw fulmenErr;\n   * }\n   * ```\n   */\n  static wrap(error: Error | FulmenErrorData, options: FulmenErrorOptions = {}): FulmenError {\n    // If already FulmenError, merge options with recomputed derived fields\n    if (error instanceof FulmenError) {\n      // Determine effective severity (prefer options, fallback to existing, default to medium)\n      const effectiveSeverity = options.severity ?? error.data.severity ?? Severity.MEDIUM;\n      // CRITICAL: Recompute severity_level from severity to maintain consistency (ADR-0006)\n      const effectiveSeverityLevel = SEVERITY_LEVELS[effectiveSeverity];\n\n      // Update timestamp when re-wrapping (indicates new error context)\n      const timestamp = new Date().toISOString();\n\n      return new FulmenError({\n        ...error.data,\n        ...options,\n        code: options.code ?? error.data.code,\n        message: error.data.message,\n        severity: effectiveSeverity, // Consistent severity\n        severity_level: effectiveSeverityLevel, // Recomputed level\n        timestamp, // Updated timestamp\n      });\n    }\n\n    // If FulmenErrorData, recompute derived fields\n    if (isFulmenErrorData(error)) {\n      const defaultSeverity = getDefaultSeverity();\n      // Prefer options.severity, fall back to error.severity, default to medium\n      const effectiveSeverity = options.severity ?? error.severity ?? defaultSeverity.name;\n      // CRITICAL: Always recompute severity_level from severity (never trust provided level)\n      const effectiveSeverityLevel = SEVERITY_LEVELS[effectiveSeverity];\n\n      return new FulmenError({\n        ...error,\n        ...options,\n        severity: effectiveSeverity,\n        severity_level: effectiveSeverityLevel, // Recomputed, not from error.severity_level\n        timestamp: error.timestamp ?? new Date().toISOString(),\n      });\n    }\n\n    // Wrap native Error\n    return FulmenError.fromError(error, options);\n  }\n\n  /**\n   * Create FulmenError from native Error object\n   *\n   * @param err - Native Error instance\n   * @param options - Error options\n   * @returns New FulmenError instance\n   *\n   * @example\n   * ```typescript\n   * const err = new TypeError('Invalid type');\n   * const fulmenErr = FulmenError.fromError(err, {\n   *   code: 'TYPE_ERROR',\n   *   severity: 'medium'\n   * });\n   * ```\n   */\n  static fromError(err: Error | unknown, options: FulmenErrorOptions = {}): FulmenError {\n    const code = options.code ?? \"UNKNOWN_ERROR\";\n    const severity = options.severity ?? Severity.MEDIUM;\n    const severityLevel = SEVERITY_LEVELS[severity];\n\n    const message = extractErrorMessage(err);\n    const stack = extractStackTrace(err);\n\n    const data: FulmenErrorData = {\n      code,\n      message,\n      severity,\n      severity_level: severityLevel,\n      timestamp: new Date().toISOString(),\n      ...options,\n      context: {\n        ...options.context,\n        originalName: err instanceof Error ? err.name : typeof err,\n        stack,\n      },\n      original: stack || message,\n    };\n\n    return new FulmenError(data);\n  }\n\n  /**\n   * Validate error data against schema\n   *\n   * @param data - Error data to validate\n   * @returns Promise resolving to true if valid\n   *\n   * @example\n   * ```typescript\n   * const data = { code: 'TEST', message: 'Test error' };\n   * if (await FulmenError.validate(data)) {\n   *   const err = new FulmenError(data);\n   * }\n   * ```\n   */\n  static async validate(data: unknown): Promise<boolean> {\n    return validateErrorData(data);\n  }\n\n  /**\n   * Exit process with structured error\n   *\n   * Logs error as JSON and exits with specified exit code.\n   * Mockable for testing (override process.exit).\n   *\n   * @param error - FulmenError instance\n   * @param options - Exit options\n   *\n   * @example\n   * ```typescript\n   * const err = FulmenError.fromError(new Error('Fatal'), {\n   *   code: 'FATAL_ERROR',\n   *   exit_code: 1\n   * });\n   * FulmenError.exitWithError(err); // Exits with code 1\n   * ```\n   */\n  static exitWithError(\n    error: FulmenError,\n    options: { logger?: (msg: string) => void } = {},\n  ): never {\n    const logger = options.logger ?? console.error;\n    const exitCode = error.data.exit_code ?? 1;\n\n    // Log structured error\n    logger(JSON.stringify(error.toJSON(), null, 2));\n\n    // Exit with code\n    process.exit(exitCode);\n  }\n}\n\n/**\n * Type guard to check if value is FulmenError instance\n *\n * @param value - Value to check\n * @returns True if value is FulmenError\n */\nexport function isFulmenError(value: unknown): value is FulmenError {\n  return value instanceof FulmenError;\n}\n\n/**\n * Type guard to check if value is FulmenErrorData\n *\n * @param value - Value to check\n * @returns True if value is FulmenErrorData\n */\nexport function isFulmenErrorData(value: unknown): value is FulmenErrorData {\n  return (\n    typeof value === \"object\" &&\n    value !== null &&\n    \"code\" in value &&\n    typeof (value as FulmenErrorData).code === \"string\" &&\n    \"message\" in value &&\n    typeof (value as FulmenErrorData).message === \"string\"\n  );\n}\n","/**\n * Errors module - structured error handling with telemetry\n *\n * Provides FulmenError data model and utilities for schema-backed error responses\n * with optional telemetry metadata (severity, correlation IDs, exit codes).\n */\n\nexport const VERSION = \"0.2.0\";\n\n// Correlation ID utilities\nexport {\n  generateCorrelationId,\n  isCorrelationId,\n  isValidCorrelationId,\n  normalizeCorrelationId,\n} from \"./correlation.js\";\n// Core error class and types\nexport {\n  FulmenError,\n  type FulmenErrorData,\n  type FulmenErrorOptions,\n  isFulmenError,\n  isFulmenErrorData,\n} from \"./fulmen-error.js\";\n// Serialization utilities\nexport {\n  extractErrorMessage,\n  extractStackTrace,\n  serializeError,\n} from \"./serialization.js\";\n// Severity utilities\nexport {\n  compareSeverity,\n  getDefaultSeverity,\n  isSeverityLevel,\n  isSeverityName,\n  LEVEL_TO_SEVERITY,\n  levelToSeverity,\n  SEVERITY_LEVELS,\n  Severity,\n  type SeverityLevel,\n  type SeverityName,\n  severityToLevel,\n} from \"./severity.js\";\n// Validation utilities\nexport {\n  assertValidErrorData,\n  formatValidationErrors,\n  getValidationErrors,\n  validateErrorData,\n} from \"./validators.js\";\n"]}