설계: docs/superpowers/specs/2026-09-25-capability-module-packaging-design.md
계획/진행 기록: docs/superpowers/plans/2026-09-25-capability-module-packaging.md
- Wave 0: 규칙 고정(AGENTS.md capability 완료 기준·테스트 규칙) + 차단 결함 7건
(compose overlay 검사, redis-sdk CI job, 적용된 V9/V13 원복 + V16, @EnableScheduling,
messaging bridge 순서, prod 에러 상세 validator, sample loggers read-only)
- Wave 1: 데이터·보안 Critical 10건 (durable operation 25P02, operation 유스케이스 이동,
outbox 재인코딩, Kafka TLS/SASL, 알림 트랜잭션, SNS 서명, tus checksum, GraphQL fragment,
Redis lane, gRPC FAILED_TERMINAL)
- Wave 2: 리팩터링 잔재·실험용 자리 삭제, outbox v1 fencing(V17), 멱등성 V2 정본화
- Wave 3: 라이브러리형 코드 정리(동작하지 않는 설정·인터페이스·gate 제거, web-advanced 분리)
- Wave 4: capability 11개를 "있으면 켜짐" 모듈로 포장, 끄는 장치 제거, 기본 조립 web-only,
qualificationBootJar 분리
- Wave 5: 빌드 로직 축소(17.2k -> 10.8k줄), sample 테스트 컨벤션 적용
삭제한 코드는 docs/capability-status.md "제거된 코드" 표에 복구 커밋(208077fd)과 함께 기록.
Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
3.7 KiB
ADR-WS-002: Resume and cluster state are caches, and are treated as caches
- Status: Superseded 2026-09-25 —
advanced.resume,advanced.clusterandadvanced.presencewere removed: nothing assembled them (seedocs/capability-status.md). - Date: 2026-08-25
- Scope:
adapter:inbound:websocket—advanced.resume,advanced.cluster,advanced.presence
Context
Advanced Tasks 2–8 add three things that all look like state and are not: a resume token that says where a client got to, a cluster index that says which node holds a session, and a presence summary derived from that index.
Each is a statement about the past. The resume token was minted before the disconnect; the index entry was written by a node that may since have died; presence is a read of the index and inherits everything wrong with it. The failure this ADR exists to prevent is treating any of them as current fact, because each reads as one at the call site.
Decision
Resume is bounded by what the replay store actually holds, not by what the token claims.
ResumeCoordinator consults ReplayAvailability before honouring a position. A token that names a
position the store has evicted produces a resynchronise, not a gap-filled stream. The alternative —
trusting the token — silently delivers a stream with a hole in it, which is worse than an explicit
resynchronise because the client believes it is complete.
Cluster index entries carry an observation time and are checked against it on every read.
ExternalSessionSummary.staleAt exists so that "the index says edge-2" cannot be used without also
answering "as of when". An entry whose node stopped reporting is not evidence that the node holds
the session.
Durable fan-out is deduplicated by stream position, not by message id. At-least-once is the
contract, so redelivery is normal operation: a redeploy, a slow consumer or a broker rebalance all
produce it. FanoutDeduplicator keys on (stream, position) and advances a high-water mark under
compute, so two consumer threads cannot both deliver the same position.
Presence has four states, not two. OFFLINE is a reported fact; STALE is the absence of one.
Collapsing them reports every user as disconnected during a Redis partition, when what happened is
that the index went dark and the connections are fine.
Nothing security-relevant may depend on presence. An attacker who can make a node stop reporting can move the platform's belief about who is present. Presence answers "show a green dot".
Consequences
- A resume that cannot be honoured is visible to the client as a resynchronise. Clients must implement one; there is no mode in which the platform silently pretends.
- Every read of the cluster index needs a clock. This is deliberate friction.
PresenceSummary.classifyrefuses an idle window at or past the stale window, because otherwiseIDLEis unreachable and the caller believes it has a four-state model when it has three.- Fan-out envelopes carry a bounded reference and the catalog-encoded document, never a business object. A rolling deploy has two versions of the code reading the same envelope.
Alternatives considered
- Trust the resume token. Rejected: it makes a gap indistinguishable from a complete stream.
- Deduplicate by message id. Rejected: a broker that redelivers may re-mint ids, and a producer that retries certainly does. Position is the property the ordering actually has.
- A single
onlineboolean. Rejected for the partition case above. - Write presence separately from the session index. Rejected: two sources of truth for "who is connected" drift, and the drift is invisible — both look plausible and nothing reconciles them.