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

OpenSpec Change: idempotency-spec-conformance

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

Summary

Bring @suaveplan/idempotency into spec conformance with openspec/specs/idempotency/spec.md. The implementation already satisfies every MUST clause; this change closes the documentation and parsing gaps so bun scripts/openspec-conformance.ts @suaveplan/idempotency exits 0. No public-API changes.

Current state

@suaveplan/idempotency ships a complete enterprise-grade implementation: structured error hierarchy, eight IDEMPOTENCY.* codes with metadata, eight Zod boundary schemas, injectable Clock, AbortSignal propagation, full OTel meter wiring, MemoryIdempotencyStore / RedisIdempotencyStore / DatabaseIdempotencyStore, MemoryLockProvider / RedisLockProvider, fast-check property tests, and a mitata benchmark suite. The conformance gaps are mechanical:

• src/error-codes.ts declared the codes inline ({ ... } as const) instead of via defineCodes("IDEMPOTENCY", [...]), so the conformance script could not parse the registry.
• The folded spec used ### REQ-IDMP-NNN — name headings, which the parser (^[A-Z][A-Z0-9]*-\d+) silently skips, yielding 0 parsed requirements.
• Schemas were exported but never invoked outside src/schemas/ (every consumer composes the underlying Zod object directly), triggering boundary warnings.
• 10/10 requirements lacked **Verified by:** lines.
• Five implicit scenarios were exercised only indirectly: clock injection, AbortSignal mid-flight, OTel no-op + per-instrument labels, structural-adapter acceptance, and benchmark presence.
• tasks.md of 2026-04-19-enterprise-idempotency/ carries the retroactively ticked marker.

What changes

1. Refactor src/error-codes.ts to declare IDEMPOTENCY_CODES via defineCodes("IDEMPOTENCY", [...]) from @suaveplan/error. Re-export from src/errors/idempotency-error.ts for backwards compat. No public-API change.
2. Add // schema: boundary-only marker to src/schemas/idempotency.schemas.ts to suppress the (correct) boundary warning — schemas are consumer-facing only.
3. Rewrite the requirement headings in openspec/specs/idempotency/spec.md from REQ-IDMP-NNN — name to IDMP-NN — name so the conformance parser picks them up. Add **Verified by:** lines under every requirement.
4. Add five *.spec-conformance.test.ts files pinning the implicit scenarios:
   • src/errors/idempotency-error.spec-conformance.test.ts — IDMP-01 (hierarchy + namespace + frozen registry).
   • src/schemas/idempotency.schemas.spec-conformance.test.ts — IDMP-02 (every required schema present and round-trippable).
   • src/guard/idempotency-guard.spec-conformance.test.ts — IDMP-03 (clock-driven timestamps & cleanup) + IDMP-04 (pre-aborted and mid-flight signal).
   • src/metrics/idempotency-metrics.spec-conformance.test.ts — IDMP-05 (no-op without meter, all five instruments, correct outcome / operation / result labels, histogram values).
   • tests/structural-adapters.spec-conformance.test.ts — IDMP-08 (plain-object adapter and lock provider).
   • tests/benchmarks-present.spec-conformance.test.ts — IDMP-07 (suite at canonical path covers all four hot paths).
5. Re-run bun scripts/openspec-conformance.ts @suaveplan/idempotency and confirm exit 0.

Impact

• Public API unchanged.
• Error-code registry now uses the canonical defineCodes helper.
• Six new test files (~350 lines combined).
• openspec/specs/idempotency/spec.md gains 10 **Verified by:** lines and parseable headings.