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

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

• bunx turbo lint typecheck test:coverage --filter=@suaveplan/logger green with ≥ 100% coverage on touched modules
• bun run docs:check --filter=@suaveplan/logger reports ≥ 90%
• All preserved public API surface exported from src/index.ts
• New LogRecord schema, LoggerError, redaction, sampling, sink, OTel modules implemented
• Zero any, ts-ignore, TODO, FIXME, @deprecated, .skip, .only in src/
• Property-based tests for redaction invariants and sampling determinism
• mitata benchmarks in src/__benchmarks__/
• sideEffects: false confirmed, tree-shake test passes