문제: 설계서·계획서·납품 패키지·증거·학습 문서와 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.4 KiB
기록 · 설계서 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.
- 상태: 구현됨
- 작성일: 2026-07-28
- 요약: Redis로 고를 수 있는 분산 rate-limit 알고리즘 셋을 제공하는 증분 설계다.
- 현재 정본:
docs/redis/support-matrix.md
Redis Distributed Rate-Limit Increment Design
Status: implemented as standalone R1
Parent: 2026-07-26-redis-production-capability-design.md §§19–21
Goal and readiness
Provide three selectable, bounded distributed rate-limit algorithms:
- fixed window;
- sliding-window counter;
- token bucket.
This increment is a standalone Redis R1 provider. It does not claim R2 topology/security/failover qualification and does not implement sliding log, GCRA, leaky bucket, evaluation dedup, hierarchical all-or-nothing policies or local emergency fallback.
Ownership
shared-contractowns the edge-enforcement semantic port and provider-neutral request, policy, decision and failure outcomes. Business quotas remain application use-case policy and do not use this port.adapter:outbound:cache-redisowns Redis keys, atomic Lua programs, structured reply parsing, failure certainty and the provider implementation.app-bootstrapowns the explicit provider/policy selection.- The existing inbound-web local limiter remains a compatibility path until a separate inbound migration. Its types do not cross into the Redis provider.
The rate-limit runtime does not reuse app.cache.redis, the cache connection or cache fail-open
decorators. Coordination has different failure and deployment semantics.
Shared semantic contract
EdgeRateLimitPort.evaluate(RateLimitRequest) accepts:
- bounded
policyId; - already pseudonymized/bounded
subjectDigest; - positive request cost;
- optional evaluation ID (rejected in this non-deduplicating revision);
- finite caller deadline.
RateLimitPolicy freezes policy ID/revision, one algorithm-specific parameter subtype, maximum
cost, cleanup grace, maximum clock regression and FAIL_CLOSED. Construction rejects mismatched
algorithm/parameters, arithmetic outside Lua's exact integer range and unsupported failure/dedup
claims.
The outcome is one of:
Evaluated(decision);Unavailable(policyId, retryAfter, category)for known pre-send/no-mutation failures and unsafe server clock;Indeterminate(policyId, retryAfter)for post-dispatch uncertain mutation;Incompatible(policyId, category)for state/program/reply mismatch.
RateLimitDecision includes allow/deny, limit, remaining, retry-after, reset-at, policy ID/revision,
GLOBAL_REDIS source and certainty. Fixed window and token bucket are CERTAIN;
sliding-window counter is APPROXIMATE_ALGORITHM.
Atomic programs
Each v1 program uses one versioned hash key and calls Redis TIME exactly once.
rate-fixed-window-v1.lua
rate-sliding-counter-v1.lua
rate-token-bucket-v1.lua
Every program returns exactly seven bounded scalar fields:
status, serverNowMillis, effectiveNowMillis,
limit, remaining, retryAfterMillis, resetAtMillis
Statuses are ALLOWED, DENIED, CLOCK_UNSAFE, STATE_INCOMPATIBLE, INVALID.
Unknown arity/status/numeric syntax/range is a compatibility failure, never allow/fail-open.
Common rules:
- Redis server time drives enforcement;
- small backward movement clamps to stored
lastObservedMillis; - regression beyond policy threshold returns
CLOCK_UNSAFEwithout consuming state; - policy/schema/algorithm mismatch returns
STATE_INCOMPATIBLE; - denied requests do not consume quota;
- state receives a finite TTL;
- all arithmetic stays within
2^53-1; - raw principal/IP/API-key/route never appears in the physical key.
The existing scalar Lua executor stays intact. A structured program path adds bounded MULTI reply
support and uses EVALSHA, falling back to the exact compiled source only on NOSCRIPT.
Algorithm rules
Fixed window stores window ID and consumed count. Allow increments only when
consumed + cost <= limit; retry/reset points to the current window end.
Sliding counter stores previous/current window IDs and counts, using scale 1_000_000 and
conservative ceiling weight. It reports approximate certainty and a bounded conservative retry.
Token bucket stores scaled tokens, last refill time and the sub-token division remainder. Refill is
therefore independent of evaluation frequency, uses quotient/remainder arithmetic without an
unsafe numerator + denominator - 1 intermediate, and saturates at capacity. Denial does not
subtract tokens; retry and full-reset use integer ceiling.
Physical key
The existing canonical builder is reused with:
capability=rate
region=<policyId>
kind=state
digest(policyId, policyRevision, algorithm, subjectDigest)
Policy revision appears in both digest input and stored state. A policy revision therefore rolls to a new key while old state expires naturally.
Runtime and composition
app.rate-limit is disabled by default. Enabling requires:
provider=redis;- one default policy and an exact policy definition;
- a dedicated Redis coordination endpoint and HMAC secret;
- finite command/admission bounds.
Only role=coordination and failure-policy=fail-closed are accepted in v1. Disabled mode creates
no connection, thread or semantic port. Cache Redis settings/beans are never an implicit fallback.
Evidence
Unit tests cover contract bounds, policy arithmetic, key privacy/revision, structured reply
validation, NOSCRIPT, boundary vectors, denial-no-consume, clock regression, pre/post-dispatch
failure certainty and disabled composition. The explicit Redis 7.4 service lane executes all three
programs, exact-boundary admission after a denied non-consuming request, excessive clock-regression
state immutability, TYPE response normalization, token refill-remainder carry, malformed hash-state
classification, cache NX, and observation-token compare-and-replace. Redis 7.4 is the minimum
version declared by the program manifests until a lower-version service lane exists. The caller
deadline is an admission precheck against the fixed command timeout; R1 does not claim per-command
dynamic timeout or hard cancellation after dispatch. Missing TLS/ACL, Sentinel/Cluster, failover and
persistence/eviction evidence keeps the provider at R1.