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:
@@ -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` |
|
||||
|
||||
@@ -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;
|
||||
|
||||
Reference in New Issue
Block a user