From c99b7a7f63a9c5a0c498ae53f0f96dfd39abfe38 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Wed, 4 Nov 2026 20:37:10 +0900 Subject: [PATCH] =?UTF-8?q?docs(contracts):=20=EB=91=90=20=EC=98=A4?= =?UTF-8?q?=EB=A5=98=20=EC=96=B4=ED=9C=98=EC=99=80=20commandRecovery?= =?UTF-8?q?=EB=A5=BC=20=EB=88=84=EA=B0=80=20=EC=9D=BD=EB=8A=94=EC=A7=80=20?= =?UTF-8?q?=ED=83=80=EC=9E=85=20=EC=98=86=EC=97=90=20=EC=A0=81=EB=8A=94?= =?UTF-8?q?=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 문제 - 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 --- docs/manual/reference/errors.md | 1 + src/contracts/errors.ts | 17 +++++++++++++++++ src/contracts/external-contract-runtime.ts | 9 +++++++++ 3 files changed, 27 insertions(+) diff --git a/docs/manual/reference/errors.md b/docs/manual/reference/errors.md index 8397a68f..02878ed2 100644 --- a/docs/manual/reference/errors.md +++ b/docs/manual/reference/errors.md @@ -97,6 +97,7 @@ lint / check:architecture / check:i18n → FE-GATE-002, FE-GATE-010 | `/: unknown authProfileId ` | V3 `frontend.authProfileId`가 없는 프로필 | V3 `frontend.authProfileId` | | `/: retry budget contradicts NEVER retry semantics` | `NEVER`인데 `retryBudget`가 0이 아니다 | V3 `frontend.retryBudget` | | `/: KEYED commands require a recovery descriptor` | `KEYED`인데 `commandRecovery`가 없다 | V3 `commandRecovery` | +| `/: is a read; its retrySemantics is SAFE or IDEMPOTENT, not <값>` | 읽기에 `KEYED`나 `NEVER`를 적었다 | V3 `retrySemantics`. 재시도를 막으려면 `frontend.retryBudget: 0` | | `/: command operations require a command effect descriptor` | 쓰기에 `commandEffect`가 없다 | V3 `commandEffect` | | `/: read operations carry no command descriptors` | GET에 `commandEffect`·`commandRecovery`를 적었다 | 둘 다 `null` | | `: package version must be exact SemVer` | 버전 범위(`^1.2.0`)나 형식 오류 | `_CONTRACT_PACKAGE.version` | diff --git a/src/contracts/errors.ts b/src/contracts/errors.ts index b559cc81..8e8b08af 100644 --- a/src/contracts/errors.ts +++ b/src/contracts/errors.ts @@ -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; diff --git a/src/contracts/external-contract-runtime.ts b/src/contracts/external-contract-runtime.ts index 2250fb90..b927e3dd 100644 --- a/src/contracts/external-contract-runtime.ts +++ b/src/contracts/external-contract-runtime.ts @@ -127,6 +127,15 @@ export function mappingViolation(code: string): MappingResult { }); } +/** + * 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;