Initial Commit

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

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

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

@@ -0,0 +1,32 @@
+# Capability Spec Delta: idempotency (spec-conformance)
+
+**Package**: `@suaveplan/idempotency`
+**Status**: PROPOSED
+
+This delta annotates each existing requirement in `openspec/specs/idempotency/spec.md` with a `**Verified by:**` line and rewrites the heading style from `REQ-IDMP-NNN — name` to `IDMP-NN — name` so the conformance parser ingests them. No requirement semantics change.
+
+## MODIFIED Requirements
+
+(See `openspec/specs/idempotency/spec.md` for the full requirement bodies; this delta only records the verification mapping.)
+
+| Requirement | Verified by |
+|---|---|
+| IDMP-01 — Structured error hierarchy | `src/errors/idempotency-error.test.ts` AND `src/error-codes.test.ts` AND `src/errors/idempotency-error.spec-conformance.test.ts` |
+| IDMP-02 — Zod schemas for all public config types | `src/schemas/idempotency.schemas.spec-conformance.test.ts` |
+| IDMP-03 — Injectable clock and RNG | `src/guard/idempotency-guard.test.ts` AND `src/distributed/distributed-guard.test.ts` AND `src/metrics/idempotency-metrics.test.ts` AND `src/key/key-generator.test.ts` AND `src/guard/idempotency-guard.spec-conformance.test.ts` |
+| IDMP-04 — AbortSignal support throughout | `src/guard/idempotency-guard.test.ts` AND `src/distributed/distributed-guard.test.ts` AND `src/guard/idempotency-guard.spec-conformance.test.ts` |
+| IDMP-05 — OTel instrumentation via `@opentelemetry/api` | `src/metrics/idempotency-metrics.test.ts` AND `src/metrics/idempotency-metrics.spec-conformance.test.ts` |
+| IDMP-06 — Property-based tests with fast-check | `tests/property.test.ts` |
+| IDMP-07 — Benchmarks with mitata | `src/__benchmarks__/idempotency.bench.ts` AND `tests/benchmarks-present.spec-conformance.test.ts` |
+| IDMP-08 — Store adapter extensibility | `src/store/memory-store.test.ts` AND `src/store/database-store.test.ts` AND `src/store/redis-store.test.ts` AND `src/distributed/distributed-guard.test.ts` AND `tests/structural-adapters.spec-conformance.test.ts` |
+| IDMP-09 — Real services for integration tests; no mock stores in unit tests | `tests/no-disallowed.test.ts` AND `src/store/memory-store.test.ts` |
+| IDMP-10 — 100% test coverage | `vitest.config.ts` (Istanbul thresholds 100/100/100/100) plus the `bunx turbo test:coverage --filter=@suaveplan/idempotency` gate |
+
+## Newly added tests in this change
+
+- `src/errors/idempotency-error.spec-conformance.test.ts` — pins error-hierarchy and namespace invariants.
+- `src/schemas/idempotency.schemas.spec-conformance.test.ts` — pins every required Zod schema export and a representative round-trip.
+- `src/guard/idempotency-guard.spec-conformance.test.ts` — pins clock-driven TTL semantics and AbortSignal mid-flight.
+- `src/metrics/idempotency-metrics.spec-conformance.test.ts` — pins OTel no-op behaviour and the five required instrument labels.
+- `tests/structural-adapters.spec-conformance.test.ts` — pins that plain-object store and lock-provider implementations are accepted.
+- `tests/benchmarks-present.spec-conformance.test.ts` — pins the canonical benchmark suite location and coverage of all four hot paths.

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

@@ -0,0 +1,26 @@
+# Tasks: idempotency-spec-conformance
+
+## 1. Source refactors (no public-API change)
+
+- [x] 1.1 Rewrite `src/error-codes.ts` to use `defineCodes("IDEMPOTENCY", [...])` from `@suaveplan/error`; re-export `IDEMPOTENCY_CODES` from `src/errors/idempotency-error.ts`.
+- [x] 1.2 Add `// schema: boundary-only` marker to `src/schemas/idempotency.schemas.ts`.
+
+## 2. Spec annotations
+
+- [x] 2.1 Rewrite `### REQ-IDMP-NNN —` headings as `### IDMP-NN —` so the conformance parser picks them up.
+- [x] 2.2 Add a `**Verified by:**` line under every requirement in `openspec/specs/idempotency/spec.md`.
+
+## 3. Pinning tests
+
+- [x] 3.1 Add `src/errors/idempotency-error.spec-conformance.test.ts` (IDMP-01).
+- [x] 3.2 Add `src/schemas/idempotency.schemas.spec-conformance.test.ts` (IDMP-02).
+- [x] 3.3 Add `src/guard/idempotency-guard.spec-conformance.test.ts` (IDMP-03 + IDMP-04).
+- [x] 3.4 Add `src/metrics/idempotency-metrics.spec-conformance.test.ts` (IDMP-05).
+- [x] 3.5 Add `tests/structural-adapters.spec-conformance.test.ts` (IDMP-08).
+- [x] 3.6 Add `tests/benchmarks-present.spec-conformance.test.ts` (IDMP-07).
+
+## 4. Verify
+
+- [x] 4.1 `bunx turbo lint typecheck test --filter=@suaveplan/idempotency` green (8/8 tasks, 234/234 tests).
+- [x] 4.2 `bunx turbo test:coverage --filter=@suaveplan/idempotency` 100/100/100/100.
+- [x] 4.3 `bun scripts/openspec-conformance.ts @suaveplan/idempotency` PASS (0 error, 9 warn, 1 info).