@fulmenhq/tsfulmen 0.1.6

package/schemas/crucible-ts/observability/logging/v1.0.0/log-event.schema.json

@@ -0,0 +1,179 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.fulmenhq.dev/crucible/observability/logging/log-event-v1.0.0.json",
+  "title": "LogEvent",
+  "description": "Structured log event envelope for consistent telemetry across Fulmen libraries",
+  "type": "object",
+  "properties": {
+    "timestamp": {
+      "$ref": "definitions.schema.json#/$defs/rfc3339Nano"
+    },
+    "severity": {
+      "$ref": "definitions.schema.json#/$defs/severityName"
+    },
+    "severityLevel": {
+      "$ref": "definitions.schema.json#/$defs/severityLevel",
+      "description": "Numeric severity for sorting/filtering (optional but recommended for runtime events)"
+    },
+    "message": {
+      "$ref": "definitions.schema.json#/$defs/logMessage"
+    },
+    "service": {
+      "$ref": "definitions.schema.json#/$defs/serviceName"
+    },
+    "component": {
+      "$ref": "definitions.schema.json#/$defs/componentName"
+    },
+    "logger": {
+      "$ref": "definitions.schema.json#/$defs/loggerName"
+    },
+    "environment": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 64,
+      "description": "Deployment environment (e.g., 'dev', 'staging', 'production')"
+    },
+    "context": {
+      "$ref": "definitions.schema.json#/$defs/context"
+    },
+    "contextId": {
+      "$ref": "definitions.schema.json#/$defs/contextId",
+      "description": "Identifier for the broader execution context (workflow, job, batch, etc.)"
+    },
+    "requestId": {
+      "$ref": "definitions.schema.json#/$defs/requestId",
+      "description": "Request identifier (HTTP X-Request-ID or CLI operation UUID)"
+    },
+    "correlationId": {
+      "$ref": "definitions.schema.json#/$defs/uuidV7",
+      "description": "Cross-service correlation identifier (UUIDv7 propagated across boundaries)"
+    },
+    "error": {
+      "type": "object",
+      "properties": {
+        "message": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 8192,
+          "description": "Error message"
+        },
+        "type": {
+          "type": "string",
+          "maxLength": 256,
+          "description": "Error type or class"
+        },
+        "stack": {
+          "type": "string",
+          "maxLength": 65536,
+          "description": "Stack trace (max 64KB)"
+        }
+      },
+      "required": [
+        "message"
+      ],
+      "description": "Error information (required for ERROR/FATAL severity)"
+    },
+    "traceId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "description": "Distributed trace ID (REQUIRED when tracing is enabled)"
+    },
+    "spanId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "description": "Span ID within trace (REQUIRED when tracing is enabled)"
+    },
+    "parentSpanId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "description": "Parent span identifier for nested operations"
+    },
+    "tags": {
+      "$ref": "definitions.schema.json#/$defs/tags"
+    },
+    "eventId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "description": "Unique event identifier (optional)"
+    },
+    "operation": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "description": "Logical operation or handler name (CLI command, HTTP route, job step)"
+    },
+    "durationMs": {
+      "type": "number",
+      "minimum": 0,
+      "description": "Operation duration in milliseconds"
+    },
+    "userId": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 128,
+      "description": "Authenticated user identifier when applicable"
+    }
+  },
+  "required": [
+    "timestamp",
+    "severity",
+    "severityLevel",
+    "message",
+    "service"
+  ],
+  "examples": [
+    {
+      "timestamp": "2025-10-02T12:34:56.789012Z",
+      "severity": "INFO",
+      "severityLevel": 20,
+      "message": "Pathfinder scan completed",
+      "logger": "gofulmen.pathfinder",
+      "service": "gofulmen",
+      "component": "pathfinder",
+      "environment": "production",
+      "contextId": "pipeline-20251008",
+      "requestId": "req-01hcn7h3a6zyv4k73k4f4z6w7j",
+      "correlationId": "018db318-8c7f-7bc1-b3ff-b2e0e689a001",
+      "traceId": "0af7651916cd43dd8448eb211c80319c",
+      "spanId": "b7ad6b7169203331",
+      "operation": "pathfinder.scan",
+      "durationMs": 2450,
+      "context": {
+        "filesScanned": 1234,
+        "duration": "2.5s"
+      },
+      "tags": [
+        "scan",
+        "success"
+      ]
+    },
+    {
+      "timestamp": "2025-10-02T12:35:01.123456Z",
+      "severity": "ERROR",
+      "severityLevel": 40,
+      "message": "Failed to read file",
+      "logger": "gofulmen.pathfinder",
+      "service": "gofulmen",
+      "component": "pathfinder",
+      "environment": "production",
+      "requestId": "req-01hcn7h5a9ab1k0tpnttw40p2n",
+      "correlationId": "018db318-8d51-7f96-9f82-0d246bc4d4cb",
+      "error": {
+        "message": "permission denied",
+        "type": "PathAccessError",
+        "stack": "..."
+      },
+      "context": {
+        "path": "/restricted/file.txt"
+      },
+      "tags": [
+        "error",
+        "filesystem"
+      ]
+    }
+  ]
+}

package/schemas/crucible-ts/observability/logging/v1.0.0/logger-config.schema.json

@@ -0,0 +1,518 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.fulmenhq.dev/crucible/observability/logging/logger-config-v1.0.0.json",
+  "title": "LoggerConfig",
+  "description": "Progressive logger configuration with profile-based complexity and policy enforcement",
+  "type": "object",
+  "properties": {
+    "profile": {
+      "type": "string",
+      "enum": [
+        "SIMPLE",
+        "STRUCTURED",
+        "ENTERPRISE",
+        "CUSTOM"
+      ],
+      "default": "SIMPLE",
+      "description": "Logging profile for progressive complexity (SIMPLE=CLI tooling, STRUCTURED=services/APIs, ENTERPRISE=full production, CUSTOM=user-defined)."
+    },
+    "service": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 80,
+      "description": "Service or application name (e.g., 'gofulmen', 'tsfulmen')."
+    },
+    "environment": {
+      "type": "string",
+      "default": "development",
+      "maxLength": 32,
+      "description": "Deployment environment identifier (development, staging, production, etc.)."
+    },
+    "policyFile": {
+      "type": "string",
+      "maxLength": 512,
+      "description": "Optional policy file path for organizational governance (search order: .goneat/logging-policy.yaml, /etc/fulmen/logging-policy.yaml, /org/logging-policy.yaml)."
+    },
+    "defaultLevel": {
+      "$ref": "#/$defs/logLevel",
+      "default": "INFO",
+      "description": "Default minimum log level."
+    },
+    "sinks": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/sinkConfig"
+      },
+      "description": "Configured sinks for log output (required for STRUCTURED and ENTERPRISE profiles)."
+    },
+    "middleware": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/middlewareConfig"
+      },
+      "description": "Middleware pipeline applied to log events (required for ENTERPRISE profile)."
+    },
+    "throttling": {
+      "$ref": "#/$defs/throttlingConfig",
+      "description": "Throttling and backpressure configuration (available for ENTERPRISE/CUSTOM profiles)."
+    },
+    "staticFields": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Static fields merged into every log event (e.g., version, region)."
+    },
+    "enableCaller": {
+      "type": "boolean",
+      "default": false,
+      "description": "Include caller information (file and line) in log events."
+    },
+    "enableStacktrace": {
+      "type": "boolean",
+      "default": false,
+      "description": "Attach stack traces for ERROR and FATAL log entries."
+    },
+    "customConfig": {
+      "type": "object",
+      "additionalProperties": true,
+      "description": "Custom configuration payload for CUSTOM profiles."
+    }
+  },
+  "required": [
+    "service"
+  ],
+  "allOf": [
+    {
+      "if": {
+        "properties": {
+          "profile": {
+            "const": "STRUCTURED"
+          }
+        }
+      },
+      "then": {
+        "required": [
+          "sinks"
+        ]
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "profile": {
+            "const": "ENTERPRISE"
+          }
+        }
+      },
+      "then": {
+        "required": [
+          "sinks",
+          "middleware"
+        ]
+      }
+    },
+    {
+      "if": {
+        "properties": {
+          "profile": {
+            "const": "CUSTOM"
+          }
+        }
+      },
+      "then": {
+        "required": [
+          "customConfig"
+        ]
+      }
+    }
+  ],
+  "additionalProperties": false,
+  "$defs": {
+    "logLevel": {
+      "type": "string",
+      "enum": [
+        "TRACE",
+        "DEBUG",
+        "INFO",
+        "WARN",
+        "ERROR",
+        "FATAL",
+        "NONE"
+      ]
+    },
+    "sinkConfig": {
+      "type": "object",
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": [
+            "console",
+            "file",
+            "rolling-file",
+            "external"
+          ],
+          "description": "Sink implementation type."
+        },
+        "name": {
+          "type": "string",
+          "description": "Optional sink identifier."
+        },
+        "level": {
+          "$ref": "#/$defs/logLevel",
+          "description": "Minimum level for this sink (overrides defaultLevel)."
+        },
+        "format": {
+          "type": "string",
+          "enum": [
+            "json",
+            "text",
+            "console"
+          ],
+          "default": "json",
+          "description": "Output format (console allows ANSI formatting)."
+        }
+      },
+      "required": [
+        "type"
+      ],
+      "additionalProperties": false,
+      "allOf": [
+        {
+          "if": {
+            "properties": {
+              "type": {
+                "const": "console"
+              }
+            }
+          },
+          "then": {
+            "properties": {
+              "stream": {
+                "type": "string",
+                "enum": [
+                  "stderr"
+                ],
+                "default": "stderr",
+                "description": "Output stream for console logs (stderr only)."
+              },
+              "colorize": {
+                "type": "boolean",
+                "default": false,
+                "description": "Enable ANSI color sequences (only when format=console)."
+              }
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "type": {
+                "const": "file"
+              }
+            }
+          },
+          "then": {
+            "properties": {
+              "path": {
+                "type": "string",
+                "minLength": 1,
+                "description": "File path for log output."
+              },
+              "maxSize": {
+                "type": "integer",
+                "minimum": 1,
+                "description": "Maximum file size in megabytes before rotation."
+              },
+              "maxAge": {
+                "type": "integer",
+                "minimum": 1,
+                "description": "Maximum file age in days before deletion."
+              },
+              "maxBackups": {
+                "type": "integer",
+                "minimum": 0,
+                "description": "Number of rotated files to retain."
+              },
+              "compress": {
+                "type": "boolean",
+                "default": false,
+                "description": "Compress rotated files with gzip."
+              }
+            },
+            "required": [
+              "path"
+            ]
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "type": {
+                "const": "rolling-file"
+              }
+            }
+          },
+          "then": {
+            "properties": {
+              "path": {
+                "type": "string",
+                "minLength": 1,
+                "description": "File path for rolling log output."
+              },
+              "maxSize": {
+                "type": "integer",
+                "minimum": 1,
+                "description": "Maximum file size in megabytes before rotation."
+              },
+              "maxAge": {
+                "type": "integer",
+                "minimum": 1,
+                "description": "Maximum file age in days before rotation."
+              },
+              "maxBackups": {
+                "type": "integer",
+                "minimum": 0,
+                "description": "Number of rotated files to retain."
+              },
+              "compress": {
+                "type": "boolean",
+                "default": false,
+                "description": "Compress rotated files with gzip."
+              },
+              "rotationInterval": {
+                "type": "integer",
+                "minimum": 1,
+                "description": "Optional rotation interval in minutes."
+              }
+            },
+            "required": [
+              "path"
+            ]
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "type": {
+                "const": "external"
+              }
+            }
+          },
+          "then": {
+            "properties": {
+              "endpoint": {
+                "type": "string",
+                "format": "uri",
+                "description": "HTTP(S) endpoint for remote log ingestion."
+              },
+              "method": {
+                "type": "string",
+                "enum": [
+                  "POST",
+                  "PUT",
+                  "PATCH"
+                ],
+                "default": "POST",
+                "description": "HTTP method used for log delivery."
+              },
+              "headers": {
+                "type": "object",
+                "additionalProperties": {
+                  "type": "string"
+                },
+                "description": "Additional request headers."
+              },
+              "batchSize": {
+                "type": "integer",
+                "minimum": 1,
+                "default": 500,
+                "description": "Maximum number of log events per batch."
+              },
+              "flushInterval": {
+                "type": "integer",
+                "minimum": 1,
+                "default": 60,
+                "description": "Flush interval in seconds."
+              },
+              "timeout": {
+                "type": "integer",
+                "minimum": 1,
+                "description": "HTTP request timeout in seconds."
+              }
+            },
+            "required": [
+              "endpoint"
+            ]
+          }
+        }
+      ]
+    },
+    "middlewareConfig": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Middleware identifier (built-in or custom)."
+        },
+        "enabled": {
+          "type": "boolean",
+          "default": true,
+          "description": "Enable or disable this middleware entry."
+        },
+        "order": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Execution order within the middleware pipeline."
+        },
+        "config": {
+          "type": "object",
+          "additionalProperties": true,
+          "description": "Middleware-specific configuration payload."
+        }
+      },
+      "required": [
+        "name"
+      ],
+      "additionalProperties": false
+    },
+    "throttlingConfig": {
+      "type": "object",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": false,
+          "description": "Enable throttling to protect downstream sinks."
+        },
+        "maxRate": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Maximum log events per second."
+        },
+        "burstSize": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Burst capacity for throttling buckets."
+        },
+        "windowSize": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Time window in seconds for rate limiting."
+        },
+        "dropPolicy": {
+          "type": "string",
+          "enum": [
+            "drop-oldest",
+            "drop-newest",
+            "block"
+          ],
+          "default": "drop-oldest",
+          "description": "Handling strategy when throttling limits are exceeded."
+        }
+      },
+      "required": [
+        "enabled"
+      ],
+      "additionalProperties": false
+    }
+  },
+  "examples": [
+    {
+      "profile": "SIMPLE",
+      "service": "mycli",
+      "environment": "development",
+      "defaultLevel": "INFO"
+    },
+    {
+      "profile": "STRUCTURED",
+      "service": "api-gateway",
+      "environment": "staging",
+      "defaultLevel": "INFO",
+      "sinks": [
+        {
+          "type": "console",
+          "format": "json"
+        },
+        {
+          "type": "file",
+          "path": "logs/gateway.log"
+        }
+      ]
+    },
+    {
+      "profile": "ENTERPRISE",
+      "service": "datawhirl",
+      "environment": "production",
+      "policyFile": "/org/logging-policy.yaml",
+      "defaultLevel": "DEBUG",
+      "sinks": [
+        {
+          "type": "console",
+          "level": "INFO",
+          "format": "json"
+        },
+        {
+          "type": "rolling-file",
+          "path": "logs/datawhirl.log",
+          "maxSize": 100,
+          "maxAge": 7,
+          "maxBackups": 5,
+          "compress": true
+        },
+        {
+          "type": "external",
+          "endpoint": "https://logs.company.com/api/v1/logs",
+          "batchSize": 500,
+          "flushInterval": 60
+        }
+      ],
+      "middleware": [
+        {
+          "name": "redact-secrets",
+          "order": 1
+        },
+        {
+          "name": "correlation",
+          "order": 2,
+          "config": {
+            "generator": "uuidv7",
+            "headerName": "X-Correlation-ID"
+          }
+        },
+        {
+          "name": "throttle",
+          "order": 3,
+          "config": {
+            "maxRate": 1000,
+            "burstSize": 100,
+            "dropPolicy": "drop-oldest"
+          }
+        }
+      ],
+      "throttling": {
+        "enabled": true,
+        "maxRate": 1000,
+        "burstSize": 100,
+        "windowSize": 60,
+        "dropPolicy": "drop-oldest"
+      },
+      "staticFields": {
+        "region": "us-east-1",
+        "version": "2025.10.2"
+      }
+    },
+    {
+      "profile": "CUSTOM",
+      "service": "lab-tooling",
+      "customConfig": {
+        "adapter": "experimental",
+        "options": {
+          "buffer": 1024,
+          "fanout": [
+            "console",
+            "in-memory"
+          ]
+        }
+      }
+    }
+  ]
+}