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

OpenSpec Change: error-spec-conformance

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

Summary

Add **Verified by:** lines to every requirement in openspec/specs/error/spec.md, fill the three missing test scenarios (subclass narrows code union, stack trace contains subclass name, code values are literal-typed), and rectify the retroactively ticked historical hazard so bun scripts/openspec-conformance.ts @suaveplan/error exits 0. No public-API changes.

Current state

@suaveplan/error is structurally solid: SuaveplanError base class, defineCodes registry helper, cycle-safe walkCauses, lossless JSON/binary serialization with markSensitive redaction, toSpanEvent adapter, setMessageResolver i18n hook, fast-check property-based round-trip, 100% coverage. The conformance gaps are documentary plus three unwritten test scenarios:

• 9/9 requirements lack **Verified by:** lines.
• "Subclass narrows code union" — the spec asserts type-level inference but no test pins it.
• "Stack trace preserved" — the existing captureStackTrace fallback test doesn't assert the subclass name appears in err.stack.
• "Code values are literal-typed" — type-level scenario with no test.
• tasks.md of 2026-04-19-enterprise-error/ carries retroactively ticked.

What changes

1. Add **Verified by:** line under every ### Requirement: block in openspec/specs/error/spec.md.
2. Add src/base/suaveplan-error.spec-conformance.test.ts covering:
   • "subclass narrows code union" — expectTypeOf assertion on err.code after instanceof MySubclass narrowing.
   • "stack trace contains subclass name" — expect(err.stack).toContain("MySubclass") AND expect(err.stack).not.toMatch(/^\s*Error\b/).
3. Add src/codes/define-codes.spec-conformance.test.ts covering:
   • "code values are literal-typed" — expectTypeOf<typeof codes.A>().toEqualTypeOf<"PKG.A">().
4. Re-run bun scripts/openspec-conformance.ts @suaveplan/error and confirm exit 0.

Impact

• Public API unchanged.
• Two new test files (~60 lines combined).
• openspec/specs/error/spec.md gains 9 **Verified by:** lines.