suaveplan/openspec/archive/2026-04-19-enterprise-error/tasks.md

Archived 2026-04-19: all tasks retroactively ticked; package shipped under universal/observability/error.

Tasks: enterprise-error

1. Scaffold

• 1.1 Create packages/universal/error/ with package.json, tsconfig.json, tsconfig.lib.json, vite.config.ts, vitest.config.ts, README.md skeleton
• 1.2 Register thresholds at 100/100/100/100 in vitest.config; coverage provider = istanbul
• 1.3 Add the three cross-cutting guards in tests/: dep-graph, no-disallowed, tree-shake
• 1.4 Add package to STRUCTURE.yml, root README.md count, CLAUDE.md listing

2. Base class + codes

• 2.1 Implement SuaveplanError<TCode> with clock injection, context, traceId, timestamp
• 2.2 Implement defineCodes(ns, reasons) with literal-type inference and freeze
• 2.3 Implement package-local ERROR_CODES registry and ErrorPackageError subclass
• 2.4 Tests for base + codes including subclass code narrowing

3. Cause chain

• 3.1 Implement walkCauses generator — cycle-safe (WeakSet), depth-bounded, non-object causes allowed
• 3.2 Tests for linear chains, self-cycle, mutual-cycle, depth cap, non-Error causes

4. Serialization

• 4.1 Implement toJSON — applies redaction, walks cause chain, emits __suaveplanError: 1 version field
• 4.2 Implement fromJSON — Zod-validated, reconstructs via ErrorPackageError fallback when the subclass can't be resolved
• 4.3 Implement toBinary — in-file MessagePack encoder covering nil/bool/int/float64/str/bin/array/map
• 4.4 Implement fromBinary — paired decoder
• 4.5 Property-based tests (fast-check): JSON round-trip, binary round-trip, binary-bytes-match-JSON-structure, cycle-safe serialization

5. Redaction

• 5.1 Implement markSensitive, unwrapSensitive, isSensitive
• 5.2 Wire redaction application inside toJSON / toBinary
• 5.3 Tests: in-memory access, wire redaction, nested sensitive values

6. OTel adapter

• 6.1 Implement toSpanEvent(err) with OTel-compliant attribute shape
• 6.2 Tests: attribute names, stack fallback, code propagation, traceId propagation

7. i18n resolver hook

• 7.1 Implement setMessageResolver, resolveMessage, clearMessageResolver
• 7.2 Tests: default pass-through, resolver wiring, params interpolation, clear resets to default

8. Docs

• 8.1 Co-located .md for every implementation file (≥200 words, simple + advanced example, full API reference)
• 8.2 Rewrite README.md with full public API overview, design rationale, and consumer guide
• 8.3 Run bun run docs:check --filter=@suaveplan/error — verify ≥90% coverage

9. Benchmarks

• 9.1 Add src/__benchmarks__/serialize.bench.ts (mitata): toJSON, fromJSON, toBinary, fromBinary throughput
• 9.2 Publish baseline numbers in README

10. Verify and publish

• 10.1 bunx turbo lint typecheck test --filter=@suaveplan/error green
• 10.2 bunx turbo test:coverage --filter=@suaveplan/error at 100/100/100/100
• 10.3 bunx turbo build --filter=@suaveplan/error green
• 10.4 bun scripts/publish.ts --package @suaveplan/error to Verdaccio at 0.0.0
• 10.5 Archive OpenSpec change folder to openspec/archive/<yyyy-mm-dd>-enterprise-error/