# 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.