suaveplan/openspec/archive/2026-05-02-logger-spec-conformance/proposal.md

OpenSpec Change: logger-spec-conformance

• Change ID: logger-spec-conformance
• Package: @suaveplan/logger
• Status: PROPOSED
• Date: 2026-04-26

Summary

Add **Verified by:** lines to every requirement in openspec/specs/logging/spec.md and pin previously-unverified scenarios — LG-12 OTel instrumentation (records counter, record-size histogram, dropped counter with both sampling and backpressure reasons) and LG-20 tree-shake safety (sideEffects: false, subpath exports) — with src/abstract/abstract-logger.spec-conformance.test.ts. No public-API or behavioural changes.

Current state

@suaveplan/logger ships AbstractLogger + concrete ConsoleLogger / StorageLogger / EventLogger, RedactionEngine, four samplers (head/tail/rule/all/none), four sinks (console/json/buffered/multi), error bridge, factory, init helper, and OTel correlation. Per-feature unit tests cover behaviour. The structural spec scenarios (OTel instruments emitted with the documented attributes; tree-shake/sideEffects: false) were not pinned at runtime, and no requirement carried a **Verified by:** annotation.

The LogRecord.error?: unknown field is intentional per LG-02 — it carries the serialised output of @suaveplan/error.toJSON(), which is a payload-by-design unknown. The conformance script flags it as a warn, not an error, which AGENTS.md §13 documents as acceptable for payload-by-design surfaces.

What changes

1. Annotate every requirement (LG-01 through LG-20) in openspec/specs/logging/spec.md with a **Verified by:** line.
2. Add src/abstract/abstract-logger.spec-conformance.test.ts covering LG-12 (recording MeterProvider via metrics.setGlobalMeterProvider, asserts the three instruments fire with the documented attributes) and LG-20 (package.json sideEffects: false, subpath exports, dist shape).
3. bun scripts/openspec-conformance.ts @suaveplan/logger reports zero errors (one warn for the by-design error?: unknown payload remains, per spec).

Impact

• Public API unchanged.
• One new test file (~150 lines).
• openspec/specs/logging/spec.md gains 20 **Verified by:** blocks.
• Coverage stays 100/100/100/100.