Merge remote-tracking branch 'origin/main' into fix/r9-form-and-primitives

This commit is contained in:
DongHyeonka
2026-11-13 08:45:29 +09:00
190 changed files with 7962 additions and 1109 deletions
+25 -3
View File
@@ -311,6 +311,7 @@ export function createFeatureHttpBinding<
contract.contract.responseEnvelope === "ENVELOPE_V1",
),
outcome,
contract.contract.responseEnvelope === "ENVELOPE_V1",
);
},
});
@@ -345,10 +346,18 @@ function envelopeProblemMapping(
problem: unknown,
status: number,
): FeatureHttpProblemMapping | undefined {
const code = envelopeCode(problem);
if (code === undefined) return undefined;
const { details } = problem as Readonly<Record<string, unknown>>;
return envelopeFailureReading(status, { code, details });
}
/** The backend `error.code` of an Envelope problem, when it is well formed. */
function envelopeCode(problem: unknown): string | undefined {
if (!problem || typeof problem !== "object") return undefined;
const { code, details } = problem as Readonly<Record<string, unknown>>;
const { code } = problem as Readonly<Record<string, unknown>>;
return typeof code === "string" && /^[A-Z0-9_]{1,64}$/u.test(code)
? envelopeFailureReading(status, { code, details })
? code
: undefined;
}
@@ -358,6 +367,8 @@ function envelopeProblemMapping(
* 0929/03-04. Without an echo (timeout, lost connection, a gateway that drops
* the header) it is the id the request carried.
* 1103/03-06. A failure Envelope's `meta.traceId` becomes `traceId`.
* 1112/01-06. An Envelope operation's problem keeps the backend's own code as
* `backendCode`, whatever code the feature mapped it to.
*/
function projectExecutionOutcome<WireOutput, Problem, Value>(
operationId: string,
@@ -372,8 +383,15 @@ function projectExecutionOutcome<WireOutput, Problem, Value>(
) => FeatureHttpProblemMapping | undefined)
| undefined,
outcome: HttpExecutionOutcome<WireOutput, Problem>,
enveloped: boolean,
): Result<Value, AppFailure> {
const projected = projectOutcome(operationId, mapSuccess, mapProblem, outcome);
const projected = projectOutcome(
operationId,
mapSuccess,
mapProblem,
outcome,
enveloped,
);
const metadata = "metadata" in outcome ? outcome.metadata : undefined;
const requestId = metadata?.correlationReference ?? outcome.sentRequestId;
const traceId = metadata?.traceReference;
@@ -402,6 +420,7 @@ function projectOutcome<WireOutput, Problem, Value>(
) => FeatureHttpProblemMapping | undefined)
| undefined,
outcome: HttpExecutionOutcome<WireOutput, Problem>,
enveloped: boolean,
): Result<Value, AppFailure> {
// A throwing feature mapper is a mapping defect, not a transport failure: it
// must not reject and lose the effect the server already confirmed.
@@ -444,11 +463,13 @@ function projectOutcome<WireOutput, Problem, Value>(
} catch {
return mapperThrew(outcome.effect, outcome.metadata.status);
}
const backendCode = enveloped ? envelopeCode(outcome.problem) : undefined;
return failure(
mapped?.kind ?? kindForStatus(outcome.metadata.status),
operationId,
mapped?.code ?? "CONTRACT_PROBLEM",
{
...(backendCode === undefined ? {} : { backendCode }),
httpStatus: outcome.metadata.status,
// 백엔드 1101/02-01. A resend of an unknown answer waits on it.
...(outcome.metadata.retryAfterMs === undefined
@@ -578,6 +599,7 @@ function failure(
operationId: string,
code: string,
details: Readonly<{
backendCode?: string;
httpStatus?: number;
retryAfterMs?: number;
effect?: FailureEffectCertainty;
@@ -117,7 +117,8 @@ export type BoundedPollCoordinatorDependencies<
* (the V3 executor returns a rejected fetch as NETWORK_FAILURE). A throw,
* like a result of the wrong shape, ends the lease with PROTOCOL_MISMATCH
* and is not retried: it is a composition defect, not a server outage.
* Design 9.2 maps each V3 executor outcome to a result.
* docs/architecture/optional-adapter-recipes.md 「poll attempt 결과 대응」
* maps each V3 executor outcome to a result.
*/
execute(input: Readonly<{
operationId: string;
+2 -2
View File
@@ -1,6 +1,6 @@
# AGENTS.md — `src/contracts` (공유 어휘와 레지스트리)
여러 계층, worker, 빌드·릴리스 스크립트가 함께 읽는 타입·스키마·레지스트리다. 공유 타입을 어디 둘지는 `docs/architecture/contract-ownership.md` 「Decision rule」이다.
여러 계층, worker, 빌드·릴리스 스크립트가 함께 읽는 타입·스키마·레지스트리다. 공유 타입을 어디 둘지는 `docs/architecture/contract-ownership.md` 「판단 규칙」이다.
## 지킬 것
@@ -13,5 +13,5 @@
- 판정은 `check:architecture`(FE-GATE-010)다. 편집 직후 훅(N3)이 이 폴더 파일의 import를 같은 규칙에 대 본다.
- `check:registries`(FE-GATE-010 안), `test:runtime-schema`(FE-GATE-004)
- 짝 백엔드 계약 pin `config/contracts/backend-contract-pin.json`과 대조 테스트(FE-GATE-007)
- 짝 백엔드 계약 pin `config/contracts/backend-contract-pin.json`과 대조 테스트(FE-GATE-005의 `tests/unit/backend-contract-pin.test.ts`·`backend-contract-pin-document.test.ts`, FE-GATE-007의 `tests/integration/fileserver-upload.test.ts`)
- 돌리는 곳은 desktop이다(`scripts/verify.sh`). 테스트는 `tests/runtime-schema`, `tests/unit`에 둔다(`.claude/rules/tests.md`).
+28 -3
View File
@@ -130,6 +130,13 @@ export type FailureEffectCertainty =
export type AppFailure = Readonly<{
kind: FailureKind;
code: string;
/**
* 1112/01-06. The code the paired backend's Envelope carried, as it came:
* a feature's `mapProblem` may change `code`, never this. Only the HTTP
* binding sets it, for an `ENVELOPE_V1` operation's problem; elsewhere it
* is absent.
*/
backendCode?: string;
httpStatus?: number;
/**
* Whether sending the same operation again is safe as far as this failure
@@ -164,6 +171,7 @@ export type ApiFailure = AppFailure;
export type FailureDetails = Readonly<{
code?: string;
backendCode?: string;
httpStatus?: number;
requestId?: string;
traceId?: string;
@@ -183,6 +191,9 @@ export function createFailure(
return Object.freeze({
kind: definition.kind,
code: typeof details.code === "string" ? details.code : definition.kind,
...(typeof details.backendCode === "string"
? { backendCode: details.backendCode }
: {}),
retryable:
details.effect === "MAYBE_APPLIED" ||
details.effect === "APPLIED_CONFIRMED"
@@ -259,6 +270,16 @@ export const REFUSALS_OF_EVERY_ATTEMPT: Readonly<Record<string, number>> =
IDEMPOTENCY_KEY_INVALID: 400,
});
/**
* 1112/01-03. The request did not fail: its caller aborted it
* (`REQUEST_ABORTED`) or a scope fence ended it (`SCOPE_GENERATION_CHANGED`,
* sign-out or account switch). Telemetry and terminal error screens do not
* count it (testing strategy 7.1절).
*/
export function isAbortFailure(failure: AppFailure): boolean {
return failure.kind === "REQUEST_ABORTED" || failure.kind === "SCOPE_GENERATION_CHANGED";
}
/**
* 1106/03-01 (D10 supplement and its second fix). A `NOT_APPLIED` refusal
* the same request gets on every attempt: a row above, code and status
@@ -268,13 +289,17 @@ export const REFUSALS_OF_EVERY_ATTEMPT: Readonly<Record<string, number>> =
* 403, 503 RATE_LIMIT_*), a code a feature declared refused before its
* write (it may be a rule on changing state), any other code, and
* `NOT_STARTED`. The kind is not read: a feature's `mapProblem` sets it, and
* it maps its own codes, or every 422, to `VALIDATION_REJECTED`.
* it maps its own codes, or every 422, to `VALIDATION_REJECTED`. 1112/01-06.
* Nor is `code`, for the same reason: the answer is `backendCode`, the code
* the backend's Envelope carried. A failure without it is not settled.
*/
export function isRefusedOnEveryAttempt(failure: AppFailure): boolean {
if (failure.effect !== "NOT_APPLIED") return false;
const code = failure.backendCode;
return (
Object.hasOwn(REFUSALS_OF_EVERY_ATTEMPT, failure.code) &&
REFUSALS_OF_EVERY_ATTEMPT[failure.code] === failure.httpStatus
code !== undefined &&
Object.hasOwn(REFUSALS_OF_EVERY_ATTEMPT, code) &&
REFUSALS_OF_EVERY_ATTEMPT[code] === failure.httpStatus
);
}
@@ -53,11 +53,17 @@ export type ApplicationResult<Value> = Result<Value>;
class ApplicationQueryError extends Error {
readonly failure: AppFailure;
/**
* 1112/01-04. What the cache diagnostics record (`safeErrorKind` reads
* `kind` first): the failure's kind, not one name for every failure.
*/
readonly kind: AppFailure["kind"];
constructor(failure: AppFailure) {
super(failure.kind);
this.name = "ApplicationQueryError";
this.failure = failure;
this.kind = failure.kind;
}
}
@@ -100,7 +106,6 @@ export function useApplicationQuery<Value>(
"definitionId" in options ? options.definitionId : "APPLICATION_QUERY";
const invalidation =
"invalidation" in options ? options.invalidation : undefined;
const [staleFailure, setStaleFailure] = useState(false);
useEffect(() => {
identity?.acquire();
return () => identity?.release();
@@ -170,9 +175,10 @@ export function useApplicationQuery<Value>(
throw new DOMException("Query cancelled", "AbortError");
}
if (error instanceof ApplicationQueryError) throw error;
// 1112/01-04. The definition it came from, as the other failures here.
throw new ApplicationQueryError(
normalizeUnknownFailure(error, {
operationId: "APPLICATION_QUERY",
operationId: queryDefinitionId,
}),
);
} finally {
@@ -181,17 +187,13 @@ export function useApplicationQuery<Value>(
},
});
const hasData = query.data !== undefined && query.data !== null;
useEffect(() => {
if (query.isError && hasData) {
setStaleFailure(true);
} else if (query.isSuccess && !query.isFetching) {
setStaleFailure(false);
}
}, [hasData, query.isError, query.isFetching, query.isSuccess]);
// 1112/01-05. Read while rendering: the data is stale because the last
// fetch failed, and no fetch runs now. A retry that is running shows as
// refreshing; copied into state by an effect, the old failure came back
// over the retry's reset.
const staleFailure = query.isError && hasData && !query.isFetching;
const retry = useCallback(async () => {
setStaleFailure(false);
await query.refetch({ cancelRefetch: false });
}, [query]);
@@ -375,6 +377,12 @@ export function useApplicationMutation<Input, Value>(
"definitionId" in options
? options.definitionId ?? "LEGACY_MUTATION"
: "LEGACY_MUTATION";
// 1112/01-04. An unexpected throw names the mutation definition it came
// from; a legacy mutation without one keeps the generic name.
const failureOperationId =
"definitionId" in options && options.definitionId
? options.definitionId
: "APPLICATION_MUTATION";
const definitionVersion =
"definitionVersion" in options ? options.definitionVersion : 0;
const duplicatePolicy =
@@ -708,7 +716,7 @@ export function useApplicationMutation<Input, Value>(
error instanceof ApplicationQueryError
? error.failure
: normalizeUnknownFailure(error, {
operationId: "APPLICATION_MUTATION",
operationId: failureOperationId,
});
const failure = mutationFailureWithEffect(reportedFailure);
switch (failure.effect) {
@@ -765,7 +773,7 @@ export function useApplicationMutation<Input, Value>(
.catch((error: unknown) => {
const failure = withFailureEffect(
normalizeUnknownFailure(error, {
operationId: "APPLICATION_MUTATION",
operationId: failureOperationId,
}),
"NOT_STARTED",
);
@@ -801,6 +809,7 @@ export function useApplicationMutation<Input, Value>(
queryClient,
definitionId,
duplicatePolicy,
failureOperationId,
mutationIntentFactory,
mutationOperationId,
requiresIdempotencyKey,