fix: resolve architecture review findings (H1-H3, M1-M6, L1-L6)

[camcima]

Fixes the findings from the architecture review in ARCHITECTURE_REVIEW.md (added here): all three high, all six medium, and six of the eight low. Two low findings are deliberately deferred — see the end.

The headline fix is H1: the docs promised that a backfilled layer keeps its own TTL policy, while the code gave it the source layer's remaining lifetime. Following the two-layer pattern the docs recommend — MemoryAdapter({ defaultTtlMs: 30_000 }) over RedisAdapter({ defaultTtlMs: 300_000 }) — L1 entries lived up to 5 minutes instead of 30 seconds. Nothing in the suite covered it, which is how the divergence survived.

What changed

#	Finding	Fix
H1	Backfill TTL contradicted the docs	Backfill applies each target layer's own defaultTtlMs, capped by the source's remaining lifetime. Adapters expose this via a new optional ttlPolicy on CacheAdapter, supplied automatically by BaseCacheAdapter.
H2	Nest token collided with @nestjs/cache-manager	Token value is now "ZIGGURAT_CACHE_MANAGER". The exported constant keeps its name.
H3	vitest.workspace.ts broken under Vitest 4	Removed; root tsconfig becomes solution-style and references all six packages instead of three.
M1	Redis clear() wiped the whole database	Throws when no prefix is set, unless the new allowUnprefixedClear opts in.
M2	wrap() blocked on every layer write	New wrapWrites: "background" resolves as soon as the factory does. Default unchanged.
M3	Read repair raced concurrent writers	Redis/Memcached reads report a miss and no longer delete. SQLite keeps cleanup (its rows are unambiguously its own) but the deletes are now conditional on the row still being the one that was read.
M4	mget partial-failure differed per adapter	Partial results are the contract; BaseCacheAdapter.mget no longer rejects the batch. Writes still reject.
M5	set(key, undefined) did 4 different things	A no-op everywhere, leaving any existing value untouched.
M6	Node 20 claimed but never tested	New compat job builds on Node 22, then loads the built bundles on Node 20 and 24 with plain node.
L1–L6	Doc drift, dead ZIGGURAT_OPTIONS export, missing otel coverage upload, unnamespaced otel metrics, duplicate-key mget miscount, missing SQLite busy_timeout	All fixed.

custom-adapters.md also taught an example that could not compile — it implemented the bare CacheAdapter interface with four of its twelve members — and pointed at an import path the package doesn't ship. It now builds on BaseCacheAdapter, and the contract-suite section says plainly that the suite isn't published for external adapters yet.

Breaking changes

All are 0.x behavior corrections, each marked with a BREAKING CHANGE: footer:

1. RedisAdapter.clear()/flushAll() throw without a prefix (opt out with allowUnprefixedClear: true).
2. Redis/Memcached reads no longer delete expired or corrupt keys.
3. BaseCacheAdapter.mget returns partial results instead of rejecting.
4. set(key, undefined) is a no-op rather than storing, throwing, or being stored-but-unreadable.
5. Backfilled entries honor the target layer's defaultTtlMs.
6. CACHE_MANAGER token value changed — only affects code that hardcoded the string rather than importing the constant. ZIGGURAT_OPTIONS (exported but never provided by anything) is gone.

Verification

• 637 unit/contract/integration tests pass (up from 594) — lint, format, and typecheck clean.
• Node 20 floor confirmed by running scripts/smoke-test.mjs against real Node 20.19.1, 22.22.2, and 24.18.1 locally.
• Functional suites run against real backends: Redis 111 passed, Memcached 97 passed, SQLite 96 passed, via docker compose.
• New regression tests cover every behavioral change, including six for H1 alone (per-layer TTL, source-lifetime cap, permanent sources, mget backfill, and independent TTLs per layer in a three-layer stack).
• The undefined and TTL rules are pinned in the shared contract suite, so all four adapters are held to them.
• Job names validate and test are unchanged, so the 8 required status checks still resolve; compat is additive.

A note on the compat job

My first attempt at M6 ran the full toolchain on each Node version and failed on Node 20 in 15 seconds — pnpm 11 refuses to install below Node 22.13, and the repo's own engines says the same. The >=20 floor simply cannot be checked that way.

The job now builds on Node 22 and then loads the built bundles under Node 20 and 24 with plain node, which is what a consumer actually does. scripts/smoke-test.mjs loads every package's ESM and CJS bundle — no adapter pulls a native module at runtime, since the backends are type-only imports — and exercises core end to end: coalescing, layered reads, backfill under the target layer's TTL policy, and delete. That turns out to test the published claim more directly than running the dev suite would have.

Deferred

• L7 — publishing the contract suite as @ziggurat-cache/adapter-testkit. It's a new published package (build config, release wiring, docs) and belongs in its own PR. custom-adapters.md now states the current limitation honestly instead of pointing at a path that doesn't resolve.
• L8 — API/perf polish (del() alias, native Redis EXISTS/PTTL for has/getTtl, a debug hook for swallowed listener errors). Churn without a correctness payoff; better bundled with the 1.0 API pass.

The five architectural observations in the review (no adapter lifecycle/dispose contract, single-cache-only Nest module, per-process-only stampede protection, envelope expiry bookkeeping, getTtl first-layer semantics) are roadmap items for the 1.0 discussion, not defects, and are untouched here.

🤖 Generated with Claude Code

https://claude.ai/code/session_01MsFZHTnQmAUMjtLUegFRPL

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (5b6fb81) to head (962275f).

Additional details and impacted files

@@             Coverage Diff             @@
##             main       #56      +/-   ##
===========================================
+ Coverage   99.85%   100.00%   +0.14%     
===========================================
  Files          11        11              
  Lines         668       695      +27     
  Branches      153       167      +14     
===========================================
+ Hits          667       695      +28     
+ Misses          1         0       -1     

Flag	Coverage Δ
unit	100.00% <100.00%> (+0.14%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.