docs(contracts): 두 오류 어휘와 commandRecovery를 누가 읽는지 타입 옆에 적는다

문제
- AppFailure(닫힌 kind, retryable, action)와 AppError(열린 owner.reason
  kind, retryability)의 관계가 타입 옆에 없다. AppFailure.retryable과
  action "retry"는 뜻이 다른데(CONFLICT는 retryable false, action retry)
  설명이 없어 모순으로 읽고 "고치는" 변경이 나올 수 있다(1101/07-05).
- CommandRecoveryDescriptor는 KEYED 쓰기에 필수지만 HTTP 실행기는 읽지
  않는다. 결과 불명 쓰기를 기능 gateway가 수습한다는 것은 설계서 4.4절에만
  있다(1101/07-07).
- 07-01(c)에서 더한 읽기 retrySemantics 거절 문구가 errors.md reason 표에
  없다.

고른 방법
주석만 더한다. AppFailure 위에 어느 경계에서 어느 어휘를 쓰는지와, 둘 다
재시도 동작을 바꾸지 않는다는 것. retryable 칸에 "src에서 읽는 곳이 없고,
화면 버튼은 action"이라는 것. CommandRecoveryDescriptor 위에 실행기가 읽지
않고 기능 gateway가 재전송·조회를 정한다는 것. errors.md reason 표에 한 행.

버린 대안
- retryable을 autoRetryable 같은 이름으로 바꾸기: 다운스트림 import를 깨는
  비용에 비해 얻는 것이 작다.

위험·한계
- 동작은 바뀌지 않는다. "src에서 읽는 곳이 없다"는 grep으로 확인한 지금
  상태다.

검증
- grep: src/presentation·bootstrap·features·application에서
  AppFailure.retryable을 읽는 곳 0. commandRecovery를 읽는 곳은 플랫폼 개요
  화면뿐.
- eslint, verify:documentation 통과.

Refs: docs/reviews/2026-11-03-maturity-review/07-contracts.md 1101/07-05, 1101/07-07
This commit is contained in:
DongHyeonka
2026-11-04 20:38:14 +09:00
parent 64f19ac665
commit c99b7a7f63
3 changed files with 27 additions and 0 deletions
+1
View File
@@ -97,6 +97,7 @@ lint / check:architecture / check:i18n → FE-GATE-002, FE-GATE-010
| `<id>/<operationId>: unknown authProfileId <profile>` | V3 `frontend.authProfileId`가 없는 프로필 | V3 `frontend.authProfileId` |
| `<id>/<operationId>: retry budget contradicts NEVER retry semantics` | `NEVER`인데 `retryBudget`가 0이 아니다 | V3 `frontend.retryBudget` |
| `<id>/<operationId>: KEYED commands require a recovery descriptor` | `KEYED`인데 `commandRecovery`가 없다 | V3 `commandRecovery` |
| `<id>/<operationId>: <GET·HEAD> is a read; its retrySemantics is SAFE or IDEMPOTENT, not <값>` | 읽기에 `KEYED`나 `NEVER`를 적었다 | V3 `retrySemantics`. 재시도를 막으려면 `frontend.retryBudget: 0` |
| `<id>/<operationId>: command operations require a command effect descriptor` | 쓰기에 `commandEffect`가 없다 | V3 `commandEffect` |
| `<id>/<operationId>: read operations carry no command descriptors` | GET에 `commandEffect`·`commandRecovery`를 적었다 | 둘 다 `null` |
| `<id>: package version must be exact SemVer` | 버전 범위(`^1.2.0`)나 형식 오류 | `<BASE>_CONTRACT_PACKAGE.version` |
+17
View File
@@ -118,10 +118,27 @@ export type FailureEffectCertainty =
| "APPLIED_CONFIRMED"
| "MAYBE_APPLIED";
/**
* 1101/07-05. The failure that crosses an application input boundary: a
* gateway result, a query or mutation error. Its `kind` is the closed set
* above. `AppError` (`src/platform/errors/app-error.ts`) is the other
* vocabulary: an open `owner.reason` kind a feature uses inside its own
* domain, mapped from an `AppFailure` where the feature needs it. Neither
* changes how a request is retried; the HTTP executor follows the
* operation's `retrySemantics` and `retryBudget`.
*/
export type AppFailure = Readonly<{
kind: FailureKind;
code: string;
httpStatus?: number;
/**
* Whether sending the same operation again is safe as far as this failure
* tells: the registry default, forced `false` once a write may have
* applied. Nothing in src reads it today. What the screen offers is
* `action`: `"retry"` shows a retry button even when this is `false`
* (`CONFLICT`, `QUERY_CACHE_FAILURE`): the user, not the runtime, sends
* again.
*/
retryable: boolean;
operationId: string;
attemptCount: number;
@@ -127,6 +127,15 @@ export function mappingViolation(code: string): MappingResult<never> {
});
}
/**
* 1101/07-07. How the package says a write whose result is unknown can be
* settled: resend with the same idempotency key, or read the operation back
* through `inspectOperationId`. Composition requires one on a KEYED command,
* and FE-REG-API records it. The HTTP executor does not read it: a write
* that ends `MAYBE_APPLIED` comes back to the feature, and the feature's
* gateway decides whether to resend or inspect (closed-deep-design.md
* §4.4 under docs/architecture).
*/
export type CommandRecoveryDescriptor = Readonly<{
mode: "IDEMPOTENCY_REPLAY" | "INSPECT_OPERATION";
operationIdentityField: string;