Initial Commit

openspec/archive/2026-04-18-enterprise-logger/specs/logging/spec.md

@@ -0,0 +1,158 @@
+# Capability Spec: Logging
+
+**Package**: `@suaveplan/logger`
+**Version**: 0.0.0 (genesis)
+**Status**: ADDED
+
+---
+
+## ADDED Requirements
+
+### LG-01 — Log levels
+
+The logger MUST support exactly four severity levels in ascending order: `debug < info < warn < error`. Messages below the configured minimum level are silently dropped. The level is runtime-configurable via `setLevel(level)`.
+
+### LG-02 — Structured log record
+
+Every emitted log record MUST conform to the `LogRecord` Zod schema:
+
+```ts
+{
+  ts:        string;   // ISO-8601 UTC timestamp (from injected clock)
+  level:     LogLevel; // "debug" | "info" | "warn" | "error"
+  msg:       string;   // human-readable message
+  ctx:       Record<string, unknown>; // merged context (tags, metadata)
+  trace_id?: string;   // hex-encoded OTel trace ID (16 bytes)
+  span_id?:  string;   // hex-encoded OTel span ID (8 bytes)
+  error?:    unknown;  // serialized error payload (from @suaveplan/error toJSON)
+}
+```
+
+### LG-03 — Pluggable sinks
+
+The logger MUST route each `LogRecord` through an ordered array of `Sink` instances. A `Sink` MUST implement:
+
+```ts
+interface Sink {
+  write(record: LogRecord): void | Promise<void>;
+  flush?(signal?: AbortSignal): Promise<void>;
+  close?(): Promise<void>;
+}
+```
+
+### LG-04 — Console sink
+
+`ConsoleSink` MUST produce human-readable output to `console` with:
+
+- ANSI colour-coding per level (configurable; off in non-TTY/CI)
+- ISO timestamp prefix (configurable)
+- Tags inline as `#tag` tokens
+- Metadata as a compact JSON suffix
+
+### LG-05 — JSON (NDJSON) sink
+
+`JsonSink` MUST serialize each `LogRecord` as a single line of JSON terminated by `\n` and pass it to a pluggable `WritableStream`-compatible writer or `(line: string) => void` callback.
+
+### LG-06 — Buffered sink
+
+`BufferedSink` MUST wrap any `Sink` with:
+
+- A configurable maximum queue depth (default: 1 000 records)
+- Two overflow policies: `"drop"` (silently discard; increment counter) and `"block"` (await drain before accepting next record)
+- `flush(signal?: AbortSignal)` that drains the queue, honouring the `AbortSignal`
+
+### LG-07 — Redaction engine
+
+`RedactionEngine` MUST:
+
+- Accept a list of `RedactionRule` items specifying field paths (dot-notation, glob `*` wildcard) to replace with the string `"[REDACTED]"` before the record reaches any sink
+- Detect `Sensitive<T>` wrappers (from `@suaveplan/error/redact`) and redact them automatically
+- Never mutate the original context object — always return a deep-cloned, redacted copy
+- Apply redaction before OTel context attachment and sink dispatch
+
+### LG-08 — Sampling
+
+The logger MUST support a pluggable `SamplingPolicy`:
+
+| Sampler | Behaviour |
+|---------|-----------|
+| `HeadSampler` | Deterministic: hash `trace_id` against a `rate ∈ [0,1]`; no-op if no `trace_id` |
+| `TailSampler` | Buffer up to `N` records per trace; invoke user-supplied `decide(records)` callback and emit/drop the buffer |
+| `RuleSampler` | Ordered predicates `(record) => boolean | undefined`; first match wins; fallback to`SampleAll` |
+
+When a sampling policy returns `"drop"`, the record is not passed to redaction or sinks but all OTel metrics are still incremented.
+
+### LG-09 — OpenTelemetry correlation
+
+When `@opentelemetry/api` has an active span, `getOtelTraceContext()` MUST return `{ trace_id, span_id }` as lowercase hex strings. When no span is active or `@opentelemetry/api` is not installed, it MUST return `{}` (no error thrown).
+
+### LG-10 — Injectable clock and RNG
+
+`AbstractLogger` MUST accept optional `clock: Clock` (from `@suaveplan/types`) and `rng: Rng` (from `@suaveplan/types`) in its config. Defaults: `Date` for clock, `crypto.getRandomValues` for rng. No `Date.now()` or `Math.random()` at module scope.
+
+### LG-11 — Metrics
+
+`AbstractLogger` MUST expose `getMetrics()` returning:
+
+```ts
+{
+  totalLogs: number;
+  logsByLevel: Record<LogLevel, number>;
+  droppedBySampling: number;
+  droppedByBackpressure: number;
+  lastLogTime?: Date;
+}
+```
+
+### LG-12 — OTel instrumentation
+
+For every `log()` call the implementation MUST:
+
+- Increment a `logger.records_total` counter (attributes: `level`)
+- Record a `logger.record_size_bytes` histogram (attributes: `level`)
+- Increment `logger.dropped_total` when a record is dropped by sampling or backpressure (attributes: `reason: "sampling" | "backpressure"`)
+
+All via `@opentelemetry/api` — no-op when no exporter is registered.
+
+### LG-13 — Structured errors
+
+All errors thrown by `@suaveplan/logger` MUST be instances of `LoggerError extends SuaveplanError` with stable codes registered via `defineCodes`:
+
+| Code constant | Trigger |
+|---------------|---------|
+| `LOGGER.SINK` | A sink's `write()` or `flush()` threw |
+| `LOGGER.SERIALIZE` | JSON serialisation of a log record failed |
+| `LOGGER.CONFIG` | Invalid configuration detected at construction time |
+| `LOGGER.FLUSH` | `flush()` aborted via `AbortSignal` |
+
+### LG-14 — i18n / keyed messages
+
+Log messages MUST be plain strings. Callers MAY pass a message key plus interpolation args as `{ key: string; args?: Record<string, unknown> }` — the logger resolves them via the `MessageResolver` from `@suaveplan/types` if one is installed. Unresolved keys are emitted as-is.
+
+### LG-15 — Error bridge
+
+`installSuaveplanErrorInterceptor(logger?)` MUST register an interceptor with `@suaveplan/error` that routes every `SuaveplanError` to the logger at the severity dictated by `err.severity`. The registration MUST be idempotent — re-calling returns the existing uninstall function.
+
+### LG-16 — Factory
+
+`createLogger(config)` MUST be an overloaded factory returning the concrete logger type (`ConsoleLogger | StorageLogger | EventLogger`) based on the `type` discriminant in config.
+
+### LG-17 — Init helper
+
+`initLogger(options?)` MUST construct a `ConsoleLogger` (or accept a pre-built logger), wire the error bridge, and return `{ logger, uninstall }`.
+
+### LG-18 — Property-based tests
+
+The following MUST have fast-check property tests:
+
+- Redaction: `∀ record, rules → redacted record contains no unredacted sensitive fields`
+- Sampling: `HeadSampler is deterministic: same trace_id + rate always gives same decision`
+- JSON round-trip: `∀ record → JSON.parse(JSON.stringify(record))` satisfies the `LogRecord` Zod schema
+
+### LG-19 — Benchmarks
+
+`src/__benchmarks__/logger.bench.ts` MUST exercise the hot path (`log()` → redaction → sampling → `JsonSink`) with mitata and record throughput (records/s). CI regression gate: > 10% slowdown vs baseline fails.
+
+### LG-20 — Tree-shake safety
+
+`sideEffects: false` MUST be set. A test importing only `import type { Logger } from "@suaveplan/logger"` MUST produce a zero-byte bundle (or type-only import). The concrete classes MUST be importable individually via subpath exports without pulling in the full bundle.