Initial Commit

openspec/archive/2026-04-18-enterprise-logger/proposal.md

@@ -0,0 +1,113 @@
+# OpenSpec Change: enterprise-logger
+
+- **Change ID**: enterprise-logger
+- **Package**: `@suaveplan/logger`
+- **Category**: universal
+- **Target path**: `packages/universal/logger`
+- **Status**: IN PROGRESS
+- **Date**: 2026-04-18
+- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/logger.md`
+
+## Summary
+
+Greenfield implementation of `@suaveplan/logger` for the genesis branch. The existing main-branch logger (v1.23) provides the baseline public-API surface to preserve; this change adds enterprise-grade structured JSON output, declarative redaction, head/tail/rule-based sampling, OpenTelemetry correlation, pluggable sinks, property-based tests, and benchmarks.
+
+## Current-state audit (genesis)
+
+The package does not exist on genesis yet — this is a fresh build.
+
+## Available workspace deps on genesis
+
+| Package | Available |
+|---------|-----------|
+| `@suaveplan/error` | ✅ |
+| `@suaveplan/events` | ✅ |
+| `@suaveplan/types` | ✅ |
+| `@suaveplan/timing` | ❌ not yet built — use `Clock` from `@suaveplan/types` |
+| `@suaveplan/storage` | ❌ not yet built — keep `StorageInterface` locally |
+| `@suaveplan/streams` | ❌ not yet built — implement bounded buffer internally |
+| `@suaveplan/opentelemetry` | ❌ not yet built — use `@opentelemetry/api` directly |
+| `@suaveplan/feature-flags` | ❌ not yet built — skip |
+| `@suaveplan/schema-registry` | ❌ not yet built — export Zod schemas directly |
+
+External deps (via catalog):
+
+- `zod` → `catalog:forms`
+- `@opentelemetry/api` → `catalog:observability`
+- `tslib` → `catalog:build`
+
+Dev deps (via catalog):
+
+- `vitest`, `@vitest/coverage-istanbul` → `catalog:testing`
+- `fast-check` → `catalog:testing`
+- `mitata` → `catalog:testing`
+
+## Preserved public API surface (from main branch)
+
+All of the following must be exported from the genesis build:
+
+### Types
+
+- `LogLevel`, `LogEntry<TMetadata>`, `LoggerConfig<TMetadata>`, `LoggerMetrics`
+- `ConsoleLoggerConfig<TMetadata>`
+- `EventLoggerConfig<TMetadata>`, `LoggerEvents<TMetadata>`
+- `StorageLoggerConfig<TMetadata>`, `StorageInterface`
+- `ConsoleLoggerFactoryConfig<TMetadata>`, `StorageLoggerFactoryConfig<TMetadata>`, `EventLoggerFactoryConfig<TMetadata>`, `LoggerFactoryConfig<TMetadata>`
+- `InitLoggerOptions<TMetadata>`, `InitLoggerResult`
+- `SeverityLevelMap`, `UninstallErrorInterceptor`, `InstallErrorInterceptorOptions`
+
+### Classes
+
+- `AbstractLogger<TMetadata>` (abstract)
+- `ConsoleLogger<TMetadata>`
+- `EventLogger<TMetadata>`
+- `StorageLogger<TMetadata>`
+
+### Interfaces
+
+- `Logger<TMetadata>`
+- `LogLevels`
+
+### Functions
+
+- `createLogger(config)` (overloaded factory)
+- `initLogger(options?)` → `InitLoggerResult`
+- `installSuaveplanErrorInterceptor(logger?)` → `UninstallErrorInterceptor`
+- `__resetDefaultLoggerForTests()`
+
+## New additions
+
+### Modules
+
+- **`record/`** — `LogRecord` structured JSON schema (Zod), `ts`/`level`/`msg`/`ctx`/`trace_id`/`span_id`/`error` fields
+- **`errors/`** — `LoggerError` extending `SuaveplanError`; codes: `LOGGER.SINK`, `LOGGER.SERIALIZE`, `LOGGER.CONFIG`, `LOGGER.FLUSH`
+- **`redaction/`** — `RedactionEngine` with field-path rules (dot-notation + glob), regex rules, depth limit; `@sensitive`-aware via `isSensitive()` from `@suaveplan/error`
+- **`sampling/`** — `HeadSampler` (deterministic per trace_id hash), `TailSampler` (bounded buffer + decision callback), `RuleSampler` (predicate-based); `SamplingPolicy` union type
+- **`sink/`** — `Sink` interface; `ConsoleSink` (ANSI dev output); `JsonSink` (NDJSON writer); `BufferedSink` (bounded queue, drop/block policy, `AbortSignal` flush)
+- **`otel/`** — `getOtelTraceContext()` reads `trace_id`/`span_id` from active OTel span (no-op when no exporter)
+- **`schemas/`** — Zod schemas for `LoggerConfig`, `LogRecord`, all sink configs (re-exported)
+
+### Cross-cutting enterprise requirements
+
+- Injectable `clock` (from `@suaveplan/types#Clock`) and `rng` on all time/random usages
+- `AbortSignal` support on `flush()` and `getLogs()`
+- `sideEffects: false` + tree-shake test
+- Property-based tests (fast-check) for redaction invariants and sampling determinism
+- mitata benchmarks in `src/__benchmarks__/`
+- OTel counters + histograms on `log()` calls (via `@opentelemetry/api`, no-op when unregistered)
+- Zero `any`, zero `ts-ignore`, zero mock usage in tests
+
+## Dependency-layer check
+
+`@suaveplan/logger` depends on `@suaveplan/error` and `@suaveplan/events`, both of which are enterprise-complete on genesis. ✅
+
+## Acceptance criteria
+
+- [x] `bunx turbo lint typecheck test:coverage --filter=@suaveplan/logger` green with ≥ 100% coverage on touched modules
+- [x] `bun run docs:check --filter=@suaveplan/logger` reports ≥ 90%
+- [x] All preserved public API surface exported from `src/index.ts`
+- [x] New `LogRecord` schema, `LoggerError`, redaction, sampling, sink, OTel modules implemented
+- [x] Zero `any`, `ts-ignore`, `TODO`, `FIXME`, `@deprecated`, `.skip`, `.only` in `src/`
+- [x] Property-based tests for redaction invariants and sampling determinism
+- [x] mitata benchmarks in `src/__benchmarks__/`
+- [x] `sideEffects: false` confirmed, tree-shake test passes