suaveplan/openspec/archive/2026-04-19-enterprise-idempotency/proposal.md

OpenSpec Change: enterprise-idempotency

• Change ID: enterprise-idempotency
• Package: @suaveplan/idempotency
• Category: universal
• Target path: packages/universal/idempotency
• Status: PROPOSED
• Date: 2026-04-19
• Reference spec: /mnt/s/web/suaveplan/enterprise/idempotency.md

Summary

Greenfield implementation of @suaveplan/idempotency for the genesis branch. The existing main-branch idempotency package (98.68% test coverage) provides the baseline public-API surface to preserve; this change delivers enterprise-grade idempotency key guarding and deduplication with a full state machine (pending → completed | failed), pluggable store adapters (memory, database, Redis), distributed locking via a LockProvider interface, HTTP middleware, key generation and fingerprinting, key versioning, metrics collection, injectable clock and RNG, AbortSignal support throughout, structured errors with stable IDEMPOTENCY.* codes, Zod schemas, OTel instrumentation, property-based tests, and benchmarks.

Current-state audit (genesis)

The package does not exist on genesis yet — this is a fresh build.

Available workspace deps on genesis

Package	Available
@suaveplan/error	✅
@suaveplan/types	✅
@suaveplan/events	✅
@suaveplan/crypto-utils	✅
@suaveplan/crypto-hash	✅
@suaveplan/crypto-curve	✅
@suaveplan/crypto-cipher	✅
@suaveplan/crypto	✅
@suaveplan/crypto-keys	✅
@suaveplan/logger	✅
@suaveplan/opentelemetry	❌ not yet built — use @opentelemetry/api directly
@suaveplan/schema-registry	❌ not yet built — export Zod schemas directly
@suaveplan/streams	❌ not yet built — skip streaming features
@suaveplan/feature-flags	❌ not yet built — skip
@suaveplan/retry	❌ in progress — skip retry integration for now

External deps (via catalog):

• zod → catalog:forms
• @opentelemetry/api → catalog:observability
• tslib → catalog:build

Dev deps (via catalog):

• vitest, @vitest/coverage-istanbul → catalog:testing
• fast-check → catalog:testing
• mitata → catalog:testing

Preserved public API surface (from main branch)

Distributed

• DistributedIdempotencyGuard class — distributed-safe guard backed by a LockProvider
• LockAcquisitionError extends SuaveplanError
• MemoryLockProvider — in-process lock provider for unit tests and single-node deployments
• RedisLockProvider — Redis-backed lock provider with lease/refresh semantics
• RedisLockProviderConfig — configuration type for RedisLockProvider

Guard

• IdempotencyConflictError extends SuaveplanError — thrown when a pending record is detected for the same key
• IdempotencyGuard class — single-node guard with state machine and pluggable store
• IdempotencyMismatchError extends SuaveplanError — thrown when the request fingerprint differs from the stored record

Key generation

• compositeKey(...parts: string[]) → string — assembles a namespaced key from ordered parts
• fingerprintPayload(input: unknown, hashFn?) → string — deterministic hex fingerprint of arbitrary input
• generateIdempotencyKey(config?: KeyGeneratorConfig) → string — generates a random, optionally prefixed key

Error codes

• IdempotencyErrorCode — union type of all stable error code strings
• IDEMPOTENCY_ERROR_METADATA — Record<IdempotencyErrorCode, CodeMetadata> mapping
• registerIdempotencyErrorCodes() — registers all codes on the shared ErrorCodes singleton

Metrics

• IdempotencyMetrics class — collects and exposes a rolling IdempotencyMetricsSnapshot

Middleware

• createIdempotencyMiddleware<TReq, TRes>(config) → middleware handler function
• MiddlewareResult<TRes> — discriminated union returned by the middleware (hit | miss | conflict)

Store adapters

• IdempotencyStoreAdapter<T> — interface: get, set, delete, cleanup
• IdempotencyDatabaseAdapter — interface for plugging in a raw database client
• RedisClientAdapter — interface for plugging in a raw Redis client
• MemoryIdempotencyStore — in-process TTL store, GC via cleanup()
• DatabaseIdempotencyStore — adapter-backed persistent store
• DatabaseIdempotencyStoreConfig — configuration type
• RedisIdempotencyStore — Redis-backed store with atomic set-if-not-exists
• RedisIdempotencyStoreConfig — configuration type

Types

• ConflictResolutionStrategy — 'reject' | 'overwrite' | 'version'
• DistributedGuardConfig — configuration for DistributedIdempotencyGuard
• IdempotencyGuardConfig — configuration for IdempotencyGuard
• IdempotencyMetricsConfig — configuration for IdempotencyMetrics
• IdempotencyMetricsSnapshot — point-in-time metrics snapshot shape
• IdempotencyMiddlewareConfig<TReq, TRes> — configuration for middleware
• IdempotencyRecord<T> — stored record shape with status, response, fingerprint, timestamps
• IdempotencyStatus — 'pending' | 'completed' | 'failed'
• IdempotencyStoreAdapter<T> — store interface
• KeyGeneratorConfig — key prefix + separator options
• KeyVersioningConfig — store + strategy + maxVersions options
• LockProvider — interface: acquire(resource, ttlMs), release(resource)
• MetricsReporter — callback type (snapshot: IdempotencyMetricsSnapshot) => void
• VersionEntry<T> — versioned record snapshot

Versioning

• KeyVersioning class — multi-version record management with configurable conflict strategy
• VersionConflictError extends SuaveplanError — thrown when version limit is exceeded

New additions for genesis

Structured errors

• IdempotencyError base class extends SuaveplanError with codes under IDEMPOTENCY.* namespace
• Codes: IDEMPOTENCY.KEY_CONFLICT, IDEMPOTENCY.RESPONSE_MISMATCH, IDEMPOTENCY.STORE_ERROR, IDEMPOTENCY.KEY_EXPIRED, IDEMPOTENCY.KEY_INVALID, IDEMPOTENCY.LOCK_ACQUISITION_FAILED, IDEMPOTENCY.VERSION_CONFLICT
• IdempotencyConflictError, IdempotencyMismatchError, LockAcquisitionError, VersionConflictError all extend IdempotencyError

Zod schemas

• IdempotencyGuardConfigSchema, DistributedGuardConfigSchema, KeyGeneratorConfigSchema, KeyVersioningConfigSchema, IdempotencyMetricsConfigSchema, IdempotencyMiddlewareConfigSchema
• IdempotencyRecordSchema, IdempotencyStatusSchema

Injectable clock + RNG

• IdempotencyGuardConfig.clock?: Clock — for deterministic TTL and timeout computation (FakeClock in tests)
• IdempotencyGuardConfig.rng?: Rng — for deterministic key generation
• DistributedGuardConfig.clock?: Clock
• KeyGeneratorConfig.rng?: Rng

AbortSignal support

• IdempotencyGuard.execute(key, fn, opts?: { signal? }) — cancels pending-record wait on abort
• DistributedIdempotencyGuard.execute(key, fn, opts?: { signal? }) — propagates signal through lock acquisition retries and fn invocation

OTel instrumentation

• Counter: idempotency.request.total (by outcome label: hit | miss | conflict | mismatch | error)
• Histogram: idempotency.execution.duration_ms (guard execution latency)
• Counter: idempotency.lock.acquisition.total (by result: acquired | failed | retried)
• Histogram: idempotency.lock.wait_ms (time spent acquiring a distributed lock)
• Counter: idempotency.store.operation.total (by operation: get | set | delete | cleanup)

Property-based tests (fast-check)

• compositeKey output is always deterministic for equal inputs
• fingerprintPayload is collision-resistant: distinct inputs produce distinct hashes across arbitrary payloads
• generateIdempotencyKey never produces duplicate outputs across N iterations with a mocked RNG
• IdempotencyGuard.execute never executes fn more than once for the same key when called concurrently
• KeyVersioning never exceeds maxVersions stored entries regardless of call order

Benchmarks (mitata)

• MemoryIdempotencyStore.get hot path — 10 000 cached reads
• IdempotencyGuard.execute with cached hit — zero-execution overhead
• compositeKey throughput — 1 000 000 iterations
• fingerprintPayload throughput — 10 000 small payloads

Notes on integration testing

• RedisIdempotencyStore and RedisLockProvider require a real Redis instance. Integration tests use a redis://localhost:6379 connection; no mock Redis. Tests are placed in tests/integration/ and are guarded by a TEST_REDIS_URL environment variable.
• DistributedIdempotencyGuard is unit-tested with MemoryLockProvider only. Integration tests covering the full distributed path with Redis are in tests/integration/.
• DatabaseIdempotencyStore integration tests require TEST_DATABASE_URL environment variable; unit tests use MemoryIdempotencyStore as a stand-in.

Impact

• Adds one new package: packages/universal/idempotency
• Adds one new spec capability: idempotency
• No existing package consumers on genesis yet