Initial Commit

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

@@ -0,0 +1,29 @@
+# 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.

openspec/archive/2026-05-02-logger-spec-conformance/specs/logging/spec.md

@@ -0,0 +1,37 @@
+# Capability Spec Delta: logging (spec-conformance)
+
+**Package**: `@suaveplan/logger`
+**Status**: PROPOSED
+
+This delta annotates each existing requirement in `openspec/specs/logging/spec.md` with a `**Verified by:**` line. No requirement semantics change.
+
+## MODIFIED Requirements
+
+(See `openspec/specs/logging/spec.md` for the full requirement bodies.)
+
+| Requirement | Verified by |
+|---|---|
+| LG-01 Log levels | `src/abstract/abstract-logger.test.ts` AND `src/record/log-record.test.ts` |
+| LG-02 Structured log record | `src/record/log-record.test.ts` |
+| LG-03 Pluggable sinks | `src/sink/sink.test.ts` AND `src/abstract/abstract-logger.test.ts` |
+| LG-04 Console sink | `src/sink/sink.test.ts` |
+| LG-05 JSON (NDJSON) sink | `src/sink/sink.test.ts` |
+| LG-06 Buffered sink | `src/sink/sink.test.ts` |
+| LG-07 Redaction engine | `src/redaction/redaction.test.ts` AND `src/abstract/abstract-logger.test.ts` |
+| LG-08 Sampling | `src/sampling/sampling.test.ts` AND `src/abstract/abstract-logger.test.ts` AND `src/abstract/abstract-logger.spec-conformance.test.ts` |
+| LG-09 OpenTelemetry correlation | `src/otel/otel-context.test.ts` |
+| LG-10 Injectable clock and RNG | `src/abstract/abstract-logger.test.ts` |
+| LG-11 Metrics | `src/abstract/abstract-logger.test.ts` |
+| LG-12 OTel instrumentation | `src/abstract/abstract-logger.spec-conformance.test.ts` |
+| LG-13 Structured errors | `src/errors/logger-error.test.ts` |
+| LG-14 i18n / keyed messages | `src/abstract/abstract-logger.test.ts` (string MUST path; the optional `{ key, args }` overload is forward-looking) |
+| LG-15 Error bridge | `src/error-bridge/error-bridge.test.ts` |
+| LG-16 Factory | `src/factory/factory.test.ts` |
+| LG-17 Init helper | `src/init/init.test.ts` |
+| LG-18 Property-based tests | `src/redaction/redaction.test.ts` AND `src/sampling/sampling.test.ts` AND `src/record/log-record.test.ts` |
+| LG-19 Benchmarks | `src/__benchmarks__/logger.bench.ts` (file existence) AND hot-path correctness via per-feature unit tests |
+| LG-20 Tree-shake safety | `src/abstract/abstract-logger.spec-conformance.test.ts` |
+
+## Newly added tests in this change
+
+- `src/abstract/abstract-logger.spec-conformance.test.ts` — pins LG-12 (recording MeterProvider, asserts `logger.records_total`, `logger.record_size_bytes`, `logger.dropped_total` fire with documented attributes) and LG-20 (`sideEffects: false`, subpath exports, dist shape).

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

@@ -0,0 +1,7 @@
+# Tasks — logger-spec-conformance
+
+- [x] Add `**Verified by:**` line under every `LG-NN` requirement in `openspec/specs/logging/spec.md`.
+- [x] Add `src/abstract/abstract-logger.spec-conformance.test.ts` covering LG-12 OTel instrumentation and LG-20 tree-shake safety.
+- [x] Confirm `bun scripts/openspec-conformance.ts @suaveplan/logger` reports zero errors.
+- [x] Confirm `bunx turbo lint typecheck test --filter=@suaveplan/logger` is green.
+- [x] Confirm `bunx turbo test:coverage --filter=@suaveplan/logger` reports 100/100/100/100.