@fulmenhq/tsfulmen 0.3.2 → 0.3.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (22) hide show
  1. package/CHANGELOG.md +14 -0
  2. package/dist/appidentity/index.d.ts +15 -5
  3. package/dist/appidentity/index.js +12 -7
  4. package/dist/appidentity/index.js.map +1 -1
  5. package/dist/bin/prometheus-cli.js +12 -7
  6. package/dist/bin/prometheus-cli.js.map +1 -1
  7. package/dist/bin/schema-cli.js.map +1 -1
  8. package/dist/config/index.d.ts +69 -11
  9. package/dist/config/index.js +18 -7
  10. package/dist/config/index.js.map +1 -1
  11. package/dist/foundry/index.d.ts +1 -1
  12. package/dist/index.d.ts +2 -2
  13. package/dist/index.js +13 -8
  14. package/dist/index.js.map +1 -1
  15. package/dist/reports/license-inventory.csv +1 -1
  16. package/dist/schema/index.js.map +1 -1
  17. package/dist/signals/index.d.ts +1 -1
  18. package/dist/telemetry/http/index.js.map +1 -1
  19. package/dist/telemetry/prometheus/index.js +12 -7
  20. package/dist/telemetry/prometheus/index.js.map +1 -1
  21. package/dist/{types-Dv5TERCM.d.ts → types-CHDvDRCf.d.ts} +17 -1
  22. package/package.json +1 -1
package/dist/telemetry/http/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"sources":["../../../src/appidentity/constants.ts","../../../src/schema/ajv-formats.ts","../../../src/schema/errors.ts","../../../src/schema/utils.ts","../../../src/schema/goneat-bridge.ts","../../../src/schema/normalizer.ts","../../../src/schema/registry.ts","../../../src/telemetry/counter.ts","../../../src/telemetry/gauge.ts","../../../src/telemetry/taxonomy.ts","../../../src/telemetry/histogram.ts","../../../src/telemetry/registry.ts","../../../src/telemetry/types.ts","../../../src/telemetry/validators.ts","../../../src/telemetry/index.ts","../../../src/schema/validator.ts","../../../src/schema/cli.ts","../../../src/schema/export.ts","../../../src/schema/index.ts","../../../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","../../../src/appidentity/errors.ts","../../../src/appidentity/embedded.ts","../../../src/appidentity/cache.ts","../../../src/appidentity/discovery.ts","../../../src/appidentity/loader.ts","../../../src/appidentity/runtime.ts","../../../src/appidentity/index.ts","../../../src/appidentity/helpers.ts","../../../src/telemetry/http/index.ts","../../../src/telemetry/http/route-normalizer.ts"],"names":["join","readFile","parseYaml","init_registry","init_validators","init_errors"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Application Identity Constants\n *\n * Centralized configuration for identity discovery and validation\n */\n\n/**\n * Filename for identity document\n */\nexport const APP_IDENTITY_FILENAME = \"app.yaml\";\n\n/**\n * Directory containing identity file\n */\nexport const APP_IDENTITY_DIR = \".fulmen\";\n\n/**\n * Environment variable for explicit path override\n */\nexport const APP_IDENTITY_ENV_VAR = \"FULMEN_APP_IDENTITY_PATH\";\n\n/**\n * Schema ID for validation\n */\nexport const APP_IDENTITY_SCHEMA_ID = \"config/repository/app-identity/v1.0.0/app-identity\";\n\n/**\n * Maximum depth for ancestor directory search\n * Prevents infinite loops and excessive filesystem traversal\n */\nexport const MAX_ANCESTOR_SEARCH_DEPTH = 20;\n","import type Ajv from \"ajv\";\nimport addFormats from \"ajv-formats\";\n\nexport interface FulmenAjvFormatsOptions {\n mode?: \"fast\" | \"full\";\n formats?: string[];\n}\n\nconst DEFAULT_FORMATS = [\n \"date-time\",\n \"email\",\n \"hostname\",\n \"ipv4\",\n \"ipv6\",\n \"uri\",\n \"uri-reference\",\n \"uuid\",\n];\n\n/**\n * Apply Fulmen-standard AJV format support.\n *\n * Useful when configuring AJV in other frameworks (e.g. Fastify) so JSON Schema\n * `format` keywords are enforced consistently.\n */\nexport function applyFulmenAjvFormats(ajv: Ajv, options: FulmenAjvFormatsOptions = {}): Ajv {\n const mode = options.mode ?? \"fast\";\n const formats = options.formats ?? DEFAULT_FORMATS;\n\n // ajv-formats types use a string-literal union; allow callers to supply strings.\n // The `as never` on ajv works around ajv-formats bundling its own older ajv types\n // that diverge from ajv@8.18+ (CodeKeywordDefinition.code parameter incompatibility).\n addFormats(ajv as never, { mode, formats: formats as unknown as never[] });\n return ajv;\n}\n","/**\n * Schema validation errors - implements Fulmen Schema Validation Standard\n */\n\nimport type { SchemaSource, SchemaValidationDiagnostic } from \"./types.js\";\n\n/**\n * Export error reason enum for type-safe error categorization\n */\nexport enum ExportErrorReason {\n FILE_EXISTS = \"FILE_EXISTS\",\n WRITE_FAILED = \"WRITE_FAILED\",\n INVALID_FORMAT = \"INVALID_FORMAT\",\n PROVENANCE_FAILED = \"PROVENANCE_FAILED\",\n UNKNOWN = \"UNKNOWN\",\n}\n\n/**\n * Base error class for schema validation operations\n */\nexport class SchemaValidationError extends Error {\n constructor(\n message: string,\n public schemaId?: string,\n public diagnostics: SchemaValidationDiagnostic[] = [],\n public source?: SchemaSource,\n public cause?: Error,\n ) {\n super(message);\n this.name = \"SchemaValidationError\";\n\n // Maintains proper stack trace for where our error was thrown (only available on V8)\n if (Error.captureStackTrace) {\n Error.captureStackTrace(this, SchemaValidationError);\n }\n }\n\n /**\n * Create error for schema not found\n */\n static schemaNotFound(schemaId: string): SchemaValidationError {\n return new SchemaValidationError(`Schema not found: ${schemaId}`, schemaId);\n }\n\n /**\n * Create error for invalid schema input\n */\n static invalidSchemaInput(source: SchemaSource, details: string): SchemaValidationError {\n return new SchemaValidationError(`Invalid schema input: ${details}`, undefined, [], source);\n }\n\n /**\n * Create error for validation failure\n */\n static validationFailed(\n schemaId: string,\n diagnostics: SchemaValidationDiagnostic[],\n source?: SchemaSource,\n ): SchemaValidationError {\n const errorCount = diagnostics.filter((d) => d.severity === \"ERROR\").length;\n const warningCount = diagnostics.filter((d) => d.severity === \"WARN\").length;\n\n const message = `Schema validation failed: ${errorCount} error(s), ${warningCount} warning(s)`;\n\n return new SchemaValidationError(message, schemaId, diagnostics, source);\n }\n\n /**\n * Create error for goneat binary not found\n */\n static goneatNotFound(goneatPath?: string): SchemaValidationError {\n const pathInfo = goneatPath ? ` at ${goneatPath}` : \"\";\n return new SchemaValidationError(\n `Goneat binary not found${pathInfo}. Falling back to AJV validation.`,\n );\n }\n\n /**\n * Create error for goneat execution failure\n */\n static goneatExecutionFailed(error: Error): SchemaValidationError {\n return new SchemaValidationError(\n \"Goneat execution failed. Falling back to AJV validation.\",\n undefined,\n [],\n undefined,\n error,\n );\n }\n\n /**\n * Create error for empty schema input\n */\n static emptySchemaInput(source?: SchemaSource): SchemaValidationError {\n return new SchemaValidationError(\"Schema content is empty\", undefined, [], source);\n }\n\n /**\n * Create error for parse failure\n */\n static parseFailed(source: SchemaSource, error: Error): SchemaValidationError {\n return new SchemaValidationError(\n `Failed to parse schema: ${error.message}`,\n undefined,\n [],\n source,\n error,\n );\n }\n\n /**\n * Create error for encoding failure\n */\n static encodingFailed(source: SchemaSource, error: Error): SchemaValidationError {\n return new SchemaValidationError(\n `Failed to encode schema: ${error.message}`,\n undefined,\n [],\n source,\n error,\n );\n }\n\n /**\n * Create error for registry operation failure\n */\n static registryError(operation: string, details: string): SchemaValidationError {\n return new SchemaValidationError(`Schema registry ${operation} failed: ${details}`);\n }\n\n /**\n * Format error for display\n */\n format(): string {\n let output = this.message;\n\n if (this.schemaId) {\n output += `\\nSchema ID: ${this.schemaId}`;\n }\n\n if (this.diagnostics.length > 0) {\n output += \"\\n\\nValidation Issues:\";\n this.diagnostics.forEach((diag, index) => {\n output += `\\n ${index + 1}. [${diag.severity}] ${diag.message}`;\n if (diag.pointer) {\n output += ` at ${diag.pointer}`;\n }\n if (diag.keyword) {\n output += ` (keyword: ${diag.keyword})`;\n }\n if (diag.source) {\n output += ` [${diag.source}]`;\n }\n });\n }\n\n if (this.source) {\n output += `\\n\\nSource: ${this.source.type}`;\n if (this.source.id) {\n output += ` (${this.source.id})`;\n }\n }\n\n return output;\n }\n\n /**\n * Convert to JSON representation\n */\n toJSON(): {\n name: string;\n message: string;\n schemaId?: string;\n diagnostics: SchemaValidationDiagnostic[];\n source?: SchemaSource;\n cause?: string;\n } {\n return {\n name: this.name,\n message: this.message,\n schemaId: this.schemaId,\n diagnostics: this.diagnostics,\n source: this.source,\n cause: this.cause?.message,\n };\n }\n}\n\n/**\n * Error class for schema export operations\n */\nexport class SchemaExportError extends SchemaValidationError {\n constructor(\n message: string,\n public reason: ExportErrorReason,\n public schemaId?: string,\n public outPath?: string,\n public cause?: Error,\n ) {\n super(message, schemaId, [], undefined, cause);\n this.name = \"SchemaExportError\";\n\n if (Error.captureStackTrace) {\n Error.captureStackTrace(this, SchemaExportError);\n }\n }\n\n /**\n * Create error for file already exists\n */\n static fileExists(outPath: string): SchemaExportError {\n return new SchemaExportError(\n `Output file already exists: ${outPath}. Use overwrite option to replace.`,\n ExportErrorReason.FILE_EXISTS,\n undefined,\n outPath,\n );\n }\n\n /**\n * Create error for invalid export format\n */\n static invalidFormat(format: string, outPath: string): SchemaExportError {\n return new SchemaExportError(\n `Invalid export format: ${format}. Must be 'json' or 'yaml'.`,\n ExportErrorReason.INVALID_FORMAT,\n undefined,\n outPath,\n );\n }\n\n /**\n * Create error for write failure\n */\n static writeFailed(outPath: string, error: Error): SchemaExportError {\n return new SchemaExportError(\n `Failed to write schema to ${outPath}: ${error.message}`,\n ExportErrorReason.WRITE_FAILED,\n undefined,\n outPath,\n error,\n );\n }\n\n /**\n * Create error for provenance extraction failure\n */\n static provenanceFailed(details: string, error?: Error): SchemaExportError {\n return new SchemaExportError(\n `Failed to extract provenance metadata: ${details}`,\n ExportErrorReason.PROVENANCE_FAILED,\n undefined,\n undefined,\n error,\n );\n }\n}\n","/**\n * Schema validation utilities - helper functions for formatting and validation\n */\n\nimport { SchemaValidationError } from \"./errors.js\";\nimport type { SchemaValidationDiagnostic, SchemaValidationResult } from \"./types.js\";\n\n/**\n * Format validation diagnostics for display\n */\nexport function formatDiagnostics(diagnostics: SchemaValidationDiagnostic[]): string {\n if (diagnostics.length === 0) {\n return \"No validation issues found.\";\n }\n\n const lines: string[] = [];\n const errors = diagnostics.filter((d) => d.severity === \"ERROR\");\n const warnings = diagnostics.filter((d) => d.severity === \"WARN\");\n\n if (errors.length > 0) {\n lines.push(`❌ ${errors.length} error(s) found:`);\n errors.forEach((diag, index) => {\n lines.push(` ${index + 1}. ${diag.message}`);\n if (diag.pointer) {\n lines.push(` at ${diag.pointer}`);\n }\n if (diag.keyword) {\n lines.push(` keyword: ${diag.keyword}`);\n }\n });\n }\n\n if (warnings.length > 0) {\n lines.push(\"\");\n lines.push(`⚠️ ${warnings.length} warning(s) found:`);\n warnings.forEach((diag, index) => {\n lines.push(` ${index + 1}. ${diag.message}`);\n if (diag.pointer) {\n lines.push(` at ${diag.pointer}`);\n }\n });\n }\n\n return lines.join(\"\\n\");\n}\n\n/**\n * Format validation result for display\n */\nexport function formatValidationResult(result: SchemaValidationResult): string {\n if (result.valid) {\n return \"✅ Validation passed\";\n }\n\n const output: string[] = [];\n output.push(\"❌ Validation failed\");\n output.push(formatDiagnostics(result.diagnostics));\n output.push(`\\nSource: ${result.source}`);\n\n return output.join(\"\\n\");\n}\n\n/**\n * Check if value is a SchemaValidationError\n */\nexport function isValidationError(error: unknown): error is SchemaValidationError {\n return error instanceof SchemaValidationError;\n}\n\n/**\n * Extract validation result from error or return success\n */\nexport function extractValidationResult(error: unknown): {\n valid: boolean;\n diagnostics: SchemaValidationDiagnostic[];\n source: \"ajv\" | \"goneat\";\n} {\n if (isValidationError(error)) {\n return {\n valid: false,\n diagnostics: error.diagnostics,\n source: error.diagnostics[0]?.source || \"ajv\",\n };\n }\n\n return {\n valid: true,\n diagnostics: [],\n source: \"ajv\",\n };\n}\n\n/**\n * Normalize JSON pointer path for display\n */\nexport function normalizePointer(pointer: string): string {\n if (pointer === \"\") {\n return \"root\";\n }\n return pointer.replace(/^\\//, \"\").replace(/\\//g, \".\");\n}\n\n/**\n * Create a validation diagnostic\n */\nexport function createDiagnostic(\n pointer: string,\n message: string,\n keyword: string,\n severity: \"ERROR\" | \"WARN\" = \"ERROR\",\n source: \"ajv\" | \"goneat\" = \"ajv\",\n data?: unknown,\n): SchemaValidationDiagnostic {\n return {\n pointer,\n message,\n keyword,\n severity,\n source,\n data,\n };\n}\n\n/**\n * Group diagnostics by severity\n */\nexport function groupDiagnosticsBySeverity(diagnostics: SchemaValidationDiagnostic[]): {\n errors: SchemaValidationDiagnostic[];\n warnings: SchemaValidationDiagnostic[];\n} {\n return {\n errors: diagnostics.filter((d) => d.severity === \"ERROR\"),\n warnings: diagnostics.filter((d) => d.severity === \"WARN\"),\n };\n}\n\n/**\n * Count diagnostics by severity\n */\nexport function countDiagnostics(diagnostics: SchemaValidationDiagnostic[]): {\n total: number;\n errors: number;\n warnings: number;\n} {\n const grouped = groupDiagnosticsBySeverity(diagnostics);\n return {\n total: diagnostics.length,\n errors: grouped.errors.length,\n warnings: grouped.warnings.length,\n };\n}\n","/**\n * Goneat bridge - Optional integration for CLI-only goneat validation\n *\n * Provides goneat validation as an opt-in alternative for CLI exploration.\n * NOT used by library consumers - AJV validation is the primary implementation.\n */\n\nimport { spawn } from \"node:child_process\";\nimport { access } from \"node:fs/promises\";\nimport type { SchemaValidationDiagnostic, SchemaValidationResult } from \"./types.js\";\nimport { createDiagnostic } from \"./utils.js\";\n\n/**\n * Goneat validation output structure\n */\ninterface GoneatValidationOutput {\n valid: boolean;\n errors?: Array<{\n path: string;\n message: string;\n keyword?: string;\n }>;\n}\n\n/**\n * Detect goneat binary location\n */\nexport async function detectGoneat(customPath?: string): Promise<string | null> {\n // Try custom path first\n if (customPath) {\n try {\n await access(customPath);\n return customPath;\n } catch {\n return null;\n }\n }\n\n // Try GONEAT_PATH environment variable\n if (process.env.GONEAT_PATH) {\n try {\n await access(process.env.GONEAT_PATH);\n return process.env.GONEAT_PATH;\n } catch {\n // Continue to next option\n }\n }\n\n // Try local bin/goneat\n try {\n await access(\"./bin/goneat\");\n return \"./bin/goneat\";\n } catch {\n // Continue to next option\n }\n\n // Try system PATH (assume 'goneat' command available)\n return \"goneat\";\n}\n\n/**\n * Check if goneat is available\n *\n * If goneatPath is provided, use it directly to test availability.\n * Otherwise, detect goneat location first.\n */\nexport async function isGoneatAvailable(goneatPath?: string): Promise<boolean> {\n let pathToTest: string | null;\n\n if (goneatPath) {\n // Use provided path directly - don't re-detect\n // This allows testing 'goneat' command from PATH\n pathToTest = goneatPath;\n } else {\n // Detect goneat location\n pathToTest = await detectGoneat();\n if (!pathToTest) return false;\n }\n\n return new Promise((resolve) => {\n const proc = spawn(pathToTest as string, [\"version\"], { stdio: \"ignore\" });\n\n // Timeout after 5 seconds to prevent hanging in CI\n const timeout = setTimeout(() => {\n proc.kill();\n resolve(false);\n }, 5000);\n\n proc.on(\"close\", (code) => {\n clearTimeout(timeout);\n resolve(code === 0);\n });\n proc.on(\"error\", () => {\n clearTimeout(timeout);\n resolve(false);\n });\n });\n}\n\n/**\n * Run goneat schema validation (CLI-only, opt-in)\n *\n * This is NOT used by library validation - it's purely for CLI comparison.\n * Library users get full AJV validation without goneat dependency.\n */\nexport async function runGoneatValidation(\n schemaPath: string,\n dataPath: string,\n goneatPath?: string,\n): Promise<SchemaValidationResult> {\n const detected = await detectGoneat(goneatPath);\n\n if (!detected) {\n return {\n valid: false,\n diagnostics: [\n createDiagnostic(\n \"\",\n \"goneat binary not found. Install goneat or specify path with --goneat-path\",\n \"goneat-unavailable\",\n \"ERROR\",\n \"goneat\",\n ),\n ],\n source: \"goneat\",\n };\n }\n\n // Check availability using the detected path directly\n if (!(await isGoneatAvailable(detected))) {\n return {\n valid: false,\n diagnostics: [\n createDiagnostic(\n \"\",\n `goneat binary found at '${detected}' but not executable or version check failed`,\n \"goneat-not-executable\",\n \"ERROR\",\n \"goneat\",\n ),\n ],\n source: \"goneat\",\n };\n }\n\n return new Promise((resolve) => {\n const args = [\n \"schema\",\n \"validate\",\n \"--schema\",\n schemaPath,\n \"--data\",\n dataPath,\n \"--format\",\n \"json\",\n ];\n const proc = spawn(detected, args);\n\n let stdout = \"\";\n let stderr = \"\";\n\n proc.stdout.on(\"data\", (data) => {\n stdout += data.toString();\n });\n\n proc.stderr.on(\"data\", (data) => {\n stderr += data.toString();\n });\n\n proc.on(\"close\", (code: number | null) => {\n // Parse goneat output\n let output: GoneatValidationOutput;\n\n try {\n output = JSON.parse(stdout) as GoneatValidationOutput;\n } catch {\n // Failed to parse output, treat as error\n resolve({\n valid: false,\n diagnostics: [\n createDiagnostic(\n \"\",\n `goneat validation failed: ${stderr || \"unknown error\"}`,\n \"goneat-error\",\n \"ERROR\",\n \"goneat\",\n ),\n ],\n source: \"goneat\",\n });\n return;\n }\n\n // Convert goneat errors to our diagnostic format\n const diagnostics: SchemaValidationDiagnostic[] =\n output.errors?.map((error) =>\n createDiagnostic(\n error.path || \"\",\n error.message,\n error.keyword || \"validation\",\n \"ERROR\",\n \"goneat\",\n ),\n ) || [];\n\n resolve({\n valid: code === 0 && output.valid,\n diagnostics,\n source: \"goneat\",\n });\n });\n\n proc.on(\"error\", (error) => {\n resolve({\n valid: false,\n diagnostics: [\n createDiagnostic(\n \"\",\n `Failed to execute goneat: ${error.message}`,\n \"goneat-spawn-error\",\n \"ERROR\",\n \"goneat\",\n ),\n ],\n source: \"goneat\",\n });\n });\n });\n}\n","/**\n * Schema normalizer - implements schema normalization per Fulmen standard\n *\n * Provides utilities for canonicalizing and comparing schemas across\n * JSON and YAML formats with comment preservation and deterministic output.\n */\n\nimport { parse as parseYAML } from \"yaml\";\nimport { SchemaValidationError } from \"./errors.js\";\nimport type { SchemaInput, SchemaNormalizationOptions } from \"./types.js\";\n\n/**\n * Parse schema input to object\n */\nfunction parseSchemaInput(input: SchemaInput): Record<string, unknown> {\n if (!input) {\n throw SchemaValidationError.parseFailed(\n { type: \"string\", content: \"\" },\n new Error(\"schema content is empty\"),\n );\n }\n\n try {\n if (typeof input === \"string\") {\n // Try JSON first, fall back to YAML\n try {\n return JSON.parse(input) as Record<string, unknown>;\n } catch {\n return parseYAML(input) as Record<string, unknown>;\n }\n }\n\n if (Buffer.isBuffer(input)) {\n const content = input.toString(\"utf-8\");\n try {\n return JSON.parse(content) as Record<string, unknown>;\n } catch {\n return parseYAML(content) as Record<string, unknown>;\n }\n }\n\n // Already an object\n return input as Record<string, unknown>;\n } catch (error) {\n throw SchemaValidationError.parseFailed(\n {\n type: typeof input === \"string\" ? \"string\" : \"object\",\n content: typeof input === \"string\" ? input : JSON.stringify(input),\n },\n error as Error,\n );\n }\n}\n\n/**\n * Sort object keys recursively in lexicographical order\n */\nfunction sortObjectKeys(obj: unknown): unknown {\n if (obj === null || typeof obj !== \"object\") {\n return obj;\n }\n\n if (Array.isArray(obj)) {\n return obj.map(sortObjectKeys);\n }\n\n const sorted: Record<string, unknown> = {};\n const keys = Object.keys(obj).sort();\n\n for (const key of keys) {\n sorted[key] = sortObjectKeys((obj as Record<string, unknown>)[key]);\n }\n\n return sorted;\n}\n\n/**\n * Normalize schema to canonical JSON format\n *\n * Per Fulmen Schema Normalization Standard:\n * - Accepts YAML or JSON input\n * - Strips comments while preserving semantic structure\n * - Sorts keys lexicographically\n * - Produces deterministic, pretty-printed JSON (or compact if requested)\n */\nexport function normalizeSchema(\n input: SchemaInput,\n options: SchemaNormalizationOptions = {},\n): string {\n try {\n // Parse input to object\n const parsed = parseSchemaInput(input);\n\n // Sort keys recursively\n const sorted = sortObjectKeys(parsed);\n\n // Serialize to JSON with optional compact mode\n if (options.compact) {\n return JSON.stringify(sorted);\n }\n\n // Default: pretty-printed with 2-space indentation\n return JSON.stringify(sorted, null, 2);\n } catch (error) {\n if (error instanceof SchemaValidationError) {\n throw error;\n }\n throw SchemaValidationError.parseFailed(\n {\n type: typeof input === \"string\" ? \"string\" : \"object\",\n content: typeof input === \"string\" ? input : JSON.stringify(input),\n },\n error as Error,\n );\n }\n}\n\n/**\n * Compare two schemas for semantic equality\n *\n * Normalizes both schemas and compares the canonical JSON output.\n * Returns equality result along with normalized versions for debugging.\n */\nexport function compareSchemas(\n schemaA: SchemaInput,\n schemaB: SchemaInput,\n options: SchemaNormalizationOptions = {},\n): { equal: boolean; normalizedA: string; normalizedB: string } {\n const normalizedA = normalizeSchema(schemaA, options);\n const normalizedB = normalizeSchema(schemaB, options);\n\n return {\n equal: normalizedA === normalizedB,\n normalizedA,\n normalizedB,\n };\n}\n","/**\n * Schema registry - implements schema discovery and metadata extraction\n */\n\nimport { access, readFile } from \"node:fs/promises\";\nimport { dirname, extname, join, relative } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport glob from \"fast-glob\";\nimport { parse as parseYAML } from \"yaml\";\nimport { SchemaValidationError } from \"./errors.js\";\nimport type { SchemaFormat, SchemaMetadata, SchemaRegistryOptions } from \"./types.js\";\n\n/**\n * Default schema file patterns\n */\nconst DEFAULT_PATTERNS = [\"**/*.schema.json\", \"**/*.schema.yaml\", \"**/*.schema.yml\"];\n\n/**\n * Schema registry class for managing schema discovery and metadata\n */\nexport class SchemaRegistry {\n private schemas: Map<string, SchemaMetadata> = new Map();\n private options: SchemaRegistryOptions;\n\n constructor(options: SchemaRegistryOptions = {}) {\n this.options = {\n baseDir: options.baseDir || this.getDefaultSchemaDir(),\n patterns: options.patterns || DEFAULT_PATTERNS,\n followSymlinks: options.followSymlinks ?? false,\n maxDepth: options.maxDepth ?? 10,\n };\n }\n\n /**\n * Get default schema directory using import.meta.url\n */\n private getDefaultSchemaDir(): string {\n const __filename = fileURLToPath(import.meta.url);\n const __dirname = dirname(__filename);\n // From src/schema/ we need to go up 2 levels to repo root, then into schemas/crucible-ts\n return join(__dirname, \"..\", \"..\", \"schemas\", \"crucible-ts\");\n }\n\n /**\n * Build logical schema ID from file path\n */\n private buildSchemaId(filePath: string, baseDir: string): string {\n const relativePath = relative(baseDir, filePath);\n const withoutExt = relativePath.replace(/\\.(schema\\.(json|yaml|yml))$/, \"\");\n return withoutExt.replace(/\\\\/g, \"/\"); // Normalize path separators\n }\n\n /**\n * Extract schema format from file extension\n */\n private getSchemaFormat(filePath: string): SchemaFormat {\n const ext = extname(filePath).toLowerCase();\n switch (ext) {\n case \".json\":\n return \"json\";\n case \".yaml\":\n case \".yml\":\n return \"yaml\";\n default:\n return \"json\"; // Default fallback\n }\n }\n\n /**\n * Extract metadata from schema file\n */\n private async extractMetadata(filePath: string): Promise<SchemaMetadata> {\n try {\n const content = await readFile(filePath, \"utf-8\");\n const format = this.getSchemaFormat(filePath);\n\n let parsed: Record<string, unknown>;\n if (format === \"yaml\") {\n parsed = parseYAML(content) as Record<string, unknown>;\n } else {\n parsed = JSON.parse(content) as Record<string, unknown>;\n }\n\n const baseDir = this.options.baseDir ?? \"\";\n const relativePath = relative(baseDir, filePath);\n\n return {\n id: this.buildSchemaId(filePath, baseDir),\n path: filePath,\n relativePath: relativePath,\n format,\n version: (parsed.$schema as string) || (parsed.version as string),\n description: (parsed.title as string) || (parsed.description as string),\n schemaDraft: parsed.$schema as string,\n };\n } catch (error) {\n throw SchemaValidationError.registryError(\n \"metadata extraction\",\n `Failed to process ${filePath}: ${(error as Error).message}`,\n );\n }\n }\n\n /**\n * Discover and index all available schemas\n */\n async discoverSchemas(): Promise<void> {\n try {\n const baseDir = this.options.baseDir ?? \"\";\n const patterns = this.options.patterns ?? [];\n\n if (patterns.length === 0) {\n this.schemas.clear();\n return;\n }\n\n const pattern = patterns.map((p) => join(baseDir, p));\n\n // Check if base directory exists\n try {\n await access(baseDir);\n } catch {\n // Base directory doesn't exist, clear registry and return\n this.schemas.clear();\n return;\n }\n\n const files = await glob(pattern, {\n absolute: true,\n followSymbolicLinks: this.options.followSymlinks,\n deep: this.options.maxDepth,\n onlyFiles: true,\n suppressErrors: true, // Don't throw on permission errors\n });\n\n // Clear existing schemas\n this.schemas.clear();\n\n // Process each schema file\n for (const filePath of files) {\n try {\n const metadata = await this.extractMetadata(filePath);\n this.schemas.set(metadata.id, metadata);\n } catch (error) {\n // Log error but continue processing other schemas\n console.warn(`Warning: Failed to process schema ${filePath}:`, error);\n }\n }\n } catch (error) {\n throw SchemaValidationError.registryError(\"discovery\", (error as Error).message);\n }\n }\n\n /**\n * List available schemas with optional prefix filtering\n */\n async listSchemas(prefix?: string): Promise<SchemaMetadata[]> {\n if (this.schemas.size === 0) {\n await this.discoverSchemas();\n }\n\n const schemas = Array.from(this.schemas.values());\n\n if (prefix) {\n return schemas.filter((schema) => schema.id.startsWith(prefix));\n }\n\n return schemas;\n }\n\n /**\n * Get schema by logical ID\n */\n async getSchema(id: string): Promise<SchemaMetadata> {\n if (this.schemas.size === 0) {\n await this.discoverSchemas();\n }\n\n const schema = this.schemas.get(id);\n if (!schema) {\n throw SchemaValidationError.schemaNotFound(id);\n }\n\n return schema;\n }\n\n /**\n * Get schema by file path\n */\n async getSchemaByPath(filePath: string): Promise<SchemaMetadata> {\n if (this.schemas.size === 0) {\n await this.discoverSchemas();\n }\n\n const absolutePath = filePath.startsWith(\"/\") ? filePath : join(process.cwd(), filePath);\n\n for (const schema of this.schemas.values()) {\n if (schema.path === absolutePath) {\n return schema;\n }\n }\n\n throw SchemaValidationError.schemaNotFound(filePath);\n }\n\n /**\n * Check if schema exists\n */\n async hasSchema(id: string): Promise<boolean> {\n if (this.schemas.size === 0) {\n await this.discoverSchemas();\n }\n\n return this.schemas.has(id);\n }\n\n /**\n * Get registry size\n */\n get size(): number {\n return this.schemas.size;\n }\n\n /**\n * Clear registry cache\n */\n clear(): void {\n this.schemas.clear();\n }\n}\n\n/**\n * Global schema registry instance with cached options\n */\nlet globalRegistry: SchemaRegistry | undefined;\nlet globalRegistryOptions: SchemaRegistryOptions | undefined;\n\n/**\n * Check if registry options have changed\n */\nfunction optionsChanged(newOptions?: SchemaRegistryOptions): boolean {\n if (!newOptions && !globalRegistryOptions) return false;\n if (!newOptions || !globalRegistryOptions) return true;\n\n return (\n newOptions.baseDir !== globalRegistryOptions.baseDir ||\n JSON.stringify(newOptions.patterns) !== JSON.stringify(globalRegistryOptions.patterns) ||\n newOptions.followSymlinks !== globalRegistryOptions.followSymlinks ||\n newOptions.maxDepth !== globalRegistryOptions.maxDepth\n );\n}\n\n/**\n * Get or create global schema registry, rebuilding if options change\n */\nexport function getSchemaRegistry(options?: SchemaRegistryOptions): SchemaRegistry {\n if (!globalRegistry || optionsChanged(options)) {\n globalRegistry = new SchemaRegistry(options);\n globalRegistryOptions = options;\n }\n return globalRegistry;\n}\n\n/**\n * List available schemas with optional prefix filtering\n */\nexport async function listSchemas(\n prefix?: string,\n options?: SchemaRegistryOptions,\n): Promise<SchemaMetadata[]> {\n const registry = getSchemaRegistry(options);\n return registry.listSchemas(prefix);\n}\n\n/**\n * Get schema by logical ID\n */\nexport async function getSchema(\n id: string,\n options?: SchemaRegistryOptions,\n): Promise<SchemaMetadata> {\n const registry = getSchemaRegistry(options);\n return registry.getSchema(id);\n}\n\n/**\n * Get schema by file path\n */\nexport async function getSchemaByPath(\n filePath: string,\n options?: SchemaRegistryOptions,\n): Promise<SchemaMetadata> {\n const registry = getSchemaRegistry(options);\n return registry.getSchemaByPath(filePath);\n}\n\n/**\n * Check if schema exists\n */\nexport async function hasSchema(id: string, options?: SchemaRegistryOptions): Promise<boolean> {\n const registry = getSchemaRegistry(options);\n return registry.hasSchema(id);\n}\n","/**\n * Counter metric implementation\n *\n * Monotonically increasing counter for counting events\n */\n\nimport type { MetricName } from \"./types.js\";\n\n/**\n * Counter metric\n *\n * Monotonically increasing value for counting events.\n * Supports labeled metrics (Crucible v0.2.7+).\n * Use for metrics like request counts, error counts, etc.\n */\nexport class Counter {\n private value = 0;\n private labeledValues = new Map<string, number>();\n\n constructor(public readonly name: MetricName) {}\n\n /**\n * Increment counter by delta (default: 1)\n *\n * @param delta - Amount to increment (must be non-negative)\n * @param labels - Optional label dimensions for this observation\n * @throws {Error} If delta is negative\n *\n * @example\n * ```typescript\n * counter.inc(); // Increment unlabeled by 1\n * counter.inc(5); // Increment unlabeled by 5\n * counter.inc(1, { status: '200' }); // Increment labeled instance\n * counter.inc(1, { result: 'success' }); // Different label set\n * ```\n */\n inc(delta = 1, labels?: Record<string, string>): void {\n if (delta < 0) {\n throw new Error(`Counter delta must be non-negative, got: ${delta}`);\n }\n\n if (labels && Object.keys(labels).length > 0) {\n // Labeled metric - track per label combination\n const labelKey = this.serializeLabels(labels);\n const current = this.labeledValues.get(labelKey) || 0;\n this.labeledValues.set(labelKey, current + delta);\n } else {\n // Unlabeled metric\n this.value += delta;\n }\n }\n\n /**\n * Get current counter value (unlabeled)\n */\n getValue(): number {\n return this.value;\n }\n\n /**\n * Get all labeled values\n * @returns Map of serialized label keys to values\n */\n getLabeledValues(): Map<string, number> {\n return new Map(this.labeledValues);\n }\n\n /**\n * Get value for specific label combination\n */\n getValueForLabels(labels: Record<string, string>): number {\n const labelKey = this.serializeLabels(labels);\n return this.labeledValues.get(labelKey) || 0;\n }\n\n /**\n * Reset counter to zero (all label combinations)\n */\n reset(): void {\n this.value = 0;\n this.labeledValues.clear();\n }\n\n /**\n * Serialize labels to deterministic string key\n * Format: key1=value1,key2=value2 (sorted by key)\n */\n private serializeLabels(labels: Record<string, string>): string {\n return Object.entries(labels)\n .sort(([a], [b]) => a.localeCompare(b))\n .map(([k, v]) => `${k}=${v}`)\n .join(\",\");\n }\n}\n","/**\n * Gauge metric implementation\n *\n * Gauge for arbitrary values that can go up and down\n */\n\nimport type { MetricName } from \"./types.js\";\n\n/**\n * Gauge metric\n *\n * Arbitrary value that can increase or decrease.\n * Supports labeled metrics (Crucible v0.2.7+).\n * Use for metrics like current connections, memory usage, temperature, etc.\n */\nexport class Gauge {\n private value = 0;\n private labeledValues = new Map<string, number>();\n\n constructor(public readonly name: MetricName) {}\n\n /**\n * Set gauge to specific value\n *\n * @param value - New gauge value (can be any number, including negative)\n * @param labels - Optional label dimensions for this observation\n *\n * @example\n * ```typescript\n * gauge.set(42); // Set unlabeled to 42\n * gauge.set(-10); // Negative values allowed\n * gauge.set(1, { phase: 'collect' }); // Set labeled instance\n * ```\n */\n set(value: number, labels?: Record<string, string>): void {\n if (labels && Object.keys(labels).length > 0) {\n const labelKey = this.serializeLabels(labels);\n this.labeledValues.set(labelKey, value);\n } else {\n this.value = value;\n }\n }\n\n /**\n * Increment gauge by delta (default: 1)\n *\n * @param delta - Amount to increment (can be negative)\n * @param labels - Optional label dimensions for this observation\n */\n inc(delta = 1, labels?: Record<string, string>): void {\n if (labels && Object.keys(labels).length > 0) {\n const labelKey = this.serializeLabels(labels);\n const current = this.labeledValues.get(labelKey) || 0;\n this.labeledValues.set(labelKey, current + delta);\n } else {\n this.value += delta;\n }\n }\n\n /**\n * Decrement gauge by delta (default: 1)\n *\n * @param delta - Amount to decrement (can be negative)\n * @param labels - Optional label dimensions for this observation\n */\n dec(delta = 1, labels?: Record<string, string>): void {\n if (labels && Object.keys(labels).length > 0) {\n const labelKey = this.serializeLabels(labels);\n const current = this.labeledValues.get(labelKey) || 0;\n this.labeledValues.set(labelKey, current - delta);\n } else {\n this.value -= delta;\n }\n }\n\n /**\n * Get current gauge value (unlabeled)\n */\n getValue(): number {\n return this.value;\n }\n\n /**\n * Get all labeled values\n * @returns Map of serialized label keys to values\n */\n getLabeledValues(): Map<string, number> {\n return new Map(this.labeledValues);\n }\n\n /**\n * Get value for specific label combination\n */\n getValueForLabels(labels: Record<string, string>): number {\n const labelKey = this.serializeLabels(labels);\n return this.labeledValues.get(labelKey) || 0;\n }\n\n /**\n * Reset gauge to zero (all label combinations)\n */\n reset(): void {\n this.value = 0;\n this.labeledValues.clear();\n }\n\n /**\n * Serialize labels to deterministic string key\n * Format: key1=value1,key2=value2 (sorted by key)\n */\n private serializeLabels(labels: Record<string, string>): string {\n return Object.entries(labels)\n .sort(([a], [b]) => a.localeCompare(b))\n .map(([k, v]) => `${k}=${v}`)\n .join(\",\");\n }\n}\n","/**\n * Taxonomy loader for metrics definitions\n *\n * Loads and caches metrics taxonomy from config/crucible-ts/taxonomy/metrics.yaml\n * Provides default histogram buckets per ADR-0007\n */\n\nimport { readFile } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport { parse as parseYaml } from \"yaml\";\nimport type { MetricName, MetricUnit } from \"./types.js\";\n\n/**\n * Metric definition from taxonomy\n */\nexport interface MetricDefinition {\n name: MetricName;\n unit: MetricUnit;\n description: string;\n}\n\n/**\n * Taxonomy structure\n */\nexport interface MetricsTaxonomy {\n version: string;\n defaults: {\n histogram_buckets: {\n ms_metrics: number[];\n };\n };\n metrics: MetricDefinition[];\n}\n\n/**\n * Default histogram buckets for _ms metrics (ADR-0007)\n * [1, 5, 10, 50, 100, 500, 1000, 5000, 10000] milliseconds\n */\nexport const DEFAULT_MS_BUCKETS = [1, 5, 10, 50, 100, 500, 1000, 5000, 10000];\n\n/**\n * Singleton taxonomy loader\n */\nclass TaxonomyLoader {\n private static instance: TaxonomyLoader;\n private taxonomy: MetricsTaxonomy | null = null;\n private loadPromise: Promise<MetricsTaxonomy> | null = null;\n private loadError: Error | null = null;\n\n private constructor() {\n // Private constructor for singleton\n }\n\n /**\n * Get singleton instance\n */\n static getInstance(): TaxonomyLoader {\n if (!TaxonomyLoader.instance) {\n TaxonomyLoader.instance = new TaxonomyLoader();\n }\n return TaxonomyLoader.instance;\n }\n\n /**\n * Load taxonomy from YAML file\n */\n private async load(): Promise<MetricsTaxonomy> {\n if (this.taxonomy !== null) {\n return this.taxonomy;\n }\n\n if (this.loadError !== null) {\n throw this.loadError;\n }\n\n if (this.loadPromise) {\n return this.loadPromise;\n }\n\n this.loadPromise = (async () => {\n try {\n // Resolve path to taxonomy file\n // From src/telemetry/ → ../../config/crucible-ts/taxonomy/metrics.yaml\n const taxonomyPath = join(\n __dirname,\n \"..\",\n \"..\",\n \"config\",\n \"crucible-ts\",\n \"taxonomy\",\n \"metrics.yaml\",\n );\n\n const content = await readFile(taxonomyPath, \"utf-8\");\n this.taxonomy = parseYaml(content) as MetricsTaxonomy;\n\n return this.taxonomy;\n } catch (err) {\n this.loadError = err instanceof Error ? err : new Error(String(err));\n throw new Error(`Failed to load metrics taxonomy: ${this.loadError.message}`);\n }\n })();\n\n return this.loadPromise;\n }\n\n /**\n * Get taxonomy (async)\n */\n async getTaxonomy(): Promise<MetricsTaxonomy> {\n return this.load();\n }\n\n /**\n * Get metric definition by name\n */\n async getMetric(name: MetricName): Promise<MetricDefinition | undefined> {\n const taxonomy = await this.load();\n return taxonomy.metrics.find((m) => m.name === name);\n }\n\n /**\n * Get default unit for metric\n */\n async getDefaultUnit(name: MetricName): Promise<MetricUnit | undefined> {\n const metric = await this.getMetric(name);\n return metric?.unit;\n }\n\n /**\n * Get default histogram buckets for metric\n * Returns ADR-0007 buckets for _ms metrics, undefined for others\n */\n async getDefaultBuckets(name: MetricName): Promise<number[] | undefined> {\n // Check if metric name ends with _ms\n if (name.endsWith(\"_ms\")) {\n const taxonomy = await this.load();\n return taxonomy.defaults.histogram_buckets.ms_metrics;\n }\n return undefined;\n }\n\n /**\n * Check if metric name is valid (exists in taxonomy)\n */\n async isValidMetricName(name: string): Promise<boolean> {\n try {\n const taxonomy = await this.load();\n return taxonomy.metrics.some((m) => m.name === name);\n } catch {\n return false;\n }\n }\n\n /**\n * Reset loader state (for testing)\n * @internal\n */\n static _reset(): void {\n TaxonomyLoader.instance = new TaxonomyLoader();\n }\n}\n\n/**\n * Get metrics taxonomy\n *\n * @returns Promise resolving to taxonomy\n */\nexport async function getTaxonomy(): Promise<MetricsTaxonomy> {\n return TaxonomyLoader.getInstance().getTaxonomy();\n}\n\n/**\n * Get metric definition by name\n *\n * @param name - Metric name\n * @returns Promise resolving to metric definition or undefined\n */\nexport async function getMetric(name: MetricName): Promise<MetricDefinition | undefined> {\n return TaxonomyLoader.getInstance().getMetric(name);\n}\n\n/**\n * Get default unit for metric from taxonomy\n *\n * @param name - Metric name\n * @returns Promise resolving to unit or undefined\n */\nexport async function getDefaultUnit(name: MetricName): Promise<MetricUnit | undefined> {\n return TaxonomyLoader.getInstance().getDefaultUnit(name);\n}\n\n/**\n * Get default histogram buckets for metric\n *\n * Returns ADR-0007 buckets ([1, 5, 10, 50, 100, 500, 1000, 5000, 10000]) for\n * metrics ending with _ms, undefined for others.\n *\n * @param name - Metric name\n * @returns Promise resolving to bucket array or undefined\n *\n * @example\n * ```typescript\n * const buckets = await getDefaultBuckets('config_load_ms');\n * // Returns [1, 5, 10, 50, 100, 500, 1000, 5000, 10000]\n * ```\n */\nexport async function getDefaultBuckets(name: MetricName): Promise<number[] | undefined> {\n return TaxonomyLoader.getInstance().getDefaultBuckets(name);\n}\n\n/**\n * Check if metric name is valid (exists in taxonomy)\n *\n * @param name - Metric name to check\n * @returns Promise resolving to true if valid\n */\nexport async function isValidMetricName(name: string): Promise<boolean> {\n return TaxonomyLoader.getInstance().isValidMetricName(name);\n}\n\n// Export for testing\nexport { TaxonomyLoader };\n","/**\n * Histogram metric implementation\n *\n * Histogram with OTLP-compatible cumulative buckets, auto-applying ADR-0007\n * default buckets for _ms metrics.\n */\n\nimport { DEFAULT_MS_BUCKETS } from \"./taxonomy.js\";\nimport type { HistogramBucket, HistogramOptions, HistogramSummary, MetricName } from \"./types.js\";\n\n/**\n * Labeled histogram state\n */\ninterface LabeledHistogramState {\n count: number;\n sum: number;\n bucketCounts: Map<number, number>;\n}\n\n/**\n * Histogram metric\n *\n * Tracks distribution of values using cumulative buckets (OTLP-compatible).\n * Automatically applies ADR-0007 default buckets for _ms metrics.\n * Supports labeled metrics (Crucible v0.2.7+).\n */\nexport class Histogram {\n private count = 0;\n private sum = 0;\n private bucketCounts: Map<number, number> = new Map();\n private labeledStates = new Map<string, LabeledHistogramState>();\n private readonly buckets: number[];\n\n constructor(\n public readonly name: MetricName,\n options?: HistogramOptions,\n ) {\n // Determine buckets: custom > ADR-0007 defaults for _ms metrics > empty\n if (options?.buckets) {\n this.buckets = [...options.buckets].sort((a, b) => a - b);\n } else if (name.endsWith(\"_ms\") || name.endsWith(\"_seconds\")) {\n this.buckets = [...DEFAULT_MS_BUCKETS];\n } else {\n this.buckets = [];\n }\n\n // Initialize bucket counts\n for (const bucket of this.buckets) {\n this.bucketCounts.set(bucket, 0);\n }\n }\n\n /**\n * Record an observation\n *\n * @param value - Value to observe (typically a duration in ms or seconds)\n * @param labels - Optional label dimensions for this observation\n *\n * @example\n * ```typescript\n * const start = performance.now();\n * // ... operation ...\n * histogram.observe(performance.now() - start);\n * histogram.observe(duration, { phase: 'collect', result: 'success' });\n * ```\n */\n observe(value: number, labels?: Record<string, string>): void {\n if (labels && Object.keys(labels).length > 0) {\n // Labeled observation\n const labelKey = this.serializeLabels(labels);\n let state = this.labeledStates.get(labelKey);\n\n if (!state) {\n // Initialize new labeled state\n state = {\n count: 0,\n sum: 0,\n bucketCounts: new Map(),\n };\n for (const bucket of this.buckets) {\n state.bucketCounts.set(bucket, 0);\n }\n this.labeledStates.set(labelKey, state);\n }\n\n state.count++;\n state.sum += value;\n\n // Update cumulative bucket counts\n for (const bucket of this.buckets) {\n if (value <= bucket) {\n state.bucketCounts.set(bucket, (state.bucketCounts.get(bucket) || 0) + 1);\n }\n }\n } else {\n // Unlabeled observation\n this.count++;\n this.sum += value;\n\n // Update cumulative bucket counts\n for (const bucket of this.buckets) {\n if (value <= bucket) {\n this.bucketCounts.set(bucket, (this.bucketCounts.get(bucket) || 0) + 1);\n }\n }\n }\n }\n\n /**\n * Get histogram summary\n *\n * Returns OTLP-compatible histogram summary with cumulative bucket counts.\n */\n getSummary(): HistogramSummary {\n const buckets: HistogramBucket[] = this.buckets.map((le) => ({\n le,\n count: this.bucketCounts.get(le) || 0,\n }));\n\n return {\n count: this.count,\n sum: this.sum,\n buckets,\n };\n }\n\n /**\n * Get current observation count\n */\n getCount(): number {\n return this.count;\n }\n\n /**\n * Get sum of all observed values\n */\n getSum(): number {\n return this.sum;\n }\n\n /**\n * Get average of observed values\n */\n getAverage(): number {\n return this.count > 0 ? this.sum / this.count : 0;\n }\n\n /**\n * Get all labeled summaries\n * @returns Map of serialized label keys to histogram summaries\n */\n getLabeledSummaries(): Map<string, HistogramSummary> {\n const summaries = new Map<string, HistogramSummary>();\n\n for (const [labelKey, state] of this.labeledStates) {\n const buckets: HistogramBucket[] = this.buckets.map((le) => ({\n le,\n count: state.bucketCounts.get(le) || 0,\n }));\n\n summaries.set(labelKey, {\n count: state.count,\n sum: state.sum,\n buckets,\n });\n }\n\n return summaries;\n }\n\n /**\n * Get summary for specific label combination\n */\n getSummaryForLabels(labels: Record<string, string>): HistogramSummary | null {\n const labelKey = this.serializeLabels(labels);\n const state = this.labeledStates.get(labelKey);\n\n if (!state) {\n return null;\n }\n\n const buckets: HistogramBucket[] = this.buckets.map((le) => ({\n le,\n count: state.bucketCounts.get(le) || 0,\n }));\n\n return {\n count: state.count,\n sum: state.sum,\n buckets,\n };\n }\n\n /**\n * Reset histogram to initial state (all label combinations)\n */\n reset(): void {\n this.count = 0;\n this.sum = 0;\n for (const bucket of this.buckets) {\n this.bucketCounts.set(bucket, 0);\n }\n this.labeledStates.clear();\n }\n\n /**\n * Serialize labels to deterministic string key\n * Format: key1=value1,key2=value2 (sorted by key)\n */\n private serializeLabels(labels: Record<string, string>): string {\n return Object.entries(labels)\n .sort(([a], [b]) => a.localeCompare(b))\n .map(([k, v]) => `${k}=${v}`)\n .join(\",\");\n }\n}\n","/**\n * Metrics registry - central registry for all metrics\n *\n * Provides singleton registry for counters, gauges, and histograms.\n * Exports events in schema-compliant format.\n */\n\nimport { Counter } from \"./counter.js\";\nimport { Gauge } from \"./gauge.js\";\nimport { Histogram } from \"./histogram.js\";\nimport { getDefaultUnit } from \"./taxonomy.js\";\nimport type { FlushOptions, HistogramOptions, MetricName, MetricsEvent } from \"./types.js\";\n\n/**\n * Metrics registry\n *\n * Central registry for all metrics. Provides factory methods for counters,\n * gauges, and histograms. Exports metrics as schema-compliant events.\n */\nexport class MetricsRegistry {\n private counters: Map<MetricName, Counter> = new Map();\n private gauges: Map<MetricName, Gauge> = new Map();\n private histograms: Map<MetricName, Histogram> = new Map();\n\n /**\n * Get or create a counter\n *\n * @param name - Metric name from taxonomy\n * @returns Counter instance\n *\n * @example\n * ```typescript\n * const counter = registry.counter('schema_validations');\n * counter.inc();\n * ```\n */\n counter(name: MetricName): Counter {\n let counter = this.counters.get(name);\n if (!counter) {\n counter = new Counter(name);\n this.counters.set(name, counter);\n }\n return counter;\n }\n\n /**\n * Get or create a gauge\n *\n * @param name - Metric name from taxonomy\n * @returns Gauge instance\n *\n * @example\n * ```typescript\n * const gauge = registry.gauge('foundry_lookup_count');\n * gauge.set(42);\n * ```\n */\n gauge(name: MetricName): Gauge {\n let gauge = this.gauges.get(name);\n if (!gauge) {\n gauge = new Gauge(name);\n this.gauges.set(name, gauge);\n }\n return gauge;\n }\n\n /**\n * Get or create a histogram\n *\n * @param name - Metric name from taxonomy\n * @param options - Optional histogram options\n * @returns Histogram instance\n *\n * @example\n * ```typescript\n * // Auto-applies ADR-0007 buckets for _ms metrics\n * const histogram = registry.histogram('config_load_ms');\n * histogram.observe(42.5);\n *\n * // Custom buckets\n * const custom = registry.histogram('custom_metric', {\n * buckets: [10, 50, 100, 500, 1000]\n * });\n * ```\n */\n histogram(name: MetricName, options?: HistogramOptions): Histogram {\n let histogram = this.histograms.get(name);\n if (!histogram) {\n histogram = new Histogram(name, options);\n this.histograms.set(name, histogram);\n }\n return histogram;\n }\n\n /**\n * Export all metrics as events\n *\n * Returns array of schema-compliant MetricsEvent objects.\n * Does not clear metrics (use flush() to clear after export).\n *\n * @returns Promise resolving to array of metrics events\n *\n * @example\n * ```typescript\n * const events = await registry.export();\n * console.log(JSON.stringify(events, null, 2));\n * ```\n */\n async export(): Promise<MetricsEvent[]> {\n const events: MetricsEvent[] = [];\n const timestamp = new Date().toISOString();\n\n // Export counters (unlabeled + labeled) - Crucible v0.2.7+\n for (const [name, counter] of this.counters) {\n const unit = await getDefaultUnit(name);\n\n // Always export unlabeled value (for backwards compatibility)\n events.push({\n timestamp,\n name,\n value: counter.getValue(),\n unit,\n });\n\n // Export labeled values (only if > 0)\n for (const [labelKey, value] of counter.getLabeledValues()) {\n if (value > 0) {\n const tags = this.deserializeLabels(labelKey);\n events.push({\n timestamp,\n name,\n value,\n tags,\n unit,\n });\n }\n }\n }\n\n // Export gauges (unlabeled + labeled) - Crucible v0.2.7+\n for (const [name, gauge] of this.gauges) {\n const unit = await getDefaultUnit(name);\n\n // Export unlabeled value (always export gauges, even if zero)\n events.push({\n timestamp,\n name,\n value: gauge.getValue(),\n unit,\n });\n\n // Export labeled values\n for (const [labelKey, value] of gauge.getLabeledValues()) {\n const tags = this.deserializeLabels(labelKey);\n events.push({\n timestamp,\n name,\n value,\n tags,\n unit,\n });\n }\n }\n\n // Export histograms (unlabeled + labeled) - Crucible v0.2.7+\n for (const [name, histogram] of this.histograms) {\n const unit = await getDefaultUnit(name);\n\n // Always export unlabeled summary (for backwards compatibility)\n events.push({\n timestamp,\n name,\n value: histogram.getSummary(),\n unit,\n });\n\n // Export labeled summaries (only if count > 0)\n for (const [labelKey, summary] of histogram.getLabeledSummaries()) {\n if (summary.count > 0) {\n const tags = this.deserializeLabels(labelKey);\n events.push({\n timestamp,\n name,\n value: summary,\n tags,\n unit,\n });\n }\n }\n }\n\n return events;\n }\n\n /**\n * Deserialize label key back to tags object\n * Format: key1=value1,key2=value2 → {key1: \"value1\", key2: \"value2\"}\n */\n private deserializeLabels(labelKey: string): Record<string, string> {\n if (!labelKey) {\n return {};\n }\n\n const tags: Record<string, string> = {};\n for (const pair of labelKey.split(\",\")) {\n const [key, value] = pair.split(\"=\");\n if (key && value) {\n tags[key] = value;\n }\n }\n return tags;\n }\n\n /**\n * Export and clear all metrics\n *\n * Exports metrics as events, optionally emits them via logger,\n * then resets all metrics to zero.\n *\n * @param options - Flush options\n * @returns Promise resolving to array of exported events\n *\n * @example\n * ```typescript\n * // Export and clear\n * const events = await registry.flush();\n *\n * // Export, emit to logger, and clear\n * const events = await registry.flush({\n * emit: (events) => console.log(JSON.stringify(events))\n * });\n * ```\n */\n async flush(options?: FlushOptions): Promise<MetricsEvent[]> {\n const events = await this.export();\n\n try {\n // Emit if logger provided\n if (options?.emit) {\n options.emit(events);\n }\n } finally {\n // Always clear metrics, even if emit throws\n this.clear();\n }\n\n return events;\n }\n\n /**\n * Clear all metrics (reset to zero)\n *\n * Resets all counters, gauges, and histograms to their initial state.\n */\n clear(): void {\n for (const counter of this.counters.values()) {\n counter.reset();\n }\n for (const gauge of this.gauges.values()) {\n gauge.reset();\n }\n for (const histogram of this.histograms.values()) {\n histogram.reset();\n }\n }\n\n /**\n * Get all registered metric names\n *\n * Returns array of all metric names that have been accessed\n * (counters, gauges, or histograms).\n */\n getMetricNames(): MetricName[] {\n const names = new Set<MetricName>();\n for (const name of this.counters.keys()) {\n names.add(name);\n }\n for (const name of this.gauges.keys()) {\n names.add(name);\n }\n for (const name of this.histograms.keys()) {\n names.add(name);\n }\n return Array.from(names);\n }\n\n /**\n * Get total count of registered metrics\n */\n getMetricCount(): number {\n return this.counters.size + this.gauges.size + this.histograms.size;\n }\n}\n","/**\n * Telemetry types - TypeScript types for metrics events\n *\n * Based on schemas/crucible-ts/observability/metrics/v1.0.0/metrics-event.schema.json\n * and config/crucible-ts/taxonomy/metrics.yaml\n */\n\n/**\n * Metric name from taxonomy\n * Aligned with config/crucible-ts/taxonomy/metrics.yaml#/$defs/metricName\n * Updated for Crucible v0.2.18 (HTTP server metrics)\n */\nexport type MetricName =\n // Core module metrics\n | \"schema_validations\"\n | \"schema_validation_errors\"\n | \"config_load_ms\"\n | \"config_load_errors\"\n | \"pathfinder_find_ms\"\n | \"pathfinder_validation_errors\"\n | \"pathfinder_security_warnings\"\n | \"foundry_lookup_count\"\n | \"logging_emit_count\"\n | \"logging_emit_latency_ms\"\n | \"goneat_command_duration_ms\"\n // Prometheus exporter metrics\n | \"prometheus_exporter_refresh_duration_seconds\"\n | \"prometheus_exporter_refresh_total\"\n | \"prometheus_exporter_refresh_errors_total\"\n | \"prometheus_exporter_refresh_inflight\"\n | \"prometheus_exporter_http_requests_total\"\n | \"prometheus_exporter_http_errors_total\"\n | \"prometheus_exporter_restarts_total\"\n // Foundry MIME detection metrics\n | \"foundry_mime_detections_total_json\"\n | \"foundry_mime_detections_total_xml\"\n | \"foundry_mime_detections_total_yaml\"\n | \"foundry_mime_detections_total_csv\"\n | \"foundry_mime_detections_total_plain_text\"\n | \"foundry_mime_detections_total_unknown\"\n | \"foundry_mime_detection_ms_json\"\n | \"foundry_mime_detection_ms_xml\"\n | \"foundry_mime_detection_ms_yaml\"\n | \"foundry_mime_detection_ms_csv\"\n | \"foundry_mime_detection_ms_plain_text\"\n | \"foundry_mime_detection_ms_unknown\"\n // Error handling metrics\n | \"error_handling_wraps_total\"\n | \"error_handling_wrap_ms\"\n // FulHash metrics\n | \"fulhash_operations_total_xxh3_128\"\n | \"fulhash_operations_total_sha256\"\n | \"fulhash_hash_string_total\"\n | \"fulhash_bytes_hashed_total\"\n | \"fulhash_operation_ms\"\n // HTTP server metrics (v0.2.18)\n | \"http_requests_total\"\n | \"http_request_duration_seconds\"\n | \"http_request_size_bytes\"\n | \"http_response_size_bytes\"\n | \"http_active_requests\";\n\n/**\n * Metric unit from taxonomy\n * Aligned with config/crucible-ts/taxonomy/metrics.yaml#/$defs/metricUnit\n * Updated for Crucible v0.2.7 (adds 's' for seconds)\n */\nexport type MetricUnit = \"count\" | \"ms\" | \"bytes\" | \"percent\" | \"s\";\n\n/**\n * Histogram bucket for OTLP-compatible histograms\n */\nexport interface HistogramBucket {\n /** Upper bound (less-than-or-equal) for the bucket */\n le: number;\n /** Cumulative count up to and including this bucket */\n count: number;\n}\n\n/**\n * Histogram summary payload\n */\nexport interface HistogramSummary {\n /** Total count of observations */\n count: number;\n /** Sum of all observed values */\n sum: number;\n /** Ordered buckets with cumulative counts (OTLP-compatible) */\n buckets: HistogramBucket[];\n}\n\n/**\n * Metric value (scalar or histogram)\n */\nexport type MetricValue = number | HistogramSummary;\n\n/**\n * Metrics event structure\n * Aligned with schemas/crucible-ts/observability/metrics/v1.0.0/metrics-event.schema.json\n */\nexport interface MetricsEvent {\n /** RFC3339 timestamp of metric emission */\n timestamp: string;\n /** Metric identifier from taxonomy */\n name: MetricName;\n /** Measurement payload (scalar or histogram summary) */\n value: MetricValue;\n /** Optional key/value dimensions */\n tags?: Record<string, string>;\n /** Optional metric unit (defaults to taxonomy default) */\n unit?: MetricUnit;\n}\n\n/**\n * Histogram options for customization\n */\nexport interface HistogramOptions {\n /** Custom bucket boundaries (overrides default ADR-0007 buckets) */\n buckets?: number[];\n}\n\n/**\n * Flush options for metrics registry\n */\nexport interface FlushOptions {\n /** Optional logger function to emit metrics */\n emit?: (events: MetricsEvent[]) => void;\n}\n\n/**\n * Type guard to check if value is a histogram summary\n */\nexport function isHistogramSummary(value: unknown): value is HistogramSummary {\n return (\n typeof value === \"object\" &&\n value !== null &&\n \"count\" in value &&\n \"sum\" in value &&\n \"buckets\" in value\n );\n}\n\n/**\n * Type guard to check if metric name is valid\n * Aligned with Crucible v0.2.18 taxonomy\n */\nexport function isValidMetricName(name: string): name is MetricName {\n const validNames: MetricName[] = [\n // Core module metrics\n \"schema_validations\",\n \"schema_validation_errors\",\n \"config_load_ms\",\n \"config_load_errors\",\n \"pathfinder_find_ms\",\n \"pathfinder_validation_errors\",\n \"pathfinder_security_warnings\",\n \"foundry_lookup_count\",\n \"logging_emit_count\",\n \"logging_emit_latency_ms\",\n \"goneat_command_duration_ms\",\n // Prometheus exporter metrics\n \"prometheus_exporter_refresh_duration_seconds\",\n \"prometheus_exporter_refresh_total\",\n \"prometheus_exporter_refresh_errors_total\",\n \"prometheus_exporter_refresh_inflight\",\n \"prometheus_exporter_http_requests_total\",\n \"prometheus_exporter_http_errors_total\",\n \"prometheus_exporter_restarts_total\",\n // Foundry MIME detection metrics\n \"foundry_mime_detections_total_json\",\n \"foundry_mime_detections_total_xml\",\n \"foundry_mime_detections_total_yaml\",\n \"foundry_mime_detections_total_csv\",\n \"foundry_mime_detections_total_plain_text\",\n \"foundry_mime_detections_total_unknown\",\n \"foundry_mime_detection_ms_json\",\n \"foundry_mime_detection_ms_xml\",\n \"foundry_mime_detection_ms_yaml\",\n \"foundry_mime_detection_ms_csv\",\n \"foundry_mime_detection_ms_plain_text\",\n \"foundry_mime_detection_ms_unknown\",\n // Error handling metrics\n \"error_handling_wraps_total\",\n \"error_handling_wrap_ms\",\n // FulHash metrics\n \"fulhash_operations_total_xxh3_128\",\n \"fulhash_operations_total_sha256\",\n \"fulhash_hash_string_total\",\n \"fulhash_bytes_hashed_total\",\n \"fulhash_operation_ms\",\n // HTTP server metrics\n \"http_requests_total\",\n \"http_request_duration_seconds\",\n \"http_request_size_bytes\",\n \"http_response_size_bytes\",\n \"http_active_requests\",\n ];\n return validNames.includes(name as MetricName);\n}\n\n/**\n * Type guard to check if unit is valid\n */\nexport function isValidMetricUnit(unit: string): unit is MetricUnit {\n const validUnits: MetricUnit[] = [\"count\", \"ms\", \"bytes\", \"percent\", \"s\"];\n return validUnits.includes(unit as MetricUnit);\n}\n","/**\n * Metrics event validators\n *\n * Schema validation for metrics events using existing src/schema infrastructure\n */\n\nimport { compileSchemaById } from \"../schema/index.js\";\nimport type { CompiledValidator } from \"../schema/types.js\";\n\n/**\n * Singleton validator for metrics events\n *\n * Pre-compiles the metrics-event schema at first access for optimal performance.\n * Reuses existing AJV setup from src/schema module.\n */\nclass MetricsValidator {\n private static instance: MetricsValidator;\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(): MetricsValidator {\n if (!MetricsValidator.instance) {\n MetricsValidator.instance = new MetricsValidator();\n }\n return MetricsValidator.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 // Compile schema using existing schema infrastructure\n this.validateFn = await compileSchemaById(\"observability/metrics/v1.0.0/metrics-event\");\n } catch (err) {\n this.initError = err instanceof Error ? err : new Error(String(err));\n throw new Error(`Failed to initialize metrics validator: ${this.initError.message}`);\n }\n })();\n\n return this.initPromise;\n }\n\n /**\n * Validate metrics event against schema\n *\n * @param event - Metrics event to validate\n * @returns Promise resolving to true if valid, false otherwise\n */\n async validate(event: 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(event);\n }\n\n /**\n * Get validation errors from last validation\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 MetricsValidator.instance = new MetricsValidator();\n }\n}\n\n/**\n * Validate metrics event against schema\n *\n * Uses pre-compiled validator singleton for optimal performance.\n *\n * @param event - Metrics event to validate\n * @returns Promise resolving to true if valid\n *\n * @example\n * ```typescript\n * const event: MetricsEvent = {\n * timestamp: new Date().toISOString(),\n * name: 'schema_validations',\n * value: 42\n * };\n *\n * if (await validateMetricsEvent(event)) {\n * // Event is schema-compliant\n * } else {\n * const errors = getValidationErrors();\n * console.error('Validation failed:', errors);\n * }\n * ```\n */\nexport async function validateMetricsEvent(event: unknown): Promise<boolean> {\n return MetricsValidator.getInstance().validate(event);\n}\n\n/**\n * Validate array of metrics events\n *\n * @param events - Array of metrics events\n * @returns Promise resolving to true if all valid\n */\nexport async function validateMetricsEvents(events: unknown[]): Promise<boolean> {\n for (const event of events) {\n if (!(await validateMetricsEvent(event))) {\n return false;\n }\n }\n return true;\n}\n\n/**\n * Get validation errors from last validation\n */\nexport function getValidationErrors() {\n return MetricsValidator.getInstance().getErrors();\n}\n\n/**\n * Format validation errors as human-readable string\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 * Assert that metrics event is valid (throws if not)\n *\n * @param event - Metrics event to validate\n * @throws {Error} If validation fails\n */\nexport async function assertValidMetricsEvent(event: unknown): Promise<void> {\n if (!(await validateMetricsEvent(event))) {\n const errors = getValidationErrors();\n const message = errors ? formatValidationErrors(errors) : \"Metrics event validation failed\";\n throw new Error(`Invalid metrics event: ${message}`);\n }\n}\n\n// Export for testing\nexport { MetricsValidator };\n","/**\n * Telemetry module - metrics collection and export\n *\n * Provides counter, gauge, and histogram metrics with schema validation\n * and taxonomy-based defaults (ADR-0007).\n */\n\nexport const VERSION = \"1.0.0\";\n\n// Core registry and singleton\nexport { MetricsRegistry } from \"./registry.js\";\n\nimport { MetricsRegistry } from \"./registry.js\";\n\n/**\n * Default singleton metrics registry\n *\n * Use this for application-wide metrics collection.\n *\n * @example\n * ```typescript\n * import { metrics } from '@fulmenhq/tsfulmen/telemetry';\n *\n * // Increment counter\n * metrics.counter('schema_validations').inc();\n *\n * // Record histogram observation\n * metrics.histogram('config_load_ms').observe(42.5);\n *\n * // Export all metrics\n * const events = await metrics.export();\n * ```\n */\nexport const metrics = new MetricsRegistry();\n\n// Metric types\nexport { Counter } from \"./counter.js\";\nexport { Gauge } from \"./gauge.js\";\nexport { Histogram } from \"./histogram.js\";\n// Taxonomy\nexport type { MetricDefinition, MetricsTaxonomy } from \"./taxonomy.js\";\nexport {\n DEFAULT_MS_BUCKETS,\n getDefaultBuckets,\n getDefaultUnit,\n getMetric,\n getTaxonomy,\n isValidMetricName as isValidMetricNameTaxonomy,\n} from \"./taxonomy.js\";\n// Types\nexport type {\n FlushOptions,\n HistogramBucket,\n HistogramOptions,\n HistogramSummary,\n MetricName,\n MetricsEvent,\n MetricUnit,\n MetricValue,\n} from \"./types.js\";\nexport {\n isHistogramSummary,\n isValidMetricName,\n isValidMetricUnit,\n} from \"./types.js\";\n\n// Validators\nexport {\n assertValidMetricsEvent,\n formatValidationErrors,\n getValidationErrors,\n validateMetricsEvent,\n validateMetricsEvents,\n} from \"./validators.js\";\n","/**\n * Schema validator - implements AJV-based schema validation with goneat integration\n */\n\nimport { readFile } from \"node:fs/promises\";\nimport { dirname, join } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport type { AnySchema } from \"ajv\";\nimport Ajv from \"ajv\";\nimport Ajv2019 from \"ajv/dist/2019.js\";\nimport Ajv2020 from \"ajv/dist/2020.js\";\nimport AjvDraft04 from \"ajv-draft-04\";\nimport { parse as parseYAML } from \"yaml\";\nimport { metrics } from \"../telemetry/index.js\";\nimport { applyFulmenAjvFormats } from \"./ajv-formats.js\";\nimport { SchemaValidationError } from \"./errors.js\";\nimport { getSchemaRegistry } from \"./registry.js\";\nimport type {\n CompiledValidator,\n SchemaInput,\n SchemaRegistryOptions,\n SchemaValidationResult,\n} from \"./types.js\";\nimport { createDiagnostic } from \"./utils.js\";\n\n/**\n * Supported JSON Schema dialects for meta validation + compilation.\n */\ntype JsonSchemaDialect = \"draft-04\" | \"draft-06\" | \"draft-07\" | \"draft-2019-09\" | \"draft-2020-12\";\n\n/**\n * AJV instances by dialect\n */\nconst ajvInstances = new Map<JsonSchemaDialect, Ajv>();\n\n/**\n * Metaschema initialization promises by dialect\n */\nconst metaschemaReady = new Map<JsonSchemaDialect, Promise<void>>();\n\n/**\n * Schema cache for compiled validators\n */\nconst schemaCache = new Map<string, CompiledValidator>();\n\n/**\n * Load metaschema from Crucible SSOT\n */\nasync function loadMetaSchema(draft: JsonSchemaDialect): Promise<Record<string, unknown>> {\n const __filename = fileURLToPath(import.meta.url);\n const __dirname = dirname(__filename);\n const metaSchemaPath = join(\n __dirname,\n \"..\",\n \"..\",\n \"schemas\",\n \"crucible-ts\",\n \"meta\",\n draft,\n \"schema.json\",\n );\n\n const content = await readFile(metaSchemaPath, \"utf-8\");\n return JSON.parse(content) as Record<string, unknown>;\n}\n\n/**\n * Load vocabulary schemas (draft 2019-09 / 2020-12)\n */\nasync function loadVocabularySchemas(draft: JsonSchemaDialect): Promise<Record<string, unknown>[]> {\n if (draft !== \"draft-2019-09\" && draft !== \"draft-2020-12\") {\n return [];\n }\n\n const __filename = fileURLToPath(import.meta.url);\n const __dirname = dirname(__filename);\n const vocabDir = join(__dirname, \"..\", \"..\", \"schemas\", \"crucible-ts\", \"meta\", draft, \"meta\");\n\n const vocabFiles =\n draft === \"draft-2020-12\"\n ? [\n \"core.json\",\n \"applicator.json\",\n \"unevaluated.json\",\n \"validation.json\",\n \"meta-data.json\",\n \"format-annotation.json\",\n \"content.json\",\n ]\n : [\n \"core.json\",\n \"applicator.json\",\n \"validation.json\",\n \"meta-data.json\",\n \"format.json\",\n \"content.json\",\n ];\n\n const schemas: Record<string, unknown>[] = [];\n for (const file of vocabFiles) {\n try {\n const content = await readFile(join(vocabDir, file), \"utf-8\");\n schemas.push(JSON.parse(content) as Record<string, unknown>);\n } catch {\n // Vocabulary schema not found, skip\n }\n }\n\n return schemas;\n}\n\n/**\n * Load referenced schemas (including YAML files) for AJV\n *\n * Resolves relative paths from schemas/ and config/ directories.\n * Handles both relative paths and https://schemas.fulmenhq.dev URIs.\n *\n * Per Canonical URI Resolution Standard (v0.4.2+), crucible-hosted schemas use:\n * https://schemas.fulmenhq.dev/crucible/<topic>/<version>/<filename>\n *\n * We only embed crucible schemas locally. Other modules (goneat/, enact/, etc.)\n * are not embedded and cannot be resolved offline.\n */\nasync function loadReferencedSchema(uri: string): Promise<Record<string, unknown>> {\n const __filename = fileURLToPath(import.meta.url);\n const __dirname = dirname(__filename);\n const repoRoot = join(__dirname, \"..\", \"..\");\n\n let resolvedPath: string;\n\n // Handle https://schemas.fulmenhq.dev/ URIs - map to local files\n if (uri.startsWith(\"https://schemas.fulmenhq.dev/\")) {\n let relativePath = uri.replace(\"https://schemas.fulmenhq.dev/\", \"\");\n\n // Strip crucible/ module prefix if present (v0.4.2+ canonical URIs)\n // We only embed crucible schemas - other modules cannot be resolved locally\n if (relativePath.startsWith(\"crucible/\")) {\n relativePath = relativePath.slice(\"crucible/\".length);\n }\n\n // Check if it's a config taxonomy reference\n if (relativePath.startsWith(\"config/taxonomy/\")) {\n resolvedPath = join(\n repoRoot,\n \"config\",\n \"crucible-ts\",\n \"taxonomy\",\n relativePath.split(\"/\").pop() || \"\",\n );\n } else {\n // Schema reference - map to schemas/crucible-ts/\n resolvedPath = join(repoRoot, \"schemas\", \"crucible-ts\", relativePath);\n }\n }\n // Handle relative paths (e.g., \"../../../../config/taxonomy/metrics.yaml\")\n else if (uri.startsWith(\"../../\") || uri.startsWith(\"../\")) {\n // Resolve relative to schemas/crucible-ts/observability/metrics/v1.0.0/\n // (where metrics-event.schema.json is located)\n const schemaBase = join(\n repoRoot,\n \"schemas\",\n \"crucible-ts\",\n \"observability\",\n \"metrics\",\n \"v1.0.0\",\n );\n resolvedPath = join(schemaBase, uri);\n }\n // Handle file:// URIs\n else if (uri.startsWith(\"file://\")) {\n resolvedPath = fileURLToPath(uri);\n }\n // Unhandled URI scheme\n else {\n throw new Error(`Cannot load remote schema: ${uri}`);\n }\n\n // Read and parse the file\n const content = await readFile(resolvedPath, \"utf-8\");\n const ext = resolvedPath.split(\".\").pop()?.toLowerCase();\n\n if (ext === \"yaml\" || ext === \"yml\") {\n return parseYAML(content) as Record<string, unknown>;\n }\n return JSON.parse(content) as Record<string, unknown>;\n}\n\n/**\n * Resolve JSON Schema dialect from schema content.\n */\nfunction detectDialect(schema: unknown): JsonSchemaDialect {\n if (schema && typeof schema === \"object\" && !Array.isArray(schema)) {\n const maybeSchema = schema as Record<string, unknown>;\n const declared = (maybeSchema as { $schema?: unknown }).$schema;\n\n if (typeof declared === \"string\") {\n if (declared.includes(\"draft-04\")) return \"draft-04\";\n if (declared.includes(\"draft-06\")) return \"draft-06\";\n if (declared.includes(\"draft-07\")) return \"draft-07\";\n if (declared.includes(\"draft/2019-09\")) return \"draft-2019-09\";\n if (declared.includes(\"draft/2020-12\")) return \"draft-2020-12\";\n }\n }\n\n // Default to 2020-12 in Fulmen ecosystem.\n return \"draft-2020-12\";\n}\n\n/**\n * Create AJV instance for a specific dialect\n */\nfunction createAjv(dialect: JsonSchemaDialect): Ajv {\n const AjvCtor =\n dialect === \"draft-2020-12\"\n ? Ajv2020\n : dialect === \"draft-2019-09\"\n ? Ajv2019\n : dialect === \"draft-04\"\n ? (AjvDraft04 as unknown as typeof Ajv)\n : Ajv;\n\n const ajv = new AjvCtor({\n strict: false,\n allErrors: true,\n verbose: true,\n // Allow schemas with $id to be added without replacing existing ones\n addUsedSchema: false,\n // draft-04 uses \"id\"; later drafts use \"$id\"\n schemaId: dialect === \"draft-04\" ? \"id\" : \"$id\",\n // Enable async schema loading for YAML references\n loadSchema: loadReferencedSchema,\n });\n\n applyFulmenAjvFormats(ajv);\n\n return ajv;\n}\n\n/**\n * Get or create AJV instance for a dialect, ensuring metaschemas are loaded.\n */\nasync function getAjv(dialect: JsonSchemaDialect): Promise<Ajv> {\n const existing = ajvInstances.get(dialect);\n if (existing) {\n const ready = metaschemaReady.get(dialect);\n if (ready) await ready;\n return existing;\n }\n\n const ajv = createAjv(dialect);\n ajvInstances.set(dialect, ajv);\n\n const readyPromise = Promise.all([loadVocabularySchemas(dialect), loadMetaSchema(dialect)])\n .then(([vocabSchemas, metaSchema]) => {\n // Add vocabulary schemas first (referenced by meta schema)\n for (const vocabSchema of vocabSchemas) {\n try {\n ajv.addMetaSchema(vocabSchema);\n } catch {\n // Already added or incompatible with Ajv's built-ins\n }\n }\n\n try {\n ajv.addMetaSchema(metaSchema);\n } catch {\n // Already added or incompatible with Ajv's built-ins\n }\n })\n .catch((error) => {\n throw new Error(`Failed to load metaschemas (${dialect}): ${error}`);\n });\n\n metaschemaReady.set(dialect, readyPromise);\n await readyPromise;\n\n return ajv;\n}\n\n/**\n * Compile a schema for validation\n */\nexport async function compileSchema(\n schema: SchemaInput,\n options: { aliases?: string[] } = {},\n): Promise<CompiledValidator> {\n const baseKey = typeof schema === \"string\" ? schema : JSON.stringify(schema);\n\n let parsedSchema: unknown;\n if (typeof schema === \"string\") {\n try {\n parsedSchema = JSON.parse(schema);\n } catch {\n // Try YAML if JSON parsing fails\n parsedSchema = parseYAML(schema);\n }\n } else if (Buffer.isBuffer(schema)) {\n const content = schema.toString(\"utf-8\");\n try {\n parsedSchema = JSON.parse(content);\n } catch {\n parsedSchema = parseYAML(content);\n }\n } else {\n parsedSchema = schema;\n }\n\n const dialect = detectDialect(parsedSchema);\n const ajv = await getAjv(dialect);\n\n const cacheKey = `${dialect}:${baseKey}`;\n const cached = schemaCache.get(cacheKey);\n if (cached !== undefined) {\n return cached;\n }\n\n try {\n // Register schema aliases (e.g., alternate $id values) before compile to support relative refs\n if (options.aliases && options.aliases.length > 0) {\n for (const alias of options.aliases) {\n if (alias && ajv.getSchema(alias) === undefined) {\n try {\n if (typeof parsedSchema === \"object\" && parsedSchema !== null) {\n ajv.addSchema(parsedSchema as Record<string, unknown>, alias);\n }\n } catch {\n // Ignore if alias already registered or invalid\n }\n }\n }\n }\n\n const validator =\n typeof parsedSchema === \"boolean\"\n ? ajv.compile(parsedSchema)\n : await ajv.compileAsync(parsedSchema as Record<string, unknown>);\n\n // Cache the compiled validator\n schemaCache.set(cacheKey, validator as CompiledValidator);\n\n return validator as CompiledValidator;\n } catch (error) {\n throw SchemaValidationError.parseFailed(\n {\n type: \"string\",\n content: typeof schema === \"string\" ? schema : JSON.stringify(schema),\n },\n error as Error,\n );\n }\n}\n\n/**\n * Validate data against a compiled schema\n */\nexport function validateData(data: unknown, validator: CompiledValidator): SchemaValidationResult {\n const valid = validator(data);\n\n const result: SchemaValidationResult = {\n valid,\n diagnostics: [],\n source: \"ajv\",\n };\n\n if (!valid && validator.errors) {\n const errors = validator.errors;\n if (Array.isArray(errors)) {\n result.diagnostics = errors.map((error) =>\n createDiagnostic(\n error.instancePath || \"\",\n error.message || \"Validation failed\",\n error.keyword || \"unknown\",\n \"ERROR\",\n \"ajv\",\n ),\n );\n }\n metrics.counter(\"schema_validation_errors\").inc();\n } else {\n metrics.counter(\"schema_validations\").inc();\n }\n\n return result;\n}\n\n/**\n * Validate file against a schema\n */\nexport async function validateFile(\n filePath: string,\n validator: CompiledValidator,\n): Promise<SchemaValidationResult> {\n try {\n const content = await readFile(filePath, \"utf-8\");\n let data: unknown;\n\n try {\n data = JSON.parse(content);\n } catch {\n // Try YAML if JSON parsing fails\n data = parseYAML(content);\n }\n\n return validateData(data, validator);\n } catch (error) {\n if (error instanceof SchemaValidationError) {\n throw error;\n }\n throw SchemaValidationError.validationFailed(\n filePath,\n [\n createDiagnostic(\n \"\",\n `Failed to read or parse file: ${(error as Error).message}`,\n \"file-read\",\n \"ERROR\",\n \"ajv\",\n ),\n ],\n { type: \"file\", id: filePath },\n );\n }\n}\n\n/**\n * Validate a schema document itself\n */\nexport async function validateSchema(schema: SchemaInput): Promise<SchemaValidationResult> {\n try {\n // Parse schema so we can both meta-validate and compile with dialect-specific Ajv.\n let parsedSchema: unknown;\n if (typeof schema === \"string\") {\n try {\n parsedSchema = JSON.parse(schema);\n } catch {\n parsedSchema = parseYAML(schema);\n }\n } else if (Buffer.isBuffer(schema)) {\n const content = schema.toString(\"utf-8\");\n try {\n parsedSchema = JSON.parse(content);\n } catch {\n parsedSchema = parseYAML(content);\n }\n } else {\n parsedSchema = schema;\n }\n\n const dialect = detectDialect(parsedSchema);\n const ajv = await getAjv(dialect);\n\n // 1) Meta validation against declared dialect\n const metaValid = ajv.validateSchema(parsedSchema as AnySchema);\n if (!metaValid && ajv.errors) {\n const diagnostics = ajv.errors.map((error) =>\n createDiagnostic(\n error.instancePath || \"\",\n error.message || \"Schema meta-validation failed\",\n error.keyword || \"unknown\",\n \"ERROR\",\n \"ajv\",\n ),\n );\n\n return { valid: false, diagnostics, source: \"ajv\" };\n }\n\n // 2) Compilation check (refs resolvable, keywords supported)\n await compileSchema(parsedSchema as SchemaInput);\n\n return {\n valid: true,\n diagnostics: [],\n source: \"ajv\",\n };\n } catch (error) {\n if (error instanceof SchemaValidationError) {\n return {\n valid: false,\n diagnostics: error.diagnostics,\n source: \"ajv\",\n };\n }\n\n return {\n valid: false,\n diagnostics: [\n createDiagnostic(\n \"\",\n `Schema validation failed: ${(error as Error).message}`,\n \"schema-validation\",\n \"ERROR\",\n \"ajv\",\n ),\n ],\n source: \"ajv\",\n };\n }\n}\n\n/**\n * Clear schema cache\n */\nexport function clearCache(): void {\n schemaCache.clear();\n // Keep Ajv instances cached; they hold metaschemas. Tests can still clear schema cache.\n}\n\n/**\n * Get schema cache size\n */\nexport function getCacheSize(): number {\n return schemaCache.size;\n}\n\n/**\n * Load schema by ID from registry and compile\n */\nexport async function compileSchemaById(\n schemaId: string,\n registryOptions?: SchemaRegistryOptions,\n): Promise<CompiledValidator> {\n try {\n const registry = getSchemaRegistry(registryOptions);\n const metadata = await registry.getSchema(schemaId);\n\n const content = await readFile(metadata.path, \"utf-8\");\n const aliases: string[] = [];\n\n const normalizedRelativePath = metadata.relativePath.replace(/\\\\/g, \"/\");\n if (normalizedRelativePath) {\n // Per Canonical URI Resolution Standard (v0.4.2+), include crucible/ module prefix\n aliases.push(\n new URL(`crucible/${normalizedRelativePath}`, \"https://schemas.fulmenhq.dev/\").toString(),\n );\n }\n\n return compileSchema(content, { aliases });\n } catch (error) {\n metrics.counter(\"schema_validation_errors\").inc();\n throw error;\n }\n}\n\n/**\n * Validate data against a schema ID from registry\n */\nexport async function validateDataBySchemaId(\n data: unknown,\n schemaId: string,\n registryOptions?: SchemaRegistryOptions,\n): Promise<SchemaValidationResult> {\n try {\n const validator = await compileSchemaById(schemaId, registryOptions);\n return validateData(data, validator);\n } catch (error) {\n metrics.counter(\"schema_validation_errors\").inc();\n throw error;\n }\n}\n\n/**\n * Validate file against a schema ID from registry\n */\nexport async function validateFileBySchemaId(\n filePath: string,\n schemaId: string,\n registryOptions?: SchemaRegistryOptions,\n): Promise<SchemaValidationResult> {\n try {\n const validator = await compileSchemaById(schemaId, registryOptions);\n return validateFile(filePath, validator);\n } catch (error) {\n metrics.counter(\"schema_validation_errors\").inc();\n throw error;\n }\n}\n","/**\n * Schema CLI - Commander-based CLI for schema operations\n *\n * Provides command-line interface for schema discovery, validation,\n * and normalization operations. This is a developer tool for exploration\n * and testing, not for production use.\n */\n\nimport { readFile, writeFile } from \"node:fs/promises\";\nimport { Command } from \"commander\";\nimport { isGoneatAvailable, runGoneatValidation } from \"./goneat-bridge.js\";\nimport { compareSchemas, normalizeSchema } from \"./normalizer.js\";\nimport { getSchemaRegistry, listSchemas } from \"./registry.js\";\nimport type { CLIOptions, SchemaValidationResult } from \"./types.js\";\nimport { formatDiagnostics } from \"./utils.js\";\nimport { validateFileBySchemaId } from \"./validator.js\";\n\n/**\n * Create CLI command structure\n */\nexport function createCLI(options: CLIOptions = {}): Command {\n const program = new Command();\n\n program\n .name(\"tsfulmen-schema\")\n .description(\"Schema validation and discovery CLI for Fulmen (developer tool)\")\n .version(\"0.1.0\");\n\n // List schemas command\n program\n .command(\"list\")\n .description(\"List available schemas from registry\")\n .argument(\"[prefix]\", \"Filter schemas by prefix\")\n .option(\"--base-dir <path>\", \"Override schema base directory\")\n .action(async (prefix?: string, cmdOptions?: { baseDir?: string }) => {\n try {\n const schemas = await listSchemas(prefix, {\n baseDir: cmdOptions?.baseDir || options.baseDir,\n });\n\n if (schemas.length === 0) {\n console.log(\"No schemas found\");\n return;\n }\n\n console.log(`Found ${schemas.length} schema(s):\\n`);\n for (const schema of schemas) {\n console.log(` ${schema.id}`);\n console.log(` Format: ${schema.format}`);\n console.log(` Path: ${schema.relativePath}`);\n if (schema.description) {\n console.log(` Description: ${schema.description}`);\n }\n console.log();\n }\n } catch (error) {\n console.error(\"Error listing schemas:\", (error as Error).message);\n process.exit(1);\n }\n });\n\n // Show schema command\n program\n .command(\"show\")\n .description(\"Show schema details\")\n .requiredOption(\"--schema-id <id>\", \"Schema ID to show\")\n .option(\"--base-dir <path>\", \"Override schema base directory\")\n .action(async (cmdOptions: { schemaId: string; baseDir?: string }) => {\n try {\n const registry = getSchemaRegistry({\n baseDir: cmdOptions.baseDir || options.baseDir,\n });\n const schema = await registry.getSchema(cmdOptions.schemaId);\n\n console.log(\"Schema Details:\\n\");\n console.log(` ID: ${schema.id}`);\n console.log(` Format: ${schema.format}`);\n console.log(` Path: ${schema.path}`);\n console.log(` Relative Path: ${schema.relativePath}`);\n if (schema.version) {\n console.log(` Version: ${schema.version}`);\n }\n if (schema.description) {\n console.log(` Description: ${schema.description}`);\n }\n if (schema.schemaDraft) {\n console.log(` Schema Draft: ${schema.schemaDraft}`);\n }\n\n // Read and display schema content\n const content = await readFile(schema.path, \"utf-8\");\n console.log(\"\\nSchema Content:\");\n console.log(content);\n } catch (error) {\n console.error(\"Error showing schema:\", (error as Error).message);\n process.exit(1);\n }\n });\n\n // Validate data command\n program\n .command(\"validate\")\n .description(\"Validate data file against schema\")\n .requiredOption(\"--schema-id <id>\", \"Schema ID to validate against\")\n .argument(\"<file>\", \"Data file to validate\")\n .option(\"--use-goneat\", \"Use goneat for validation (requires goneat binary)\")\n .option(\"--goneat-path <path>\", \"Path to goneat binary\")\n .option(\"--base-dir <path>\", \"Override schema base directory\")\n .action(\n async (\n file: string,\n cmdOptions: {\n schemaId: string;\n useGoneat?: boolean;\n goneatPath?: string;\n baseDir?: string;\n },\n ) => {\n try {\n let result: SchemaValidationResult;\n\n if (cmdOptions.useGoneat) {\n // Check goneat availability\n const available = await isGoneatAvailable(cmdOptions.goneatPath);\n if (!available) {\n console.error(\"❌ goneat not available. Install goneat or remove --use-goneat flag.\");\n console.error(\" AJV validation (default) works without external dependencies.\");\n process.exit(1);\n }\n\n // Get schema path\n const registry = getSchemaRegistry({\n baseDir: cmdOptions.baseDir || options.baseDir,\n });\n const schema = await registry.getSchema(cmdOptions.schemaId);\n\n console.log(\"Using goneat validation...\");\n result = await runGoneatValidation(schema.path, file, cmdOptions.goneatPath);\n } else {\n // Use AJV validation (default, library implementation)\n console.log(\"Using AJV validation...\");\n result = await validateFileBySchemaId(file, cmdOptions.schemaId, {\n baseDir: cmdOptions.baseDir || options.baseDir,\n });\n }\n\n if (result.valid) {\n console.log(`✅ Validation passed (${result.source})`);\n process.exit(0);\n } else {\n console.log(`❌ Validation failed (${result.source})`);\n console.log(\"\\nDiagnostics:\");\n console.log(formatDiagnostics(result.diagnostics));\n process.exit(1);\n }\n } catch (error) {\n console.error(\"Error validating file:\", (error as Error).message);\n process.exit(1);\n }\n },\n );\n\n // Validate schema command\n program\n .command(\"validate-schema\")\n .description(\"Validate a schema file itself\")\n .argument(\"<file>\", \"Schema file to validate\")\n .action(async (file: string) => {\n try {\n const content = await readFile(file, \"utf-8\");\n const { validateSchema } = await import(\"./validator.js\");\n const result = await validateSchema(content);\n\n if (result.valid) {\n console.log(\"✅ Schema is valid\");\n process.exit(0);\n } else {\n console.log(\"❌ Schema is invalid\");\n console.log(\"\\nDiagnostics:\");\n console.log(formatDiagnostics(result.diagnostics));\n process.exit(1);\n }\n } catch (error) {\n console.error(\"Error validating schema:\", (error as Error).message);\n process.exit(1);\n }\n });\n\n // Normalize schema command\n program\n .command(\"normalize\")\n .description(\"Normalize schema to canonical JSON format\")\n .argument(\"<file>\", \"Schema file to normalize\")\n .option(\"--compact\", \"Output compact JSON (no formatting)\")\n .option(\"-o, --output <file>\", \"Write to output file instead of stdout\")\n .action(async (file: string, cmdOptions: { compact?: boolean; output?: string }) => {\n try {\n const content = await readFile(file, \"utf-8\");\n const normalized = normalizeSchema(content, {\n compact: cmdOptions.compact,\n });\n\n if (cmdOptions.output) {\n await writeFile(cmdOptions.output, normalized, \"utf-8\");\n console.log(`✅ Normalized schema written to ${cmdOptions.output}`);\n } else {\n console.log(normalized);\n }\n } catch (error) {\n console.error(\"Error normalizing schema:\", (error as Error).message);\n process.exit(1);\n }\n });\n\n // Compare schemas command\n program\n .command(\"compare\")\n .description(\"Compare two schemas for semantic equality\")\n .argument(\"<file1>\", \"First schema file\")\n .argument(\"<file2>\", \"Second schema file\")\n .option(\"--show-normalized\", \"Show normalized outputs\")\n .action(async (file1: string, file2: string, cmdOptions: { showNormalized?: boolean }) => {\n try {\n const content1 = await readFile(file1, \"utf-8\");\n const content2 = await readFile(file2, \"utf-8\");\n\n const result = compareSchemas(content1, content2);\n\n if (result.equal) {\n console.log(\"✅ Schemas are semantically equal\");\n } else {\n console.log(\"❌ Schemas differ\");\n }\n\n if (cmdOptions.showNormalized) {\n console.log(\"\\nNormalized Schema 1:\");\n console.log(result.normalizedA);\n console.log(\"\\nNormalized Schema 2:\");\n console.log(result.normalizedB);\n }\n\n process.exit(result.equal ? 0 : 1);\n } catch (error) {\n console.error(\"Error comparing schemas:\", (error as Error).message);\n process.exit(1);\n }\n });\n\n // Export schema command\n program\n .command(\"export\")\n .description(\"Export schema from registry to file with provenance\")\n .requiredOption(\"--schema-id <id>\", \"Schema ID to export\")\n .requiredOption(\"--out <path>\", \"Output file path\")\n .option(\"--force\", \"Overwrite existing file\", false)\n .option(\"--no-provenance\", \"Exclude provenance metadata\")\n .option(\"--no-validate\", \"Skip schema validation before export\")\n .option(\"--format <format>\", \"Export format (json|yaml|auto)\", \"auto\")\n .option(\"--base-dir <path>\", \"Override schema base directory\")\n .action(\n async (cmdOptions: {\n schemaId: string;\n out: string;\n force?: boolean;\n provenance?: boolean;\n validate?: boolean;\n format?: string;\n baseDir?: string;\n }) => {\n try {\n const { exportSchema } = await import(\"./export.js\");\n const { exitCodes } = await import(\"../foundry/index.js\");\n\n const result = await exportSchema({\n schemaId: cmdOptions.schemaId,\n outPath: cmdOptions.out,\n includeProvenance: cmdOptions.provenance ?? true,\n validate: cmdOptions.validate ?? true,\n overwrite: cmdOptions.force ?? false,\n format: (cmdOptions.format as \"json\" | \"yaml\" | \"auto\") ?? \"auto\",\n baseDir: cmdOptions.baseDir || options.baseDir,\n });\n\n console.log(\"✅ Schema exported successfully\");\n console.log(` Schema ID: ${result.schemaId}`);\n console.log(` Output: ${result.outPath}`);\n console.log(` Format: ${result.format}`);\n\n if (result.provenance) {\n console.log(\"\\nProvenance:\");\n console.log(` Crucible: ${result.provenance.crucible_version}`);\n console.log(` Library: ${result.provenance.library_version}`);\n if (result.provenance.revision) {\n console.log(` Revision: ${result.provenance.revision}`);\n }\n console.log(` Exported: ${result.provenance.exported_at}`);\n }\n\n process.exit(exitCodes.EXIT_SUCCESS);\n } catch (error) {\n const { exitCodes } = await import(\"../foundry/index.js\");\n const { SchemaExportError, SchemaValidationError, ExportErrorReason } = await import(\n \"./errors.js\"\n );\n\n console.error(\"❌ Schema export failed:\", (error as Error).message);\n\n // Map specific error types to appropriate exit codes\n if (error instanceof SchemaExportError) {\n if (error.outPath) {\n console.error(` Output path: ${error.outPath}`);\n }\n\n // Use error reason for type-safe exit code mapping\n switch (error.reason) {\n case ExportErrorReason.FILE_EXISTS:\n case ExportErrorReason.WRITE_FAILED:\n process.exit(exitCodes.EXIT_FILE_WRITE_ERROR);\n break;\n\n case ExportErrorReason.INVALID_FORMAT:\n process.exit(exitCodes.EXIT_INVALID_ARGUMENT);\n break;\n\n default:\n // PROVENANCE_FAILED, UNKNOWN, and any future reasons\n process.exit(exitCodes.EXIT_FAILURE);\n }\n }\n\n if (error instanceof SchemaValidationError) {\n // Schema not found or validation failed\n const errorMsg = error.message.toLowerCase();\n\n if (errorMsg.includes(\"not found\")) {\n process.exit(exitCodes.EXIT_FILE_NOT_FOUND);\n }\n\n // Validation failures\n process.exit(exitCodes.EXIT_DATA_INVALID);\n }\n\n process.exit(exitCodes.EXIT_FAILURE);\n }\n },\n );\n\n // Identity show command\n program\n .command(\"identity-show\")\n .description(\"Show application identity from .fulmen/app.yaml\")\n .option(\"--path <path>\", \"Explicit path to app.yaml\")\n .option(\"--json\", \"Output as JSON\")\n .action(async (cmdOptions: { path?: string; json?: boolean }) => {\n try {\n const { loadIdentity } = await import(\"../appidentity/loader.js\");\n const { exitCodes } = await import(\"../foundry/index.js\");\n\n const identity = await loadIdentity({ path: cmdOptions.path });\n\n if (cmdOptions.json) {\n console.log(JSON.stringify(identity, null, 2));\n } else {\n console.log(\"Application Identity:\\n\");\n console.log(` Binary Name: ${identity.app.binary_name}`);\n console.log(` Vendor: ${identity.app.vendor}`);\n console.log(` Env Prefix: ${identity.app.env_prefix}`);\n console.log(` Config Name: ${identity.app.config_name}`);\n console.log(` Description: ${identity.app.description}`);\n\n if (identity.metadata) {\n console.log(\"\\nMetadata:\");\n if (identity.metadata.license) {\n console.log(` License: ${identity.metadata.license}`);\n }\n if (identity.metadata.repository_category) {\n console.log(` Category: ${identity.metadata.repository_category}`);\n }\n if (identity.metadata.telemetry_namespace) {\n console.log(` Telemetry: ${identity.metadata.telemetry_namespace}`);\n }\n if (identity.metadata.project_url) {\n console.log(` Project URL: ${identity.metadata.project_url}`);\n }\n }\n }\n\n process.exit(exitCodes.EXIT_SUCCESS);\n } catch (error) {\n const { exitCodes } = await import(\"../foundry/index.js\");\n const { AppIdentityError } = await import(\"../appidentity/errors.js\");\n\n console.error(\"❌ Failed to load identity:\", (error as Error).message);\n\n if (error instanceof AppIdentityError) {\n if (error.message.includes(\"not found\")) {\n process.exit(exitCodes.EXIT_FILE_NOT_FOUND);\n }\n if (error.message.includes(\"Invalid\") || error.message.includes(\"validation\")) {\n process.exit(exitCodes.EXIT_DATA_INVALID);\n }\n }\n\n process.exit(exitCodes.EXIT_FAILURE);\n }\n });\n\n // Identity validate command\n program\n .command(\"identity-validate\")\n .description(\"Validate application identity against schema\")\n .argument(\"[file]\", \"Path to app.yaml (defaults to discovery)\")\n .action(async (file?: string) => {\n try {\n const { loadIdentity } = await import(\"../appidentity/loader.js\");\n const { exitCodes } = await import(\"../foundry/index.js\");\n\n console.log(\"Validating application identity...\");\n\n const identity = await loadIdentity({ path: file });\n\n console.log(\"✅ Identity is valid\");\n console.log(` Binary: ${identity.app.binary_name}`);\n console.log(` Vendor: ${identity.app.vendor}`);\n\n process.exit(exitCodes.EXIT_SUCCESS);\n } catch (error) {\n const { exitCodes } = await import(\"../foundry/index.js\");\n const { AppIdentityError } = await import(\"../appidentity/errors.js\");\n\n console.error(\"❌ Identity validation failed:\", (error as Error).message);\n\n if (error instanceof AppIdentityError) {\n if (error.message.includes(\"not found\")) {\n process.exit(exitCodes.EXIT_FILE_NOT_FOUND);\n }\n if (error.message.includes(\"Invalid\") || error.message.includes(\"validation\")) {\n process.exit(exitCodes.EXIT_DATA_INVALID);\n }\n }\n\n process.exit(exitCodes.EXIT_FAILURE);\n }\n });\n\n return program;\n}\n","/**\n * Schema export utilities - implements schema export with provenance\n */\n\nimport { access, mkdir, readFile, writeFile } from \"node:fs/promises\";\nimport { dirname, extname, join } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { parse as parseYAML, stringify as stringifyYAML } from \"yaml\";\nimport { SchemaExportError, SchemaValidationError } from \"./errors.js\";\nimport { getSchemaRegistry } from \"./registry.js\";\nimport type {\n ExportSchemaOptions,\n ExportSchemaResult,\n SchemaExportFormat,\n SchemaProvenanceMetadata,\n} from \"./types.js\";\nimport { validateSchema } from \"./validator.js\";\n\n/**\n * Extract provenance metadata from Crucible sync metadata\n */\nasync function extractProvenanceMetadata(schemaId: string): Promise<SchemaProvenanceMetadata> {\n try {\n // Read Crucible metadata using proper path resolution\n const __filename = fileURLToPath(import.meta.url);\n const __dirname = dirname(__filename);\n const metadataPath = join(__dirname, \"..\", \"..\", \".crucible\", \"metadata\", \"metadata.yaml\");\n const metadataContent = await readFile(metadataPath, \"utf-8\");\n\n // Parse YAML properly to avoid brittle regex matching\n const metadata = parseYAML(metadataContent) as {\n sources?: Array<{\n name?: string;\n version?: string;\n commit?: string;\n }>;\n };\n\n // Extract Crucible source metadata (first source is typically 'crucible')\n const crucibleSource = metadata.sources?.[0];\n const crucibleVersion = crucibleSource?.version || \"unknown\";\n const revision = crucibleSource?.commit;\n\n // Read library version from package.json\n const pkgPath = join(__dirname, \"..\", \"..\", \"package.json\");\n const pkgContent = await readFile(pkgPath, \"utf-8\");\n const pkg = JSON.parse(pkgContent) as { version: string };\n\n return {\n schema_id: schemaId,\n crucible_version: crucibleVersion,\n library_version: pkg.version,\n revision: revision,\n exported_at: new Date().toISOString(),\n export_source: \"tsfulmen\",\n };\n } catch (error) {\n throw SchemaExportError.provenanceFailed((error as Error).message, error as Error);\n }\n}\n\n/**\n * Embed provenance metadata in schema content\n */\nfunction embedProvenance(\n schemaContent: Record<string, unknown>,\n provenance: SchemaProvenanceMetadata,\n format: SchemaExportFormat,\n): string {\n if (format === \"json\") {\n // For JSON: embed under $comment[\"x-crucible-source\"]\n const withProvenance = {\n ...schemaContent,\n $comment: {\n ...(typeof schemaContent.$comment === \"object\" ? schemaContent.$comment : {}),\n \"x-crucible-source\": provenance,\n },\n };\n return JSON.stringify(withProvenance, null, 2);\n }\n\n // For YAML: prepend comment block\n const yamlContent = stringifyYAML(schemaContent, {\n indent: 2,\n lineWidth: 0,\n });\n\n const provenanceComment = [\n \"# x-crucible-source:\",\n `# schema_id: ${provenance.schema_id}`,\n `# crucible_version: ${provenance.crucible_version}`,\n `# library_version: ${provenance.library_version}`,\n ...(provenance.revision ? [`# revision: ${provenance.revision}`] : []),\n `# exported_at: ${provenance.exported_at}`,\n `# export_source: ${provenance.export_source}`,\n \"\",\n ].join(\"\\n\");\n\n return provenanceComment + yamlContent;\n}\n\n/**\n * Detect export format from file extension or explicit option\n */\nfunction detectFormat(outPath: string, formatOption?: SchemaExportFormat): SchemaExportFormat {\n if (formatOption && formatOption !== \"auto\") {\n return formatOption;\n }\n\n const ext = extname(outPath).toLowerCase();\n switch (ext) {\n case \".json\":\n return \"json\";\n case \".yaml\":\n case \".yml\":\n return \"yaml\";\n default:\n throw SchemaExportError.invalidFormat(ext, outPath);\n }\n}\n\n/**\n * Export schema from registry to file with provenance\n *\n * @param options - Export options\n * @returns Export result with metadata\n *\n * @throws {SchemaExportError} If export fails\n * @throws {SchemaValidationError} If schema not found or validation fails\n *\n * @example\n * ```typescript\n * import { exportSchema } from '@fulmenhq/tsfulmen/schema';\n *\n * await exportSchema({\n * schemaId: 'library/foundry/v1.0.0/exit-codes',\n * outPath: './schemas/exit-codes.schema.json',\n * includeProvenance: true,\n * validate: true,\n * });\n * ```\n */\nexport async function exportSchema(options: ExportSchemaOptions): Promise<ExportSchemaResult> {\n const {\n schemaId,\n outPath,\n includeProvenance = true,\n validate = true,\n overwrite = false,\n format: formatOption,\n baseDir,\n } = options;\n\n // Detect output format\n const format = detectFormat(outPath, formatOption);\n\n // Check if file exists\n if (!overwrite) {\n try {\n await access(outPath);\n throw SchemaExportError.fileExists(outPath);\n } catch (error) {\n // File doesn't exist - proceed\n if ((error as NodeJS.ErrnoException).code !== \"ENOENT\") {\n throw error;\n }\n }\n }\n\n // Get schema from registry\n const registry = getSchemaRegistry({ baseDir });\n const schema = await registry.getSchema(schemaId);\n\n // Read schema content\n const schemaContent = await readFile(schema.path, \"utf-8\");\n\n // Validate if requested\n if (validate) {\n const validationResult = await validateSchema(schemaContent);\n if (!validationResult.valid) {\n throw SchemaValidationError.validationFailed(schemaId, validationResult.diagnostics, {\n type: \"file\",\n id: schema.path,\n });\n }\n }\n\n // Parse schema content\n let schemaObject: Record<string, unknown>;\n try {\n schemaObject = JSON.parse(schemaContent) as Record<string, unknown>;\n } catch {\n schemaObject = parseYAML(schemaContent) as Record<string, unknown>;\n }\n\n // Freeze schema object to prevent mutation\n Object.freeze(schemaObject);\n\n let provenance: SchemaProvenanceMetadata | undefined;\n let outputContent: string;\n\n if (includeProvenance) {\n // Extract provenance metadata\n provenance = await extractProvenanceMetadata(schemaId);\n\n // Embed provenance in output\n outputContent = embedProvenance(schemaObject, provenance, format);\n } else {\n // Export without provenance\n if (format === \"json\") {\n outputContent = JSON.stringify(schemaObject, null, 2);\n } else {\n outputContent = stringifyYAML(schemaObject, { indent: 2, lineWidth: 0 });\n }\n }\n\n // Ensure output directory exists\n await mkdir(dirname(outPath), { recursive: true });\n\n // Write to file\n try {\n await writeFile(outPath, outputContent, \"utf-8\");\n } catch (error) {\n throw SchemaExportError.writeFailed(outPath, error as Error);\n }\n\n return {\n success: true,\n schemaId,\n outPath,\n format,\n includeProvenance,\n provenance,\n };\n}\n\n/**\n * Strip provenance metadata from schema content\n *\n * This helper is useful for comparing exported schemas with runtime\n * schemas or validating that provenance doesn't affect schema semantics.\n *\n * @param content - Schema content (JSON or YAML string)\n * @returns Schema content without provenance metadata\n *\n * @example\n * ```typescript\n * import { stripProvenance } from '@fulmenhq/tsfulmen/schema';\n *\n * const exported = await readFile('./schema.json', 'utf-8');\n * const withoutProvenance = stripProvenance(exported);\n * ```\n */\nexport function stripProvenance(content: string): string {\n try {\n // Try parsing as JSON\n const parsed = JSON.parse(content) as Record<string, unknown>;\n\n // Remove provenance from $comment\n if (parsed.$comment && typeof parsed.$comment === \"object\") {\n const comment = { ...parsed.$comment } as Record<string, unknown>;\n delete comment[\"x-crucible-source\"];\n\n // Remove $comment entirely if it's now empty\n if (Object.keys(comment).length === 0) {\n delete parsed.$comment;\n } else {\n parsed.$comment = comment;\n }\n }\n\n return JSON.stringify(parsed, null, 2);\n } catch {\n // YAML format - strip comment lines\n const lines = content.split(\"\\n\");\n const filtered = lines.filter((line) => {\n const trimmed = line.trim();\n return !(\n trimmed.startsWith(\"# x-crucible-source:\") ||\n (trimmed.startsWith(\"# \") &&\n /^#\\s+(schema_id|crucible_version|library_version|revision|exported_at|export_source):/.test(\n trimmed,\n ))\n );\n });\n\n // Remove leading blank lines\n while (filtered.length > 0 && filtered[0]?.trim() === \"\") {\n filtered.shift();\n }\n\n return filtered.join(\"\\n\");\n }\n}\n","/**\n * Schema validation module - implements Fulmen Schema Validation Standard\n *\n * Provides schema discovery, validation, and normalization utilities for Crucible schemas\n * with JSON Schema 2020-12 support and optional goneat integration.\n */\n\nexport const VERSION = \"0.1.0\";\n\nexport {\n applyFulmenAjvFormats,\n type FulmenAjvFormatsOptions,\n} from \"./ajv-formats.js\";\n\n// CLI exports\nexport { createCLI } from \"./cli.js\";\n// Error exports\nexport * from \"./errors.js\";\n// Export exports\nexport { exportSchema, stripProvenance } from \"./export.js\";\n// Goneat bridge exports (CLI-only, optional)\nexport {\n detectGoneat,\n isGoneatAvailable,\n runGoneatValidation,\n} from \"./goneat-bridge.js\";\n// Normalizer exports\nexport { compareSchemas, normalizeSchema } from \"./normalizer.js\";\n// Registry exports\nexport {\n getSchema,\n getSchemaByPath,\n getSchemaRegistry,\n hasSchema,\n listSchemas,\n SchemaRegistry,\n} from \"./registry.js\";\n// Core exports\nexport type {\n AjvError,\n CLIOptions,\n CompiledValidator,\n ExportSchemaOptions,\n ExportSchemaResult,\n SchemaComparisonResult,\n SchemaExportFormat,\n SchemaFormat,\n SchemaInput,\n SchemaMetadata,\n SchemaNormalizationOptions,\n SchemaProvenanceMetadata,\n SchemaRegistryOptions,\n SchemaSource,\n SchemaValidationDiagnostic,\n SchemaValidationOptions,\n SchemaValidationResult,\n} from \"./types.js\";\n// Utility exports\nexport {\n countDiagnostics,\n createDiagnostic,\n formatDiagnostics,\n formatValidationResult,\n groupDiagnosticsBySeverity,\n isValidationError,\n normalizePointer,\n} from \"./utils.js\";\n// Validator exports\nexport {\n clearCache,\n compileSchema,\n compileSchemaById,\n getCacheSize,\n validateData,\n validateDataBySchemaId,\n validateFile,\n validateFileBySchemaId,\n validateSchema,\n} from \"./validator.js\";\n","/**\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","/**\n * Application Identity Errors\n *\n * Module-specific error classes for identity operations\n */\n\nimport { FulmenError, type FulmenErrorData } from \"../errors/index.js\";\nimport type { SchemaValidationDiagnostic } from \"../schema/types.js\";\n\n/**\n * Base error class for app identity operations\n */\nexport class AppIdentityError extends FulmenError {\n public readonly identityPath?: string;\n\n constructor(message: string, identityPath?: string, cause?: Error) {\n // Build FulmenErrorData\n let errorData: FulmenErrorData;\n\n if (cause) {\n errorData = FulmenError.fromError(cause, {\n code: \"APP_IDENTITY_ERROR\",\n severity: \"high\",\n context: { identityPath },\n }).data;\n } else {\n errorData = {\n code: \"APP_IDENTITY_ERROR\",\n message,\n severity: \"high\",\n timestamp: new Date().toISOString(),\n context: { identityPath },\n };\n }\n\n super(errorData);\n this.name = \"AppIdentityError\";\n this.identityPath = identityPath;\n\n // Maintains proper stack trace for where our error was thrown (only available on V8)\n if (Error.captureStackTrace) {\n Error.captureStackTrace(this, AppIdentityError);\n }\n }\n\n /**\n * Create error for identity not found\n */\n static notFound(searchedPaths: string[]): AppIdentityError {\n const message = `App identity not found\\nSearched paths:\\n${searchedPaths.map((p) => ` - ${p}`).join(\"\\n\")}`;\n return new AppIdentityError(message);\n }\n\n /**\n * Create error for schema validation failure\n */\n static validationFailed(\n path: string,\n diagnostics: SchemaValidationDiagnostic[],\n ): AppIdentityError {\n const errorCount = diagnostics.filter((d) => d.severity === \"ERROR\").length;\n const warningCount = diagnostics.filter((d) => d.severity === \"WARN\").length;\n\n let message = `Invalid app identity: ${path}\\n`;\n message += `Validation errors: ${errorCount} error(s), ${warningCount} warning(s)\\n`;\n\n // Include first few diagnostics\n const displayDiagnostics = diagnostics.slice(0, 3);\n for (const diag of displayDiagnostics) {\n message += ` - ${diag.message}`;\n if (diag.pointer) {\n message += ` at ${diag.pointer}`;\n }\n message += \"\\n\";\n }\n\n if (diagnostics.length > 3) {\n message += ` ... and ${diagnostics.length - 3} more\\n`;\n }\n\n return new AppIdentityError(message, path);\n }\n\n /**\n * Create error for environment variable override pointing to missing file\n */\n static envOverrideMissing(envPath: string): AppIdentityError {\n const message = `FULMEN_APP_IDENTITY_PATH points to missing file: ${envPath}\\n`;\n return new AppIdentityError(message, envPath);\n }\n\n /**\n * Create error for YAML parsing failure\n */\n static parseFailed(path: string, cause: Error): AppIdentityError {\n const message = `Failed to parse identity file: ${path}\\n${cause.message}`;\n return new AppIdentityError(message, path, cause);\n }\n\n /**\n * Create error for file read failure\n */\n static readFailed(path: string, cause: Error): AppIdentityError {\n const message = `Failed to read identity file: ${path}\\n${cause.message}`;\n return new AppIdentityError(message, path, cause);\n }\n\n /**\n * Create error for embedded identity already registered\n *\n * Uses first-wins semantics - once registered, cannot be replaced\n */\n static alreadyRegistered(): AppIdentityError {\n const message =\n \"Embedded identity already registered. \" +\n \"Registration uses first-wins semantics and cannot be replaced.\";\n return new AppIdentityError(message);\n }\n\n /**\n * Create error for embedded identity YAML parsing failure\n */\n static embeddedParseFailed(cause: Error): AppIdentityError {\n const message = `Failed to parse embedded identity YAML: ${cause.message}`;\n return new AppIdentityError(message, undefined, cause);\n }\n\n /**\n * Create error for embedded identity schema validation failure\n */\n static embeddedValidationFailed(diagnostics: SchemaValidationDiagnostic[]): AppIdentityError {\n const errorCount = diagnostics.filter((d) => d.severity === \"ERROR\").length;\n const warningCount = diagnostics.filter((d) => d.severity === \"WARN\").length;\n\n let message = \"Invalid embedded identity\\n\";\n message += `Validation errors: ${errorCount} error(s), ${warningCount} warning(s)\\n`;\n\n const displayDiagnostics = diagnostics.slice(0, 3);\n for (const diag of displayDiagnostics) {\n message += ` - ${diag.message}`;\n if (diag.pointer) {\n message += ` at ${diag.pointer}`;\n }\n message += \"\\n\";\n }\n\n if (diagnostics.length > 3) {\n message += ` ... and ${diagnostics.length - 3} more\\n`;\n }\n\n return new AppIdentityError(message);\n }\n}\n","/**\n * Embedded Identity Registration\n *\n * Provides a mechanism to register embedded identity at application startup\n * for standalone binary/package support. This allows applications to work\n * without requiring .fulmen/app.yaml to be discoverable on the filesystem.\n *\n * Discovery precedence (with embedded fallback):\n * 1. Explicit path parameter\n * 2. FULMEN_APP_IDENTITY_PATH environment variable\n * 3. Ancestor search from CWD\n * 4. Embedded identity fallback (this module)\n */\n\nimport { parse as parseYAML } from \"yaml\";\nimport { validateDataBySchemaId } from \"../schema/index.js\";\nimport { APP_IDENTITY_SCHEMA_ID } from \"./constants.js\";\nimport { AppIdentityError } from \"./errors.js\";\nimport type { Identity } from \"./types.js\";\n\n/**\n * Process-level storage for embedded identity\n * Uses first-wins semantics - once registered, cannot be replaced\n */\nlet embeddedIdentity: Identity | null = null;\nlet isRegistered = false;\n\n/**\n * Deep freeze an object and all its nested properties\n */\nfunction deepFreeze<T>(obj: T): T {\n Object.freeze(obj);\n Object.getOwnPropertyNames(obj).forEach((prop) => {\n // biome-ignore lint/suspicious/noExplicitAny: Required for recursive property access\n const value = (obj as any)[prop];\n if (\n value !== null &&\n (typeof value === \"object\" || typeof value === \"function\") &&\n !Object.isFrozen(value)\n ) {\n deepFreeze(value);\n }\n });\n return obj;\n}\n\n/**\n * Register embedded identity YAML that serves as fallback when\n * runtime discovery cannot find an external app.yaml.\n *\n * Semantics:\n * - First registration wins (subsequent calls throw error)\n * - Validates against schema on registration\n * - Stores as immutable process-level fallback\n *\n * @param data - YAML string or pre-parsed Identity object\n * @throws {AppIdentityError} If already registered or validation fails\n *\n * @example\n * ```typescript\n * // From npm package entry point\n * import { registerEmbeddedIdentity } from \"@fulmenhq/tsfulmen/appidentity\";\n * import { readFileSync } from \"node:fs\";\n * import { fileURLToPath } from \"node:url\";\n * import { dirname, join } from \"node:path\";\n *\n * const __filename = fileURLToPath(import.meta.url);\n * const __dirname = dirname(__filename);\n * const embeddedPath = join(__dirname, \"..\", \".fulmen\", \"app.yaml\");\n *\n * try {\n * const yaml = readFileSync(embeddedPath, \"utf-8\");\n * registerEmbeddedIdentity(yaml);\n * } catch {\n * // Embedded identity not available - discovery will use filesystem\n * }\n * ```\n */\nexport async function registerEmbeddedIdentity(data: string | Identity): Promise<void> {\n // First-wins semantics\n if (isRegistered) {\n throw AppIdentityError.alreadyRegistered();\n }\n\n let identity: Identity;\n\n if (typeof data === \"string\") {\n // Parse YAML\n let parsed: unknown;\n try {\n parsed = parseYAML(data);\n } catch (error) {\n throw AppIdentityError.embeddedParseFailed(\n error instanceof Error ? error : new Error(String(error)),\n );\n }\n\n // Validate against schema\n const result = await validateDataBySchemaId(parsed, APP_IDENTITY_SCHEMA_ID);\n if (!result.valid) {\n throw AppIdentityError.embeddedValidationFailed(result.diagnostics);\n }\n\n identity = parsed as Identity;\n } else {\n // Pre-parsed object - still validate\n const result = await validateDataBySchemaId(data, APP_IDENTITY_SCHEMA_ID);\n if (!result.valid) {\n throw AppIdentityError.embeddedValidationFailed(result.diagnostics);\n }\n identity = data;\n }\n\n // Deep freeze and store\n embeddedIdentity = deepFreeze(structuredClone(identity)) as Identity;\n isRegistered = true;\n}\n\n/**\n * Check if embedded identity has been registered\n *\n * @returns true if registerEmbeddedIdentity() has been called successfully\n */\nexport function hasEmbeddedIdentity(): boolean {\n return isRegistered;\n}\n\n/**\n * Get the registered embedded identity\n *\n * @returns Frozen identity object or null if not registered\n */\nexport function getEmbeddedIdentity(): Identity | null {\n return embeddedIdentity;\n}\n\n/**\n * Clear embedded identity registration\n *\n * WARNING: For testing only. In production, embedded identity should be\n * set once at startup and never cleared.\n */\nexport function clearEmbeddedIdentity(): void {\n embeddedIdentity = null;\n isRegistered = false;\n}\n","/**\n * Application Identity Cache\n *\n * Process-level caching for identity objects with immutability guarantees\n */\n\nimport type { Identity } from \"./types.js\";\n\n/**\n * Process-level cache storage\n * null = not cached, Identity = cached value\n */\nlet cachedIdentity: Identity | null = null;\n\n/**\n * Get cached identity if available\n *\n * @returns Cached identity or null if not cached\n */\nexport function getCachedIdentity(): Identity | null {\n return cachedIdentity;\n}\n\n/**\n * Set cached identity\n *\n * Identity object should already be frozen before caching\n *\n * @param identity - Identity to cache (must be frozen)\n */\nexport function setCachedIdentity(identity: Identity): void {\n cachedIdentity = identity;\n}\n\n/**\n * Clear the identity cache\n *\n * Useful for testing or when identity needs to be reloaded\n */\nexport function clearIdentityCache(): void {\n cachedIdentity = null;\n}\n","/**\n * Application Identity Discovery\n *\n * Implements the Crucible discovery precedence algorithm:\n * 1. Explicit path parameter (highest priority)\n * 2. Environment variable override (FULMEN_APP_IDENTITY_PATH)\n * 3. Ancestor search from CWD upward\n */\n\nimport { access } from \"node:fs/promises\";\nimport { dirname, join } from \"node:path\";\nimport {\n APP_IDENTITY_DIR,\n APP_IDENTITY_ENV_VAR,\n APP_IDENTITY_FILENAME,\n MAX_ANCESTOR_SEARCH_DEPTH,\n} from \"./constants.js\";\nimport { AppIdentityError } from \"./errors.js\";\n\n/**\n * Discovery result with path and source\n */\nexport interface DiscoveryResult {\n readonly path: string;\n readonly source: \"explicit\" | \"env\" | \"ancestor\" | \"test\";\n}\n\n/**\n * Options for identity discovery\n */\nexport interface DiscoveryOptions {\n /**\n * Explicit path override (highest priority)\n */\n readonly path?: string;\n\n /**\n * Starting directory for ancestor search\n * Defaults to process.cwd()\n */\n readonly startDir?: string;\n}\n\n/**\n * Discover application identity file using Crucible precedence algorithm\n *\n * Discovery order:\n * 1. Explicit path parameter (throws if not found)\n * 2. FULMEN_APP_IDENTITY_PATH env var (throws if set but not found)\n * 3. Ancestor search from startDir (throws if not found after max depth)\n *\n * @param options - Discovery options\n * @returns Discovery result with path and source\n * @throws {AppIdentityError} If identity file not found or inaccessible\n */\nexport async function discoverIdentityPath(\n options?: DiscoveryOptions,\n): Promise<DiscoveryResult | null> {\n // 1. Explicit path parameter (highest priority)\n if (options?.path) {\n const exists = await fileExists(options.path);\n if (!exists) {\n throw AppIdentityError.notFound([options.path]);\n }\n return { path: options.path, source: \"explicit\" };\n }\n\n // 2. Environment variable override\n const envPath = process.env[APP_IDENTITY_ENV_VAR];\n if (envPath) {\n const exists = await fileExists(envPath);\n if (!exists) {\n throw AppIdentityError.envOverrideMissing(envPath);\n }\n return { path: envPath, source: \"env\" };\n }\n\n // 3. Ancestor search from startDir\n const startDir = options?.startDir || process.cwd();\n const result = await searchAncestors(startDir);\n if (result) {\n return { path: result, source: \"ancestor\" };\n }\n\n return null;\n}\n\n/**\n * Search ancestor directories for identity file\n *\n * Walks upward from startDir to filesystem root, looking for .fulmen/app.yaml\n * Stops at MAX_ANCESTOR_SEARCH_DEPTH or filesystem root\n *\n * @param startDir - Directory to start search from\n * @returns Path to identity file if found, null otherwise\n * @throws {AppIdentityError} If max depth reached or filesystem root reached without finding file\n */\nasync function searchAncestors(startDir: string): Promise<string | null> {\n let currentDir = startDir;\n const searchedPaths: string[] = [];\n\n for (let i = 0; i < MAX_ANCESTOR_SEARCH_DEPTH; i++) {\n const candidatePath = join(currentDir, APP_IDENTITY_DIR, APP_IDENTITY_FILENAME);\n searchedPaths.push(candidatePath);\n\n if (await fileExists(candidatePath)) {\n return candidatePath;\n }\n\n const parentDir = dirname(currentDir);\n if (parentDir === currentDir) {\n // Reached filesystem root\n throw AppIdentityError.notFound(searchedPaths);\n }\n currentDir = parentDir;\n }\n\n // Max depth reached\n throw AppIdentityError.notFound(searchedPaths);\n}\n\n/**\n * Check if a file exists and is accessible\n *\n * @param path - Path to check\n * @returns true if file exists and is readable, false otherwise\n */\nasync function fileExists(path: string): Promise<boolean> {\n try {\n await access(path);\n return true;\n } catch {\n return false;\n }\n}\n","/**\n * Application Identity Loader\n *\n * Main loading logic with YAML parsing, schema validation, and caching\n */\n\nimport { readFile } from \"node:fs/promises\";\nimport { parse as parseYAML } from \"yaml\";\nimport { validateDataBySchemaId } from \"../schema/index.js\";\nimport { clearIdentityCache, getCachedIdentity, setCachedIdentity } from \"./cache.js\";\nimport { APP_IDENTITY_ENV_VAR, APP_IDENTITY_SCHEMA_ID } from \"./constants.js\";\nimport { discoverIdentityPath } from \"./discovery.js\";\nimport { getEmbeddedIdentity } from \"./embedded.js\";\nimport { AppIdentityError } from \"./errors.js\";\nimport type { Identity, LoadIdentityOptions } from \"./types.js\";\n\n/**\n * Deep freeze an object and all its nested properties\n *\n * Recursively freezes an object and all nested objects/functions to ensure\n * complete immutability. This prevents accidental mutations of identity data.\n *\n * Note: Uses `any` type assertion (line 28) to access arbitrary properties\n * during recursive traversal. This is necessary because TypeScript's generic\n * constraint system cannot express \"any object with indexable properties\"\n * without losing the return type safety. The `any` is scoped to a single\n * line and protected by runtime guards.\n *\n * @param obj - Object to freeze\n * @returns Frozen object (same type as input)\n */\nfunction deepFreeze<T>(obj: T): T {\n // Freeze the object itself\n Object.freeze(obj);\n\n // Recursively freeze all properties\n Object.getOwnPropertyNames(obj).forEach((prop) => {\n // biome-ignore lint/suspicious/noExplicitAny: Required for recursive property access - see function docs\n const value = (obj as any)[prop];\n if (\n value !== null &&\n (typeof value === \"object\" || typeof value === \"function\") &&\n !Object.isFrozen(value)\n ) {\n deepFreeze(value);\n }\n });\n\n return obj;\n}\n\n/**\n * Load application identity from .fulmen/app.yaml\n *\n * Discovery order:\n * 1. Test injection (options.identity) - bypasses all discovery and caching\n * 2. Explicit path (options.path)\n * 3. Environment variable (FULMEN_APP_IDENTITY_PATH)\n * 4. Ancestor search from startDir or CWD\n * 5. Embedded identity fallback (if registered via registerEmbeddedIdentity)\n *\n * Results are cached after first successful load unless skipCache is true.\n * Test injections are never cached.\n *\n * @param options - Load options\n * @returns Frozen, immutable identity object\n * @throws {AppIdentityError} If identity not found, invalid, or unreadable\n */\nexport async function loadIdentity(options?: LoadIdentityOptions): Promise<Identity> {\n // Test injection (never caches)\n if (options?.identity) {\n return deepFreeze(structuredClone(options.identity)) as Identity;\n }\n\n // Check cache unless skipCache\n if (!options?.skipCache) {\n const cached = getCachedIdentity();\n if (cached) {\n return cached;\n }\n }\n\n // Discover file - may throw AppIdentityError.notFound or return null\n let discovery: Awaited<ReturnType<typeof discoverIdentityPath>>;\n try {\n discovery = await discoverIdentityPath({\n path: options?.path,\n startDir: options?.startDir,\n });\n } catch (error) {\n // Discovery failed (e.g., reached filesystem root without finding identity)\n // Embedded fallback MUST NOT override explicit path or env override semantics.\n const hasExplicitPath = Boolean(options?.path);\n const hasEnvOverride = Boolean(process.env[APP_IDENTITY_ENV_VAR]);\n\n if (!hasExplicitPath && !hasEnvOverride && error instanceof AppIdentityError) {\n const embedded = getEmbeddedIdentity();\n if (embedded) {\n // Cache the embedded identity for subsequent calls\n setCachedIdentity(embedded);\n return embedded;\n }\n }\n\n throw error;\n }\n\n // If discovery returned null (no env var, no explicit path, and ancestor search returned null)\n if (!discovery) {\n const embedded = getEmbeddedIdentity();\n if (embedded) {\n // Cache the embedded identity for subsequent calls\n setCachedIdentity(embedded);\n return embedded;\n }\n throw AppIdentityError.notFound([]);\n }\n\n // Read file\n let content: string;\n try {\n content = await readFile(discovery.path, \"utf-8\");\n } catch (error) {\n throw AppIdentityError.readFailed(\n discovery.path,\n error instanceof Error ? error : new Error(String(error)),\n );\n }\n\n // Parse YAML\n let parsed: unknown;\n try {\n parsed = parseYAML(content);\n } catch (error) {\n throw AppIdentityError.parseFailed(\n discovery.path,\n error instanceof Error ? error : new Error(String(error)),\n );\n }\n\n // Validate against schema (unless skipValidation)\n if (!options?.skipValidation) {\n const result = await validateDataBySchemaId(parsed, APP_IDENTITY_SCHEMA_ID);\n\n if (!result.valid) {\n throw AppIdentityError.validationFailed(discovery.path, result.diagnostics);\n }\n }\n\n // Deep freeze for immutability\n const identity = deepFreeze(structuredClone(parsed)) as Identity;\n\n // Cache result\n setCachedIdentity(identity);\n\n return identity;\n}\n\n/**\n * Get cached identity without triggering load\n *\n * @returns Cached identity or null if not cached\n */\n/**\n * Clear the identity cache\n *\n * Useful for testing or when identity needs to be reloaded\n */\nexport { clearIdentityCache, getCachedIdentity };\n","import type { Identity } from \"./types.js\";\n\nexport type RuntimeName = \"bun\" | \"node\" | \"unknown\";\n\nexport interface RuntimeInfo {\n service: {\n name: string;\n vendor?: string;\n version?: string;\n };\n runtime: {\n name: RuntimeName;\n version?: string;\n };\n platform: {\n os: NodeJS.Platform;\n arch: string;\n };\n}\n\nexport interface BuildRuntimeInfoOptions {\n identity?: Identity;\n version?: string;\n serviceName?: string;\n vendor?: string;\n}\n\nfunction detectRuntime(): { name: RuntimeName; version?: string } {\n const versions = process.versions as unknown as Record<string, string | undefined>;\n\n if (typeof versions.bun === \"string\" && versions.bun.length > 0) {\n return { name: \"bun\", version: versions.bun };\n }\n\n if (typeof versions.node === \"string\" && versions.node.length > 0) {\n return { name: \"node\", version: versions.node };\n }\n\n return { name: \"unknown\" };\n}\n\n/**\n * Build a minimal runtime info payload suitable for discovery endpoints.\n */\nexport function buildRuntimeInfo(options: BuildRuntimeInfoOptions = {}): RuntimeInfo {\n const runtime = detectRuntime();\n\n const serviceName = options.serviceName ?? options.identity?.app.binary_name ?? \"unknown-service\";\n const vendor = options.vendor ?? options.identity?.app.vendor;\n\n return {\n service: {\n name: serviceName,\n vendor,\n version: options.version,\n },\n runtime,\n platform: {\n os: process.platform,\n arch: process.arch,\n },\n };\n}\n","/**\n * Application Identity Module\n *\n * Provides typed access to .fulmen/app.yaml identity metadata\n * Layer 0 module: zero Fulmen module dependencies\n */\n\n// Constants\nexport {\n APP_IDENTITY_DIR,\n APP_IDENTITY_ENV_VAR,\n APP_IDENTITY_FILENAME,\n APP_IDENTITY_SCHEMA_ID,\n MAX_ANCESTOR_SEARCH_DEPTH,\n} from \"./constants.js\";\n\n// Embedded identity (for standalone binary/package support)\nexport {\n clearEmbeddedIdentity,\n getEmbeddedIdentity,\n hasEmbeddedIdentity,\n registerEmbeddedIdentity,\n} from \"./embedded.js\";\n\n// Errors\nexport { AppIdentityError } from \"./errors.js\";\nexport type { ConfigIdentifiers } from \"./helpers.js\";\n// Helpers\nexport {\n buildEnvVar,\n getBinaryName,\n getConfigIdentifiers,\n getConfigName,\n getEnvPrefix,\n getEnvVar,\n getTelemetryNamespace,\n getVendor,\n} from \"./helpers.js\";\n// Functions\nexport {\n clearIdentityCache,\n getCachedIdentity,\n loadIdentity,\n} from \"./loader.js\";\n\nexport {\n type BuildRuntimeInfoOptions,\n buildRuntimeInfo,\n type RuntimeInfo,\n type RuntimeName,\n} from \"./runtime.js\";\n// Types\nexport type {\n AppIdentity,\n Identity,\n IdentityMetadata,\n LoadIdentityOptions,\n PythonMetadata,\n RepositoryCategory,\n} from \"./types.js\";\n","/**\n * Application Identity Helpers\n *\n * Convenience functions for accessing identity fields\n * All helpers use loadIdentity() under the hood for caching benefits\n */\n\nimport { loadIdentity } from \"./loader.js\";\nimport type { LoadIdentityOptions } from \"./types.js\";\n\n/**\n * Config identifiers for path construction\n */\nexport interface ConfigIdentifiers {\n readonly vendor: string;\n readonly configName: string;\n}\n\n/**\n * Get the binary name from app identity\n *\n * @param options - Load options (optional)\n * @returns Binary name (e.g., 'myapp')\n */\nexport async function getBinaryName(options?: LoadIdentityOptions): Promise<string> {\n const identity = await loadIdentity(options);\n return identity.app.binary_name;\n}\n\n/**\n * Get the vendor namespace from app identity\n *\n * @param options - Load options (optional)\n * @returns Vendor namespace (e.g., 'acmecorp')\n */\nexport async function getVendor(options?: LoadIdentityOptions): Promise<string> {\n const identity = await loadIdentity(options);\n return identity.app.vendor;\n}\n\n/**\n * Get the environment variable prefix from app identity\n *\n * @param options - Load options (optional)\n * @returns Env prefix (e.g., 'MYAPP_')\n */\nexport async function getEnvPrefix(options?: LoadIdentityOptions): Promise<string> {\n const identity = await loadIdentity(options);\n return identity.app.env_prefix;\n}\n\n/**\n * Get the config directory name from app identity\n *\n * @param options - Load options (optional)\n * @returns Config name (e.g., 'myapp')\n */\nexport async function getConfigName(options?: LoadIdentityOptions): Promise<string> {\n const identity = await loadIdentity(options);\n return identity.app.config_name;\n}\n\n/**\n * Get the telemetry namespace from app identity\n *\n * Falls back to binary_name if telemetry_namespace is not specified\n *\n * @param options - Load options (optional)\n * @returns Telemetry namespace (e.g., 'acmecorp_myapp' or 'myapp')\n */\nexport async function getTelemetryNamespace(options?: LoadIdentityOptions): Promise<string> {\n const identity = await loadIdentity(options);\n return identity.metadata?.telemetry_namespace ?? identity.app.binary_name;\n}\n\n/**\n * Get config identifiers for path construction\n *\n * Returns vendor and configName for building config paths like:\n * ~/.config/{vendor}/{configName}/config.yaml\n *\n * @param options - Load options (optional)\n * @returns Frozen config identifiers { vendor, configName }\n */\nexport async function getConfigIdentifiers(\n options?: LoadIdentityOptions,\n): Promise<ConfigIdentifiers> {\n const identity = await loadIdentity(options);\n return Object.freeze({\n vendor: identity.app.vendor,\n configName: identity.app.config_name,\n });\n}\n\n/**\n * Build environment variable name with app prefix\n *\n * Constructs env var names like: MYAPP_DATABASE_URL\n * Normalizes invalid characters (anything outside [A-Z0-9_]) to underscores\n * for conventional env var naming.\n *\n * Examples:\n * - 'database-url' → 'MYAPP_DATABASE_URL'\n * - 'my.config' → 'MYAPP_MY_CONFIG'\n * - 'log_level' → 'MYAPP_LOG_LEVEL'\n *\n * @param key - Environment variable key (will be uppercased and normalized)\n * @param options - Load options (optional)\n * @returns Full environment variable name (e.g., 'MYAPP_DATABASE_URL')\n */\nexport async function buildEnvVar(key: string, options?: LoadIdentityOptions): Promise<string> {\n const envPrefix = await getEnvPrefix(options);\n // Uppercase and replace any non-alphanumeric/underscore characters with underscores\n const normalizedKey = key.toUpperCase().replace(/[^A-Z0-9_]/g, \"_\");\n return `${envPrefix}${normalizedKey}`;\n}\n\n/**\n * Get environment variable value using app prefix\n *\n * Convenience wrapper around process.env using buildEnvVar\n *\n * @param key - Environment variable key (will be uppercased)\n * @param options - Load options (optional)\n * @returns Environment variable value or undefined\n */\nexport async function getEnvVar(\n key: string,\n options?: LoadIdentityOptions,\n): Promise<string | undefined> {\n const envVarName = await buildEnvVar(key, options);\n return process.env[envVarName];\n}\n","/**\n * HTTP Metrics Helpers\n *\n * Type-safe HTTP server instrumentation for Express, Fastify, Bun, and Node.js HTTP servers.\n * Implements Crucible v0.2.18 HTTP metrics taxonomy with automatic label injection,\n * unit conversion (ms → seconds), and cardinality protection.\n *\n * CRITICAL: Routes must be templated (/users/:id) to prevent cardinality explosion.\n * Use normalizeRoute() from route-normalizer.ts before calling recordHttpRequest().\n *\n * @example\n * ```typescript\n * import { recordHttpRequest, trackActiveRequest } from '@fulmenhq/tsfulmen/telemetry/http';\n *\n * // Manual instrumentation\n * const start = performance.now();\n * const release = trackActiveRequest('api-server');\n * try {\n * await handleRequest();\n * recordHttpRequest({\n * method: 'GET',\n * route: '/users/:id', // Pre-normalized\n * status: 200,\n * durationMs: performance.now() - start,\n * requestBytes: 512,\n * responseBytes: 2048,\n * });\n * } finally {\n * release();\n * }\n * ```\n */\n\nimport { getCachedIdentity } from \"../../appidentity/index.js\";\nimport { metrics } from \"../index.js\";\nimport type {\n GenericHttpRequest,\n GenericHttpResponse,\n MethodExtractor,\n NextFunction,\n RouteNormalizer,\n StatusExtractor,\n} from \"./types.js\";\n\n// Optional framework type imports - consumers need these as peer dependencies\ntype ExpressRequest = import(\"express\").Request;\ntype ExpressResponse = import(\"express\").Response;\ntype FastifyInstance = import(\"fastify\").FastifyInstance;\ntype FastifyRequest = import(\"fastify\").FastifyRequest;\ntype FastifyReply = import(\"fastify\").FastifyReply;\ntype FastifyPluginCallback = import(\"fastify\").FastifyPluginCallback;\n\n/**\n * HTTP request recording options\n */\nexport interface HttpRequestOptions {\n /**\n * HTTP method (GET, POST, PUT, DELETE, etc.)\n * REQUIRED label for all HTTP metrics\n */\n method: string;\n\n /**\n * Route template (e.g., /users/:id, not /users/123)\n * REQUIRED label for all HTTP metrics\n * CRITICAL: Must be normalized to prevent cardinality explosion\n */\n route: string;\n\n /**\n * HTTP status code (200, 404, 500, etc.)\n * REQUIRED label for http_requests_total, http_request_duration_seconds, http_response_size_bytes\n */\n status: number;\n\n /**\n * Request duration in milliseconds\n * Automatically converted to seconds for http_request_duration_seconds\n * REQUIRED for recording duration metric\n */\n durationMs: number;\n\n /**\n * Request body size in bytes (optional)\n * Records http_request_size_bytes histogram when provided\n */\n requestBytes?: number;\n\n /**\n * Response body size in bytes (optional)\n * Records http_response_size_bytes histogram when provided\n */\n responseBytes?: number;\n\n /**\n * Service name (optional, defaults to AppIdentity binary_name)\n * REQUIRED label for all HTTP metrics\n * Falls back to 'unknown' if AppIdentity not available\n */\n service?: string;\n}\n\n/**\n * Active request release function\n * Call to decrement http_active_requests gauge\n */\nexport type ActiveRequestRelease = () => void;\n\n/**\n * Record HTTP request metrics\n *\n * Records all applicable HTTP metrics from Crucible v0.2.18 taxonomy:\n * - http_requests_total (counter)\n * - http_request_duration_seconds (histogram, converted from ms)\n * - http_request_size_bytes (histogram, if requestBytes provided)\n * - http_response_size_bytes (histogram, if responseBytes provided)\n *\n * Auto-injects service label from AppIdentity if not provided.\n * Converts durationMs to seconds for duration metric.\n *\n * @param options - HTTP request recording options\n *\n * @example\n * ```typescript\n * recordHttpRequest({\n * method: 'GET',\n * route: '/users/:id',\n * status: 200,\n * durationMs: 45.2,\n * requestBytes: 512,\n * responseBytes: 2048,\n * service: 'api-server', // Optional, defaults to AppIdentity\n * });\n * ```\n */\nexport function recordHttpRequest(options: HttpRequestOptions): void {\n const {\n method,\n route,\n status,\n durationMs,\n requestBytes,\n responseBytes,\n service: providedService,\n } = options;\n\n // Resolve service name (AppIdentity fallback)\n const service = providedService || getServiceName();\n\n // Convert status to string for labels\n const statusStr = String(status);\n\n // Common labels for metrics requiring status\n const labelsWithStatus = {\n method,\n route,\n status: statusStr,\n service,\n };\n\n // Labels for metrics without status requirement\n const labelsWithoutStatus = {\n method,\n route,\n service,\n };\n\n // Record http_requests_total (counter)\n // Required labels: method, route, status, service\n metrics.counter(\"http_requests_total\").inc(1, labelsWithStatus);\n\n // Record http_request_duration_seconds (histogram)\n // CRITICAL: Convert milliseconds to seconds\n // Required labels: method, route, status, service\n const durationSeconds = durationMs / 1000;\n metrics.histogram(\"http_request_duration_seconds\").observe(durationSeconds, labelsWithStatus);\n\n // Record http_request_size_bytes (histogram, optional)\n // Required labels: method, route, service\n if (requestBytes !== undefined) {\n metrics.histogram(\"http_request_size_bytes\").observe(requestBytes, labelsWithoutStatus);\n }\n\n // Record http_response_size_bytes (histogram, optional)\n // Required labels: method, route, status, service\n if (responseBytes !== undefined) {\n metrics.histogram(\"http_response_size_bytes\").observe(responseBytes, labelsWithStatus);\n }\n}\n\n/**\n * Track active HTTP request\n *\n * Increments http_active_requests gauge and returns a release function.\n * Call the release function when the request completes to decrement the gauge.\n *\n * @param service - Service name (optional, defaults to AppIdentity binary_name)\n * @returns Release function to decrement gauge\n *\n * @example\n * ```typescript\n * const release = trackActiveRequest('api-server');\n * try {\n * await handleRequest();\n * } finally {\n * release(); // Always decrement, even on error\n * }\n * ```\n */\nexport function trackActiveRequest(service?: string): ActiveRequestRelease {\n const serviceName = service || getServiceName();\n const labels = { service: serviceName };\n\n // Increment gauge\n metrics.gauge(\"http_active_requests\").inc(1, labels);\n\n // Return release function to decrement\n return () => {\n metrics.gauge(\"http_active_requests\").dec(1, labels);\n };\n}\n\n/**\n * Middleware options for HTTP metrics collection\n */\nexport interface MiddlewareOptions {\n /**\n * Service name (optional, defaults to AppIdentity binary_name)\n */\n serviceName?: string;\n\n /**\n * Custom route normalizer function\n * Receives request object and returns normalized route\n * Defaults to basic normalization (framework-specific)\n *\n * @example\n * ```typescript\n * // Express: use route.path if available\n * routeNormalizer: (req) => req.route?.path || req.path\n *\n * // Custom normalization\n * routeNormalizer: (req) => normalizeRoute(req.path)\n * ```\n */\n routeNormalizer?: RouteNormalizer;\n\n /**\n * Custom method extractor (defaults to req.method)\n */\n methodExtractor?: MethodExtractor;\n\n /**\n * Custom status extractor (defaults to res.statusCode)\n */\n statusExtractor?: StatusExtractor;\n\n /**\n * Whether to track request/response body sizes (default: false)\n * May have performance impact for large bodies\n */\n trackBodySizes?: boolean;\n}\n\n/**\n * Create Express/Connect-compatible middleware for HTTP metrics\n *\n * Automatically instruments HTTP requests with metrics collection.\n * Compatible with Express, Connect, and similar frameworks using (req, res, next) signature.\n *\n * @param options - Middleware configuration options\n * @returns Express/Connect middleware function\n *\n * @example\n * ```typescript\n * import express from 'express';\n * import { createHttpMetricsMiddleware } from '@fulmenhq/tsfulmen/telemetry/http';\n *\n * const app = express();\n * app.use(createHttpMetricsMiddleware({\n * serviceName: 'api-server',\n * routeNormalizer: (req) => req.route?.path || req.path,\n * }));\n * ```\n */\nexport function createHttpMetricsMiddleware(options: MiddlewareOptions = {}) {\n const {\n serviceName,\n routeNormalizer = (req: GenericHttpRequest) => req.route?.path || req.path || \"unknown\",\n methodExtractor = (req: GenericHttpRequest) => req.method || \"UNKNOWN\",\n statusExtractor = (res: GenericHttpResponse) => res.statusCode || 0,\n trackBodySizes = false,\n } = options;\n\n return (req: ExpressRequest, res: ExpressResponse, next: NextFunction) => {\n const startTime = performance.now();\n const release = trackActiveRequest(serviceName);\n\n // Track request size if enabled\n const requestBytes =\n trackBodySizes && req.headers?.[\"content-length\"]\n ? Number.parseInt(req.headers[\"content-length\"], 10)\n : undefined;\n\n // Hook into response finish event\n const onFinish = () => {\n const durationMs = performance.now() - startTime;\n const method = methodExtractor(req);\n const route = routeNormalizer(req);\n const status = statusExtractor(res);\n\n // Track response size if enabled\n const responseBytes =\n trackBodySizes && res.getHeader?.(\"content-length\")\n ? Number.parseInt(String(res.getHeader(\"content-length\")), 10)\n : undefined;\n\n recordHttpRequest({\n method,\n route,\n status,\n durationMs,\n requestBytes,\n responseBytes,\n service: serviceName,\n });\n\n release();\n cleanup();\n };\n\n const onError = () => {\n release();\n cleanup();\n };\n\n const cleanup = () => {\n res.off?.(\"finish\", onFinish);\n res.off?.(\"error\", onError);\n res.off?.(\"close\", onError);\n };\n\n // Attach listeners\n res.on?.(\"finish\", onFinish);\n res.on?.(\"error\", onError);\n res.on?.(\"close\", onError);\n\n next();\n };\n}\n\n/**\n * Create Fastify plugin for HTTP metrics\n *\n * Fastify-compatible plugin for automatic HTTP metrics collection.\n *\n * @param options - Middleware configuration options\n * @returns Fastify plugin function\n *\n * @example\n * ```typescript\n * import Fastify from 'fastify';\n * import { createFastifyMetricsPlugin } from '@fulmenhq/tsfulmen/telemetry/http';\n *\n * const fastify = Fastify();\n * fastify.register(createFastifyMetricsPlugin({\n * serviceName: 'fastify-api',\n * routeNormalizer: (req) => req.routeOptions?.url || req.url,\n * }));\n * ```\n */\nexport function createFastifyMetricsPlugin(options: MiddlewareOptions = {}) {\n const {\n serviceName,\n routeNormalizer = (req: GenericHttpRequest) => req.routeOptions?.url || req.url || \"unknown\",\n methodExtractor = (req: GenericHttpRequest) => req.method || \"UNKNOWN\",\n } = options;\n\n const plugin: FastifyPluginCallback = (\n fastify: FastifyInstance,\n _opts: unknown,\n done: (err?: Error) => void,\n ) => {\n fastify.addHook(\"onRequest\", async (req: FastifyRequest, _reply: FastifyReply) => {\n // Store start time and release function in request context\n // biome-ignore lint/suspicious/noExplicitAny: Runtime property injection for metrics tracking\n (req as any).metricsStartTime = performance.now();\n // biome-ignore lint/suspicious/noExplicitAny: Runtime property injection for metrics tracking\n (req as any).metricsRelease = trackActiveRequest(serviceName);\n });\n\n fastify.addHook(\"onResponse\", async (req: FastifyRequest, reply: FastifyReply) => {\n // biome-ignore lint/suspicious/noExplicitAny: Runtime property access for metrics tracking\n const durationMs = performance.now() - (req as any).metricsStartTime;\n const method = methodExtractor(req);\n const route = routeNormalizer(req);\n const status = reply.statusCode || 0;\n\n recordHttpRequest({\n method,\n route,\n status,\n durationMs,\n service: serviceName,\n });\n\n // biome-ignore lint/suspicious/noExplicitAny: Runtime property access for metrics tracking\n (req as any).metricsRelease?.();\n });\n\n // Handle errors/close\n fastify.addHook(\"onError\", async (req: FastifyRequest, _reply: FastifyReply, _error: Error) => {\n // biome-ignore lint/suspicious/noExplicitAny: Runtime property access for metrics tracking\n (req as any).metricsRelease?.();\n });\n\n done();\n };\n\n return plugin;\n}\n\n/**\n * Create Bun.serve fetch handler wrapper for HTTP metrics\n *\n * Wraps a Bun.serve fetch handler with automatic HTTP metrics collection.\n *\n * @param handler - Original fetch handler\n * @param options - Middleware configuration options\n * @returns Wrapped fetch handler with metrics\n *\n * @example\n * ```typescript\n * import { createBunMetricsHandler } from '@fulmenhq/tsfulmen/telemetry/http';\n *\n * Bun.serve({\n * fetch: createBunMetricsHandler(async (req) => {\n * return new Response(\"Hello World\");\n * }, {\n * serviceName: 'bun-api',\n * routeNormalizer: (req) => new URL(req.url).pathname,\n * }),\n * });\n * ```\n */\nexport function createBunMetricsHandler(\n handler: (req: Request) => Response | Promise<Response>,\n options: MiddlewareOptions = {},\n) {\n const {\n serviceName,\n routeNormalizer: customNormalizer,\n methodExtractor: customExtractor,\n } = options;\n\n // Type-safe defaults for Bun Request\n const routeNormalizer =\n customNormalizer ||\n ((req: GenericHttpRequest) => {\n const url = (req as unknown as Request).url;\n return new URL(url).pathname;\n });\n const methodExtractor =\n customExtractor ||\n ((req: GenericHttpRequest) => {\n return (req as unknown as Request).method;\n });\n\n return async (req: Request): Promise<Response> => {\n const startTime = performance.now();\n const release = trackActiveRequest(serviceName);\n\n try {\n const response = await handler(req);\n const durationMs = performance.now() - startTime;\n // Cast to GenericHttpRequest for extractors\n const method = methodExtractor(req as unknown as GenericHttpRequest);\n const route = routeNormalizer(req as unknown as GenericHttpRequest);\n const status = response.status;\n\n recordHttpRequest({\n method,\n route,\n status,\n durationMs,\n service: serviceName,\n });\n\n release();\n return response;\n } catch (error) {\n release();\n throw error;\n }\n };\n}\n\n/**\n * Get service name from AppIdentity or fallback to 'unknown'\n * @internal\n */\nfunction getServiceName(): string {\n try {\n const identity = getCachedIdentity();\n if (identity?.app?.binary_name) {\n return identity.app.binary_name;\n }\n } catch {\n // AppIdentity not loaded or available, use fallback\n }\n return \"unknown\";\n}\n\nexport type { NormalizeOptions } from \"./route-normalizer.js\";\n// Re-export route normalization utilities for convenience\nexport { normalizeRoute } from \"./route-normalizer.js\";\n","/**\n * Route normalization utilities for HTTP metrics\n *\n * Prevents cardinality explosion by converting actual paths to templated routes.\n * Example: /users/123 → /users/:id\n *\n * CRITICAL: High cardinality routes will overwhelm Prometheus and break monitoring.\n * Always normalize routes before recording HTTP metrics.\n */\n\n/**\n * Route normalization options\n */\nexport interface NormalizeOptions {\n /**\n * Optional explicit template to use instead of auto-detection\n * Example: \"/api/v1/orders/:orderId/items/:itemId\"\n */\n template?: string;\n\n /**\n * Whether to preserve trailing slashes (default: false, strips them)\n */\n preserveTrailingSlash?: boolean;\n\n /**\n * Custom segment replacements (segment index → placeholder name)\n * Example: { 2: \"userId\", 4: \"itemId\" } for /api/v1/users/:userId/items/:itemId\n */\n segmentReplacements?: Record<number, string>;\n\n /**\n * Use context-aware placeholder names (default: true)\n * When true: /users/123 → /users/:userId\n * When false: /users/123 → /users/:id\n */\n useContextAwarePlaceholders?: boolean;\n}\n\n/**\n * Common static route segments that should never be normalized\n * (API resources, actions, settings pages, etc.)\n */\nconst STATIC_SEGMENTS = new Set([\n // Common API resources/collections\n \"api\",\n \"users\",\n \"posts\",\n \"articles\",\n \"items\",\n \"products\",\n \"orders\",\n \"accounts\",\n \"profiles\",\n \"comments\",\n \"reviews\",\n \"files\",\n \"docs\",\n \"auth\",\n \"admin\",\n \"settings\",\n \"config\",\n \"metrics\",\n \"health\",\n \"status\",\n \"search\",\n \"upload\",\n \"download\",\n // Common actions\n \"create\",\n \"update\",\n \"delete\",\n \"list\",\n \"show\",\n \"edit\",\n \"new\",\n // Common settings/config sections\n \"notifications\",\n \"preferences\",\n \"billing\",\n \"security\",\n \"privacy\",\n \"profile\",\n \"account\",\n \"dashboard\",\n // API versioning\n \"v1\",\n \"v2\",\n \"v3\",\n \"v4\",\n // Content sections\n \"blog\",\n \"wiki\",\n \"guides\",\n \"guide\",\n \"help\",\n \"faq\",\n \"about\",\n \"contact\",\n \"terms\",\n \"custom\",\n \"verify\",\n]);\n\n/**\n * Pattern matchers for common ID formats\n */\nconst ID_PATTERNS = {\n /** UUID v4: 550e8400-e29b-41d4-a716-446655440000 */\n uuid: /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,\n\n /** Numeric ID: 123, 456789 */\n numeric: /^\\d+$/,\n\n /** MongoDB ObjectId: 507f1f77bcf86cd799439011 */\n objectId: /^[0-9a-f]{24}$/i,\n\n /** Nanoid/CUID: cjld2cjxh0000qzrmn831i7rn */\n nanoid: /^[0-9a-z_-]{20,30}$/i,\n\n /** Alphanumeric slug with hyphens: my-article-title, user-profile-2024 */\n slug: /^[a-z0-9]+(-[a-z0-9]+)+$/i,\n\n /** Base64-like (16+ chars, mixed case OR padding): YWJjZGVmZ2hpamtsbW5v or dGVzdA== */\n base64: /^(?=.*[A-Z])(?=.*[a-z])[A-Za-z0-9+/]{16,}={0,2}$|^[A-Za-z0-9+/]{16,}={1,2}$/,\n\n /** Short alphanumeric IDs with mixed chars: abc123, xyz789 (must contain both letters AND numbers) */\n shortId: /^(?=.*[a-z])(?=.*[0-9])[a-z0-9]{3,12}$/i,\n};\n\n/**\n * Detect if a path segment looks like a dynamic parameter\n */\nfunction isDynamicSegment(segment: string): boolean {\n // Already a parameter placeholder\n if (segment.startsWith(\":\") || segment === \"*\") {\n return true;\n }\n\n // Empty segment\n if (!segment) {\n return false;\n }\n\n // Check if it's a known static segment\n if (STATIC_SEGMENTS.has(segment.toLowerCase())) {\n return false;\n }\n\n // Check against known ID patterns\n // Order matters: check more specific patterns first\n return (\n ID_PATTERNS.uuid.test(segment) ||\n ID_PATTERNS.numeric.test(segment) ||\n ID_PATTERNS.objectId.test(segment) ||\n ID_PATTERNS.slug.test(segment) ||\n ID_PATTERNS.base64.test(segment) || // Check before nanoid (more specific)\n ID_PATTERNS.nanoid.test(segment) ||\n ID_PATTERNS.shortId.test(segment) // Check last (most permissive)\n );\n}\n\n/**\n * Infer placeholder name from context\n */\nfunction inferPlaceholderName(\n segment: string,\n index: number,\n segments: string[],\n useContextAware = true,\n): string {\n // UUID → :id\n if (ID_PATTERNS.uuid.test(segment)) {\n return \"id\";\n }\n\n // MongoDB ObjectId → :id\n if (ID_PATTERNS.objectId.test(segment)) {\n return \"id\";\n }\n\n // Numeric → :id (context-aware if enabled)\n if (ID_PATTERNS.numeric.test(segment)) {\n if (!useContextAware) {\n return \"id\";\n }\n // Look at previous segment for context\n const prev = segments[index - 1]?.toLowerCase();\n if (prev === \"users\" || prev === \"accounts\" || prev === \"profiles\") {\n return \"userId\";\n }\n if (prev === \"posts\" || prev === \"articles\") {\n return \"postId\";\n }\n if (prev === \"orders\") {\n return \"orderId\";\n }\n if (prev === \"items\" || prev === \"products\") {\n return \"itemId\";\n }\n return \"id\";\n }\n\n // Slug pattern → :slug\n if (ID_PATTERNS.slug.test(segment)) {\n return \"slug\";\n }\n\n // Base64 → :token (check BEFORE nanoid which is less specific)\n if (ID_PATTERNS.base64.test(segment)) {\n return \"token\";\n }\n\n // Nanoid/CUID → :id\n if (ID_PATTERNS.nanoid.test(segment)) {\n return \"id\";\n }\n\n // Short alphanumeric ID → context-aware or :id\n // Note: Check this AFTER base64 since base64 also has letters+numbers\n if (ID_PATTERNS.shortId.test(segment)) {\n if (!useContextAware) {\n return \"id\";\n }\n // Check previous segment for context\n const prev = segments[index - 1]?.toLowerCase();\n if (prev === \"orders\") {\n return \"orderId\";\n }\n if (prev === \"items\" || prev === \"products\") {\n return \"itemId\";\n }\n if (prev === \"reviews\") {\n return \"id\";\n }\n return \"id\";\n }\n\n // Already-normalized placeholder - preserve the name\n if (segment.startsWith(\":\")) {\n return segment.slice(1); // Remove the : prefix\n }\n\n // Wildcard - preserve as-is\n if (segment === \"*\") {\n return \"*\";\n }\n\n // Fallback for unknown dynamic segments\n return \"param\";\n}\n\n/**\n * Normalize an HTTP route path to prevent cardinality explosion\n *\n * Converts actual paths with IDs/slugs to templated routes:\n * - /users/123 → /users/:id\n * - /api/v1/orders/abc-123/items/456 → /api/v1/orders/:orderId/items/:itemId\n * - /articles/my-article-title → /articles/:slug\n *\n * @param path - The actual request path\n * @param options - Normalization options\n * @returns Normalized route template\n *\n * @example\n * ```typescript\n * normalizeRoute('/users/123'); // '/users/:id'\n * normalizeRoute('/api/v1/orders/abc/items/456'); // '/api/v1/orders/:id/items/:id'\n * normalizeRoute('/posts/my-title', { template: '/posts/:slug' }); // '/posts/:slug'\n * ```\n */\nexport function normalizeRoute(path: string, options: NormalizeOptions = {}): string {\n // Use explicit template if provided\n if (options.template) {\n return options.template;\n }\n\n // Handle empty or root\n if (!path || path === \"/\") {\n return \"/\";\n }\n\n // Strip query params and fragments\n let cleanPath = path.split(\"?\")[0].split(\"#\")[0];\n\n // Track if path had trailing slash\n const hadTrailingSlash = cleanPath.endsWith(\"/\") && cleanPath !== \"/\";\n\n // Strip trailing slash for processing\n if (cleanPath.endsWith(\"/\") && cleanPath !== \"/\") {\n cleanPath = cleanPath.slice(0, -1);\n }\n\n // Split into segments\n const segments = cleanPath.split(\"/\").filter(Boolean);\n\n // Process each segment\n const normalized = segments.map((segment, index) => {\n // Check for explicit segment replacement\n if (options.segmentReplacements?.[index]) {\n return `:${options.segmentReplacements[index]}`;\n }\n\n // Keep wildcards as-is\n if (segment === \"*\") {\n return \"*\";\n }\n\n // Check if segment is dynamic\n if (isDynamicSegment(segment)) {\n const placeholder = inferPlaceholderName(\n segment,\n index,\n segments,\n options.useContextAwarePlaceholders ?? true,\n );\n // Don't re-wrap if already a placeholder\n return placeholder === \"*\" ? \"*\" : `:${placeholder}`;\n }\n\n // Keep static segment as-is\n return segment;\n });\n\n // Reconstruct path\n let result = `/${normalized.join(\"/\")}`;\n\n // Re-add trailing slash if requested and original had one\n if (options.preserveTrailingSlash && hadTrailingSlash) {\n result += \"/\";\n }\n\n return result;\n}\n\n/**\n * Batch normalize multiple routes\n */\nexport function normalizeRoutes(paths: string[], options: NormalizeOptions = {}): string[] {\n return paths.map((path) => normalizeRoute(path, options));\n}\n\n/**\n * Check if a route has high cardinality risk\n *\n * Returns true if the route contains segments that look like dynamic values\n * but haven't been normalized yet.\n */\nexport function hasCardinalityRisk(route: string): boolean {\n if (!route || route === \"/\") {\n return false;\n }\n\n const segments = route.split(\"/\").filter(Boolean);\n return segments.some((segment) => {\n // Already normalized\n if (segment.startsWith(\":\") || segment === \"*\") {\n return false;\n }\n\n // Check for dynamic patterns\n return isDynamicSegment(segment);\n });\n}\n\n/**\n * Estimate cardinality of a route\n *\n * Returns approximate number of unique routes this pattern could generate.\n * Used for capacity planning and alerting on high-cardinality routes.\n */\nexport function estimateCardinality(route: string): number {\n if (!route || route === \"/\") {\n return 1;\n }\n\n const segments = route.split(\"/\").filter(Boolean);\n let cardinality = 1;\n\n for (const segment of segments) {\n if (segment.startsWith(\":\")) {\n // Parameter could be infinite values, use conservative estimate\n cardinality *= 1000;\n } else if (segment === \"*\") {\n // Wildcard could match many paths\n cardinality *= 100;\n }\n // Static segments don't multiply cardinality\n }\n\n return cardinality;\n}\n"]}
1
+ {"version":3,"sources":["../../../src/appidentity/constants.ts","../../../src/schema/ajv-formats.ts","../../../src/schema/errors.ts","../../../src/schema/utils.ts","../../../src/schema/goneat-bridge.ts","../../../src/schema/normalizer.ts","../../../src/schema/registry.ts","../../../src/telemetry/counter.ts","../../../src/telemetry/gauge.ts","../../../src/telemetry/taxonomy.ts","../../../src/telemetry/histogram.ts","../../../src/telemetry/registry.ts","../../../src/telemetry/types.ts","../../../src/telemetry/validators.ts","../../../src/telemetry/index.ts","../../../src/schema/validator.ts","../../../src/schema/cli.ts","../../../src/schema/export.ts","../../../src/schema/index.ts","../../../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","../../../src/appidentity/errors.ts","../../../src/appidentity/embedded.ts","../../../src/appidentity/cache.ts","../../../src/appidentity/discovery.ts","../../../src/appidentity/loader.ts","../../../src/appidentity/runtime.ts","../../../src/appidentity/index.ts","../../../src/appidentity/helpers.ts","../../../src/telemetry/http/index.ts","../../../src/telemetry/http/route-normalizer.ts"],"names":["join","readFile","parseYaml","init_registry","init_validators","init_errors"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Application Identity Constants\n *\n * Centralized configuration for identity discovery and validation\n */\n\n/**\n * Filename for identity document\n */\nexport const APP_IDENTITY_FILENAME = \"app.yaml\";\n\n/**\n * Directory containing identity file\n */\nexport const APP_IDENTITY_DIR = \".fulmen\";\n\n/**\n * Environment variable for explicit path override\n */\nexport const APP_IDENTITY_ENV_VAR = \"FULMEN_APP_IDENTITY_PATH\";\n\n/**\n * Schema ID for validation\n */\nexport const APP_IDENTITY_SCHEMA_ID = \"config/repository/app-identity/v1.0.0/app-identity\";\n\n/**\n * Maximum depth for ancestor directory search\n * Prevents infinite loops and excessive filesystem traversal\n */\nexport const MAX_ANCESTOR_SEARCH_DEPTH = 20;\n","import type Ajv from \"ajv\";\nimport addFormats from \"ajv-formats\";\n\nexport interface FulmenAjvFormatsOptions {\n mode?: \"fast\" | \"full\";\n formats?: string[];\n}\n\nconst DEFAULT_FORMATS = [\n \"date-time\",\n \"email\",\n \"hostname\",\n \"ipv4\",\n \"ipv6\",\n \"uri\",\n \"uri-reference\",\n \"uuid\",\n];\n\n/**\n * Apply Fulmen-standard AJV format support.\n *\n * Useful when configuring AJV in other frameworks (e.g. Fastify) so JSON Schema\n * `format` keywords are enforced consistently.\n */\nexport function applyFulmenAjvFormats(ajv: Ajv, options: FulmenAjvFormatsOptions = {}): Ajv {\n const mode = options.mode ?? \"fast\";\n const formats = options.formats ?? DEFAULT_FORMATS;\n\n // ajv-formats types use a string-literal union; allow callers to supply strings.\n // The `as never` on ajv works around ajv-formats bundling its own older ajv types\n // that diverge from ajv@8.18+ (CodeKeywordDefinition.code parameter incompatibility).\n addFormats(ajv as never, { mode, formats: formats as unknown as never[] });\n return ajv;\n}\n","/**\n * Schema validation errors - implements Fulmen Schema Validation Standard\n */\n\nimport type { SchemaSource, SchemaValidationDiagnostic } from \"./types.js\";\n\n/**\n * Export error reason enum for type-safe error categorization\n */\nexport enum ExportErrorReason {\n FILE_EXISTS = \"FILE_EXISTS\",\n WRITE_FAILED = \"WRITE_FAILED\",\n INVALID_FORMAT = \"INVALID_FORMAT\",\n PROVENANCE_FAILED = \"PROVENANCE_FAILED\",\n UNKNOWN = \"UNKNOWN\",\n}\n\n/**\n * Base error class for schema validation operations\n */\nexport class SchemaValidationError extends Error {\n constructor(\n message: string,\n public schemaId?: string,\n public diagnostics: SchemaValidationDiagnostic[] = [],\n public source?: SchemaSource,\n public cause?: Error,\n ) {\n super(message);\n this.name = \"SchemaValidationError\";\n\n // Maintains proper stack trace for where our error was thrown (only available on V8)\n if (Error.captureStackTrace) {\n Error.captureStackTrace(this, SchemaValidationError);\n }\n }\n\n /**\n * Create error for schema not found\n */\n static schemaNotFound(schemaId: string): SchemaValidationError {\n return new SchemaValidationError(`Schema not found: ${schemaId}`, schemaId);\n }\n\n /**\n * Create error for invalid schema input\n */\n static invalidSchemaInput(source: SchemaSource, details: string): SchemaValidationError {\n return new SchemaValidationError(`Invalid schema input: ${details}`, undefined, [], source);\n }\n\n /**\n * Create error for validation failure\n */\n static validationFailed(\n schemaId: string,\n diagnostics: SchemaValidationDiagnostic[],\n source?: SchemaSource,\n ): SchemaValidationError {\n const errorCount = diagnostics.filter((d) => d.severity === \"ERROR\").length;\n const warningCount = diagnostics.filter((d) => d.severity === \"WARN\").length;\n\n const message = `Schema validation failed: ${errorCount} error(s), ${warningCount} warning(s)`;\n\n return new SchemaValidationError(message, schemaId, diagnostics, source);\n }\n\n /**\n * Create error for goneat binary not found\n */\n static goneatNotFound(goneatPath?: string): SchemaValidationError {\n const pathInfo = goneatPath ? ` at ${goneatPath}` : \"\";\n return new SchemaValidationError(\n `Goneat binary not found${pathInfo}. Falling back to AJV validation.`,\n );\n }\n\n /**\n * Create error for goneat execution failure\n */\n static goneatExecutionFailed(error: Error): SchemaValidationError {\n return new SchemaValidationError(\n \"Goneat execution failed. Falling back to AJV validation.\",\n undefined,\n [],\n undefined,\n error,\n );\n }\n\n /**\n * Create error for empty schema input\n */\n static emptySchemaInput(source?: SchemaSource): SchemaValidationError {\n return new SchemaValidationError(\"Schema content is empty\", undefined, [], source);\n }\n\n /**\n * Create error for parse failure\n */\n static parseFailed(source: SchemaSource, error: Error): SchemaValidationError {\n return new SchemaValidationError(\n `Failed to parse schema: ${error.message}`,\n undefined,\n [],\n source,\n error,\n );\n }\n\n /**\n * Create error for encoding failure\n */\n static encodingFailed(source: SchemaSource, error: Error): SchemaValidationError {\n return new SchemaValidationError(\n `Failed to encode schema: ${error.message}`,\n undefined,\n [],\n source,\n error,\n );\n }\n\n /**\n * Create error for registry operation failure\n */\n static registryError(operation: string, details: string): SchemaValidationError {\n return new SchemaValidationError(`Schema registry ${operation} failed: ${details}`);\n }\n\n /**\n * Format error for display\n */\n format(): string {\n let output = this.message;\n\n if (this.schemaId) {\n output += `\\nSchema ID: ${this.schemaId}`;\n }\n\n if (this.diagnostics.length > 0) {\n output += \"\\n\\nValidation Issues:\";\n this.diagnostics.forEach((diag, index) => {\n output += `\\n ${index + 1}. [${diag.severity}] ${diag.message}`;\n if (diag.pointer) {\n output += ` at ${diag.pointer}`;\n }\n if (diag.keyword) {\n output += ` (keyword: ${diag.keyword})`;\n }\n if (diag.source) {\n output += ` [${diag.source}]`;\n }\n });\n }\n\n if (this.source) {\n output += `\\n\\nSource: ${this.source.type}`;\n if (this.source.id) {\n output += ` (${this.source.id})`;\n }\n }\n\n return output;\n }\n\n /**\n * Convert to JSON representation\n */\n toJSON(): {\n name: string;\n message: string;\n schemaId?: string;\n diagnostics: SchemaValidationDiagnostic[];\n source?: SchemaSource;\n cause?: string;\n } {\n return {\n name: this.name,\n message: this.message,\n schemaId: this.schemaId,\n diagnostics: this.diagnostics,\n source: this.source,\n cause: this.cause?.message,\n };\n }\n}\n\n/**\n * Error class for schema export operations\n */\nexport class SchemaExportError extends SchemaValidationError {\n constructor(\n message: string,\n public reason: ExportErrorReason,\n public schemaId?: string,\n public outPath?: string,\n public cause?: Error,\n ) {\n super(message, schemaId, [], undefined, cause);\n this.name = \"SchemaExportError\";\n\n if (Error.captureStackTrace) {\n Error.captureStackTrace(this, SchemaExportError);\n }\n }\n\n /**\n * Create error for file already exists\n */\n static fileExists(outPath: string): SchemaExportError {\n return new SchemaExportError(\n `Output file already exists: ${outPath}. Use overwrite option to replace.`,\n ExportErrorReason.FILE_EXISTS,\n undefined,\n outPath,\n );\n }\n\n /**\n * Create error for invalid export format\n */\n static invalidFormat(format: string, outPath: string): SchemaExportError {\n return new SchemaExportError(\n `Invalid export format: ${format}. Must be 'json' or 'yaml'.`,\n ExportErrorReason.INVALID_FORMAT,\n undefined,\n outPath,\n );\n }\n\n /**\n * Create error for write failure\n */\n static writeFailed(outPath: string, error: Error): SchemaExportError {\n return new SchemaExportError(\n `Failed to write schema to ${outPath}: ${error.message}`,\n ExportErrorReason.WRITE_FAILED,\n undefined,\n outPath,\n error,\n );\n }\n\n /**\n * Create error for provenance extraction failure\n */\n static provenanceFailed(details: string, error?: Error): SchemaExportError {\n return new SchemaExportError(\n `Failed to extract provenance metadata: ${details}`,\n ExportErrorReason.PROVENANCE_FAILED,\n undefined,\n undefined,\n error,\n );\n }\n}\n","/**\n * Schema validation utilities - helper functions for formatting and validation\n */\n\nimport { SchemaValidationError } from \"./errors.js\";\nimport type { SchemaValidationDiagnostic, SchemaValidationResult } from \"./types.js\";\n\n/**\n * Format validation diagnostics for display\n */\nexport function formatDiagnostics(diagnostics: SchemaValidationDiagnostic[]): string {\n if (diagnostics.length === 0) {\n return \"No validation issues found.\";\n }\n\n const lines: string[] = [];\n const errors = diagnostics.filter((d) => d.severity === \"ERROR\");\n const warnings = diagnostics.filter((d) => d.severity === \"WARN\");\n\n if (errors.length > 0) {\n lines.push(`❌ ${errors.length} error(s) found:`);\n errors.forEach((diag, index) => {\n lines.push(` ${index + 1}. ${diag.message}`);\n if (diag.pointer) {\n lines.push(` at ${diag.pointer}`);\n }\n if (diag.keyword) {\n lines.push(` keyword: ${diag.keyword}`);\n }\n });\n }\n\n if (warnings.length > 0) {\n lines.push(\"\");\n lines.push(`⚠️ ${warnings.length} warning(s) found:`);\n warnings.forEach((diag, index) => {\n lines.push(` ${index + 1}. ${diag.message}`);\n if (diag.pointer) {\n lines.push(` at ${diag.pointer}`);\n }\n });\n }\n\n return lines.join(\"\\n\");\n}\n\n/**\n * Format validation result for display\n */\nexport function formatValidationResult(result: SchemaValidationResult): string {\n if (result.valid) {\n return \"✅ Validation passed\";\n }\n\n const output: string[] = [];\n output.push(\"❌ Validation failed\");\n output.push(formatDiagnostics(result.diagnostics));\n output.push(`\\nSource: ${result.source}`);\n\n return output.join(\"\\n\");\n}\n\n/**\n * Check if value is a SchemaValidationError\n */\nexport function isValidationError(error: unknown): error is SchemaValidationError {\n return error instanceof SchemaValidationError;\n}\n\n/**\n * Extract validation result from error or return success\n */\nexport function extractValidationResult(error: unknown): {\n valid: boolean;\n diagnostics: SchemaValidationDiagnostic[];\n source: \"ajv\" | \"goneat\";\n} {\n if (isValidationError(error)) {\n return {\n valid: false,\n diagnostics: error.diagnostics,\n source: error.diagnostics[0]?.source || \"ajv\",\n };\n }\n\n return {\n valid: true,\n diagnostics: [],\n source: \"ajv\",\n };\n}\n\n/**\n * Normalize JSON pointer path for display\n */\nexport function normalizePointer(pointer: string): string {\n if (pointer === \"\") {\n return \"root\";\n }\n return pointer.replace(/^\\//, \"\").replace(/\\//g, \".\");\n}\n\n/**\n * Create a validation diagnostic\n */\nexport function createDiagnostic(\n pointer: string,\n message: string,\n keyword: string,\n severity: \"ERROR\" | \"WARN\" = \"ERROR\",\n source: \"ajv\" | \"goneat\" = \"ajv\",\n data?: unknown,\n): SchemaValidationDiagnostic {\n return {\n pointer,\n message,\n keyword,\n severity,\n source,\n data,\n };\n}\n\n/**\n * Group diagnostics by severity\n */\nexport function groupDiagnosticsBySeverity(diagnostics: SchemaValidationDiagnostic[]): {\n errors: SchemaValidationDiagnostic[];\n warnings: SchemaValidationDiagnostic[];\n} {\n return {\n errors: diagnostics.filter((d) => d.severity === \"ERROR\"),\n warnings: diagnostics.filter((d) => d.severity === \"WARN\"),\n };\n}\n\n/**\n * Count diagnostics by severity\n */\nexport function countDiagnostics(diagnostics: SchemaValidationDiagnostic[]): {\n total: number;\n errors: number;\n warnings: number;\n} {\n const grouped = groupDiagnosticsBySeverity(diagnostics);\n return {\n total: diagnostics.length,\n errors: grouped.errors.length,\n warnings: grouped.warnings.length,\n };\n}\n","/**\n * Goneat bridge - Optional integration for CLI-only goneat validation\n *\n * Provides goneat validation as an opt-in alternative for CLI exploration.\n * NOT used by library consumers - AJV validation is the primary implementation.\n */\n\nimport { spawn } from \"node:child_process\";\nimport { access } from \"node:fs/promises\";\nimport type { SchemaValidationDiagnostic, SchemaValidationResult } from \"./types.js\";\nimport { createDiagnostic } from \"./utils.js\";\n\n/**\n * Goneat validation output structure\n */\ninterface GoneatValidationOutput {\n valid: boolean;\n errors?: Array<{\n path: string;\n message: string;\n keyword?: string;\n }>;\n}\n\n/**\n * Detect goneat binary location\n */\nexport async function detectGoneat(customPath?: string): Promise<string | null> {\n // Try custom path first\n if (customPath) {\n try {\n await access(customPath);\n return customPath;\n } catch {\n return null;\n }\n }\n\n // Try GONEAT_PATH environment variable\n if (process.env.GONEAT_PATH) {\n try {\n await access(process.env.GONEAT_PATH);\n return process.env.GONEAT_PATH;\n } catch {\n // Continue to next option\n }\n }\n\n // Try local bin/goneat\n try {\n await access(\"./bin/goneat\");\n return \"./bin/goneat\";\n } catch {\n // Continue to next option\n }\n\n // Try system PATH (assume 'goneat' command available)\n return \"goneat\";\n}\n\n/**\n * Check if goneat is available\n *\n * If goneatPath is provided, use it directly to test availability.\n * Otherwise, detect goneat location first.\n */\nexport async function isGoneatAvailable(goneatPath?: string): Promise<boolean> {\n let pathToTest: string | null;\n\n if (goneatPath) {\n // Use provided path directly - don't re-detect\n // This allows testing 'goneat' command from PATH\n pathToTest = goneatPath;\n } else {\n // Detect goneat location\n pathToTest = await detectGoneat();\n if (!pathToTest) return false;\n }\n\n return new Promise((resolve) => {\n const proc = spawn(pathToTest as string, [\"version\"], { stdio: \"ignore\" });\n\n // Timeout after 5 seconds to prevent hanging in CI\n const timeout = setTimeout(() => {\n proc.kill();\n resolve(false);\n }, 5000);\n\n proc.on(\"close\", (code) => {\n clearTimeout(timeout);\n resolve(code === 0);\n });\n proc.on(\"error\", () => {\n clearTimeout(timeout);\n resolve(false);\n });\n });\n}\n\n/**\n * Run goneat schema validation (CLI-only, opt-in)\n *\n * This is NOT used by library validation - it's purely for CLI comparison.\n * Library users get full AJV validation without goneat dependency.\n */\nexport async function runGoneatValidation(\n schemaPath: string,\n dataPath: string,\n goneatPath?: string,\n): Promise<SchemaValidationResult> {\n const detected = await detectGoneat(goneatPath);\n\n if (!detected) {\n return {\n valid: false,\n diagnostics: [\n createDiagnostic(\n \"\",\n \"goneat binary not found. Install goneat or specify path with --goneat-path\",\n \"goneat-unavailable\",\n \"ERROR\",\n \"goneat\",\n ),\n ],\n source: \"goneat\",\n };\n }\n\n // Check availability using the detected path directly\n if (!(await isGoneatAvailable(detected))) {\n return {\n valid: false,\n diagnostics: [\n createDiagnostic(\n \"\",\n `goneat binary found at '${detected}' but not executable or version check failed`,\n \"goneat-not-executable\",\n \"ERROR\",\n \"goneat\",\n ),\n ],\n source: \"goneat\",\n };\n }\n\n return new Promise((resolve) => {\n const args = [\n \"schema\",\n \"validate\",\n \"--schema\",\n schemaPath,\n \"--data\",\n dataPath,\n \"--format\",\n \"json\",\n ];\n const proc = spawn(detected, args);\n\n let stdout = \"\";\n let stderr = \"\";\n\n proc.stdout.on(\"data\", (data) => {\n stdout += data.toString();\n });\n\n proc.stderr.on(\"data\", (data) => {\n stderr += data.toString();\n });\n\n proc.on(\"close\", (code: number | null) => {\n // Parse goneat output\n let output: GoneatValidationOutput;\n\n try {\n output = JSON.parse(stdout) as GoneatValidationOutput;\n } catch {\n // Failed to parse output, treat as error\n resolve({\n valid: false,\n diagnostics: [\n createDiagnostic(\n \"\",\n `goneat validation failed: ${stderr || \"unknown error\"}`,\n \"goneat-error\",\n \"ERROR\",\n \"goneat\",\n ),\n ],\n source: \"goneat\",\n });\n return;\n }\n\n // Convert goneat errors to our diagnostic format\n const diagnostics: SchemaValidationDiagnostic[] =\n output.errors?.map((error) =>\n createDiagnostic(\n error.path || \"\",\n error.message,\n error.keyword || \"validation\",\n \"ERROR\",\n \"goneat\",\n ),\n ) || [];\n\n resolve({\n valid: code === 0 && output.valid,\n diagnostics,\n source: \"goneat\",\n });\n });\n\n proc.on(\"error\", (error) => {\n resolve({\n valid: false,\n diagnostics: [\n createDiagnostic(\n \"\",\n `Failed to execute goneat: ${error.message}`,\n \"goneat-spawn-error\",\n \"ERROR\",\n \"goneat\",\n ),\n ],\n source: \"goneat\",\n });\n });\n });\n}\n","/**\n * Schema normalizer - implements schema normalization per Fulmen standard\n *\n * Provides utilities for canonicalizing and comparing schemas across\n * JSON and YAML formats with comment preservation and deterministic output.\n */\n\nimport { parse as parseYAML } from \"yaml\";\nimport { SchemaValidationError } from \"./errors.js\";\nimport type { SchemaInput, SchemaNormalizationOptions } from \"./types.js\";\n\n/**\n * Parse schema input to object\n */\nfunction parseSchemaInput(input: SchemaInput): Record<string, unknown> {\n if (!input) {\n throw SchemaValidationError.parseFailed(\n { type: \"string\", content: \"\" },\n new Error(\"schema content is empty\"),\n );\n }\n\n try {\n if (typeof input === \"string\") {\n // Try JSON first, fall back to YAML\n try {\n return JSON.parse(input) as Record<string, unknown>;\n } catch {\n return parseYAML(input) as Record<string, unknown>;\n }\n }\n\n if (Buffer.isBuffer(input)) {\n const content = input.toString(\"utf-8\");\n try {\n return JSON.parse(content) as Record<string, unknown>;\n } catch {\n return parseYAML(content) as Record<string, unknown>;\n }\n }\n\n // Already an object\n return input as Record<string, unknown>;\n } catch (error) {\n throw SchemaValidationError.parseFailed(\n {\n type: typeof input === \"string\" ? \"string\" : \"object\",\n content: typeof input === \"string\" ? input : JSON.stringify(input),\n },\n error as Error,\n );\n }\n}\n\n/**\n * Sort object keys recursively in lexicographical order\n */\nfunction sortObjectKeys(obj: unknown): unknown {\n if (obj === null || typeof obj !== \"object\") {\n return obj;\n }\n\n if (Array.isArray(obj)) {\n return obj.map(sortObjectKeys);\n }\n\n const sorted: Record<string, unknown> = {};\n const keys = Object.keys(obj).sort();\n\n for (const key of keys) {\n sorted[key] = sortObjectKeys((obj as Record<string, unknown>)[key]);\n }\n\n return sorted;\n}\n\n/**\n * Normalize schema to canonical JSON format\n *\n * Per Fulmen Schema Normalization Standard:\n * - Accepts YAML or JSON input\n * - Strips comments while preserving semantic structure\n * - Sorts keys lexicographically\n * - Produces deterministic, pretty-printed JSON (or compact if requested)\n */\nexport function normalizeSchema(\n input: SchemaInput,\n options: SchemaNormalizationOptions = {},\n): string {\n try {\n // Parse input to object\n const parsed = parseSchemaInput(input);\n\n // Sort keys recursively\n const sorted = sortObjectKeys(parsed);\n\n // Serialize to JSON with optional compact mode\n if (options.compact) {\n return JSON.stringify(sorted);\n }\n\n // Default: pretty-printed with 2-space indentation\n return JSON.stringify(sorted, null, 2);\n } catch (error) {\n if (error instanceof SchemaValidationError) {\n throw error;\n }\n throw SchemaValidationError.parseFailed(\n {\n type: typeof input === \"string\" ? \"string\" : \"object\",\n content: typeof input === \"string\" ? input : JSON.stringify(input),\n },\n error as Error,\n );\n }\n}\n\n/**\n * Compare two schemas for semantic equality\n *\n * Normalizes both schemas and compares the canonical JSON output.\n * Returns equality result along with normalized versions for debugging.\n */\nexport function compareSchemas(\n schemaA: SchemaInput,\n schemaB: SchemaInput,\n options: SchemaNormalizationOptions = {},\n): { equal: boolean; normalizedA: string; normalizedB: string } {\n const normalizedA = normalizeSchema(schemaA, options);\n const normalizedB = normalizeSchema(schemaB, options);\n\n return {\n equal: normalizedA === normalizedB,\n normalizedA,\n normalizedB,\n };\n}\n","/**\n * Schema registry - implements schema discovery and metadata extraction\n */\n\nimport { access, readFile } from \"node:fs/promises\";\nimport { dirname, extname, join, relative } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport glob from \"fast-glob\";\nimport { parse as parseYAML } from \"yaml\";\nimport { SchemaValidationError } from \"./errors.js\";\nimport type { SchemaFormat, SchemaMetadata, SchemaRegistryOptions } from \"./types.js\";\n\n/**\n * Default schema file patterns\n */\nconst DEFAULT_PATTERNS = [\"**/*.schema.json\", \"**/*.schema.yaml\", \"**/*.schema.yml\"];\n\n/**\n * Schema registry class for managing schema discovery and metadata\n */\nexport class SchemaRegistry {\n private schemas: Map<string, SchemaMetadata> = new Map();\n private options: SchemaRegistryOptions;\n\n constructor(options: SchemaRegistryOptions = {}) {\n this.options = {\n baseDir: options.baseDir || this.getDefaultSchemaDir(),\n patterns: options.patterns || DEFAULT_PATTERNS,\n followSymlinks: options.followSymlinks ?? false,\n maxDepth: options.maxDepth ?? 10,\n };\n }\n\n /**\n * Get default schema directory using import.meta.url\n */\n private getDefaultSchemaDir(): string {\n const __filename = fileURLToPath(import.meta.url);\n const __dirname = dirname(__filename);\n // From src/schema/ we need to go up 2 levels to repo root, then into schemas/crucible-ts\n return join(__dirname, \"..\", \"..\", \"schemas\", \"crucible-ts\");\n }\n\n /**\n * Build logical schema ID from file path\n */\n private buildSchemaId(filePath: string, baseDir: string): string {\n const relativePath = relative(baseDir, filePath);\n const withoutExt = relativePath.replace(/\\.(schema\\.(json|yaml|yml))$/, \"\");\n return withoutExt.replace(/\\\\/g, \"/\"); // Normalize path separators\n }\n\n /**\n * Extract schema format from file extension\n */\n private getSchemaFormat(filePath: string): SchemaFormat {\n const ext = extname(filePath).toLowerCase();\n switch (ext) {\n case \".json\":\n return \"json\";\n case \".yaml\":\n case \".yml\":\n return \"yaml\";\n default:\n return \"json\"; // Default fallback\n }\n }\n\n /**\n * Extract metadata from schema file\n */\n private async extractMetadata(filePath: string): Promise<SchemaMetadata> {\n try {\n const content = await readFile(filePath, \"utf-8\");\n const format = this.getSchemaFormat(filePath);\n\n let parsed: Record<string, unknown>;\n if (format === \"yaml\") {\n parsed = parseYAML(content) as Record<string, unknown>;\n } else {\n parsed = JSON.parse(content) as Record<string, unknown>;\n }\n\n const baseDir = this.options.baseDir ?? \"\";\n const relativePath = relative(baseDir, filePath);\n\n return {\n id: this.buildSchemaId(filePath, baseDir),\n path: filePath,\n relativePath: relativePath,\n format,\n version: (parsed.$schema as string) || (parsed.version as string),\n description: (parsed.title as string) || (parsed.description as string),\n schemaDraft: parsed.$schema as string,\n };\n } catch (error) {\n throw SchemaValidationError.registryError(\n \"metadata extraction\",\n `Failed to process ${filePath}: ${(error as Error).message}`,\n );\n }\n }\n\n /**\n * Discover and index all available schemas\n */\n async discoverSchemas(): Promise<void> {\n try {\n const baseDir = this.options.baseDir ?? \"\";\n const patterns = this.options.patterns ?? [];\n\n if (patterns.length === 0) {\n this.schemas.clear();\n return;\n }\n\n const pattern = patterns.map((p) => join(baseDir, p));\n\n // Check if base directory exists\n try {\n await access(baseDir);\n } catch {\n // Base directory doesn't exist, clear registry and return\n this.schemas.clear();\n return;\n }\n\n const files = await glob(pattern, {\n absolute: true,\n followSymbolicLinks: this.options.followSymlinks,\n deep: this.options.maxDepth,\n onlyFiles: true,\n suppressErrors: true, // Don't throw on permission errors\n });\n\n // Clear existing schemas\n this.schemas.clear();\n\n // Process each schema file\n for (const filePath of files) {\n try {\n const metadata = await this.extractMetadata(filePath);\n this.schemas.set(metadata.id, metadata);\n } catch (error) {\n // Log error but continue processing other schemas\n console.warn(`Warning: Failed to process schema ${filePath}:`, error);\n }\n }\n } catch (error) {\n throw SchemaValidationError.registryError(\"discovery\", (error as Error).message);\n }\n }\n\n /**\n * List available schemas with optional prefix filtering\n */\n async listSchemas(prefix?: string): Promise<SchemaMetadata[]> {\n if (this.schemas.size === 0) {\n await this.discoverSchemas();\n }\n\n const schemas = Array.from(this.schemas.values());\n\n if (prefix) {\n return schemas.filter((schema) => schema.id.startsWith(prefix));\n }\n\n return schemas;\n }\n\n /**\n * Get schema by logical ID\n */\n async getSchema(id: string): Promise<SchemaMetadata> {\n if (this.schemas.size === 0) {\n await this.discoverSchemas();\n }\n\n const schema = this.schemas.get(id);\n if (!schema) {\n throw SchemaValidationError.schemaNotFound(id);\n }\n\n return schema;\n }\n\n /**\n * Get schema by file path\n */\n async getSchemaByPath(filePath: string): Promise<SchemaMetadata> {\n if (this.schemas.size === 0) {\n await this.discoverSchemas();\n }\n\n const absolutePath = filePath.startsWith(\"/\") ? filePath : join(process.cwd(), filePath);\n\n for (const schema of this.schemas.values()) {\n if (schema.path === absolutePath) {\n return schema;\n }\n }\n\n throw SchemaValidationError.schemaNotFound(filePath);\n }\n\n /**\n * Check if schema exists\n */\n async hasSchema(id: string): Promise<boolean> {\n if (this.schemas.size === 0) {\n await this.discoverSchemas();\n }\n\n return this.schemas.has(id);\n }\n\n /**\n * Get registry size\n */\n get size(): number {\n return this.schemas.size;\n }\n\n /**\n * Clear registry cache\n */\n clear(): void {\n this.schemas.clear();\n }\n}\n\n/**\n * Global schema registry instance with cached options\n */\nlet globalRegistry: SchemaRegistry | undefined;\nlet globalRegistryOptions: SchemaRegistryOptions | undefined;\n\n/**\n * Check if registry options have changed\n */\nfunction optionsChanged(newOptions?: SchemaRegistryOptions): boolean {\n if (!newOptions && !globalRegistryOptions) return false;\n if (!newOptions || !globalRegistryOptions) return true;\n\n return (\n newOptions.baseDir !== globalRegistryOptions.baseDir ||\n JSON.stringify(newOptions.patterns) !== JSON.stringify(globalRegistryOptions.patterns) ||\n newOptions.followSymlinks !== globalRegistryOptions.followSymlinks ||\n newOptions.maxDepth !== globalRegistryOptions.maxDepth\n );\n}\n\n/**\n * Get or create global schema registry, rebuilding if options change\n */\nexport function getSchemaRegistry(options?: SchemaRegistryOptions): SchemaRegistry {\n if (!globalRegistry || optionsChanged(options)) {\n globalRegistry = new SchemaRegistry(options);\n globalRegistryOptions = options;\n }\n return globalRegistry;\n}\n\n/**\n * List available schemas with optional prefix filtering\n */\nexport async function listSchemas(\n prefix?: string,\n options?: SchemaRegistryOptions,\n): Promise<SchemaMetadata[]> {\n const registry = getSchemaRegistry(options);\n return registry.listSchemas(prefix);\n}\n\n/**\n * Get schema by logical ID\n */\nexport async function getSchema(\n id: string,\n options?: SchemaRegistryOptions,\n): Promise<SchemaMetadata> {\n const registry = getSchemaRegistry(options);\n return registry.getSchema(id);\n}\n\n/**\n * Get schema by file path\n */\nexport async function getSchemaByPath(\n filePath: string,\n options?: SchemaRegistryOptions,\n): Promise<SchemaMetadata> {\n const registry = getSchemaRegistry(options);\n return registry.getSchemaByPath(filePath);\n}\n\n/**\n * Check if schema exists\n */\nexport async function hasSchema(id: string, options?: SchemaRegistryOptions): Promise<boolean> {\n const registry = getSchemaRegistry(options);\n return registry.hasSchema(id);\n}\n","/**\n * Counter metric implementation\n *\n * Monotonically increasing counter for counting events\n */\n\nimport type { MetricName } from \"./types.js\";\n\n/**\n * Counter metric\n *\n * Monotonically increasing value for counting events.\n * Supports labeled metrics (Crucible v0.2.7+).\n * Use for metrics like request counts, error counts, etc.\n */\nexport class Counter {\n private value = 0;\n private labeledValues = new Map<string, number>();\n\n constructor(public readonly name: MetricName) {}\n\n /**\n * Increment counter by delta (default: 1)\n *\n * @param delta - Amount to increment (must be non-negative)\n * @param labels - Optional label dimensions for this observation\n * @throws {Error} If delta is negative\n *\n * @example\n * ```typescript\n * counter.inc(); // Increment unlabeled by 1\n * counter.inc(5); // Increment unlabeled by 5\n * counter.inc(1, { status: '200' }); // Increment labeled instance\n * counter.inc(1, { result: 'success' }); // Different label set\n * ```\n */\n inc(delta = 1, labels?: Record<string, string>): void {\n if (delta < 0) {\n throw new Error(`Counter delta must be non-negative, got: ${delta}`);\n }\n\n if (labels && Object.keys(labels).length > 0) {\n // Labeled metric - track per label combination\n const labelKey = this.serializeLabels(labels);\n const current = this.labeledValues.get(labelKey) || 0;\n this.labeledValues.set(labelKey, current + delta);\n } else {\n // Unlabeled metric\n this.value += delta;\n }\n }\n\n /**\n * Get current counter value (unlabeled)\n */\n getValue(): number {\n return this.value;\n }\n\n /**\n * Get all labeled values\n * @returns Map of serialized label keys to values\n */\n getLabeledValues(): Map<string, number> {\n return new Map(this.labeledValues);\n }\n\n /**\n * Get value for specific label combination\n */\n getValueForLabels(labels: Record<string, string>): number {\n const labelKey = this.serializeLabels(labels);\n return this.labeledValues.get(labelKey) || 0;\n }\n\n /**\n * Reset counter to zero (all label combinations)\n */\n reset(): void {\n this.value = 0;\n this.labeledValues.clear();\n }\n\n /**\n * Serialize labels to deterministic string key\n * Format: key1=value1,key2=value2 (sorted by key)\n */\n private serializeLabels(labels: Record<string, string>): string {\n return Object.entries(labels)\n .sort(([a], [b]) => a.localeCompare(b))\n .map(([k, v]) => `${k}=${v}`)\n .join(\",\");\n }\n}\n","/**\n * Gauge metric implementation\n *\n * Gauge for arbitrary values that can go up and down\n */\n\nimport type { MetricName } from \"./types.js\";\n\n/**\n * Gauge metric\n *\n * Arbitrary value that can increase or decrease.\n * Supports labeled metrics (Crucible v0.2.7+).\n * Use for metrics like current connections, memory usage, temperature, etc.\n */\nexport class Gauge {\n private value = 0;\n private labeledValues = new Map<string, number>();\n\n constructor(public readonly name: MetricName) {}\n\n /**\n * Set gauge to specific value\n *\n * @param value - New gauge value (can be any number, including negative)\n * @param labels - Optional label dimensions for this observation\n *\n * @example\n * ```typescript\n * gauge.set(42); // Set unlabeled to 42\n * gauge.set(-10); // Negative values allowed\n * gauge.set(1, { phase: 'collect' }); // Set labeled instance\n * ```\n */\n set(value: number, labels?: Record<string, string>): void {\n if (labels && Object.keys(labels).length > 0) {\n const labelKey = this.serializeLabels(labels);\n this.labeledValues.set(labelKey, value);\n } else {\n this.value = value;\n }\n }\n\n /**\n * Increment gauge by delta (default: 1)\n *\n * @param delta - Amount to increment (can be negative)\n * @param labels - Optional label dimensions for this observation\n */\n inc(delta = 1, labels?: Record<string, string>): void {\n if (labels && Object.keys(labels).length > 0) {\n const labelKey = this.serializeLabels(labels);\n const current = this.labeledValues.get(labelKey) || 0;\n this.labeledValues.set(labelKey, current + delta);\n } else {\n this.value += delta;\n }\n }\n\n /**\n * Decrement gauge by delta (default: 1)\n *\n * @param delta - Amount to decrement (can be negative)\n * @param labels - Optional label dimensions for this observation\n */\n dec(delta = 1, labels?: Record<string, string>): void {\n if (labels && Object.keys(labels).length > 0) {\n const labelKey = this.serializeLabels(labels);\n const current = this.labeledValues.get(labelKey) || 0;\n this.labeledValues.set(labelKey, current - delta);\n } else {\n this.value -= delta;\n }\n }\n\n /**\n * Get current gauge value (unlabeled)\n */\n getValue(): number {\n return this.value;\n }\n\n /**\n * Get all labeled values\n * @returns Map of serialized label keys to values\n */\n getLabeledValues(): Map<string, number> {\n return new Map(this.labeledValues);\n }\n\n /**\n * Get value for specific label combination\n */\n getValueForLabels(labels: Record<string, string>): number {\n const labelKey = this.serializeLabels(labels);\n return this.labeledValues.get(labelKey) || 0;\n }\n\n /**\n * Reset gauge to zero (all label combinations)\n */\n reset(): void {\n this.value = 0;\n this.labeledValues.clear();\n }\n\n /**\n * Serialize labels to deterministic string key\n * Format: key1=value1,key2=value2 (sorted by key)\n */\n private serializeLabels(labels: Record<string, string>): string {\n return Object.entries(labels)\n .sort(([a], [b]) => a.localeCompare(b))\n .map(([k, v]) => `${k}=${v}`)\n .join(\",\");\n }\n}\n","/**\n * Taxonomy loader for metrics definitions\n *\n * Loads and caches metrics taxonomy from config/crucible-ts/taxonomy/metrics.yaml\n * Provides default histogram buckets per ADR-0007\n */\n\nimport { readFile } from \"node:fs/promises\";\nimport { join } from \"node:path\";\nimport { parse as parseYaml } from \"yaml\";\nimport type { MetricName, MetricUnit } from \"./types.js\";\n\n/**\n * Metric definition from taxonomy\n */\nexport interface MetricDefinition {\n name: MetricName;\n unit: MetricUnit;\n description: string;\n}\n\n/**\n * Taxonomy structure\n */\nexport interface MetricsTaxonomy {\n version: string;\n defaults: {\n histogram_buckets: {\n ms_metrics: number[];\n };\n };\n metrics: MetricDefinition[];\n}\n\n/**\n * Default histogram buckets for _ms metrics (ADR-0007)\n * [1, 5, 10, 50, 100, 500, 1000, 5000, 10000] milliseconds\n */\nexport const DEFAULT_MS_BUCKETS = [1, 5, 10, 50, 100, 500, 1000, 5000, 10000];\n\n/**\n * Singleton taxonomy loader\n */\nclass TaxonomyLoader {\n private static instance: TaxonomyLoader;\n private taxonomy: MetricsTaxonomy | null = null;\n private loadPromise: Promise<MetricsTaxonomy> | null = null;\n private loadError: Error | null = null;\n\n private constructor() {\n // Private constructor for singleton\n }\n\n /**\n * Get singleton instance\n */\n static getInstance(): TaxonomyLoader {\n if (!TaxonomyLoader.instance) {\n TaxonomyLoader.instance = new TaxonomyLoader();\n }\n return TaxonomyLoader.instance;\n }\n\n /**\n * Load taxonomy from YAML file\n */\n private async load(): Promise<MetricsTaxonomy> {\n if (this.taxonomy !== null) {\n return this.taxonomy;\n }\n\n if (this.loadError !== null) {\n throw this.loadError;\n }\n\n if (this.loadPromise) {\n return this.loadPromise;\n }\n\n this.loadPromise = (async () => {\n try {\n // Resolve path to taxonomy file\n // From src/telemetry/ → ../../config/crucible-ts/taxonomy/metrics.yaml\n const taxonomyPath = join(\n __dirname,\n \"..\",\n \"..\",\n \"config\",\n \"crucible-ts\",\n \"taxonomy\",\n \"metrics.yaml\",\n );\n\n const content = await readFile(taxonomyPath, \"utf-8\");\n this.taxonomy = parseYaml(content) as MetricsTaxonomy;\n\n return this.taxonomy;\n } catch (err) {\n this.loadError = err instanceof Error ? err : new Error(String(err));\n throw new Error(`Failed to load metrics taxonomy: ${this.loadError.message}`);\n }\n })();\n\n return this.loadPromise;\n }\n\n /**\n * Get taxonomy (async)\n */\n async getTaxonomy(): Promise<MetricsTaxonomy> {\n return this.load();\n }\n\n /**\n * Get metric definition by name\n */\n async getMetric(name: MetricName): Promise<MetricDefinition | undefined> {\n const taxonomy = await this.load();\n return taxonomy.metrics.find((m) => m.name === name);\n }\n\n /**\n * Get default unit for metric\n */\n async getDefaultUnit(name: MetricName): Promise<MetricUnit | undefined> {\n const metric = await this.getMetric(name);\n return metric?.unit;\n }\n\n /**\n * Get default histogram buckets for metric\n * Returns ADR-0007 buckets for _ms metrics, undefined for others\n */\n async getDefaultBuckets(name: MetricName): Promise<number[] | undefined> {\n // Check if metric name ends with _ms\n if (name.endsWith(\"_ms\")) {\n const taxonomy = await this.load();\n return taxonomy.defaults.histogram_buckets.ms_metrics;\n }\n return undefined;\n }\n\n /**\n * Check if metric name is valid (exists in taxonomy)\n */\n async isValidMetricName(name: string): Promise<boolean> {\n try {\n const taxonomy = await this.load();\n return taxonomy.metrics.some((m) => m.name === name);\n } catch {\n return false;\n }\n }\n\n /**\n * Reset loader state (for testing)\n * @internal\n */\n static _reset(): void {\n TaxonomyLoader.instance = new TaxonomyLoader();\n }\n}\n\n/**\n * Get metrics taxonomy\n *\n * @returns Promise resolving to taxonomy\n */\nexport async function getTaxonomy(): Promise<MetricsTaxonomy> {\n return TaxonomyLoader.getInstance().getTaxonomy();\n}\n\n/**\n * Get metric definition by name\n *\n * @param name - Metric name\n * @returns Promise resolving to metric definition or undefined\n */\nexport async function getMetric(name: MetricName): Promise<MetricDefinition | undefined> {\n return TaxonomyLoader.getInstance().getMetric(name);\n}\n\n/**\n * Get default unit for metric from taxonomy\n *\n * @param name - Metric name\n * @returns Promise resolving to unit or undefined\n */\nexport async function getDefaultUnit(name: MetricName): Promise<MetricUnit | undefined> {\n return TaxonomyLoader.getInstance().getDefaultUnit(name);\n}\n\n/**\n * Get default histogram buckets for metric\n *\n * Returns ADR-0007 buckets ([1, 5, 10, 50, 100, 500, 1000, 5000, 10000]) for\n * metrics ending with _ms, undefined for others.\n *\n * @param name - Metric name\n * @returns Promise resolving to bucket array or undefined\n *\n * @example\n * ```typescript\n * const buckets = await getDefaultBuckets('config_load_ms');\n * // Returns [1, 5, 10, 50, 100, 500, 1000, 5000, 10000]\n * ```\n */\nexport async function getDefaultBuckets(name: MetricName): Promise<number[] | undefined> {\n return TaxonomyLoader.getInstance().getDefaultBuckets(name);\n}\n\n/**\n * Check if metric name is valid (exists in taxonomy)\n *\n * @param name - Metric name to check\n * @returns Promise resolving to true if valid\n */\nexport async function isValidMetricName(name: string): Promise<boolean> {\n return TaxonomyLoader.getInstance().isValidMetricName(name);\n}\n\n// Export for testing\nexport { TaxonomyLoader };\n","/**\n * Histogram metric implementation\n *\n * Histogram with OTLP-compatible cumulative buckets, auto-applying ADR-0007\n * default buckets for _ms metrics.\n */\n\nimport { DEFAULT_MS_BUCKETS } from \"./taxonomy.js\";\nimport type { HistogramBucket, HistogramOptions, HistogramSummary, MetricName } from \"./types.js\";\n\n/**\n * Labeled histogram state\n */\ninterface LabeledHistogramState {\n count: number;\n sum: number;\n bucketCounts: Map<number, number>;\n}\n\n/**\n * Histogram metric\n *\n * Tracks distribution of values using cumulative buckets (OTLP-compatible).\n * Automatically applies ADR-0007 default buckets for _ms metrics.\n * Supports labeled metrics (Crucible v0.2.7+).\n */\nexport class Histogram {\n private count = 0;\n private sum = 0;\n private bucketCounts: Map<number, number> = new Map();\n private labeledStates = new Map<string, LabeledHistogramState>();\n private readonly buckets: number[];\n\n constructor(\n public readonly name: MetricName,\n options?: HistogramOptions,\n ) {\n // Determine buckets: custom > ADR-0007 defaults for _ms metrics > empty\n if (options?.buckets) {\n this.buckets = [...options.buckets].sort((a, b) => a - b);\n } else if (name.endsWith(\"_ms\") || name.endsWith(\"_seconds\")) {\n this.buckets = [...DEFAULT_MS_BUCKETS];\n } else {\n this.buckets = [];\n }\n\n // Initialize bucket counts\n for (const bucket of this.buckets) {\n this.bucketCounts.set(bucket, 0);\n }\n }\n\n /**\n * Record an observation\n *\n * @param value - Value to observe (typically a duration in ms or seconds)\n * @param labels - Optional label dimensions for this observation\n *\n * @example\n * ```typescript\n * const start = performance.now();\n * // ... operation ...\n * histogram.observe(performance.now() - start);\n * histogram.observe(duration, { phase: 'collect', result: 'success' });\n * ```\n */\n observe(value: number, labels?: Record<string, string>): void {\n if (labels && Object.keys(labels).length > 0) {\n // Labeled observation\n const labelKey = this.serializeLabels(labels);\n let state = this.labeledStates.get(labelKey);\n\n if (!state) {\n // Initialize new labeled state\n state = {\n count: 0,\n sum: 0,\n bucketCounts: new Map(),\n };\n for (const bucket of this.buckets) {\n state.bucketCounts.set(bucket, 0);\n }\n this.labeledStates.set(labelKey, state);\n }\n\n state.count++;\n state.sum += value;\n\n // Update cumulative bucket counts\n for (const bucket of this.buckets) {\n if (value <= bucket) {\n state.bucketCounts.set(bucket, (state.bucketCounts.get(bucket) || 0) + 1);\n }\n }\n } else {\n // Unlabeled observation\n this.count++;\n this.sum += value;\n\n // Update cumulative bucket counts\n for (const bucket of this.buckets) {\n if (value <= bucket) {\n this.bucketCounts.set(bucket, (this.bucketCounts.get(bucket) || 0) + 1);\n }\n }\n }\n }\n\n /**\n * Get histogram summary\n *\n * Returns OTLP-compatible histogram summary with cumulative bucket counts.\n */\n getSummary(): HistogramSummary {\n const buckets: HistogramBucket[] = this.buckets.map((le) => ({\n le,\n count: this.bucketCounts.get(le) || 0,\n }));\n\n return {\n count: this.count,\n sum: this.sum,\n buckets,\n };\n }\n\n /**\n * Get current observation count\n */\n getCount(): number {\n return this.count;\n }\n\n /**\n * Get sum of all observed values\n */\n getSum(): number {\n return this.sum;\n }\n\n /**\n * Get average of observed values\n */\n getAverage(): number {\n return this.count > 0 ? this.sum / this.count : 0;\n }\n\n /**\n * Get all labeled summaries\n * @returns Map of serialized label keys to histogram summaries\n */\n getLabeledSummaries(): Map<string, HistogramSummary> {\n const summaries = new Map<string, HistogramSummary>();\n\n for (const [labelKey, state] of this.labeledStates) {\n const buckets: HistogramBucket[] = this.buckets.map((le) => ({\n le,\n count: state.bucketCounts.get(le) || 0,\n }));\n\n summaries.set(labelKey, {\n count: state.count,\n sum: state.sum,\n buckets,\n });\n }\n\n return summaries;\n }\n\n /**\n * Get summary for specific label combination\n */\n getSummaryForLabels(labels: Record<string, string>): HistogramSummary | null {\n const labelKey = this.serializeLabels(labels);\n const state = this.labeledStates.get(labelKey);\n\n if (!state) {\n return null;\n }\n\n const buckets: HistogramBucket[] = this.buckets.map((le) => ({\n le,\n count: state.bucketCounts.get(le) || 0,\n }));\n\n return {\n count: state.count,\n sum: state.sum,\n buckets,\n };\n }\n\n /**\n * Reset histogram to initial state (all label combinations)\n */\n reset(): void {\n this.count = 0;\n this.sum = 0;\n for (const bucket of this.buckets) {\n this.bucketCounts.set(bucket, 0);\n }\n this.labeledStates.clear();\n }\n\n /**\n * Serialize labels to deterministic string key\n * Format: key1=value1,key2=value2 (sorted by key)\n */\n private serializeLabels(labels: Record<string, string>): string {\n return Object.entries(labels)\n .sort(([a], [b]) => a.localeCompare(b))\n .map(([k, v]) => `${k}=${v}`)\n .join(\",\");\n }\n}\n","/**\n * Metrics registry - central registry for all metrics\n *\n * Provides singleton registry for counters, gauges, and histograms.\n * Exports events in schema-compliant format.\n */\n\nimport { Counter } from \"./counter.js\";\nimport { Gauge } from \"./gauge.js\";\nimport { Histogram } from \"./histogram.js\";\nimport { getDefaultUnit } from \"./taxonomy.js\";\nimport type { FlushOptions, HistogramOptions, MetricName, MetricsEvent } from \"./types.js\";\n\n/**\n * Metrics registry\n *\n * Central registry for all metrics. Provides factory methods for counters,\n * gauges, and histograms. Exports metrics as schema-compliant events.\n */\nexport class MetricsRegistry {\n private counters: Map<MetricName, Counter> = new Map();\n private gauges: Map<MetricName, Gauge> = new Map();\n private histograms: Map<MetricName, Histogram> = new Map();\n\n /**\n * Get or create a counter\n *\n * @param name - Metric name from taxonomy\n * @returns Counter instance\n *\n * @example\n * ```typescript\n * const counter = registry.counter('schema_validations');\n * counter.inc();\n * ```\n */\n counter(name: MetricName): Counter {\n let counter = this.counters.get(name);\n if (!counter) {\n counter = new Counter(name);\n this.counters.set(name, counter);\n }\n return counter;\n }\n\n /**\n * Get or create a gauge\n *\n * @param name - Metric name from taxonomy\n * @returns Gauge instance\n *\n * @example\n * ```typescript\n * const gauge = registry.gauge('foundry_lookup_count');\n * gauge.set(42);\n * ```\n */\n gauge(name: MetricName): Gauge {\n let gauge = this.gauges.get(name);\n if (!gauge) {\n gauge = new Gauge(name);\n this.gauges.set(name, gauge);\n }\n return gauge;\n }\n\n /**\n * Get or create a histogram\n *\n * @param name - Metric name from taxonomy\n * @param options - Optional histogram options\n * @returns Histogram instance\n *\n * @example\n * ```typescript\n * // Auto-applies ADR-0007 buckets for _ms metrics\n * const histogram = registry.histogram('config_load_ms');\n * histogram.observe(42.5);\n *\n * // Custom buckets\n * const custom = registry.histogram('custom_metric', {\n * buckets: [10, 50, 100, 500, 1000]\n * });\n * ```\n */\n histogram(name: MetricName, options?: HistogramOptions): Histogram {\n let histogram = this.histograms.get(name);\n if (!histogram) {\n histogram = new Histogram(name, options);\n this.histograms.set(name, histogram);\n }\n return histogram;\n }\n\n /**\n * Export all metrics as events\n *\n * Returns array of schema-compliant MetricsEvent objects.\n * Does not clear metrics (use flush() to clear after export).\n *\n * @returns Promise resolving to array of metrics events\n *\n * @example\n * ```typescript\n * const events = await registry.export();\n * console.log(JSON.stringify(events, null, 2));\n * ```\n */\n async export(): Promise<MetricsEvent[]> {\n const events: MetricsEvent[] = [];\n const timestamp = new Date().toISOString();\n\n // Export counters (unlabeled + labeled) - Crucible v0.2.7+\n for (const [name, counter] of this.counters) {\n const unit = await getDefaultUnit(name);\n\n // Always export unlabeled value (for backwards compatibility)\n events.push({\n timestamp,\n name,\n value: counter.getValue(),\n unit,\n });\n\n // Export labeled values (only if > 0)\n for (const [labelKey, value] of counter.getLabeledValues()) {\n if (value > 0) {\n const tags = this.deserializeLabels(labelKey);\n events.push({\n timestamp,\n name,\n value,\n tags,\n unit,\n });\n }\n }\n }\n\n // Export gauges (unlabeled + labeled) - Crucible v0.2.7+\n for (const [name, gauge] of this.gauges) {\n const unit = await getDefaultUnit(name);\n\n // Export unlabeled value (always export gauges, even if zero)\n events.push({\n timestamp,\n name,\n value: gauge.getValue(),\n unit,\n });\n\n // Export labeled values\n for (const [labelKey, value] of gauge.getLabeledValues()) {\n const tags = this.deserializeLabels(labelKey);\n events.push({\n timestamp,\n name,\n value,\n tags,\n unit,\n });\n }\n }\n\n // Export histograms (unlabeled + labeled) - Crucible v0.2.7+\n for (const [name, histogram] of this.histograms) {\n const unit = await getDefaultUnit(name);\n\n // Always export unlabeled summary (for backwards compatibility)\n events.push({\n timestamp,\n name,\n value: histogram.getSummary(),\n unit,\n });\n\n // Export labeled summaries (only if count > 0)\n for (const [labelKey, summary] of histogram.getLabeledSummaries()) {\n if (summary.count > 0) {\n const tags = this.deserializeLabels(labelKey);\n events.push({\n timestamp,\n name,\n value: summary,\n tags,\n unit,\n });\n }\n }\n }\n\n return events;\n }\n\n /**\n * Deserialize label key back to tags object\n * Format: key1=value1,key2=value2 → {key1: \"value1\", key2: \"value2\"}\n */\n private deserializeLabels(labelKey: string): Record<string, string> {\n if (!labelKey) {\n return {};\n }\n\n const tags: Record<string, string> = {};\n for (const pair of labelKey.split(\",\")) {\n const [key, value] = pair.split(\"=\");\n if (key && value) {\n tags[key] = value;\n }\n }\n return tags;\n }\n\n /**\n * Export and clear all metrics\n *\n * Exports metrics as events, optionally emits them via logger,\n * then resets all metrics to zero.\n *\n * @param options - Flush options\n * @returns Promise resolving to array of exported events\n *\n * @example\n * ```typescript\n * // Export and clear\n * const events = await registry.flush();\n *\n * // Export, emit to logger, and clear\n * const events = await registry.flush({\n * emit: (events) => console.log(JSON.stringify(events))\n * });\n * ```\n */\n async flush(options?: FlushOptions): Promise<MetricsEvent[]> {\n const events = await this.export();\n\n try {\n // Emit if logger provided\n if (options?.emit) {\n options.emit(events);\n }\n } finally {\n // Always clear metrics, even if emit throws\n this.clear();\n }\n\n return events;\n }\n\n /**\n * Clear all metrics (reset to zero)\n *\n * Resets all counters, gauges, and histograms to their initial state.\n */\n clear(): void {\n for (const counter of this.counters.values()) {\n counter.reset();\n }\n for (const gauge of this.gauges.values()) {\n gauge.reset();\n }\n for (const histogram of this.histograms.values()) {\n histogram.reset();\n }\n }\n\n /**\n * Get all registered metric names\n *\n * Returns array of all metric names that have been accessed\n * (counters, gauges, or histograms).\n */\n getMetricNames(): MetricName[] {\n const names = new Set<MetricName>();\n for (const name of this.counters.keys()) {\n names.add(name);\n }\n for (const name of this.gauges.keys()) {\n names.add(name);\n }\n for (const name of this.histograms.keys()) {\n names.add(name);\n }\n return Array.from(names);\n }\n\n /**\n * Get total count of registered metrics\n */\n getMetricCount(): number {\n return this.counters.size + this.gauges.size + this.histograms.size;\n }\n}\n","/**\n * Telemetry types - TypeScript types for metrics events\n *\n * Based on schemas/crucible-ts/observability/metrics/v1.0.0/metrics-event.schema.json\n * and config/crucible-ts/taxonomy/metrics.yaml\n */\n\n/**\n * Metric name from taxonomy\n * Aligned with config/crucible-ts/taxonomy/metrics.yaml#/$defs/metricName\n * Updated for Crucible v0.2.18 (HTTP server metrics)\n */\nexport type MetricName =\n // Core module metrics\n | \"schema_validations\"\n | \"schema_validation_errors\"\n | \"config_load_ms\"\n | \"config_load_errors\"\n | \"pathfinder_find_ms\"\n | \"pathfinder_validation_errors\"\n | \"pathfinder_security_warnings\"\n | \"foundry_lookup_count\"\n | \"logging_emit_count\"\n | \"logging_emit_latency_ms\"\n | \"goneat_command_duration_ms\"\n // Prometheus exporter metrics\n | \"prometheus_exporter_refresh_duration_seconds\"\n | \"prometheus_exporter_refresh_total\"\n | \"prometheus_exporter_refresh_errors_total\"\n | \"prometheus_exporter_refresh_inflight\"\n | \"prometheus_exporter_http_requests_total\"\n | \"prometheus_exporter_http_errors_total\"\n | \"prometheus_exporter_restarts_total\"\n // Foundry MIME detection metrics\n | \"foundry_mime_detections_total_json\"\n | \"foundry_mime_detections_total_xml\"\n | \"foundry_mime_detections_total_yaml\"\n | \"foundry_mime_detections_total_csv\"\n | \"foundry_mime_detections_total_plain_text\"\n | \"foundry_mime_detections_total_unknown\"\n | \"foundry_mime_detection_ms_json\"\n | \"foundry_mime_detection_ms_xml\"\n | \"foundry_mime_detection_ms_yaml\"\n | \"foundry_mime_detection_ms_csv\"\n | \"foundry_mime_detection_ms_plain_text\"\n | \"foundry_mime_detection_ms_unknown\"\n // Error handling metrics\n | \"error_handling_wraps_total\"\n | \"error_handling_wrap_ms\"\n // FulHash metrics\n | \"fulhash_operations_total_xxh3_128\"\n | \"fulhash_operations_total_sha256\"\n | \"fulhash_hash_string_total\"\n | \"fulhash_bytes_hashed_total\"\n | \"fulhash_operation_ms\"\n // HTTP server metrics (v0.2.18)\n | \"http_requests_total\"\n | \"http_request_duration_seconds\"\n | \"http_request_size_bytes\"\n | \"http_response_size_bytes\"\n | \"http_active_requests\";\n\n/**\n * Metric unit from taxonomy\n * Aligned with config/crucible-ts/taxonomy/metrics.yaml#/$defs/metricUnit\n * Updated for Crucible v0.2.7 (adds 's' for seconds)\n */\nexport type MetricUnit = \"count\" | \"ms\" | \"bytes\" | \"percent\" | \"s\";\n\n/**\n * Histogram bucket for OTLP-compatible histograms\n */\nexport interface HistogramBucket {\n /** Upper bound (less-than-or-equal) for the bucket */\n le: number;\n /** Cumulative count up to and including this bucket */\n count: number;\n}\n\n/**\n * Histogram summary payload\n */\nexport interface HistogramSummary {\n /** Total count of observations */\n count: number;\n /** Sum of all observed values */\n sum: number;\n /** Ordered buckets with cumulative counts (OTLP-compatible) */\n buckets: HistogramBucket[];\n}\n\n/**\n * Metric value (scalar or histogram)\n */\nexport type MetricValue = number | HistogramSummary;\n\n/**\n * Metrics event structure\n * Aligned with schemas/crucible-ts/observability/metrics/v1.0.0/metrics-event.schema.json\n */\nexport interface MetricsEvent {\n /** RFC3339 timestamp of metric emission */\n timestamp: string;\n /** Metric identifier from taxonomy */\n name: MetricName;\n /** Measurement payload (scalar or histogram summary) */\n value: MetricValue;\n /** Optional key/value dimensions */\n tags?: Record<string, string>;\n /** Optional metric unit (defaults to taxonomy default) */\n unit?: MetricUnit;\n}\n\n/**\n * Histogram options for customization\n */\nexport interface HistogramOptions {\n /** Custom bucket boundaries (overrides default ADR-0007 buckets) */\n buckets?: number[];\n}\n\n/**\n * Flush options for metrics registry\n */\nexport interface FlushOptions {\n /** Optional logger function to emit metrics */\n emit?: (events: MetricsEvent[]) => void;\n}\n\n/**\n * Type guard to check if value is a histogram summary\n */\nexport function isHistogramSummary(value: unknown): value is HistogramSummary {\n return (\n typeof value === \"object\" &&\n value !== null &&\n \"count\" in value &&\n \"sum\" in value &&\n \"buckets\" in value\n );\n}\n\n/**\n * Type guard to check if metric name is valid\n * Aligned with Crucible v0.2.18 taxonomy\n */\nexport function isValidMetricName(name: string): name is MetricName {\n const validNames: MetricName[] = [\n // Core module metrics\n \"schema_validations\",\n \"schema_validation_errors\",\n \"config_load_ms\",\n \"config_load_errors\",\n \"pathfinder_find_ms\",\n \"pathfinder_validation_errors\",\n \"pathfinder_security_warnings\",\n \"foundry_lookup_count\",\n \"logging_emit_count\",\n \"logging_emit_latency_ms\",\n \"goneat_command_duration_ms\",\n // Prometheus exporter metrics\n \"prometheus_exporter_refresh_duration_seconds\",\n \"prometheus_exporter_refresh_total\",\n \"prometheus_exporter_refresh_errors_total\",\n \"prometheus_exporter_refresh_inflight\",\n \"prometheus_exporter_http_requests_total\",\n \"prometheus_exporter_http_errors_total\",\n \"prometheus_exporter_restarts_total\",\n // Foundry MIME detection metrics\n \"foundry_mime_detections_total_json\",\n \"foundry_mime_detections_total_xml\",\n \"foundry_mime_detections_total_yaml\",\n \"foundry_mime_detections_total_csv\",\n \"foundry_mime_detections_total_plain_text\",\n \"foundry_mime_detections_total_unknown\",\n \"foundry_mime_detection_ms_json\",\n \"foundry_mime_detection_ms_xml\",\n \"foundry_mime_detection_ms_yaml\",\n \"foundry_mime_detection_ms_csv\",\n \"foundry_mime_detection_ms_plain_text\",\n \"foundry_mime_detection_ms_unknown\",\n // Error handling metrics\n \"error_handling_wraps_total\",\n \"error_handling_wrap_ms\",\n // FulHash metrics\n \"fulhash_operations_total_xxh3_128\",\n \"fulhash_operations_total_sha256\",\n \"fulhash_hash_string_total\",\n \"fulhash_bytes_hashed_total\",\n \"fulhash_operation_ms\",\n // HTTP server metrics\n \"http_requests_total\",\n \"http_request_duration_seconds\",\n \"http_request_size_bytes\",\n \"http_response_size_bytes\",\n \"http_active_requests\",\n ];\n return validNames.includes(name as MetricName);\n}\n\n/**\n * Type guard to check if unit is valid\n */\nexport function isValidMetricUnit(unit: string): unit is MetricUnit {\n const validUnits: MetricUnit[] = [\"count\", \"ms\", \"bytes\", \"percent\", \"s\"];\n return validUnits.includes(unit as MetricUnit);\n}\n","/**\n * Metrics event validators\n *\n * Schema validation for metrics events using existing src/schema infrastructure\n */\n\nimport { compileSchemaById } from \"../schema/index.js\";\nimport type { CompiledValidator } from \"../schema/types.js\";\n\n/**\n * Singleton validator for metrics events\n *\n * Pre-compiles the metrics-event schema at first access for optimal performance.\n * Reuses existing AJV setup from src/schema module.\n */\nclass MetricsValidator {\n private static instance: MetricsValidator;\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(): MetricsValidator {\n if (!MetricsValidator.instance) {\n MetricsValidator.instance = new MetricsValidator();\n }\n return MetricsValidator.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 // Compile schema using existing schema infrastructure\n this.validateFn = await compileSchemaById(\"observability/metrics/v1.0.0/metrics-event\");\n } catch (err) {\n this.initError = err instanceof Error ? err : new Error(String(err));\n throw new Error(`Failed to initialize metrics validator: ${this.initError.message}`);\n }\n })();\n\n return this.initPromise;\n }\n\n /**\n * Validate metrics event against schema\n *\n * @param event - Metrics event to validate\n * @returns Promise resolving to true if valid, false otherwise\n */\n async validate(event: 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(event);\n }\n\n /**\n * Get validation errors from last validation\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 MetricsValidator.instance = new MetricsValidator();\n }\n}\n\n/**\n * Validate metrics event against schema\n *\n * Uses pre-compiled validator singleton for optimal performance.\n *\n * @param event - Metrics event to validate\n * @returns Promise resolving to true if valid\n *\n * @example\n * ```typescript\n * const event: MetricsEvent = {\n * timestamp: new Date().toISOString(),\n * name: 'schema_validations',\n * value: 42\n * };\n *\n * if (await validateMetricsEvent(event)) {\n * // Event is schema-compliant\n * } else {\n * const errors = getValidationErrors();\n * console.error('Validation failed:', errors);\n * }\n * ```\n */\nexport async function validateMetricsEvent(event: unknown): Promise<boolean> {\n return MetricsValidator.getInstance().validate(event);\n}\n\n/**\n * Validate array of metrics events\n *\n * @param events - Array of metrics events\n * @returns Promise resolving to true if all valid\n */\nexport async function validateMetricsEvents(events: unknown[]): Promise<boolean> {\n for (const event of events) {\n if (!(await validateMetricsEvent(event))) {\n return false;\n }\n }\n return true;\n}\n\n/**\n * Get validation errors from last validation\n */\nexport function getValidationErrors() {\n return MetricsValidator.getInstance().getErrors();\n}\n\n/**\n * Format validation errors as human-readable string\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 * Assert that metrics event is valid (throws if not)\n *\n * @param event - Metrics event to validate\n * @throws {Error} If validation fails\n */\nexport async function assertValidMetricsEvent(event: unknown): Promise<void> {\n if (!(await validateMetricsEvent(event))) {\n const errors = getValidationErrors();\n const message = errors ? formatValidationErrors(errors) : \"Metrics event validation failed\";\n throw new Error(`Invalid metrics event: ${message}`);\n }\n}\n\n// Export for testing\nexport { MetricsValidator };\n","/**\n * Telemetry module - metrics collection and export\n *\n * Provides counter, gauge, and histogram metrics with schema validation\n * and taxonomy-based defaults (ADR-0007).\n */\n\nexport const VERSION = \"1.0.0\";\n\n// Core registry and singleton\nexport { MetricsRegistry } from \"./registry.js\";\n\nimport { MetricsRegistry } from \"./registry.js\";\n\n/**\n * Default singleton metrics registry\n *\n * Use this for application-wide metrics collection.\n *\n * @example\n * ```typescript\n * import { metrics } from '@fulmenhq/tsfulmen/telemetry';\n *\n * // Increment counter\n * metrics.counter('schema_validations').inc();\n *\n * // Record histogram observation\n * metrics.histogram('config_load_ms').observe(42.5);\n *\n * // Export all metrics\n * const events = await metrics.export();\n * ```\n */\nexport const metrics = new MetricsRegistry();\n\n// Metric types\nexport { Counter } from \"./counter.js\";\nexport { Gauge } from \"./gauge.js\";\nexport { Histogram } from \"./histogram.js\";\n// Taxonomy\nexport type { MetricDefinition, MetricsTaxonomy } from \"./taxonomy.js\";\nexport {\n DEFAULT_MS_BUCKETS,\n getDefaultBuckets,\n getDefaultUnit,\n getMetric,\n getTaxonomy,\n isValidMetricName as isValidMetricNameTaxonomy,\n} from \"./taxonomy.js\";\n// Types\nexport type {\n FlushOptions,\n HistogramBucket,\n HistogramOptions,\n HistogramSummary,\n MetricName,\n MetricsEvent,\n MetricUnit,\n MetricValue,\n} from \"./types.js\";\nexport {\n isHistogramSummary,\n isValidMetricName,\n isValidMetricUnit,\n} from \"./types.js\";\n\n// Validators\nexport {\n assertValidMetricsEvent,\n formatValidationErrors,\n getValidationErrors,\n validateMetricsEvent,\n validateMetricsEvents,\n} from \"./validators.js\";\n","/**\n * Schema validator - implements AJV-based schema validation with goneat integration\n */\n\nimport { readFile } from \"node:fs/promises\";\nimport { dirname, join } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport type { AnySchema } from \"ajv\";\nimport Ajv from \"ajv\";\nimport Ajv2019 from \"ajv/dist/2019.js\";\nimport Ajv2020 from \"ajv/dist/2020.js\";\nimport AjvDraft04 from \"ajv-draft-04\";\nimport { parse as parseYAML } from \"yaml\";\nimport { metrics } from \"../telemetry/index.js\";\nimport { applyFulmenAjvFormats } from \"./ajv-formats.js\";\nimport { SchemaValidationError } from \"./errors.js\";\nimport { getSchemaRegistry } from \"./registry.js\";\nimport type {\n CompiledValidator,\n SchemaInput,\n SchemaRegistryOptions,\n SchemaValidationResult,\n} from \"./types.js\";\nimport { createDiagnostic } from \"./utils.js\";\n\n/**\n * Supported JSON Schema dialects for meta validation + compilation.\n */\ntype JsonSchemaDialect = \"draft-04\" | \"draft-06\" | \"draft-07\" | \"draft-2019-09\" | \"draft-2020-12\";\n\n/**\n * AJV instances by dialect\n */\nconst ajvInstances = new Map<JsonSchemaDialect, Ajv>();\n\n/**\n * Metaschema initialization promises by dialect\n */\nconst metaschemaReady = new Map<JsonSchemaDialect, Promise<void>>();\n\n/**\n * Schema cache for compiled validators\n */\nconst schemaCache = new Map<string, CompiledValidator>();\n\n/**\n * Load metaschema from Crucible SSOT\n */\nasync function loadMetaSchema(draft: JsonSchemaDialect): Promise<Record<string, unknown>> {\n const __filename = fileURLToPath(import.meta.url);\n const __dirname = dirname(__filename);\n const metaSchemaPath = join(\n __dirname,\n \"..\",\n \"..\",\n \"schemas\",\n \"crucible-ts\",\n \"meta\",\n draft,\n \"schema.json\",\n );\n\n const content = await readFile(metaSchemaPath, \"utf-8\");\n return JSON.parse(content) as Record<string, unknown>;\n}\n\n/**\n * Load vocabulary schemas (draft 2019-09 / 2020-12)\n */\nasync function loadVocabularySchemas(draft: JsonSchemaDialect): Promise<Record<string, unknown>[]> {\n if (draft !== \"draft-2019-09\" && draft !== \"draft-2020-12\") {\n return [];\n }\n\n const __filename = fileURLToPath(import.meta.url);\n const __dirname = dirname(__filename);\n const vocabDir = join(__dirname, \"..\", \"..\", \"schemas\", \"crucible-ts\", \"meta\", draft, \"meta\");\n\n const vocabFiles =\n draft === \"draft-2020-12\"\n ? [\n \"core.json\",\n \"applicator.json\",\n \"unevaluated.json\",\n \"validation.json\",\n \"meta-data.json\",\n \"format-annotation.json\",\n \"content.json\",\n ]\n : [\n \"core.json\",\n \"applicator.json\",\n \"validation.json\",\n \"meta-data.json\",\n \"format.json\",\n \"content.json\",\n ];\n\n const schemas: Record<string, unknown>[] = [];\n for (const file of vocabFiles) {\n try {\n const content = await readFile(join(vocabDir, file), \"utf-8\");\n schemas.push(JSON.parse(content) as Record<string, unknown>);\n } catch {\n // Vocabulary schema not found, skip\n }\n }\n\n return schemas;\n}\n\n/**\n * Load referenced schemas (including YAML files) for AJV\n *\n * Resolves relative paths from schemas/ and config/ directories.\n * Handles both relative paths and https://schemas.fulmenhq.dev URIs.\n *\n * Per Canonical URI Resolution Standard (v0.4.2+), crucible-hosted schemas use:\n * https://schemas.fulmenhq.dev/crucible/<topic>/<version>/<filename>\n *\n * We only embed crucible schemas locally. Other modules (goneat/, enact/, etc.)\n * are not embedded and cannot be resolved offline.\n */\nasync function loadReferencedSchema(uri: string): Promise<Record<string, unknown>> {\n const __filename = fileURLToPath(import.meta.url);\n const __dirname = dirname(__filename);\n const repoRoot = join(__dirname, \"..\", \"..\");\n\n let resolvedPath: string;\n\n // Handle https://schemas.fulmenhq.dev/ URIs - map to local files\n if (uri.startsWith(\"https://schemas.fulmenhq.dev/\")) {\n let relativePath = uri.replace(\"https://schemas.fulmenhq.dev/\", \"\");\n\n // Strip crucible/ module prefix if present (v0.4.2+ canonical URIs)\n // We only embed crucible schemas - other modules cannot be resolved locally\n if (relativePath.startsWith(\"crucible/\")) {\n relativePath = relativePath.slice(\"crucible/\".length);\n }\n\n // Check if it's a config taxonomy reference\n if (relativePath.startsWith(\"config/taxonomy/\")) {\n resolvedPath = join(\n repoRoot,\n \"config\",\n \"crucible-ts\",\n \"taxonomy\",\n relativePath.split(\"/\").pop() || \"\",\n );\n } else {\n // Schema reference - map to schemas/crucible-ts/\n resolvedPath = join(repoRoot, \"schemas\", \"crucible-ts\", relativePath);\n }\n }\n // Handle relative paths (e.g., \"../../../../config/taxonomy/metrics.yaml\")\n else if (uri.startsWith(\"../../\") || uri.startsWith(\"../\")) {\n // Resolve relative to schemas/crucible-ts/observability/metrics/v1.0.0/\n // (where metrics-event.schema.json is located)\n const schemaBase = join(\n repoRoot,\n \"schemas\",\n \"crucible-ts\",\n \"observability\",\n \"metrics\",\n \"v1.0.0\",\n );\n resolvedPath = join(schemaBase, uri);\n }\n // Handle file:// URIs\n else if (uri.startsWith(\"file://\")) {\n resolvedPath = fileURLToPath(uri);\n }\n // Unhandled URI scheme\n else {\n throw new Error(`Cannot load remote schema: ${uri}`);\n }\n\n // Read and parse the file\n const content = await readFile(resolvedPath, \"utf-8\");\n const ext = resolvedPath.split(\".\").pop()?.toLowerCase();\n\n if (ext === \"yaml\" || ext === \"yml\") {\n return parseYAML(content) as Record<string, unknown>;\n }\n return JSON.parse(content) as Record<string, unknown>;\n}\n\n/**\n * Resolve JSON Schema dialect from schema content.\n */\nfunction detectDialect(schema: unknown): JsonSchemaDialect {\n if (schema && typeof schema === \"object\" && !Array.isArray(schema)) {\n const maybeSchema = schema as Record<string, unknown>;\n const declared = (maybeSchema as { $schema?: unknown }).$schema;\n\n if (typeof declared === \"string\") {\n if (declared.includes(\"draft-04\")) return \"draft-04\";\n if (declared.includes(\"draft-06\")) return \"draft-06\";\n if (declared.includes(\"draft-07\")) return \"draft-07\";\n if (declared.includes(\"draft/2019-09\")) return \"draft-2019-09\";\n if (declared.includes(\"draft/2020-12\")) return \"draft-2020-12\";\n }\n }\n\n // Default to 2020-12 in Fulmen ecosystem.\n return \"draft-2020-12\";\n}\n\n/**\n * Create AJV instance for a specific dialect\n */\nfunction createAjv(dialect: JsonSchemaDialect): Ajv {\n const AjvCtor =\n dialect === \"draft-2020-12\"\n ? Ajv2020\n : dialect === \"draft-2019-09\"\n ? Ajv2019\n : dialect === \"draft-04\"\n ? (AjvDraft04 as unknown as typeof Ajv)\n : Ajv;\n\n const ajv = new AjvCtor({\n strict: false,\n allErrors: true,\n verbose: true,\n // Allow schemas with $id to be added without replacing existing ones\n addUsedSchema: false,\n // draft-04 uses \"id\"; later drafts use \"$id\"\n schemaId: dialect === \"draft-04\" ? \"id\" : \"$id\",\n // Enable async schema loading for YAML references\n loadSchema: loadReferencedSchema,\n });\n\n applyFulmenAjvFormats(ajv);\n\n return ajv;\n}\n\n/**\n * Get or create AJV instance for a dialect, ensuring metaschemas are loaded.\n */\nasync function getAjv(dialect: JsonSchemaDialect): Promise<Ajv> {\n const existing = ajvInstances.get(dialect);\n if (existing) {\n const ready = metaschemaReady.get(dialect);\n if (ready) await ready;\n return existing;\n }\n\n const ajv = createAjv(dialect);\n ajvInstances.set(dialect, ajv);\n\n const readyPromise = Promise.all([loadVocabularySchemas(dialect), loadMetaSchema(dialect)])\n .then(([vocabSchemas, metaSchema]) => {\n // Add vocabulary schemas first (referenced by meta schema)\n for (const vocabSchema of vocabSchemas) {\n try {\n ajv.addMetaSchema(vocabSchema);\n } catch {\n // Already added or incompatible with Ajv's built-ins\n }\n }\n\n try {\n ajv.addMetaSchema(metaSchema);\n } catch {\n // Already added or incompatible with Ajv's built-ins\n }\n })\n .catch((error) => {\n throw new Error(`Failed to load metaschemas (${dialect}): ${error}`);\n });\n\n metaschemaReady.set(dialect, readyPromise);\n await readyPromise;\n\n return ajv;\n}\n\n/**\n * Compile a schema for validation\n */\nexport async function compileSchema(\n schema: SchemaInput,\n options: { aliases?: string[] } = {},\n): Promise<CompiledValidator> {\n const baseKey = typeof schema === \"string\" ? schema : JSON.stringify(schema);\n\n let parsedSchema: unknown;\n if (typeof schema === \"string\") {\n try {\n parsedSchema = JSON.parse(schema);\n } catch {\n // Try YAML if JSON parsing fails\n parsedSchema = parseYAML(schema);\n }\n } else if (Buffer.isBuffer(schema)) {\n const content = schema.toString(\"utf-8\");\n try {\n parsedSchema = JSON.parse(content);\n } catch {\n parsedSchema = parseYAML(content);\n }\n } else {\n parsedSchema = schema;\n }\n\n const dialect = detectDialect(parsedSchema);\n const ajv = await getAjv(dialect);\n\n const cacheKey = `${dialect}:${baseKey}`;\n const cached = schemaCache.get(cacheKey);\n if (cached !== undefined) {\n return cached;\n }\n\n try {\n // Register schema aliases (e.g., alternate $id values) before compile to support relative refs\n if (options.aliases && options.aliases.length > 0) {\n for (const alias of options.aliases) {\n if (alias && ajv.getSchema(alias) === undefined) {\n try {\n if (typeof parsedSchema === \"object\" && parsedSchema !== null) {\n ajv.addSchema(parsedSchema as Record<string, unknown>, alias);\n }\n } catch {\n // Ignore if alias already registered or invalid\n }\n }\n }\n }\n\n const validator =\n typeof parsedSchema === \"boolean\"\n ? ajv.compile(parsedSchema)\n : await ajv.compileAsync(parsedSchema as Record<string, unknown>);\n\n // Cache the compiled validator\n schemaCache.set(cacheKey, validator as CompiledValidator);\n\n return validator as CompiledValidator;\n } catch (error) {\n throw SchemaValidationError.parseFailed(\n {\n type: \"string\",\n content: typeof schema === \"string\" ? schema : JSON.stringify(schema),\n },\n error as Error,\n );\n }\n}\n\n/**\n * Validate data against a compiled schema\n */\nexport function validateData(data: unknown, validator: CompiledValidator): SchemaValidationResult {\n const valid = validator(data);\n\n const result: SchemaValidationResult = {\n valid,\n diagnostics: [],\n source: \"ajv\",\n };\n\n if (!valid && validator.errors) {\n const errors = validator.errors;\n if (Array.isArray(errors)) {\n result.diagnostics = errors.map((error) =>\n createDiagnostic(\n error.instancePath || \"\",\n error.message || \"Validation failed\",\n error.keyword || \"unknown\",\n \"ERROR\",\n \"ajv\",\n ),\n );\n }\n metrics.counter(\"schema_validation_errors\").inc();\n } else {\n metrics.counter(\"schema_validations\").inc();\n }\n\n return result;\n}\n\n/**\n * Validate file against a schema\n */\nexport async function validateFile(\n filePath: string,\n validator: CompiledValidator,\n): Promise<SchemaValidationResult> {\n try {\n const content = await readFile(filePath, \"utf-8\");\n let data: unknown;\n\n try {\n data = JSON.parse(content);\n } catch {\n // Try YAML if JSON parsing fails\n data = parseYAML(content);\n }\n\n return validateData(data, validator);\n } catch (error) {\n if (error instanceof SchemaValidationError) {\n throw error;\n }\n throw SchemaValidationError.validationFailed(\n filePath,\n [\n createDiagnostic(\n \"\",\n `Failed to read or parse file: ${(error as Error).message}`,\n \"file-read\",\n \"ERROR\",\n \"ajv\",\n ),\n ],\n { type: \"file\", id: filePath },\n );\n }\n}\n\n/**\n * Validate a schema document itself\n */\nexport async function validateSchema(schema: SchemaInput): Promise<SchemaValidationResult> {\n try {\n // Parse schema so we can both meta-validate and compile with dialect-specific Ajv.\n let parsedSchema: unknown;\n if (typeof schema === \"string\") {\n try {\n parsedSchema = JSON.parse(schema);\n } catch {\n parsedSchema = parseYAML(schema);\n }\n } else if (Buffer.isBuffer(schema)) {\n const content = schema.toString(\"utf-8\");\n try {\n parsedSchema = JSON.parse(content);\n } catch {\n parsedSchema = parseYAML(content);\n }\n } else {\n parsedSchema = schema;\n }\n\n const dialect = detectDialect(parsedSchema);\n const ajv = await getAjv(dialect);\n\n // 1) Meta validation against declared dialect\n const metaValid = ajv.validateSchema(parsedSchema as AnySchema);\n if (!metaValid && ajv.errors) {\n const diagnostics = ajv.errors.map((error) =>\n createDiagnostic(\n error.instancePath || \"\",\n error.message || \"Schema meta-validation failed\",\n error.keyword || \"unknown\",\n \"ERROR\",\n \"ajv\",\n ),\n );\n\n return { valid: false, diagnostics, source: \"ajv\" };\n }\n\n // 2) Compilation check (refs resolvable, keywords supported)\n await compileSchema(parsedSchema as SchemaInput);\n\n return {\n valid: true,\n diagnostics: [],\n source: \"ajv\",\n };\n } catch (error) {\n if (error instanceof SchemaValidationError) {\n return {\n valid: false,\n diagnostics: error.diagnostics,\n source: \"ajv\",\n };\n }\n\n return {\n valid: false,\n diagnostics: [\n createDiagnostic(\n \"\",\n `Schema validation failed: ${(error as Error).message}`,\n \"schema-validation\",\n \"ERROR\",\n \"ajv\",\n ),\n ],\n source: \"ajv\",\n };\n }\n}\n\n/**\n * Clear schema cache\n */\nexport function clearCache(): void {\n schemaCache.clear();\n // Keep Ajv instances cached; they hold metaschemas. Tests can still clear schema cache.\n}\n\n/**\n * Get schema cache size\n */\nexport function getCacheSize(): number {\n return schemaCache.size;\n}\n\n/**\n * Load schema by ID from registry and compile\n */\nexport async function compileSchemaById(\n schemaId: string,\n registryOptions?: SchemaRegistryOptions,\n): Promise<CompiledValidator> {\n try {\n const registry = getSchemaRegistry(registryOptions);\n const metadata = await registry.getSchema(schemaId);\n\n const content = await readFile(metadata.path, \"utf-8\");\n const aliases: string[] = [];\n\n const normalizedRelativePath = metadata.relativePath.replace(/\\\\/g, \"/\");\n if (normalizedRelativePath) {\n // Per Canonical URI Resolution Standard (v0.4.2+), include crucible/ module prefix\n aliases.push(\n new URL(`crucible/${normalizedRelativePath}`, \"https://schemas.fulmenhq.dev/\").toString(),\n );\n }\n\n return compileSchema(content, { aliases });\n } catch (error) {\n metrics.counter(\"schema_validation_errors\").inc();\n throw error;\n }\n}\n\n/**\n * Validate data against a schema ID from registry\n */\nexport async function validateDataBySchemaId(\n data: unknown,\n schemaId: string,\n registryOptions?: SchemaRegistryOptions,\n): Promise<SchemaValidationResult> {\n try {\n const validator = await compileSchemaById(schemaId, registryOptions);\n return validateData(data, validator);\n } catch (error) {\n metrics.counter(\"schema_validation_errors\").inc();\n throw error;\n }\n}\n\n/**\n * Validate file against a schema ID from registry\n */\nexport async function validateFileBySchemaId(\n filePath: string,\n schemaId: string,\n registryOptions?: SchemaRegistryOptions,\n): Promise<SchemaValidationResult> {\n try {\n const validator = await compileSchemaById(schemaId, registryOptions);\n return validateFile(filePath, validator);\n } catch (error) {\n metrics.counter(\"schema_validation_errors\").inc();\n throw error;\n }\n}\n","/**\n * Schema CLI - Commander-based CLI for schema operations\n *\n * Provides command-line interface for schema discovery, validation,\n * and normalization operations. This is a developer tool for exploration\n * and testing, not for production use.\n */\n\nimport { readFile, writeFile } from \"node:fs/promises\";\nimport { Command } from \"commander\";\nimport { isGoneatAvailable, runGoneatValidation } from \"./goneat-bridge.js\";\nimport { compareSchemas, normalizeSchema } from \"./normalizer.js\";\nimport { getSchemaRegistry, listSchemas } from \"./registry.js\";\nimport type { CLIOptions, SchemaValidationResult } from \"./types.js\";\nimport { formatDiagnostics } from \"./utils.js\";\nimport { validateFileBySchemaId } from \"./validator.js\";\n\n/**\n * Create CLI command structure\n */\nexport function createCLI(options: CLIOptions = {}): Command {\n const program = new Command();\n\n program\n .name(\"tsfulmen-schema\")\n .description(\"Schema validation and discovery CLI for Fulmen (developer tool)\")\n .version(\"0.1.0\");\n\n // List schemas command\n program\n .command(\"list\")\n .description(\"List available schemas from registry\")\n .argument(\"[prefix]\", \"Filter schemas by prefix\")\n .option(\"--base-dir <path>\", \"Override schema base directory\")\n .action(async (prefix?: string, cmdOptions?: { baseDir?: string }) => {\n try {\n const schemas = await listSchemas(prefix, {\n baseDir: cmdOptions?.baseDir || options.baseDir,\n });\n\n if (schemas.length === 0) {\n console.log(\"No schemas found\");\n return;\n }\n\n console.log(`Found ${schemas.length} schema(s):\\n`);\n for (const schema of schemas) {\n console.log(` ${schema.id}`);\n console.log(` Format: ${schema.format}`);\n console.log(` Path: ${schema.relativePath}`);\n if (schema.description) {\n console.log(` Description: ${schema.description}`);\n }\n console.log();\n }\n } catch (error) {\n console.error(\"Error listing schemas:\", (error as Error).message);\n process.exit(1);\n }\n });\n\n // Show schema command\n program\n .command(\"show\")\n .description(\"Show schema details\")\n .requiredOption(\"--schema-id <id>\", \"Schema ID to show\")\n .option(\"--base-dir <path>\", \"Override schema base directory\")\n .action(async (cmdOptions: { schemaId: string; baseDir?: string }) => {\n try {\n const registry = getSchemaRegistry({\n baseDir: cmdOptions.baseDir || options.baseDir,\n });\n const schema = await registry.getSchema(cmdOptions.schemaId);\n\n console.log(\"Schema Details:\\n\");\n console.log(` ID: ${schema.id}`);\n console.log(` Format: ${schema.format}`);\n console.log(` Path: ${schema.path}`);\n console.log(` Relative Path: ${schema.relativePath}`);\n if (schema.version) {\n console.log(` Version: ${schema.version}`);\n }\n if (schema.description) {\n console.log(` Description: ${schema.description}`);\n }\n if (schema.schemaDraft) {\n console.log(` Schema Draft: ${schema.schemaDraft}`);\n }\n\n // Read and display schema content\n const content = await readFile(schema.path, \"utf-8\");\n console.log(\"\\nSchema Content:\");\n console.log(content);\n } catch (error) {\n console.error(\"Error showing schema:\", (error as Error).message);\n process.exit(1);\n }\n });\n\n // Validate data command\n program\n .command(\"validate\")\n .description(\"Validate data file against schema\")\n .requiredOption(\"--schema-id <id>\", \"Schema ID to validate against\")\n .argument(\"<file>\", \"Data file to validate\")\n .option(\"--use-goneat\", \"Use goneat for validation (requires goneat binary)\")\n .option(\"--goneat-path <path>\", \"Path to goneat binary\")\n .option(\"--base-dir <path>\", \"Override schema base directory\")\n .action(\n async (\n file: string,\n cmdOptions: {\n schemaId: string;\n useGoneat?: boolean;\n goneatPath?: string;\n baseDir?: string;\n },\n ) => {\n try {\n let result: SchemaValidationResult;\n\n if (cmdOptions.useGoneat) {\n // Check goneat availability\n const available = await isGoneatAvailable(cmdOptions.goneatPath);\n if (!available) {\n console.error(\"❌ goneat not available. Install goneat or remove --use-goneat flag.\");\n console.error(\" AJV validation (default) works without external dependencies.\");\n process.exit(1);\n }\n\n // Get schema path\n const registry = getSchemaRegistry({\n baseDir: cmdOptions.baseDir || options.baseDir,\n });\n const schema = await registry.getSchema(cmdOptions.schemaId);\n\n console.log(\"Using goneat validation...\");\n result = await runGoneatValidation(schema.path, file, cmdOptions.goneatPath);\n } else {\n // Use AJV validation (default, library implementation)\n console.log(\"Using AJV validation...\");\n result = await validateFileBySchemaId(file, cmdOptions.schemaId, {\n baseDir: cmdOptions.baseDir || options.baseDir,\n });\n }\n\n if (result.valid) {\n console.log(`✅ Validation passed (${result.source})`);\n process.exit(0);\n } else {\n console.log(`❌ Validation failed (${result.source})`);\n console.log(\"\\nDiagnostics:\");\n console.log(formatDiagnostics(result.diagnostics));\n process.exit(1);\n }\n } catch (error) {\n console.error(\"Error validating file:\", (error as Error).message);\n process.exit(1);\n }\n },\n );\n\n // Validate schema command\n program\n .command(\"validate-schema\")\n .description(\"Validate a schema file itself\")\n .argument(\"<file>\", \"Schema file to validate\")\n .action(async (file: string) => {\n try {\n const content = await readFile(file, \"utf-8\");\n const { validateSchema } = await import(\"./validator.js\");\n const result = await validateSchema(content);\n\n if (result.valid) {\n console.log(\"✅ Schema is valid\");\n process.exit(0);\n } else {\n console.log(\"❌ Schema is invalid\");\n console.log(\"\\nDiagnostics:\");\n console.log(formatDiagnostics(result.diagnostics));\n process.exit(1);\n }\n } catch (error) {\n console.error(\"Error validating schema:\", (error as Error).message);\n process.exit(1);\n }\n });\n\n // Normalize schema command\n program\n .command(\"normalize\")\n .description(\"Normalize schema to canonical JSON format\")\n .argument(\"<file>\", \"Schema file to normalize\")\n .option(\"--compact\", \"Output compact JSON (no formatting)\")\n .option(\"-o, --output <file>\", \"Write to output file instead of stdout\")\n .action(async (file: string, cmdOptions: { compact?: boolean; output?: string }) => {\n try {\n const content = await readFile(file, \"utf-8\");\n const normalized = normalizeSchema(content, {\n compact: cmdOptions.compact,\n });\n\n if (cmdOptions.output) {\n await writeFile(cmdOptions.output, normalized, \"utf-8\");\n console.log(`✅ Normalized schema written to ${cmdOptions.output}`);\n } else {\n console.log(normalized);\n }\n } catch (error) {\n console.error(\"Error normalizing schema:\", (error as Error).message);\n process.exit(1);\n }\n });\n\n // Compare schemas command\n program\n .command(\"compare\")\n .description(\"Compare two schemas for semantic equality\")\n .argument(\"<file1>\", \"First schema file\")\n .argument(\"<file2>\", \"Second schema file\")\n .option(\"--show-normalized\", \"Show normalized outputs\")\n .action(async (file1: string, file2: string, cmdOptions: { showNormalized?: boolean }) => {\n try {\n const content1 = await readFile(file1, \"utf-8\");\n const content2 = await readFile(file2, \"utf-8\");\n\n const result = compareSchemas(content1, content2);\n\n if (result.equal) {\n console.log(\"✅ Schemas are semantically equal\");\n } else {\n console.log(\"❌ Schemas differ\");\n }\n\n if (cmdOptions.showNormalized) {\n console.log(\"\\nNormalized Schema 1:\");\n console.log(result.normalizedA);\n console.log(\"\\nNormalized Schema 2:\");\n console.log(result.normalizedB);\n }\n\n process.exit(result.equal ? 0 : 1);\n } catch (error) {\n console.error(\"Error comparing schemas:\", (error as Error).message);\n process.exit(1);\n }\n });\n\n // Export schema command\n program\n .command(\"export\")\n .description(\"Export schema from registry to file with provenance\")\n .requiredOption(\"--schema-id <id>\", \"Schema ID to export\")\n .requiredOption(\"--out <path>\", \"Output file path\")\n .option(\"--force\", \"Overwrite existing file\", false)\n .option(\"--no-provenance\", \"Exclude provenance metadata\")\n .option(\"--no-validate\", \"Skip schema validation before export\")\n .option(\"--format <format>\", \"Export format (json|yaml|auto)\", \"auto\")\n .option(\"--base-dir <path>\", \"Override schema base directory\")\n .action(\n async (cmdOptions: {\n schemaId: string;\n out: string;\n force?: boolean;\n provenance?: boolean;\n validate?: boolean;\n format?: string;\n baseDir?: string;\n }) => {\n try {\n const { exportSchema } = await import(\"./export.js\");\n const { exitCodes } = await import(\"../foundry/index.js\");\n\n const result = await exportSchema({\n schemaId: cmdOptions.schemaId,\n outPath: cmdOptions.out,\n includeProvenance: cmdOptions.provenance ?? true,\n validate: cmdOptions.validate ?? true,\n overwrite: cmdOptions.force ?? false,\n format: (cmdOptions.format as \"json\" | \"yaml\" | \"auto\") ?? \"auto\",\n baseDir: cmdOptions.baseDir || options.baseDir,\n });\n\n console.log(\"✅ Schema exported successfully\");\n console.log(` Schema ID: ${result.schemaId}`);\n console.log(` Output: ${result.outPath}`);\n console.log(` Format: ${result.format}`);\n\n if (result.provenance) {\n console.log(\"\\nProvenance:\");\n console.log(` Crucible: ${result.provenance.crucible_version}`);\n console.log(` Library: ${result.provenance.library_version}`);\n if (result.provenance.revision) {\n console.log(` Revision: ${result.provenance.revision}`);\n }\n console.log(` Exported: ${result.provenance.exported_at}`);\n }\n\n process.exit(exitCodes.EXIT_SUCCESS);\n } catch (error) {\n const { exitCodes } = await import(\"../foundry/index.js\");\n const { SchemaExportError, SchemaValidationError, ExportErrorReason } = await import(\n \"./errors.js\"\n );\n\n console.error(\"❌ Schema export failed:\", (error as Error).message);\n\n // Map specific error types to appropriate exit codes\n if (error instanceof SchemaExportError) {\n if (error.outPath) {\n console.error(` Output path: ${error.outPath}`);\n }\n\n // Use error reason for type-safe exit code mapping\n switch (error.reason) {\n case ExportErrorReason.FILE_EXISTS:\n case ExportErrorReason.WRITE_FAILED:\n process.exit(exitCodes.EXIT_FILE_WRITE_ERROR);\n break;\n\n case ExportErrorReason.INVALID_FORMAT:\n process.exit(exitCodes.EXIT_INVALID_ARGUMENT);\n break;\n\n default:\n // PROVENANCE_FAILED, UNKNOWN, and any future reasons\n process.exit(exitCodes.EXIT_FAILURE);\n }\n }\n\n if (error instanceof SchemaValidationError) {\n // Schema not found or validation failed\n const errorMsg = error.message.toLowerCase();\n\n if (errorMsg.includes(\"not found\")) {\n process.exit(exitCodes.EXIT_FILE_NOT_FOUND);\n }\n\n // Validation failures\n process.exit(exitCodes.EXIT_DATA_INVALID);\n }\n\n process.exit(exitCodes.EXIT_FAILURE);\n }\n },\n );\n\n // Identity show command\n program\n .command(\"identity-show\")\n .description(\"Show application identity from .fulmen/app.yaml\")\n .option(\"--path <path>\", \"Explicit path to app.yaml\")\n .option(\"--json\", \"Output as JSON\")\n .action(async (cmdOptions: { path?: string; json?: boolean }) => {\n try {\n const { loadIdentity } = await import(\"../appidentity/loader.js\");\n const { exitCodes } = await import(\"../foundry/index.js\");\n\n const identity = await loadIdentity({ path: cmdOptions.path });\n\n if (cmdOptions.json) {\n console.log(JSON.stringify(identity, null, 2));\n } else {\n console.log(\"Application Identity:\\n\");\n console.log(` Binary Name: ${identity.app.binary_name}`);\n console.log(` Vendor: ${identity.app.vendor}`);\n console.log(` Env Prefix: ${identity.app.env_prefix}`);\n console.log(` Config Name: ${identity.app.config_name}`);\n console.log(` Description: ${identity.app.description}`);\n\n if (identity.metadata) {\n console.log(\"\\nMetadata:\");\n if (identity.metadata.license) {\n console.log(` License: ${identity.metadata.license}`);\n }\n if (identity.metadata.repository_category) {\n console.log(` Category: ${identity.metadata.repository_category}`);\n }\n if (identity.metadata.telemetry_namespace) {\n console.log(` Telemetry: ${identity.metadata.telemetry_namespace}`);\n }\n if (identity.metadata.project_url) {\n console.log(` Project URL: ${identity.metadata.project_url}`);\n }\n }\n }\n\n process.exit(exitCodes.EXIT_SUCCESS);\n } catch (error) {\n const { exitCodes } = await import(\"../foundry/index.js\");\n const { AppIdentityError } = await import(\"../appidentity/errors.js\");\n\n console.error(\"❌ Failed to load identity:\", (error as Error).message);\n\n if (error instanceof AppIdentityError) {\n if (error.message.includes(\"not found\")) {\n process.exit(exitCodes.EXIT_FILE_NOT_FOUND);\n }\n if (error.message.includes(\"Invalid\") || error.message.includes(\"validation\")) {\n process.exit(exitCodes.EXIT_DATA_INVALID);\n }\n }\n\n process.exit(exitCodes.EXIT_FAILURE);\n }\n });\n\n // Identity validate command\n program\n .command(\"identity-validate\")\n .description(\"Validate application identity against schema\")\n .argument(\"[file]\", \"Path to app.yaml (defaults to discovery)\")\n .action(async (file?: string) => {\n try {\n const { loadIdentity } = await import(\"../appidentity/loader.js\");\n const { exitCodes } = await import(\"../foundry/index.js\");\n\n console.log(\"Validating application identity...\");\n\n const identity = await loadIdentity({ path: file });\n\n console.log(\"✅ Identity is valid\");\n console.log(` Binary: ${identity.app.binary_name}`);\n console.log(` Vendor: ${identity.app.vendor}`);\n\n process.exit(exitCodes.EXIT_SUCCESS);\n } catch (error) {\n const { exitCodes } = await import(\"../foundry/index.js\");\n const { AppIdentityError } = await import(\"../appidentity/errors.js\");\n\n console.error(\"❌ Identity validation failed:\", (error as Error).message);\n\n if (error instanceof AppIdentityError) {\n if (error.message.includes(\"not found\")) {\n process.exit(exitCodes.EXIT_FILE_NOT_FOUND);\n }\n if (error.message.includes(\"Invalid\") || error.message.includes(\"validation\")) {\n process.exit(exitCodes.EXIT_DATA_INVALID);\n }\n }\n\n process.exit(exitCodes.EXIT_FAILURE);\n }\n });\n\n return program;\n}\n","/**\n * Schema export utilities - implements schema export with provenance\n */\n\nimport { access, mkdir, readFile, writeFile } from \"node:fs/promises\";\nimport { dirname, extname, join } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { parse as parseYAML, stringify as stringifyYAML } from \"yaml\";\nimport { SchemaExportError, SchemaValidationError } from \"./errors.js\";\nimport { getSchemaRegistry } from \"./registry.js\";\nimport type {\n ExportSchemaOptions,\n ExportSchemaResult,\n SchemaExportFormat,\n SchemaProvenanceMetadata,\n} from \"./types.js\";\nimport { validateSchema } from \"./validator.js\";\n\n/**\n * Extract provenance metadata from Crucible sync metadata\n */\nasync function extractProvenanceMetadata(schemaId: string): Promise<SchemaProvenanceMetadata> {\n try {\n // Read Crucible metadata using proper path resolution\n const __filename = fileURLToPath(import.meta.url);\n const __dirname = dirname(__filename);\n const metadataPath = join(__dirname, \"..\", \"..\", \".crucible\", \"metadata\", \"metadata.yaml\");\n const metadataContent = await readFile(metadataPath, \"utf-8\");\n\n // Parse YAML properly to avoid brittle regex matching\n const metadata = parseYAML(metadataContent) as {\n sources?: Array<{\n name?: string;\n version?: string;\n commit?: string;\n }>;\n };\n\n // Extract Crucible source metadata (first source is typically 'crucible')\n const crucibleSource = metadata.sources?.[0];\n const crucibleVersion = crucibleSource?.version || \"unknown\";\n const revision = crucibleSource?.commit;\n\n // Read library version from package.json\n const pkgPath = join(__dirname, \"..\", \"..\", \"package.json\");\n const pkgContent = await readFile(pkgPath, \"utf-8\");\n const pkg = JSON.parse(pkgContent) as { version: string };\n\n return {\n schema_id: schemaId,\n crucible_version: crucibleVersion,\n library_version: pkg.version,\n revision: revision,\n exported_at: new Date().toISOString(),\n export_source: \"tsfulmen\",\n };\n } catch (error) {\n throw SchemaExportError.provenanceFailed((error as Error).message, error as Error);\n }\n}\n\n/**\n * Embed provenance metadata in schema content\n */\nfunction embedProvenance(\n schemaContent: Record<string, unknown>,\n provenance: SchemaProvenanceMetadata,\n format: SchemaExportFormat,\n): string {\n if (format === \"json\") {\n // For JSON: embed under $comment[\"x-crucible-source\"]\n const withProvenance = {\n ...schemaContent,\n $comment: {\n ...(typeof schemaContent.$comment === \"object\" ? schemaContent.$comment : {}),\n \"x-crucible-source\": provenance,\n },\n };\n return JSON.stringify(withProvenance, null, 2);\n }\n\n // For YAML: prepend comment block\n const yamlContent = stringifyYAML(schemaContent, {\n indent: 2,\n lineWidth: 0,\n });\n\n const provenanceComment = [\n \"# x-crucible-source:\",\n `# schema_id: ${provenance.schema_id}`,\n `# crucible_version: ${provenance.crucible_version}`,\n `# library_version: ${provenance.library_version}`,\n ...(provenance.revision ? [`# revision: ${provenance.revision}`] : []),\n `# exported_at: ${provenance.exported_at}`,\n `# export_source: ${provenance.export_source}`,\n \"\",\n ].join(\"\\n\");\n\n return provenanceComment + yamlContent;\n}\n\n/**\n * Detect export format from file extension or explicit option\n */\nfunction detectFormat(outPath: string, formatOption?: SchemaExportFormat): SchemaExportFormat {\n if (formatOption && formatOption !== \"auto\") {\n return formatOption;\n }\n\n const ext = extname(outPath).toLowerCase();\n switch (ext) {\n case \".json\":\n return \"json\";\n case \".yaml\":\n case \".yml\":\n return \"yaml\";\n default:\n throw SchemaExportError.invalidFormat(ext, outPath);\n }\n}\n\n/**\n * Export schema from registry to file with provenance\n *\n * @param options - Export options\n * @returns Export result with metadata\n *\n * @throws {SchemaExportError} If export fails\n * @throws {SchemaValidationError} If schema not found or validation fails\n *\n * @example\n * ```typescript\n * import { exportSchema } from '@fulmenhq/tsfulmen/schema';\n *\n * await exportSchema({\n * schemaId: 'library/foundry/v1.0.0/exit-codes',\n * outPath: './schemas/exit-codes.schema.json',\n * includeProvenance: true,\n * validate: true,\n * });\n * ```\n */\nexport async function exportSchema(options: ExportSchemaOptions): Promise<ExportSchemaResult> {\n const {\n schemaId,\n outPath,\n includeProvenance = true,\n validate = true,\n overwrite = false,\n format: formatOption,\n baseDir,\n } = options;\n\n // Detect output format\n const format = detectFormat(outPath, formatOption);\n\n // Check if file exists\n if (!overwrite) {\n try {\n await access(outPath);\n throw SchemaExportError.fileExists(outPath);\n } catch (error) {\n // File doesn't exist - proceed\n if ((error as NodeJS.ErrnoException).code !== \"ENOENT\") {\n throw error;\n }\n }\n }\n\n // Get schema from registry\n const registry = getSchemaRegistry({ baseDir });\n const schema = await registry.getSchema(schemaId);\n\n // Read schema content\n const schemaContent = await readFile(schema.path, \"utf-8\");\n\n // Validate if requested\n if (validate) {\n const validationResult = await validateSchema(schemaContent);\n if (!validationResult.valid) {\n throw SchemaValidationError.validationFailed(schemaId, validationResult.diagnostics, {\n type: \"file\",\n id: schema.path,\n });\n }\n }\n\n // Parse schema content\n let schemaObject: Record<string, unknown>;\n try {\n schemaObject = JSON.parse(schemaContent) as Record<string, unknown>;\n } catch {\n schemaObject = parseYAML(schemaContent) as Record<string, unknown>;\n }\n\n // Freeze schema object to prevent mutation\n Object.freeze(schemaObject);\n\n let provenance: SchemaProvenanceMetadata | undefined;\n let outputContent: string;\n\n if (includeProvenance) {\n // Extract provenance metadata\n provenance = await extractProvenanceMetadata(schemaId);\n\n // Embed provenance in output\n outputContent = embedProvenance(schemaObject, provenance, format);\n } else {\n // Export without provenance\n if (format === \"json\") {\n outputContent = JSON.stringify(schemaObject, null, 2);\n } else {\n outputContent = stringifyYAML(schemaObject, { indent: 2, lineWidth: 0 });\n }\n }\n\n // Ensure output directory exists\n await mkdir(dirname(outPath), { recursive: true });\n\n // Write to file\n try {\n await writeFile(outPath, outputContent, \"utf-8\");\n } catch (error) {\n throw SchemaExportError.writeFailed(outPath, error as Error);\n }\n\n return {\n success: true,\n schemaId,\n outPath,\n format,\n includeProvenance,\n provenance,\n };\n}\n\n/**\n * Strip provenance metadata from schema content\n *\n * This helper is useful for comparing exported schemas with runtime\n * schemas or validating that provenance doesn't affect schema semantics.\n *\n * @param content - Schema content (JSON or YAML string)\n * @returns Schema content without provenance metadata\n *\n * @example\n * ```typescript\n * import { stripProvenance } from '@fulmenhq/tsfulmen/schema';\n *\n * const exported = await readFile('./schema.json', 'utf-8');\n * const withoutProvenance = stripProvenance(exported);\n * ```\n */\nexport function stripProvenance(content: string): string {\n try {\n // Try parsing as JSON\n const parsed = JSON.parse(content) as Record<string, unknown>;\n\n // Remove provenance from $comment\n if (parsed.$comment && typeof parsed.$comment === \"object\") {\n const comment = { ...parsed.$comment } as Record<string, unknown>;\n delete comment[\"x-crucible-source\"];\n\n // Remove $comment entirely if it's now empty\n if (Object.keys(comment).length === 0) {\n delete parsed.$comment;\n } else {\n parsed.$comment = comment;\n }\n }\n\n return JSON.stringify(parsed, null, 2);\n } catch {\n // YAML format - strip comment lines\n const lines = content.split(\"\\n\");\n const filtered = lines.filter((line) => {\n const trimmed = line.trim();\n return !(\n trimmed.startsWith(\"# x-crucible-source:\") ||\n (trimmed.startsWith(\"# \") &&\n /^#\\s+(schema_id|crucible_version|library_version|revision|exported_at|export_source):/.test(\n trimmed,\n ))\n );\n });\n\n // Remove leading blank lines\n while (filtered.length > 0 && filtered[0]?.trim() === \"\") {\n filtered.shift();\n }\n\n return filtered.join(\"\\n\");\n }\n}\n","/**\n * Schema validation module - implements Fulmen Schema Validation Standard\n *\n * Provides schema discovery, validation, and normalization utilities for Crucible schemas\n * with JSON Schema 2020-12 support and optional goneat integration.\n */\n\nexport const VERSION = \"0.1.0\";\n\nexport {\n applyFulmenAjvFormats,\n type FulmenAjvFormatsOptions,\n} from \"./ajv-formats.js\";\n\n// CLI exports\nexport { createCLI } from \"./cli.js\";\n// Error exports\nexport * from \"./errors.js\";\n// Export exports\nexport { exportSchema, stripProvenance } from \"./export.js\";\n// Goneat bridge exports (CLI-only, optional)\nexport {\n detectGoneat,\n isGoneatAvailable,\n runGoneatValidation,\n} from \"./goneat-bridge.js\";\n// Normalizer exports\nexport { compareSchemas, normalizeSchema } from \"./normalizer.js\";\n// Registry exports\nexport {\n getSchema,\n getSchemaByPath,\n getSchemaRegistry,\n hasSchema,\n listSchemas,\n SchemaRegistry,\n} from \"./registry.js\";\n// Core exports\nexport type {\n AjvError,\n CLIOptions,\n CompiledValidator,\n ExportSchemaOptions,\n ExportSchemaResult,\n SchemaComparisonResult,\n SchemaExportFormat,\n SchemaFormat,\n SchemaInput,\n SchemaMetadata,\n SchemaNormalizationOptions,\n SchemaProvenanceMetadata,\n SchemaRegistryOptions,\n SchemaSource,\n SchemaValidationDiagnostic,\n SchemaValidationOptions,\n SchemaValidationResult,\n} from \"./types.js\";\n// Utility exports\nexport {\n countDiagnostics,\n createDiagnostic,\n formatDiagnostics,\n formatValidationResult,\n groupDiagnosticsBySeverity,\n isValidationError,\n normalizePointer,\n} from \"./utils.js\";\n// Validator exports\nexport {\n clearCache,\n compileSchema,\n compileSchemaById,\n getCacheSize,\n validateData,\n validateDataBySchemaId,\n validateFile,\n validateFileBySchemaId,\n validateSchema,\n} from \"./validator.js\";\n","/**\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","/**\n * Application Identity Errors\n *\n * Module-specific error classes for identity operations\n */\n\nimport { FulmenError, type FulmenErrorData } from \"../errors/index.js\";\nimport type { SchemaValidationDiagnostic } from \"../schema/types.js\";\n\n/**\n * Base error class for app identity operations\n */\nexport class AppIdentityError extends FulmenError {\n public readonly identityPath?: string;\n\n constructor(message: string, identityPath?: string, cause?: Error) {\n // Build FulmenErrorData\n let errorData: FulmenErrorData;\n\n if (cause) {\n errorData = FulmenError.fromError(cause, {\n code: \"APP_IDENTITY_ERROR\",\n severity: \"high\",\n context: { identityPath },\n }).data;\n } else {\n errorData = {\n code: \"APP_IDENTITY_ERROR\",\n message,\n severity: \"high\",\n timestamp: new Date().toISOString(),\n context: { identityPath },\n };\n }\n\n super(errorData);\n this.name = \"AppIdentityError\";\n this.identityPath = identityPath;\n\n // Maintains proper stack trace for where our error was thrown (only available on V8)\n if (Error.captureStackTrace) {\n Error.captureStackTrace(this, AppIdentityError);\n }\n }\n\n /**\n * Create error for identity not found\n */\n static notFound(searchedPaths: string[]): AppIdentityError {\n const message = `App identity not found\\nSearched paths:\\n${searchedPaths.map((p) => ` - ${p}`).join(\"\\n\")}`;\n return new AppIdentityError(message);\n }\n\n /**\n * Create error for schema validation failure\n */\n static validationFailed(\n path: string,\n diagnostics: SchemaValidationDiagnostic[],\n ): AppIdentityError {\n const errorCount = diagnostics.filter((d) => d.severity === \"ERROR\").length;\n const warningCount = diagnostics.filter((d) => d.severity === \"WARN\").length;\n\n let message = `Invalid app identity: ${path}\\n`;\n message += `Validation errors: ${errorCount} error(s), ${warningCount} warning(s)\\n`;\n\n // Include first few diagnostics\n const displayDiagnostics = diagnostics.slice(0, 3);\n for (const diag of displayDiagnostics) {\n message += ` - ${diag.message}`;\n if (diag.pointer) {\n message += ` at ${diag.pointer}`;\n }\n message += \"\\n\";\n }\n\n if (diagnostics.length > 3) {\n message += ` ... and ${diagnostics.length - 3} more\\n`;\n }\n\n return new AppIdentityError(message, path);\n }\n\n /**\n * Create error for environment variable override pointing to missing file\n */\n static envOverrideMissing(envPath: string): AppIdentityError {\n const message = `FULMEN_APP_IDENTITY_PATH points to missing file: ${envPath}\\n`;\n return new AppIdentityError(message, envPath);\n }\n\n /**\n * Create error for YAML parsing failure\n */\n static parseFailed(path: string, cause: Error): AppIdentityError {\n const message = `Failed to parse identity file: ${path}\\n${cause.message}`;\n return new AppIdentityError(message, path, cause);\n }\n\n /**\n * Create error for file read failure\n */\n static readFailed(path: string, cause: Error): AppIdentityError {\n const message = `Failed to read identity file: ${path}\\n${cause.message}`;\n return new AppIdentityError(message, path, cause);\n }\n\n /**\n * Create error for embedded identity already registered\n *\n * Uses first-wins semantics - once registered, cannot be replaced\n */\n static alreadyRegistered(): AppIdentityError {\n const message =\n \"Embedded identity already registered. \" +\n \"Registration uses first-wins semantics and cannot be replaced.\";\n return new AppIdentityError(message);\n }\n\n /**\n * Create error for embedded identity YAML parsing failure\n */\n static embeddedParseFailed(cause: Error): AppIdentityError {\n const message = `Failed to parse embedded identity YAML: ${cause.message}`;\n return new AppIdentityError(message, undefined, cause);\n }\n\n /**\n * Create error for embedded identity schema validation failure\n */\n static embeddedValidationFailed(diagnostics: SchemaValidationDiagnostic[]): AppIdentityError {\n const errorCount = diagnostics.filter((d) => d.severity === \"ERROR\").length;\n const warningCount = diagnostics.filter((d) => d.severity === \"WARN\").length;\n\n let message = \"Invalid embedded identity\\n\";\n message += `Validation errors: ${errorCount} error(s), ${warningCount} warning(s)\\n`;\n\n const displayDiagnostics = diagnostics.slice(0, 3);\n for (const diag of displayDiagnostics) {\n message += ` - ${diag.message}`;\n if (diag.pointer) {\n message += ` at ${diag.pointer}`;\n }\n message += \"\\n\";\n }\n\n if (diagnostics.length > 3) {\n message += ` ... and ${diagnostics.length - 3} more\\n`;\n }\n\n return new AppIdentityError(message);\n }\n}\n","/**\n * Embedded Identity Registration\n *\n * Provides a mechanism to register embedded identity at application startup\n * for standalone binary/package support. This allows applications to work\n * without requiring .fulmen/app.yaml to be discoverable on the filesystem.\n *\n * Discovery precedence (with embedded fallback):\n * 1. Explicit path parameter\n * 2. FULMEN_APP_IDENTITY_PATH environment variable\n * 3. Ancestor search from CWD\n * 4. Embedded identity fallback (this module)\n */\n\nimport { parse as parseYAML } from \"yaml\";\nimport { validateDataBySchemaId } from \"../schema/index.js\";\nimport { APP_IDENTITY_SCHEMA_ID } from \"./constants.js\";\nimport { AppIdentityError } from \"./errors.js\";\nimport type { Identity, RegisterEmbeddedIdentityOptions } from \"./types.js\";\n\n/**\n * Process-level storage for embedded identity\n * Uses first-wins semantics - once registered, cannot be replaced\n */\nlet embeddedIdentity: Identity | null = null;\nlet isRegistered = false;\n\n/**\n * Deep freeze an object and all its nested properties\n */\nfunction deepFreeze<T>(obj: T): T {\n Object.freeze(obj);\n Object.getOwnPropertyNames(obj).forEach((prop) => {\n // biome-ignore lint/suspicious/noExplicitAny: Required for recursive property access\n const value = (obj as any)[prop];\n if (\n value !== null &&\n (typeof value === \"object\" || typeof value === \"function\") &&\n !Object.isFrozen(value)\n ) {\n deepFreeze(value);\n }\n });\n return obj;\n}\n\n/**\n * Register embedded identity YAML that serves as fallback when\n * runtime discovery cannot find an external app.yaml.\n *\n * Semantics:\n * - First registration wins (subsequent calls throw error)\n * - Validates against schema on registration (unless `skipValidation`)\n * - Stores as immutable process-level fallback\n *\n * @param data - YAML string or pre-parsed Identity object\n * @param options - Optional registration options (see {@link RegisterEmbeddedIdentityOptions})\n * @throws {AppIdentityError} If already registered or validation fails\n *\n * @example\n * ```typescript\n * // From npm package entry point\n * import { registerEmbeddedIdentity } from \"@fulmenhq/tsfulmen/appidentity\";\n * import { readFileSync } from \"node:fs\";\n * import { fileURLToPath } from \"node:url\";\n * import { dirname, join } from \"node:path\";\n *\n * const __filename = fileURLToPath(import.meta.url);\n * const __dirname = dirname(__filename);\n * const embeddedPath = join(__dirname, \"..\", \".fulmen\", \"app.yaml\");\n *\n * try {\n * const yaml = readFileSync(embeddedPath, \"utf-8\");\n * registerEmbeddedIdentity(yaml);\n * } catch {\n * // Embedded identity not available - discovery will use filesystem\n * }\n * ```\n *\n * @example\n * ```typescript\n * // In a `bun --compile` single-file binary, the FS-backed schema registry\n * // is unavailable. Register a build-time-embedded, CI-validated identity\n * // without re-validating against the (absent) schema registry:\n * import embeddedYaml from \"./app-identity.embedded.js\"; // inlined at build\n * registerEmbeddedIdentity(embeddedYaml, { skipValidation: true });\n * ```\n */\nexport async function registerEmbeddedIdentity(\n data: string | Identity,\n options?: RegisterEmbeddedIdentityOptions,\n): Promise<void> {\n // First-wins semantics\n if (isRegistered) {\n throw AppIdentityError.alreadyRegistered();\n }\n\n const skipValidation = options?.skipValidation ?? false;\n let identity: Identity;\n\n if (typeof data === \"string\") {\n // Parse YAML\n let parsed: unknown;\n try {\n parsed = parseYAML(data);\n } catch (error) {\n throw AppIdentityError.embeddedParseFailed(\n error instanceof Error ? error : new Error(String(error)),\n );\n }\n\n // Validate against schema (unless skipValidation)\n if (!skipValidation) {\n const result = await validateDataBySchemaId(parsed, APP_IDENTITY_SCHEMA_ID);\n if (!result.valid) {\n throw AppIdentityError.embeddedValidationFailed(result.diagnostics);\n }\n }\n\n identity = parsed as Identity;\n } else {\n // Pre-parsed object - still validate (unless skipValidation)\n if (!skipValidation) {\n const result = await validateDataBySchemaId(data, APP_IDENTITY_SCHEMA_ID);\n if (!result.valid) {\n throw AppIdentityError.embeddedValidationFailed(result.diagnostics);\n }\n }\n identity = data;\n }\n\n // Deep freeze and store\n embeddedIdentity = deepFreeze(structuredClone(identity)) as Identity;\n isRegistered = true;\n}\n\n/**\n * Check if embedded identity has been registered\n *\n * @returns true if registerEmbeddedIdentity() has been called successfully\n */\nexport function hasEmbeddedIdentity(): boolean {\n return isRegistered;\n}\n\n/**\n * Get the registered embedded identity\n *\n * @returns Frozen identity object or null if not registered\n */\nexport function getEmbeddedIdentity(): Identity | null {\n return embeddedIdentity;\n}\n\n/**\n * Clear embedded identity registration\n *\n * WARNING: For testing only. In production, embedded identity should be\n * set once at startup and never cleared.\n */\nexport function clearEmbeddedIdentity(): void {\n embeddedIdentity = null;\n isRegistered = false;\n}\n","/**\n * Application Identity Cache\n *\n * Process-level caching for identity objects with immutability guarantees\n */\n\nimport type { Identity } from \"./types.js\";\n\n/**\n * Process-level cache storage\n * null = not cached, Identity = cached value\n */\nlet cachedIdentity: Identity | null = null;\n\n/**\n * Get cached identity if available\n *\n * @returns Cached identity or null if not cached\n */\nexport function getCachedIdentity(): Identity | null {\n return cachedIdentity;\n}\n\n/**\n * Set cached identity\n *\n * Identity object should already be frozen before caching\n *\n * @param identity - Identity to cache (must be frozen)\n */\nexport function setCachedIdentity(identity: Identity): void {\n cachedIdentity = identity;\n}\n\n/**\n * Clear the identity cache\n *\n * Useful for testing or when identity needs to be reloaded\n */\nexport function clearIdentityCache(): void {\n cachedIdentity = null;\n}\n","/**\n * Application Identity Discovery\n *\n * Implements the Crucible discovery precedence algorithm:\n * 1. Explicit path parameter (highest priority)\n * 2. Environment variable override (FULMEN_APP_IDENTITY_PATH)\n * 3. Ancestor search from CWD upward\n */\n\nimport { access } from \"node:fs/promises\";\nimport { dirname, join } from \"node:path\";\nimport {\n APP_IDENTITY_DIR,\n APP_IDENTITY_ENV_VAR,\n APP_IDENTITY_FILENAME,\n MAX_ANCESTOR_SEARCH_DEPTH,\n} from \"./constants.js\";\nimport { AppIdentityError } from \"./errors.js\";\n\n/**\n * Discovery result with path and source\n */\nexport interface DiscoveryResult {\n readonly path: string;\n readonly source: \"explicit\" | \"env\" | \"ancestor\" | \"test\";\n}\n\n/**\n * Options for identity discovery\n */\nexport interface DiscoveryOptions {\n /**\n * Explicit path override (highest priority)\n */\n readonly path?: string;\n\n /**\n * Starting directory for ancestor search\n * Defaults to process.cwd()\n */\n readonly startDir?: string;\n}\n\n/**\n * Discover application identity file using Crucible precedence algorithm\n *\n * Discovery order:\n * 1. Explicit path parameter (throws if not found)\n * 2. FULMEN_APP_IDENTITY_PATH env var (throws if set but not found)\n * 3. Ancestor search from startDir (throws if not found after max depth)\n *\n * @param options - Discovery options\n * @returns Discovery result with path and source\n * @throws {AppIdentityError} If identity file not found or inaccessible\n */\nexport async function discoverIdentityPath(\n options?: DiscoveryOptions,\n): Promise<DiscoveryResult | null> {\n // 1. Explicit path parameter (highest priority)\n if (options?.path) {\n const exists = await fileExists(options.path);\n if (!exists) {\n throw AppIdentityError.notFound([options.path]);\n }\n return { path: options.path, source: \"explicit\" };\n }\n\n // 2. Environment variable override\n const envPath = process.env[APP_IDENTITY_ENV_VAR];\n if (envPath) {\n const exists = await fileExists(envPath);\n if (!exists) {\n throw AppIdentityError.envOverrideMissing(envPath);\n }\n return { path: envPath, source: \"env\" };\n }\n\n // 3. Ancestor search from startDir\n const startDir = options?.startDir || process.cwd();\n const result = await searchAncestors(startDir);\n if (result) {\n return { path: result, source: \"ancestor\" };\n }\n\n return null;\n}\n\n/**\n * Search ancestor directories for identity file\n *\n * Walks upward from startDir to filesystem root, looking for .fulmen/app.yaml\n * Stops at MAX_ANCESTOR_SEARCH_DEPTH or filesystem root\n *\n * @param startDir - Directory to start search from\n * @returns Path to identity file if found, null otherwise\n * @throws {AppIdentityError} If max depth reached or filesystem root reached without finding file\n */\nasync function searchAncestors(startDir: string): Promise<string | null> {\n let currentDir = startDir;\n const searchedPaths: string[] = [];\n\n for (let i = 0; i < MAX_ANCESTOR_SEARCH_DEPTH; i++) {\n const candidatePath = join(currentDir, APP_IDENTITY_DIR, APP_IDENTITY_FILENAME);\n searchedPaths.push(candidatePath);\n\n if (await fileExists(candidatePath)) {\n return candidatePath;\n }\n\n const parentDir = dirname(currentDir);\n if (parentDir === currentDir) {\n // Reached filesystem root\n throw AppIdentityError.notFound(searchedPaths);\n }\n currentDir = parentDir;\n }\n\n // Max depth reached\n throw AppIdentityError.notFound(searchedPaths);\n}\n\n/**\n * Check if a file exists and is accessible\n *\n * @param path - Path to check\n * @returns true if file exists and is readable, false otherwise\n */\nasync function fileExists(path: string): Promise<boolean> {\n try {\n await access(path);\n return true;\n } catch {\n return false;\n }\n}\n","/**\n * Application Identity Loader\n *\n * Main loading logic with YAML parsing, schema validation, and caching\n */\n\nimport { readFile } from \"node:fs/promises\";\nimport { parse as parseYAML } from \"yaml\";\nimport { validateDataBySchemaId } from \"../schema/index.js\";\nimport { clearIdentityCache, getCachedIdentity, setCachedIdentity } from \"./cache.js\";\nimport { APP_IDENTITY_ENV_VAR, APP_IDENTITY_SCHEMA_ID } from \"./constants.js\";\nimport { discoverIdentityPath } from \"./discovery.js\";\nimport { getEmbeddedIdentity } from \"./embedded.js\";\nimport { AppIdentityError } from \"./errors.js\";\nimport type { Identity, LoadIdentityOptions } from \"./types.js\";\n\n/**\n * Deep freeze an object and all its nested properties\n *\n * Recursively freezes an object and all nested objects/functions to ensure\n * complete immutability. This prevents accidental mutations of identity data.\n *\n * Note: Uses `any` type assertion (line 28) to access arbitrary properties\n * during recursive traversal. This is necessary because TypeScript's generic\n * constraint system cannot express \"any object with indexable properties\"\n * without losing the return type safety. The `any` is scoped to a single\n * line and protected by runtime guards.\n *\n * @param obj - Object to freeze\n * @returns Frozen object (same type as input)\n */\nfunction deepFreeze<T>(obj: T): T {\n // Freeze the object itself\n Object.freeze(obj);\n\n // Recursively freeze all properties\n Object.getOwnPropertyNames(obj).forEach((prop) => {\n // biome-ignore lint/suspicious/noExplicitAny: Required for recursive property access - see function docs\n const value = (obj as any)[prop];\n if (\n value !== null &&\n (typeof value === \"object\" || typeof value === \"function\") &&\n !Object.isFrozen(value)\n ) {\n deepFreeze(value);\n }\n });\n\n return obj;\n}\n\n/**\n * Load application identity from .fulmen/app.yaml\n *\n * Discovery order:\n * 1. Test injection (options.identity) - bypasses all discovery and caching\n * 2. Explicit path (options.path)\n * 3. Environment variable (FULMEN_APP_IDENTITY_PATH)\n * 4. Ancestor search from startDir or CWD\n * 5. Embedded identity fallback (if registered via registerEmbeddedIdentity)\n *\n * Results are cached after first successful load unless skipCache is true.\n * Test injections are never cached.\n *\n * @param options - Load options\n * @returns Frozen, immutable identity object\n * @throws {AppIdentityError} If identity not found, invalid, or unreadable\n */\nexport async function loadIdentity(options?: LoadIdentityOptions): Promise<Identity> {\n // Test injection (never caches)\n if (options?.identity) {\n return deepFreeze(structuredClone(options.identity)) as Identity;\n }\n\n // Check cache unless skipCache\n if (!options?.skipCache) {\n const cached = getCachedIdentity();\n if (cached) {\n return cached;\n }\n }\n\n // Discover file - may throw AppIdentityError.notFound or return null\n let discovery: Awaited<ReturnType<typeof discoverIdentityPath>>;\n try {\n discovery = await discoverIdentityPath({\n path: options?.path,\n startDir: options?.startDir,\n });\n } catch (error) {\n // Discovery failed (e.g., reached filesystem root without finding identity)\n // Embedded fallback MUST NOT override explicit path or env override semantics.\n const hasExplicitPath = Boolean(options?.path);\n const hasEnvOverride = Boolean(process.env[APP_IDENTITY_ENV_VAR]);\n\n if (!hasExplicitPath && !hasEnvOverride && error instanceof AppIdentityError) {\n const embedded = getEmbeddedIdentity();\n if (embedded) {\n // Cache the embedded identity for subsequent calls\n setCachedIdentity(embedded);\n return embedded;\n }\n }\n\n throw error;\n }\n\n // If discovery returned null (no env var, no explicit path, and ancestor search returned null)\n if (!discovery) {\n const embedded = getEmbeddedIdentity();\n if (embedded) {\n // Cache the embedded identity for subsequent calls\n setCachedIdentity(embedded);\n return embedded;\n }\n throw AppIdentityError.notFound([]);\n }\n\n // Read file\n let content: string;\n try {\n content = await readFile(discovery.path, \"utf-8\");\n } catch (error) {\n throw AppIdentityError.readFailed(\n discovery.path,\n error instanceof Error ? error : new Error(String(error)),\n );\n }\n\n // Parse YAML\n let parsed: unknown;\n try {\n parsed = parseYAML(content);\n } catch (error) {\n throw AppIdentityError.parseFailed(\n discovery.path,\n error instanceof Error ? error : new Error(String(error)),\n );\n }\n\n // Validate against schema (unless skipValidation)\n if (!options?.skipValidation) {\n const result = await validateDataBySchemaId(parsed, APP_IDENTITY_SCHEMA_ID);\n\n if (!result.valid) {\n throw AppIdentityError.validationFailed(discovery.path, result.diagnostics);\n }\n }\n\n // Deep freeze for immutability\n const identity = deepFreeze(structuredClone(parsed)) as Identity;\n\n // Cache result\n setCachedIdentity(identity);\n\n return identity;\n}\n\n/**\n * Get cached identity without triggering load\n *\n * @returns Cached identity or null if not cached\n */\n/**\n * Clear the identity cache\n *\n * Useful for testing or when identity needs to be reloaded\n */\nexport { clearIdentityCache, getCachedIdentity };\n","import type { Identity } from \"./types.js\";\n\nexport type RuntimeName = \"bun\" | \"node\" | \"unknown\";\n\nexport interface RuntimeInfo {\n service: {\n name: string;\n vendor?: string;\n version?: string;\n };\n runtime: {\n name: RuntimeName;\n version?: string;\n };\n platform: {\n os: NodeJS.Platform;\n arch: string;\n };\n}\n\nexport interface BuildRuntimeInfoOptions {\n identity?: Identity;\n version?: string;\n serviceName?: string;\n vendor?: string;\n}\n\nfunction detectRuntime(): { name: RuntimeName; version?: string } {\n const versions = process.versions as unknown as Record<string, string | undefined>;\n\n if (typeof versions.bun === \"string\" && versions.bun.length > 0) {\n return { name: \"bun\", version: versions.bun };\n }\n\n if (typeof versions.node === \"string\" && versions.node.length > 0) {\n return { name: \"node\", version: versions.node };\n }\n\n return { name: \"unknown\" };\n}\n\n/**\n * Build a minimal runtime info payload suitable for discovery endpoints.\n */\nexport function buildRuntimeInfo(options: BuildRuntimeInfoOptions = {}): RuntimeInfo {\n const runtime = detectRuntime();\n\n const serviceName = options.serviceName ?? options.identity?.app.binary_name ?? \"unknown-service\";\n const vendor = options.vendor ?? options.identity?.app.vendor;\n\n return {\n service: {\n name: serviceName,\n vendor,\n version: options.version,\n },\n runtime,\n platform: {\n os: process.platform,\n arch: process.arch,\n },\n };\n}\n","/**\n * Application Identity Module\n *\n * Provides typed access to .fulmen/app.yaml identity metadata\n * Layer 0 module: zero Fulmen module dependencies\n */\n\n// Constants\nexport {\n APP_IDENTITY_DIR,\n APP_IDENTITY_ENV_VAR,\n APP_IDENTITY_FILENAME,\n APP_IDENTITY_SCHEMA_ID,\n MAX_ANCESTOR_SEARCH_DEPTH,\n} from \"./constants.js\";\n\n// Embedded identity (for standalone binary/package support)\nexport {\n clearEmbeddedIdentity,\n getEmbeddedIdentity,\n hasEmbeddedIdentity,\n registerEmbeddedIdentity,\n} from \"./embedded.js\";\n\n// Errors\nexport { AppIdentityError } from \"./errors.js\";\nexport type { ConfigIdentifiers } from \"./helpers.js\";\n// Helpers\nexport {\n buildEnvVar,\n getBinaryName,\n getConfigIdentifiers,\n getConfigName,\n getEnvPrefix,\n getEnvVar,\n getTelemetryNamespace,\n getVendor,\n} from \"./helpers.js\";\n// Functions\nexport {\n clearIdentityCache,\n getCachedIdentity,\n loadIdentity,\n} from \"./loader.js\";\n\nexport {\n type BuildRuntimeInfoOptions,\n buildRuntimeInfo,\n type RuntimeInfo,\n type RuntimeName,\n} from \"./runtime.js\";\n// Types\nexport type {\n AppIdentity,\n Identity,\n IdentityMetadata,\n LoadIdentityOptions,\n PythonMetadata,\n RegisterEmbeddedIdentityOptions,\n RepositoryCategory,\n} from \"./types.js\";\n","/**\n * Application Identity Helpers\n *\n * Convenience functions for accessing identity fields\n * All helpers use loadIdentity() under the hood for caching benefits\n */\n\nimport { loadIdentity } from \"./loader.js\";\nimport type { LoadIdentityOptions } from \"./types.js\";\n\n/**\n * Config identifiers for path construction\n */\nexport interface ConfigIdentifiers {\n readonly vendor: string;\n readonly configName: string;\n}\n\n/**\n * Get the binary name from app identity\n *\n * @param options - Load options (optional)\n * @returns Binary name (e.g., 'myapp')\n */\nexport async function getBinaryName(options?: LoadIdentityOptions): Promise<string> {\n const identity = await loadIdentity(options);\n return identity.app.binary_name;\n}\n\n/**\n * Get the vendor namespace from app identity\n *\n * @param options - Load options (optional)\n * @returns Vendor namespace (e.g., 'acmecorp')\n */\nexport async function getVendor(options?: LoadIdentityOptions): Promise<string> {\n const identity = await loadIdentity(options);\n return identity.app.vendor;\n}\n\n/**\n * Get the environment variable prefix from app identity\n *\n * @param options - Load options (optional)\n * @returns Env prefix (e.g., 'MYAPP_')\n */\nexport async function getEnvPrefix(options?: LoadIdentityOptions): Promise<string> {\n const identity = await loadIdentity(options);\n return identity.app.env_prefix;\n}\n\n/**\n * Get the config directory name from app identity\n *\n * @param options - Load options (optional)\n * @returns Config name (e.g., 'myapp')\n */\nexport async function getConfigName(options?: LoadIdentityOptions): Promise<string> {\n const identity = await loadIdentity(options);\n return identity.app.config_name;\n}\n\n/**\n * Get the telemetry namespace from app identity\n *\n * Falls back to binary_name if telemetry_namespace is not specified\n *\n * @param options - Load options (optional)\n * @returns Telemetry namespace (e.g., 'acmecorp_myapp' or 'myapp')\n */\nexport async function getTelemetryNamespace(options?: LoadIdentityOptions): Promise<string> {\n const identity = await loadIdentity(options);\n return identity.metadata?.telemetry_namespace ?? identity.app.binary_name;\n}\n\n/**\n * Get config identifiers for path construction\n *\n * Returns vendor and configName for building config paths like:\n * ~/.config/{vendor}/{configName}/config.yaml\n *\n * @param options - Load options (optional)\n * @returns Frozen config identifiers { vendor, configName }\n */\nexport async function getConfigIdentifiers(\n options?: LoadIdentityOptions,\n): Promise<ConfigIdentifiers> {\n const identity = await loadIdentity(options);\n return Object.freeze({\n vendor: identity.app.vendor,\n configName: identity.app.config_name,\n });\n}\n\n/**\n * Build environment variable name with app prefix\n *\n * Constructs env var names like: MYAPP_DATABASE_URL\n * Normalizes invalid characters (anything outside [A-Z0-9_]) to underscores\n * for conventional env var naming.\n *\n * Examples:\n * - 'database-url' → 'MYAPP_DATABASE_URL'\n * - 'my.config' → 'MYAPP_MY_CONFIG'\n * - 'log_level' → 'MYAPP_LOG_LEVEL'\n *\n * @param key - Environment variable key (will be uppercased and normalized)\n * @param options - Load options (optional)\n * @returns Full environment variable name (e.g., 'MYAPP_DATABASE_URL')\n */\nexport async function buildEnvVar(key: string, options?: LoadIdentityOptions): Promise<string> {\n const envPrefix = await getEnvPrefix(options);\n // Uppercase and replace any non-alphanumeric/underscore characters with underscores\n const normalizedKey = key.toUpperCase().replace(/[^A-Z0-9_]/g, \"_\");\n return `${envPrefix}${normalizedKey}`;\n}\n\n/**\n * Get environment variable value using app prefix\n *\n * Convenience wrapper around process.env using buildEnvVar\n *\n * @param key - Environment variable key (will be uppercased)\n * @param options - Load options (optional)\n * @returns Environment variable value or undefined\n */\nexport async function getEnvVar(\n key: string,\n options?: LoadIdentityOptions,\n): Promise<string | undefined> {\n const envVarName = await buildEnvVar(key, options);\n return process.env[envVarName];\n}\n","/**\n * HTTP Metrics Helpers\n *\n * Type-safe HTTP server instrumentation for Express, Fastify, Bun, and Node.js HTTP servers.\n * Implements Crucible v0.2.18 HTTP metrics taxonomy with automatic label injection,\n * unit conversion (ms → seconds), and cardinality protection.\n *\n * CRITICAL: Routes must be templated (/users/:id) to prevent cardinality explosion.\n * Use normalizeRoute() from route-normalizer.ts before calling recordHttpRequest().\n *\n * @example\n * ```typescript\n * import { recordHttpRequest, trackActiveRequest } from '@fulmenhq/tsfulmen/telemetry/http';\n *\n * // Manual instrumentation\n * const start = performance.now();\n * const release = trackActiveRequest('api-server');\n * try {\n * await handleRequest();\n * recordHttpRequest({\n * method: 'GET',\n * route: '/users/:id', // Pre-normalized\n * status: 200,\n * durationMs: performance.now() - start,\n * requestBytes: 512,\n * responseBytes: 2048,\n * });\n * } finally {\n * release();\n * }\n * ```\n */\n\nimport { getCachedIdentity } from \"../../appidentity/index.js\";\nimport { metrics } from \"../index.js\";\nimport type {\n GenericHttpRequest,\n GenericHttpResponse,\n MethodExtractor,\n NextFunction,\n RouteNormalizer,\n StatusExtractor,\n} from \"./types.js\";\n\n// Optional framework type imports - consumers need these as peer dependencies\ntype ExpressRequest = import(\"express\").Request;\ntype ExpressResponse = import(\"express\").Response;\ntype FastifyInstance = import(\"fastify\").FastifyInstance;\ntype FastifyRequest = import(\"fastify\").FastifyRequest;\ntype FastifyReply = import(\"fastify\").FastifyReply;\ntype FastifyPluginCallback = import(\"fastify\").FastifyPluginCallback;\n\n/**\n * HTTP request recording options\n */\nexport interface HttpRequestOptions {\n /**\n * HTTP method (GET, POST, PUT, DELETE, etc.)\n * REQUIRED label for all HTTP metrics\n */\n method: string;\n\n /**\n * Route template (e.g., /users/:id, not /users/123)\n * REQUIRED label for all HTTP metrics\n * CRITICAL: Must be normalized to prevent cardinality explosion\n */\n route: string;\n\n /**\n * HTTP status code (200, 404, 500, etc.)\n * REQUIRED label for http_requests_total, http_request_duration_seconds, http_response_size_bytes\n */\n status: number;\n\n /**\n * Request duration in milliseconds\n * Automatically converted to seconds for http_request_duration_seconds\n * REQUIRED for recording duration metric\n */\n durationMs: number;\n\n /**\n * Request body size in bytes (optional)\n * Records http_request_size_bytes histogram when provided\n */\n requestBytes?: number;\n\n /**\n * Response body size in bytes (optional)\n * Records http_response_size_bytes histogram when provided\n */\n responseBytes?: number;\n\n /**\n * Service name (optional, defaults to AppIdentity binary_name)\n * REQUIRED label for all HTTP metrics\n * Falls back to 'unknown' if AppIdentity not available\n */\n service?: string;\n}\n\n/**\n * Active request release function\n * Call to decrement http_active_requests gauge\n */\nexport type ActiveRequestRelease = () => void;\n\n/**\n * Record HTTP request metrics\n *\n * Records all applicable HTTP metrics from Crucible v0.2.18 taxonomy:\n * - http_requests_total (counter)\n * - http_request_duration_seconds (histogram, converted from ms)\n * - http_request_size_bytes (histogram, if requestBytes provided)\n * - http_response_size_bytes (histogram, if responseBytes provided)\n *\n * Auto-injects service label from AppIdentity if not provided.\n * Converts durationMs to seconds for duration metric.\n *\n * @param options - HTTP request recording options\n *\n * @example\n * ```typescript\n * recordHttpRequest({\n * method: 'GET',\n * route: '/users/:id',\n * status: 200,\n * durationMs: 45.2,\n * requestBytes: 512,\n * responseBytes: 2048,\n * service: 'api-server', // Optional, defaults to AppIdentity\n * });\n * ```\n */\nexport function recordHttpRequest(options: HttpRequestOptions): void {\n const {\n method,\n route,\n status,\n durationMs,\n requestBytes,\n responseBytes,\n service: providedService,\n } = options;\n\n // Resolve service name (AppIdentity fallback)\n const service = providedService || getServiceName();\n\n // Convert status to string for labels\n const statusStr = String(status);\n\n // Common labels for metrics requiring status\n const labelsWithStatus = {\n method,\n route,\n status: statusStr,\n service,\n };\n\n // Labels for metrics without status requirement\n const labelsWithoutStatus = {\n method,\n route,\n service,\n };\n\n // Record http_requests_total (counter)\n // Required labels: method, route, status, service\n metrics.counter(\"http_requests_total\").inc(1, labelsWithStatus);\n\n // Record http_request_duration_seconds (histogram)\n // CRITICAL: Convert milliseconds to seconds\n // Required labels: method, route, status, service\n const durationSeconds = durationMs / 1000;\n metrics.histogram(\"http_request_duration_seconds\").observe(durationSeconds, labelsWithStatus);\n\n // Record http_request_size_bytes (histogram, optional)\n // Required labels: method, route, service\n if (requestBytes !== undefined) {\n metrics.histogram(\"http_request_size_bytes\").observe(requestBytes, labelsWithoutStatus);\n }\n\n // Record http_response_size_bytes (histogram, optional)\n // Required labels: method, route, status, service\n if (responseBytes !== undefined) {\n metrics.histogram(\"http_response_size_bytes\").observe(responseBytes, labelsWithStatus);\n }\n}\n\n/**\n * Track active HTTP request\n *\n * Increments http_active_requests gauge and returns a release function.\n * Call the release function when the request completes to decrement the gauge.\n *\n * @param service - Service name (optional, defaults to AppIdentity binary_name)\n * @returns Release function to decrement gauge\n *\n * @example\n * ```typescript\n * const release = trackActiveRequest('api-server');\n * try {\n * await handleRequest();\n * } finally {\n * release(); // Always decrement, even on error\n * }\n * ```\n */\nexport function trackActiveRequest(service?: string): ActiveRequestRelease {\n const serviceName = service || getServiceName();\n const labels = { service: serviceName };\n\n // Increment gauge\n metrics.gauge(\"http_active_requests\").inc(1, labels);\n\n // Return release function to decrement\n return () => {\n metrics.gauge(\"http_active_requests\").dec(1, labels);\n };\n}\n\n/**\n * Middleware options for HTTP metrics collection\n */\nexport interface MiddlewareOptions {\n /**\n * Service name (optional, defaults to AppIdentity binary_name)\n */\n serviceName?: string;\n\n /**\n * Custom route normalizer function\n * Receives request object and returns normalized route\n * Defaults to basic normalization (framework-specific)\n *\n * @example\n * ```typescript\n * // Express: use route.path if available\n * routeNormalizer: (req) => req.route?.path || req.path\n *\n * // Custom normalization\n * routeNormalizer: (req) => normalizeRoute(req.path)\n * ```\n */\n routeNormalizer?: RouteNormalizer;\n\n /**\n * Custom method extractor (defaults to req.method)\n */\n methodExtractor?: MethodExtractor;\n\n /**\n * Custom status extractor (defaults to res.statusCode)\n */\n statusExtractor?: StatusExtractor;\n\n /**\n * Whether to track request/response body sizes (default: false)\n * May have performance impact for large bodies\n */\n trackBodySizes?: boolean;\n}\n\n/**\n * Create Express/Connect-compatible middleware for HTTP metrics\n *\n * Automatically instruments HTTP requests with metrics collection.\n * Compatible with Express, Connect, and similar frameworks using (req, res, next) signature.\n *\n * @param options - Middleware configuration options\n * @returns Express/Connect middleware function\n *\n * @example\n * ```typescript\n * import express from 'express';\n * import { createHttpMetricsMiddleware } from '@fulmenhq/tsfulmen/telemetry/http';\n *\n * const app = express();\n * app.use(createHttpMetricsMiddleware({\n * serviceName: 'api-server',\n * routeNormalizer: (req) => req.route?.path || req.path,\n * }));\n * ```\n */\nexport function createHttpMetricsMiddleware(options: MiddlewareOptions = {}) {\n const {\n serviceName,\n routeNormalizer = (req: GenericHttpRequest) => req.route?.path || req.path || \"unknown\",\n methodExtractor = (req: GenericHttpRequest) => req.method || \"UNKNOWN\",\n statusExtractor = (res: GenericHttpResponse) => res.statusCode || 0,\n trackBodySizes = false,\n } = options;\n\n return (req: ExpressRequest, res: ExpressResponse, next: NextFunction) => {\n const startTime = performance.now();\n const release = trackActiveRequest(serviceName);\n\n // Track request size if enabled\n const requestBytes =\n trackBodySizes && req.headers?.[\"content-length\"]\n ? Number.parseInt(req.headers[\"content-length\"], 10)\n : undefined;\n\n // Hook into response finish event\n const onFinish = () => {\n const durationMs = performance.now() - startTime;\n const method = methodExtractor(req);\n const route = routeNormalizer(req);\n const status = statusExtractor(res);\n\n // Track response size if enabled\n const responseBytes =\n trackBodySizes && res.getHeader?.(\"content-length\")\n ? Number.parseInt(String(res.getHeader(\"content-length\")), 10)\n : undefined;\n\n recordHttpRequest({\n method,\n route,\n status,\n durationMs,\n requestBytes,\n responseBytes,\n service: serviceName,\n });\n\n release();\n cleanup();\n };\n\n const onError = () => {\n release();\n cleanup();\n };\n\n const cleanup = () => {\n res.off?.(\"finish\", onFinish);\n res.off?.(\"error\", onError);\n res.off?.(\"close\", onError);\n };\n\n // Attach listeners\n res.on?.(\"finish\", onFinish);\n res.on?.(\"error\", onError);\n res.on?.(\"close\", onError);\n\n next();\n };\n}\n\n/**\n * Create Fastify plugin for HTTP metrics\n *\n * Fastify-compatible plugin for automatic HTTP metrics collection.\n *\n * @param options - Middleware configuration options\n * @returns Fastify plugin function\n *\n * @example\n * ```typescript\n * import Fastify from 'fastify';\n * import { createFastifyMetricsPlugin } from '@fulmenhq/tsfulmen/telemetry/http';\n *\n * const fastify = Fastify();\n * fastify.register(createFastifyMetricsPlugin({\n * serviceName: 'fastify-api',\n * routeNormalizer: (req) => req.routeOptions?.url || req.url,\n * }));\n * ```\n */\nexport function createFastifyMetricsPlugin(options: MiddlewareOptions = {}) {\n const {\n serviceName,\n routeNormalizer = (req: GenericHttpRequest) => req.routeOptions?.url || req.url || \"unknown\",\n methodExtractor = (req: GenericHttpRequest) => req.method || \"UNKNOWN\",\n } = options;\n\n const plugin: FastifyPluginCallback = (\n fastify: FastifyInstance,\n _opts: unknown,\n done: (err?: Error) => void,\n ) => {\n fastify.addHook(\"onRequest\", async (req: FastifyRequest, _reply: FastifyReply) => {\n // Store start time and release function in request context\n // biome-ignore lint/suspicious/noExplicitAny: Runtime property injection for metrics tracking\n (req as any).metricsStartTime = performance.now();\n // biome-ignore lint/suspicious/noExplicitAny: Runtime property injection for metrics tracking\n (req as any).metricsRelease = trackActiveRequest(serviceName);\n });\n\n fastify.addHook(\"onResponse\", async (req: FastifyRequest, reply: FastifyReply) => {\n // biome-ignore lint/suspicious/noExplicitAny: Runtime property access for metrics tracking\n const durationMs = performance.now() - (req as any).metricsStartTime;\n const method = methodExtractor(req);\n const route = routeNormalizer(req);\n const status = reply.statusCode || 0;\n\n recordHttpRequest({\n method,\n route,\n status,\n durationMs,\n service: serviceName,\n });\n\n // biome-ignore lint/suspicious/noExplicitAny: Runtime property access for metrics tracking\n (req as any).metricsRelease?.();\n });\n\n // Handle errors/close\n fastify.addHook(\"onError\", async (req: FastifyRequest, _reply: FastifyReply, _error: Error) => {\n // biome-ignore lint/suspicious/noExplicitAny: Runtime property access for metrics tracking\n (req as any).metricsRelease?.();\n });\n\n done();\n };\n\n return plugin;\n}\n\n/**\n * Create Bun.serve fetch handler wrapper for HTTP metrics\n *\n * Wraps a Bun.serve fetch handler with automatic HTTP metrics collection.\n *\n * @param handler - Original fetch handler\n * @param options - Middleware configuration options\n * @returns Wrapped fetch handler with metrics\n *\n * @example\n * ```typescript\n * import { createBunMetricsHandler } from '@fulmenhq/tsfulmen/telemetry/http';\n *\n * Bun.serve({\n * fetch: createBunMetricsHandler(async (req) => {\n * return new Response(\"Hello World\");\n * }, {\n * serviceName: 'bun-api',\n * routeNormalizer: (req) => new URL(req.url).pathname,\n * }),\n * });\n * ```\n */\nexport function createBunMetricsHandler(\n handler: (req: Request) => Response | Promise<Response>,\n options: MiddlewareOptions = {},\n) {\n const {\n serviceName,\n routeNormalizer: customNormalizer,\n methodExtractor: customExtractor,\n } = options;\n\n // Type-safe defaults for Bun Request\n const routeNormalizer =\n customNormalizer ||\n ((req: GenericHttpRequest) => {\n const url = (req as unknown as Request).url;\n return new URL(url).pathname;\n });\n const methodExtractor =\n customExtractor ||\n ((req: GenericHttpRequest) => {\n return (req as unknown as Request).method;\n });\n\n return async (req: Request): Promise<Response> => {\n const startTime = performance.now();\n const release = trackActiveRequest(serviceName);\n\n try {\n const response = await handler(req);\n const durationMs = performance.now() - startTime;\n // Cast to GenericHttpRequest for extractors\n const method = methodExtractor(req as unknown as GenericHttpRequest);\n const route = routeNormalizer(req as unknown as GenericHttpRequest);\n const status = response.status;\n\n recordHttpRequest({\n method,\n route,\n status,\n durationMs,\n service: serviceName,\n });\n\n release();\n return response;\n } catch (error) {\n release();\n throw error;\n }\n };\n}\n\n/**\n * Get service name from AppIdentity or fallback to 'unknown'\n * @internal\n */\nfunction getServiceName(): string {\n try {\n const identity = getCachedIdentity();\n if (identity?.app?.binary_name) {\n return identity.app.binary_name;\n }\n } catch {\n // AppIdentity not loaded or available, use fallback\n }\n return \"unknown\";\n}\n\nexport type { NormalizeOptions } from \"./route-normalizer.js\";\n// Re-export route normalization utilities for convenience\nexport { normalizeRoute } from \"./route-normalizer.js\";\n","/**\n * Route normalization utilities for HTTP metrics\n *\n * Prevents cardinality explosion by converting actual paths to templated routes.\n * Example: /users/123 → /users/:id\n *\n * CRITICAL: High cardinality routes will overwhelm Prometheus and break monitoring.\n * Always normalize routes before recording HTTP metrics.\n */\n\n/**\n * Route normalization options\n */\nexport interface NormalizeOptions {\n /**\n * Optional explicit template to use instead of auto-detection\n * Example: \"/api/v1/orders/:orderId/items/:itemId\"\n */\n template?: string;\n\n /**\n * Whether to preserve trailing slashes (default: false, strips them)\n */\n preserveTrailingSlash?: boolean;\n\n /**\n * Custom segment replacements (segment index → placeholder name)\n * Example: { 2: \"userId\", 4: \"itemId\" } for /api/v1/users/:userId/items/:itemId\n */\n segmentReplacements?: Record<number, string>;\n\n /**\n * Use context-aware placeholder names (default: true)\n * When true: /users/123 → /users/:userId\n * When false: /users/123 → /users/:id\n */\n useContextAwarePlaceholders?: boolean;\n}\n\n/**\n * Common static route segments that should never be normalized\n * (API resources, actions, settings pages, etc.)\n */\nconst STATIC_SEGMENTS = new Set([\n // Common API resources/collections\n \"api\",\n \"users\",\n \"posts\",\n \"articles\",\n \"items\",\n \"products\",\n \"orders\",\n \"accounts\",\n \"profiles\",\n \"comments\",\n \"reviews\",\n \"files\",\n \"docs\",\n \"auth\",\n \"admin\",\n \"settings\",\n \"config\",\n \"metrics\",\n \"health\",\n \"status\",\n \"search\",\n \"upload\",\n \"download\",\n // Common actions\n \"create\",\n \"update\",\n \"delete\",\n \"list\",\n \"show\",\n \"edit\",\n \"new\",\n // Common settings/config sections\n \"notifications\",\n \"preferences\",\n \"billing\",\n \"security\",\n \"privacy\",\n \"profile\",\n \"account\",\n \"dashboard\",\n // API versioning\n \"v1\",\n \"v2\",\n \"v3\",\n \"v4\",\n // Content sections\n \"blog\",\n \"wiki\",\n \"guides\",\n \"guide\",\n \"help\",\n \"faq\",\n \"about\",\n \"contact\",\n \"terms\",\n \"custom\",\n \"verify\",\n]);\n\n/**\n * Pattern matchers for common ID formats\n */\nconst ID_PATTERNS = {\n /** UUID v4: 550e8400-e29b-41d4-a716-446655440000 */\n uuid: /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,\n\n /** Numeric ID: 123, 456789 */\n numeric: /^\\d+$/,\n\n /** MongoDB ObjectId: 507f1f77bcf86cd799439011 */\n objectId: /^[0-9a-f]{24}$/i,\n\n /** Nanoid/CUID: cjld2cjxh0000qzrmn831i7rn */\n nanoid: /^[0-9a-z_-]{20,30}$/i,\n\n /** Alphanumeric slug with hyphens: my-article-title, user-profile-2024 */\n slug: /^[a-z0-9]+(-[a-z0-9]+)+$/i,\n\n /** Base64-like (16+ chars, mixed case OR padding): YWJjZGVmZ2hpamtsbW5v or dGVzdA== */\n base64: /^(?=.*[A-Z])(?=.*[a-z])[A-Za-z0-9+/]{16,}={0,2}$|^[A-Za-z0-9+/]{16,}={1,2}$/,\n\n /** Short alphanumeric IDs with mixed chars: abc123, xyz789 (must contain both letters AND numbers) */\n shortId: /^(?=.*[a-z])(?=.*[0-9])[a-z0-9]{3,12}$/i,\n};\n\n/**\n * Detect if a path segment looks like a dynamic parameter\n */\nfunction isDynamicSegment(segment: string): boolean {\n // Already a parameter placeholder\n if (segment.startsWith(\":\") || segment === \"*\") {\n return true;\n }\n\n // Empty segment\n if (!segment) {\n return false;\n }\n\n // Check if it's a known static segment\n if (STATIC_SEGMENTS.has(segment.toLowerCase())) {\n return false;\n }\n\n // Check against known ID patterns\n // Order matters: check more specific patterns first\n return (\n ID_PATTERNS.uuid.test(segment) ||\n ID_PATTERNS.numeric.test(segment) ||\n ID_PATTERNS.objectId.test(segment) ||\n ID_PATTERNS.slug.test(segment) ||\n ID_PATTERNS.base64.test(segment) || // Check before nanoid (more specific)\n ID_PATTERNS.nanoid.test(segment) ||\n ID_PATTERNS.shortId.test(segment) // Check last (most permissive)\n );\n}\n\n/**\n * Infer placeholder name from context\n */\nfunction inferPlaceholderName(\n segment: string,\n index: number,\n segments: string[],\n useContextAware = true,\n): string {\n // UUID → :id\n if (ID_PATTERNS.uuid.test(segment)) {\n return \"id\";\n }\n\n // MongoDB ObjectId → :id\n if (ID_PATTERNS.objectId.test(segment)) {\n return \"id\";\n }\n\n // Numeric → :id (context-aware if enabled)\n if (ID_PATTERNS.numeric.test(segment)) {\n if (!useContextAware) {\n return \"id\";\n }\n // Look at previous segment for context\n const prev = segments[index - 1]?.toLowerCase();\n if (prev === \"users\" || prev === \"accounts\" || prev === \"profiles\") {\n return \"userId\";\n }\n if (prev === \"posts\" || prev === \"articles\") {\n return \"postId\";\n }\n if (prev === \"orders\") {\n return \"orderId\";\n }\n if (prev === \"items\" || prev === \"products\") {\n return \"itemId\";\n }\n return \"id\";\n }\n\n // Slug pattern → :slug\n if (ID_PATTERNS.slug.test(segment)) {\n return \"slug\";\n }\n\n // Base64 → :token (check BEFORE nanoid which is less specific)\n if (ID_PATTERNS.base64.test(segment)) {\n return \"token\";\n }\n\n // Nanoid/CUID → :id\n if (ID_PATTERNS.nanoid.test(segment)) {\n return \"id\";\n }\n\n // Short alphanumeric ID → context-aware or :id\n // Note: Check this AFTER base64 since base64 also has letters+numbers\n if (ID_PATTERNS.shortId.test(segment)) {\n if (!useContextAware) {\n return \"id\";\n }\n // Check previous segment for context\n const prev = segments[index - 1]?.toLowerCase();\n if (prev === \"orders\") {\n return \"orderId\";\n }\n if (prev === \"items\" || prev === \"products\") {\n return \"itemId\";\n }\n if (prev === \"reviews\") {\n return \"id\";\n }\n return \"id\";\n }\n\n // Already-normalized placeholder - preserve the name\n if (segment.startsWith(\":\")) {\n return segment.slice(1); // Remove the : prefix\n }\n\n // Wildcard - preserve as-is\n if (segment === \"*\") {\n return \"*\";\n }\n\n // Fallback for unknown dynamic segments\n return \"param\";\n}\n\n/**\n * Normalize an HTTP route path to prevent cardinality explosion\n *\n * Converts actual paths with IDs/slugs to templated routes:\n * - /users/123 → /users/:id\n * - /api/v1/orders/abc-123/items/456 → /api/v1/orders/:orderId/items/:itemId\n * - /articles/my-article-title → /articles/:slug\n *\n * @param path - The actual request path\n * @param options - Normalization options\n * @returns Normalized route template\n *\n * @example\n * ```typescript\n * normalizeRoute('/users/123'); // '/users/:id'\n * normalizeRoute('/api/v1/orders/abc/items/456'); // '/api/v1/orders/:id/items/:id'\n * normalizeRoute('/posts/my-title', { template: '/posts/:slug' }); // '/posts/:slug'\n * ```\n */\nexport function normalizeRoute(path: string, options: NormalizeOptions = {}): string {\n // Use explicit template if provided\n if (options.template) {\n return options.template;\n }\n\n // Handle empty or root\n if (!path || path === \"/\") {\n return \"/\";\n }\n\n // Strip query params and fragments\n let cleanPath = path.split(\"?\")[0].split(\"#\")[0];\n\n // Track if path had trailing slash\n const hadTrailingSlash = cleanPath.endsWith(\"/\") && cleanPath !== \"/\";\n\n // Strip trailing slash for processing\n if (cleanPath.endsWith(\"/\") && cleanPath !== \"/\") {\n cleanPath = cleanPath.slice(0, -1);\n }\n\n // Split into segments\n const segments = cleanPath.split(\"/\").filter(Boolean);\n\n // Process each segment\n const normalized = segments.map((segment, index) => {\n // Check for explicit segment replacement\n if (options.segmentReplacements?.[index]) {\n return `:${options.segmentReplacements[index]}`;\n }\n\n // Keep wildcards as-is\n if (segment === \"*\") {\n return \"*\";\n }\n\n // Check if segment is dynamic\n if (isDynamicSegment(segment)) {\n const placeholder = inferPlaceholderName(\n segment,\n index,\n segments,\n options.useContextAwarePlaceholders ?? true,\n );\n // Don't re-wrap if already a placeholder\n return placeholder === \"*\" ? \"*\" : `:${placeholder}`;\n }\n\n // Keep static segment as-is\n return segment;\n });\n\n // Reconstruct path\n let result = `/${normalized.join(\"/\")}`;\n\n // Re-add trailing slash if requested and original had one\n if (options.preserveTrailingSlash && hadTrailingSlash) {\n result += \"/\";\n }\n\n return result;\n}\n\n/**\n * Batch normalize multiple routes\n */\nexport function normalizeRoutes(paths: string[], options: NormalizeOptions = {}): string[] {\n return paths.map((path) => normalizeRoute(path, options));\n}\n\n/**\n * Check if a route has high cardinality risk\n *\n * Returns true if the route contains segments that look like dynamic values\n * but haven't been normalized yet.\n */\nexport function hasCardinalityRisk(route: string): boolean {\n if (!route || route === \"/\") {\n return false;\n }\n\n const segments = route.split(\"/\").filter(Boolean);\n return segments.some((segment) => {\n // Already normalized\n if (segment.startsWith(\":\") || segment === \"*\") {\n return false;\n }\n\n // Check for dynamic patterns\n return isDynamicSegment(segment);\n });\n}\n\n/**\n * Estimate cardinality of a route\n *\n * Returns approximate number of unique routes this pattern could generate.\n * Used for capacity planning and alerting on high-cardinality routes.\n */\nexport function estimateCardinality(route: string): number {\n if (!route || route === \"/\") {\n return 1;\n }\n\n const segments = route.split(\"/\").filter(Boolean);\n let cardinality = 1;\n\n for (const segment of segments) {\n if (segment.startsWith(\":\")) {\n // Parameter could be infinite values, use conservative estimate\n cardinality *= 1000;\n } else if (segment === \"*\") {\n // Wildcard could match many paths\n cardinality *= 100;\n }\n // Static segments don't multiply cardinality\n }\n\n return cardinality;\n}\n"]}