문제: 설계서·계획서·납품 패키지·증거·학습 문서와 ADR이 기록이라는 표시 없이 지금 문서처럼 읽힌다. 상태 칸이 설계서 72개 중 40개, 계획서는 거의 없고, 있어도 Approved·확정·Accepted.처럼 값이 제각각이며 영어다. 고른 방법: docs/design, docs/history, docs/adr, docs/notification/adr의 .md 246개 맨 위에 같은 모양의 머리 블록을 단다. 칸은 상태·작성일· 요약(한국어 한 문장)·현재 정본, 대체됐으면 대체됨이다. 블록은 표시 줄 두 개로 감싸서 빼면 원문 바이트가 그대로 돌아온다(246개 모두 대조함). - 종류는 폴더가 정하고 둘째 줄에 적는다(plans/evidence는 증거). - 상태는 원래 상태 줄을 고정 어휘로 바꾼 값이다. 상태 줄이 없는 설계서와 체크 상자가 다 표시되지 않은 계획서는 「확인 안 함」. capability-status.md 제거 표로 지운 것이 확인된 설계서 다섯은 「폐기」, 2026-07-20 하네스 설계·계획과 production capability platform 설계는 「대체됨」이다. - 현재 정본은 구조 정리로 옮겨질 수 있는 src/messaging·src/grpc 대신 docs/ 쪽 문서나 옮기지 않는 leaf README를 가리킨다. docs/README.md에 「문서 수명과 언어」「기록 문서의 머리 블록」「문서와 코드를 같은 변경에서 고친다」를 더하고, 파생 서비스 안내에 머리 블록 충돌 가능성을 적었다. 버린 대안: H1 제목 아래에 블록을 두는 안은 보기에는 낫지만 빼는 규칙이 파일마다 달라져 원문 복원이 기계적이지 않다. 「종류」 칸을 따로 두는 안은 폴더와 같은 정보를 두 번 쓰게 한다. 위험·한계: 「확인 안 함」 설계서 38개, 계획서 51개는 지금 유효한지 아무도 판정하지 않았다. 요약은 제목·목표 줄을 보고 쓴 것이라 본문을 끝까지 읽지 않았다. 납품 패키지 셋의 MANIFEST.sha256는 이제 맞지 않는다 (납품 당시 바이트의 해시이고, 블록을 빼면 다시 맞는다). 리뷰 폴더에는 아직 머리 블록을 달지 않았다. 검증: 머리 블록을 뺀 내용과 HEAD 원본 246개 일치, check-work-docs.py rc=0, --links docs·README.md·CLAUDE.md·AGENTS.md 깨진 링크 0.
6.9 KiB
기록 · 설계서 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 채택
- 작성일: 2026-07-28
- 요약: Redis 캐시에 cache-aside, 원본 보호, soft/hard TTL을 더하는 증분 설계다.
- 현재 정본:
docs/redis/support-matrix.md
Redis Cache Resilience Increment Design
Status: approved for implementation
Parent: 2026-07-26-redis-production-capability-design.md §§15, 16, 18
Goal
Complete one coherent production-facing cache increment on top of the current standalone R1 Redis runtime:
- a framework-free cache-aside policy in
application-core; - bounded local single-flight and source bulkhead protection;
- deterministic TTL jitter plus soft/hard expiry and stale lookup semantics in the Redis adapter.
This increment does not promote Redis beyond standalone cache R1. Distributed refresh leases, generation invalidation, rate limiting, owner-safe locks, idempotency, sessions, Sentinel/Cluster, TLS/ACL and fault qualification remain later increments.
Architecture boundary
application-coreowns lookup interpretation, source-result classification, cache-aside sequencing, stale-if-error, local coalescing and source admission policy.adapter:outbound:cache-redisowns physical TTL, envelope timestamps, deterministic jitter, serialization and Redis command outcomes.- The application contract contains no Redis/Lettuce/Lua/Spring type.
- Cache fallback never becomes unlimited source fallback. A miss, provider outage and waiter burst all pass through the same bounded source path.
Application contract
CacheSourceLoader<K,V> returns a typed SourceLoadOutcome<V>:
Loaded(value, sourceRevision);AuthoritativeAbsent(reason, sourceRevision);TransientFailure(SourceFailure);PermanentFailure(SourceFailure);Cancelled.
SourceFailure carries a bounded code and the original cause. It never serializes the cause message
into Redis or metric tags. An unclassified thrown exception is rethrown unchanged and is never
negative-cached or converted to stale success.
CacheResult<V> distinguishes:
- fresh cache hit;
- source-loaded value and its cache-record outcome;
- authoritative absence and its cache-record outcome;
- stale fallback after a classified transient source failure;
- source failure;
- bounded overload/timeout rejection;
- cancellation.
CacheAsidePolicy is immutable and constructed once per semantic region. It contains maximum
in-flight source keys, waiter limit per key, source concurrency, admission wait, load deadline and
whether transient source failure may serve stale.
Cache-aside state machine
Hit(FRESH)returns immediately.NegativeHitreturns immediately.Hit(STALE)retains the value and attempts a bounded refresh.Miss, anIncompatibleSchema(QUARANTINE_AND_RELOAD)carrying a usable opaque observation token, andUnavailableenter the same bounded source path.FAIL_FASTschema results and unobservable incompatible values are not overwritten.- A local single-flight elects one leader per semantic key. Waiters share the typed source outcome.
- The leader must acquire the source bulkhead before calling the loader.
- A miss records with
ONLY_IF_ABSENT. A stale or quarantined observation records withONLY_IF_OBSERVED, which atomically compares the digest captured by lookup before replacing the value. No lookup-then-delete sequence is used, so a concurrent writer is never deleted. - Only
AuthoritativeAbsentrecords a negative entry, using the same absent/observed condition as a positive source result. TransientFailuremay return the retained stale value when policy allows it.PermanentFailure, unclassified exceptions and cancellation are never hidden by negative cache.- Entries are removed from the flight map after success or failure. In-flight keys and waiters are bounded; waiting uses a finite deadline and preserves thread interruption.
The loader is synchronous and cancellation is cooperative. Its token exposes deadline/interruption; the executor bounds admission and waiter time but cannot safely terminate arbitrary source code.
Redis envelope and TTL policy
The positive envelope moves to version 2 and stores:
- source revision;
softExpiresAtepoch milliseconds;hardExpiresAtepoch milliseconds;- payload and SHA-256 integrity digest.
Negative envelopes store only the hard expiry. Lookup behavior is:
now < softExpiresAt:Hit(FRESH);softExpiresAt <= now < hardExpiresAt:Hit(STALE);now >= hardExpiresAt:Miss(EXPIRED);- negative
now < hardExpiresAt:NegativeHit; - expired negative:
Miss(EXPIRED).
Version 1 becomes an explicit retired schema result. Future versions and corrupt envelopes fail fast. Digest-valid retired/unknown envelopes carry an opaque observation token so an approved quarantine reload can compare-and-replace the exact observation. Structurally invalid current envelopes remain corrupt/fail-fast even when their digest is valid. Unknown envelopes remain typed incompatibility results and are not silently treated as misses. Envelope integrity is checked before the version byte is trusted.
The policy contains positive soft TTL, positive hard TTL, negative TTL, jitter ratio, minimum hard TTL and maximum value bytes. Construction rejects:
- non-positive or over-30-day TTLs;
- soft TTL greater than hard TTL;
- jitter outside
0.0..0.5; - minimum hard TTL greater than either configured hard TTL.
- configured hard TTL plus maximum positive jitter greater than 30 days.
Jitter is deterministic from the HMAC-derived physical key and the compiled policy revision. It
uses a symmetric bounded factor. The actual positive soft/hard TTLs use the same factor so ordering
is preserved. Physical Redis TTL equals the encoded hard expiry duration in the same SET.
Negative TTL is jittered independently and also respects the hard minimum.
Evidence
Tests must prove:
- fresh/negative hits do not call the source;
- concurrent same-key misses call the loader once;
- in-flight-key, waiter, bulkhead and deadline bounds;
- completion/failure cleanup and exception/interruption behavior;
- only authoritative absence is negative-cached;
- stale is served only after a classified transient failure;
- fresh/stale/expired boundaries with an injected
Clock; - deterministic bounded jitter and hard minimum;
- version 1/future/corrupt envelope behavior;
- Redis physical TTL matches the encoded hard expiry.
- observed replace reads only the trailing digest and never overwrites a concurrent writer;
- the exact 16MiB opt-in payload is accepted while 16MiB+1 is rejected before dispatch;
- mutation interruption restores the thread flag and maps to indeterminate certainty.
Focused checks run before the repository-wide architecture, dependency, env and public-path gates.