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;