- P14(W2): inbox archive 종단 상태 보존, GraphQL platform context 누락 경고, fileserver 전이·quota·진행 중 upload 삭제, 알림 profile 소실 재시도·lease fencing·body 읽기 기한, Mongo bulk write concern, Dynamic Target cross-origin 헤더(결정 23), S3 profile CONDITIONAL_RETIREMENT 주장 거부, sample 포스터 abort·reconcile 경합(결정 22) - P17(W3): gRPC 18→9 leaf(registry), .proto는 protobuf Gradle 플러그인 + Buf CI(결정 18), hyeonworks→caskeleton, 인증 식별자 Context 전달, 한계값 정합 검사, P5-new-2·3 결함 수정 - 오케스트레이터: 현황표 적용(완료 395·남음 359), 새 결함 행 9개, capability-status 「제거된 코드」 17행, 계획서 Wave 3 상세 Task, by_area.py NEW-15+ KeyError 수정 검증: ./gradlew check architectureCheck verifyDependencyLocks --continue 통과(597 task), ./gradlew -p optional-platforms ci 통과, CapabilityStatusDocumentTest 통과 Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
51 lines
2.8 KiB
Markdown
51 lines
2.8 KiB
Markdown
# ADR-GRPC-003: Transport, business and stream evidence are three axes, and none implies another
|
|
|
|
- Status: accepted
|
|
- Date: 2026-08-30
|
|
- Scope: `:grpc:grpc-core-api`, `:grpc:grpc-runtime` (was `grpc-policy`), `:grpc:grpc-testkit`
|
|
|
|
## Context
|
|
|
|
A failed RPC produces a status code, and a status code is not an answer to the question the caller
|
|
actually has. `DEADLINE_EXCEEDED` on a mutation does not say whether the mutation happened;
|
|
`UNAVAILABLE` after the request was sent does not say the server never saw it; response headers
|
|
arriving does not say a transaction committed.
|
|
|
|
Every one of those is a place where a plausible inference produces a duplicate write or a lost one,
|
|
and none of them is visible in a test that only exercises the happy path.
|
|
|
|
## Decision
|
|
|
|
Model what happened as three independent axes, and refuse the inferences between them.
|
|
|
|
`GrpcTransportEvidence` records what the client observed on the wire, and distinguishes `NOT_SENT` —
|
|
the client watched its own send fail — from `UNOBSERVED`, which is every other case where nothing is
|
|
known. `GrpcBusinessEvidence` records what the application confirmed, with `COMMIT_UNKNOWN` as a real
|
|
state rather than a placeholder. `GrpcStreamEvidence` is a sealed hierarchy whose non-empty cases all
|
|
carry a position, because "partial" without a last sequence can be neither resumed nor reconciled.
|
|
|
|
`GrpcExecutionEvidence` holds all three and rejects combinations nobody could have observed: a unary
|
|
call with stream evidence, or a request the client watched fail to send that nonetheless carries
|
|
business evidence. Promoting response headers to a confirmed commit is possible only by editing
|
|
`withResponseHeadersSeen`, which is one method rather than a plausible line in an interceptor.
|
|
|
|
`GrpcCompletionOutcome.forMutation` derives what a caller may conclude, and defaults
|
|
`DEADLINE_EXCEEDED` and post-send `UNAVAILABLE` on a mutation to `COMPLETION_UNKNOWN`.
|
|
|
|
The same types are used by the failure model and by the observation convention, so an incident has
|
|
one account of a call rather than two.
|
|
|
|
## Consequences
|
|
|
|
**A whole class of retry bug becomes unrepresentable.** `GrpcRetryEligibility` reads all three axes
|
|
plus the idempotency profile; a caller cannot reach "retry" from a status alone because the status
|
|
alone is not an input.
|
|
|
|
**The fault lane has something to check.** `GrpcTransportEvidenceClassifier` turns a client's
|
|
observations into evidence and refuses to infer `NOT_SENT` from an unobserved state — and the lane
|
|
exercises it against a real connection dropped mid-call, not against a mock.
|
|
|
|
**Callers must handle a third outcome.** `COMPLETION_UNKNOWN` is not a failure and not a success, and
|
|
a caller that treats it as either is wrong. `GrpcOperationStatusQuery` and `GrpcCompletionReconciler`
|
|
exist so that resolving it is a supported path rather than an exercise for the caller.
|