fix(reference): 처리 중 409를 결과 불명으로 보고 같은 키를 유지한다 (0929/03-01)

문제
참조 기능의 생성 분류기가 모든 409를 NOT_APPLIED로 판정한다
(reference-feature-contract-contribution.ts:42-44). 결과 불명 쓰기를 같은
멱등 키로 다시 보냈을 때 첫 요청이 아직 처리 중이면 짝 백엔드 템플릿은
409 IDEMPOTENT_IN_FLIGHT를 준다. 그러면 코디네이터가 intent를 정리하고
conflict를 세우고(application-query.ts:584-589), 폼은 결과 불명 기록을
지운다(use-app-form.ts:227-230). 화면이 "충돌"로 바뀌고 저장 버튼이 다시
열려 다음 저장이 새 키로 나간다. 첫 요청이 끝나면 같은 리소스가 두 번
생긴다(키 [K, K, K']).

고른 방법
분류기가 409를 problem code로 나눈다. fixture가 선언한 충돌 code
(CREATE_NOT_APPLIED_CONFLICT_CODES, 지금은 MSW fixture가 내는 "CONFLICT"
하나)만 NOT_APPLIED다. IDEMPOTENT_IN_FLIGHT, code 없는 409, 모르는 code의
409는 MAYBE_APPLIED다. 결과 불명이 유지되므로 코디네이터가 intent를 들고
있고 다음 전송이 같은 키를 쓴다. 400·422 판정은 바꾸지 않았다.
시나리오 카탈로그에 in-flight-409를 더해 "처리 중 409 -> 결과 불명"과
"충돌 409 -> 적용 안 됨"(기존 conflict-409)을 둘 다 고정했다.

버린 대안
- IDEMPOTENT_IN_FLIGHT 하나만 MAYBE_APPLIED로 빼기: 모르는 409가 계속
  NOT_APPLIED다. 백엔드가 처리 중 code를 바꾸거나 다른 백엔드를 붙이면
  같은 결함이 조용히 돌아온다. "모르는 409는 안전한 쪽" 결정과 어긋난다.
- 플랫폼 방어(같은 intent의 재전송이 NOT_APPLIED를 받아도
  APPLIED_CONFIRMED 전까지 키 결합을 유지, 리뷰 03 5절 A의 (b)): 분류기가
  틀려도 막지만 application-query의 admission 수명 규칙을 바꾸는 구조
  변경이다. 이번 범위를 넘어 뺐다.
- 계약 문서의 409 IDEMPOTENCY_KEY_REUSED(같은 키·다른 지문)를 NOT_APPLIED
  목록에 넣기: 프론트는 canonical 입력이 같을 때만 같은 키를 쓴다. 이
  응답은 서버와 클라이언트의 지문 기준이 어긋났다는 뜻이고 같은 키의 앞선
  요청은 적용됐을 수 있다. NOT_APPLIED로 풀면 다음 저장이 새 키로 중복을
  만든다. 그래서 모르는 409와 같이 MAYBE_APPLIED로 둔다.

위험·한계
- 백엔드 계약(이 repo에서 끝낼 수 없음): backend-api-and-server-state-
  contract.md §6은 같은 키 동시 재전송을 "bounded IN_PROGRESS 결과"라고만
  적고 status·code를 정하지 않는다(:299-300). 409 + IDEMPOTENT_IN_FLIGHT로
  고정하고, 진짜 충돌을 뜻하는 409 code 목록을 계약에 적어야 한다. 짝
  백엔드 템플릿(01a8a2a, 읽기만 함)은 OperationalError.IDEMPOTENT_IN_FLIGHT
  (CONFLICT, 409, retryable=false)를 쓴다. 승인자: 템플릿 소유자, 백엔드
  템플릿 소유자.
- problem 형태: 짝 백엔드 web 어댑터는 실패를 problem+json이 아니라
  Envelope {success:false, error:{code,...}}로 보낸다(ErrorResponseFactory).
  참조 fixture는 최상위 code가 있는 problem 형태다. 그 Envelope가 오면
  referenceProblemSchema 검증이 실패해 MAYBE_APPLIED가 되므로 안전 쪽이지만
  code 분류는 닿지 않는다. 제품 계약 패키지가 code 위치를 정해야 한다.
- 화면 종류는 여전히 mapProblem이 409 전부를 CONFLICT로 만든다
  (reference-http-gateway.ts:38). 폼이 effect를 먼저 보므로 결과 불명이
  이기지만, 효과와 화면 종류가 두 함수에 나뉜 문제(03-04)는 그대로다.
  "처리 중" 전용 문구는 없고 일반 결과 불명 문구를 보인다.
- 다운스트림 tech-log 분류기는 4xx 전체를 NOT_APPLIED로 쓴다(지난 라운드
  확인). 동기화 때 같은 수정이 필요하다.
- 카탈로그 실행 수가 54 -> 57이 된다. 문서 세 곳의 "19개"와
  run-http-scenario-evidence.ts 출력 문구를 맞췄다.
- 초기 JS gzip +37 B(203,507 -> 203,544, 예산 204,800). 같은 build-frontend로
  두 번 빌드해 gzipSync로 쟀다. 예산은 바꾸지 않았다.

검증
- RED(수정 전): reference-production-vertical "keeps the key when the
  resend meets the first attempt still in flight" 실패, 키 [K, K, K'].
  분류 단위 테스트 3건 "expected 'NOT_APPLIED' to be 'MAYBE_APPLIED'"
  (IDEMPOTENT_IN_FLIGHT, 모르는 code, code 없음).
  카탈로그 CREATE_REFERENCE_RESOURCE::in-flight-409 불일치.
- GREEN: 같은 세 파일 23/23 통과.
- 회귀: run-vitest tests/features tests/component tests/contract
  tests/integration tests/unit(pnpm을 띄우는 security-followup-archive
  제외) 233 files / 2817 tests 통과. tests/runtime-schema 56 통과.
  tsc app/test/node rc=0. 바꾼 파일 eslint rc=0. check-adapter-inventory
  PASS. verify-documentation-readiness PASS_SCOPED.
- 미실행: check:architecture(pnpm 필요). depcruise 직접 실행은 TS 7을
  읽지 못해 0 modules라 사실상 미검증. src 변경은 import를 더하지 않는다.
  check:ci 미실행.

Refs: docs/reviews/2026-11-01-maturity-review/03-adapters-http-state.md
This commit is contained in:
DongHyeonka
2026-11-01 19:09:47 +09:00
parent 49d8675f97
commit 112c870fe3
10 changed files with 174 additions and 14 deletions
@@ -88,7 +88,7 @@ P0/P1 acceptance와 P2 recipe 기본값은 `LOCAL_TEMPLATE_READY`다. 다만 실
| logging/diagnostics | 준비됨 | 별도 `DiagnosticsPort`, 8-event registry, allowlist, bounded/no-op adapter와 production producer | 실제 프로젝트의 remote sink는 port 뒤에서 선택 |
| telemetry | 준비됨/프로젝트 선택 | 5-event registry, bounded queue, redaction/value policy, boot·HTTP·render·release·drop producer | analytics/RUM/error vendor와 consent는 프로젝트에서 선택 |
| 비동기 상태 불변식 | 준비됨 | 배타적 typed overlay, stale latch, 실제 retry/conflict action | reference 화면에서 전체 상태 전시 |
| 단위·통합·E2E | 준비됨 | source/test strict typecheck, shared MSW 19개 scenario, 실제 bootstrap, built-dist 3엔진·compact E2E | 제품별 critical flow를 같은 catalog/gate에 추가 |
| 단위·통합·E2E | 준비됨 | source/test strict typecheck, shared MSW 20개 scenario, 실제 bootstrap, built-dist 3엔진·compact E2E | 제품별 critical flow를 같은 catalog/gate에 추가 |
| UI 회귀 검증 | 준비됨 | dev-only Storybook interaction/axe와 pinned Chromium visual baseline 4종 | cloud review와 다중 OS/device는 프로젝트 선택 |
| 샘플 제거 | 준비됨 | feature/catalog/test 제거 후 type/architecture/registry/test/home/build 9단계 검증 | 새 contribution도 같은 제거 gate에 포함 |
| registry·compatibility 집행 | 준비됨 | 10개 registry type/reference/consumer/orphan, 승인 digest와 actual semantic diff, breaking evidence | public 계약 변경 시 baseline review 유지 |
@@ -852,7 +852,7 @@ owner와 만료 시한이 있는 quarantine만 허용한다.
`behavior-change`, 제거/type/path/contract 변경은 `breaking`으로 계산한다.
breaking에는 version, migration, compatibility window, rollback과 owner를
요구하며 digest 변조와 누락 fixture가 실제로 실패한다.
- API operation별 19개 shared MSW scenario catalog와 strict unhandled-request
- API operation별 20개 shared MSW scenario catalog와 strict unhandled-request
server를 제공하고 reference vertical integration이 공통 envelope/handler를
사용한다.
- 기본 Playwright는 `build` + `preview`의 실제 `dist`를 Chromium, Firefox,
@@ -141,7 +141,7 @@ rasterization과 실제 device farm은 프로젝트가 요구할 때 연결한
#### Shared MSW와 결정성
operation별 success/empty/slow/network/timeout/content/envelope/schema/auth/
403/404/409/422/429/retry/terminal을 포함한 19개 scenario catalog와 strict
403/404/409(충돌·처리 중)/422/429/retry/terminal을 포함한 20개 scenario catalog와 strict
unhandled-request server(`tests/mocks/server.ts`의
`onUnhandledRequest: "error"`)를 공유한다. browser test는 공용 fixture
(`tests/support/browser/strict-browser-test.ts`)가 console error/warning,
@@ -746,7 +746,8 @@ tests/factories/
| `unauthenticated-401` | 401. 명령은 적용되지 않음(`NOT_APPLIED`) |
| `forbidden-403` | 권한 없음 |
| `not-found-404` | 리소스 없음 |
| `conflict-409` | mutation conflict |
| `conflict-409` | mutation conflict. 계약에 적힌 충돌 code라 명령은 적용되지 않음(`NOT_APPLIED`) |
| `in-flight-409` | 같은 멱등 키의 앞선 요청이 아직 처리 중(`IDEMPOTENT_IN_FLIGHT`). 명령은 결과 불명(`MAYBE_APPLIED`)이라 다음 전송도 같은 키 |
| `validation-422` | 승인된 field/global error |
| `rate-limited-429` | Retry-After 포함 |
| `server-retry-success` | bounded retry 뒤 성공 |
+1 -1
View File
@@ -45,7 +45,7 @@ if (
}
process.stdout.write(
"HTTP scenario evidence: PASS (stale receipt removed, 54 executed, missing-ID fixture rejected)\n",
"HTTP scenario evidence: PASS (stale receipt removed, 57 executed, missing-ID fixture rejected)\n",
);
function run(script: string) {
@@ -30,6 +30,18 @@ const PROBLEM_VALIDATOR = zodValidator(
referenceProblemSchema,
);
/**
* 0929/03-01. A 409 does not by itself mean "refused": a resend with the same
* key can meet the first attempt still running (the paired backend answers
* `409 IDEMPOTENT_IN_FLIGHT`). Only the conflict codes this fixture declares
* are `NOT_APPLIED`; any other 409 stays `MAYBE_APPLIED`, so the coordinator
* keeps the intent and the next send reuses the key. Answering `NOT_APPLIED`
* there would let the next save mint a new key and create the resource twice.
*/
const CREATE_NOT_APPLIED_CONFLICT_CODES: ReadonlySet<string> = new Set([
"CONFLICT",
]);
/**
* Fixture-side classifier standing in for the package-provided pure bounded
* classifier. A status the fixture does not describe stays `MAYBE_APPLIED`.
@@ -38,8 +50,14 @@ const CREATE_EFFECT: CommandEffectDescriptor<ReferenceProblem> = Object.freeze({
successEffect: "APPLIED_CONFIRMED" as const,
classifyProblem({
status,
problem,
}: Readonly<{ status: number; problem: ReferenceProblem }>) {
if (status === 400 || status === 409 || status === 422) {
if (status === 400 || status === 422) return "NOT_APPLIED";
if (
status === 409 &&
problem.code !== undefined &&
CREATE_NOT_APPLIED_CONFLICT_CODES.has(problem.code)
) {
return "NOT_APPLIED";
}
return "MAYBE_APPLIED";
@@ -8,6 +8,7 @@ import {
createReferenceHttpGateway,
REFERENCE_HTTP_OPERATIONS,
} from "../../../src/features/reference-feature/adapters/reference-http-gateway.ts";
import { CREATE_REFERENCE_RESOURCE_CONTRACT } from "../../../src/features/reference-feature/contracts/reference-feature-contract-contribution.ts";
function executorReturning(
outcome: Readonly<Record<string, unknown>>,
@@ -133,3 +134,35 @@ describe("reference HTTP business problem mapping", () => {
});
});
});
describe("reference create problem effect classification (0929/03-01)", () => {
const classify = (status: number, code?: string) =>
CREATE_REFERENCE_RESOURCE_CONTRACT.contract.commandEffect.classifyProblem({
status,
problem: Object.freeze({
type: "https://api.test/problems/reference",
title: "Reference problem",
status,
...(code === undefined ? {} : { code }),
}),
});
it.each([
// The first attempt with this key still runs: the key must stay bound.
{ status: 409, code: "IDEMPOTENT_IN_FLIGHT", effect: "MAYBE_APPLIED" },
// An undeclared 409 may hide a running attempt: safe side.
{ status: 409, code: "SOMETHING_NEW", effect: "MAYBE_APPLIED" },
{ status: 409, code: undefined, effect: "MAYBE_APPLIED" },
// The fixture's declared semantic conflict is the only refused 409.
{ status: 409, code: "CONFLICT", effect: "NOT_APPLIED" },
{ status: 400, code: undefined, effect: "NOT_APPLIED" },
{ status: 422, code: "VALIDATION_REJECTED", effect: "NOT_APPLIED" },
{ status: 404, code: "NOT_FOUND", effect: "MAYBE_APPLIED" },
{ status: 503, code: "SERVER_FAILURE", effect: "MAYBE_APPLIED" },
] as const)(
"classifies status $status code $code as $effect",
({ status, code, effect }) => {
expect(classify(status, code)).toBe(effect);
},
);
});
@@ -1,6 +1,6 @@
// @vitest-environment jsdom
import { render, screen } from "@testing-library/react";
import { render, screen, waitFor } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { http, HttpResponse } from "msw";
import {
@@ -166,6 +166,93 @@ describe("reference feature production vertical path", () => {
expect(idempotencyKeys[1]).toBe(idempotencyKeys[0]);
});
it("keeps the key when the resend meets the first attempt still in flight (0929/03-01)", async () => {
const user = userEvent.setup();
const idempotencyKeys: (string | null)[] = [];
// A server that deduplicates by key: one receipt per created resource.
const receipts = new Map<string, Record<string, string>>();
let firstAttemptRunning = true;
mockApi.server.use(
http.post("https://api.test/api/reference-resources", async ({ request }) => {
const key = request.headers.get("idempotency-key") ?? "";
idempotencyKeys.push(key);
const receipt = receipts.get(key);
if (receipt) {
if (firstAttemptRunning) {
// The paired backend answers a same-key request while the first
// attempt still runs with 409 IDEMPOTENT_IN_FLIGHT.
firstAttemptRunning = false;
return HttpResponse.json(
{
type: "https://api.test/problems/idempotent_in_flight",
title: "IDEMPOTENT_IN_FLIGHT",
status: 409,
code: "IDEMPOTENT_IN_FLIGHT",
},
{
status: 409,
headers: { "content-type": "application/problem+json" },
},
);
}
return HttpResponse.json(receipt, { status: 201 });
}
const body = (await request.json()) as { name: string };
const resource = {
id: `reference-created-${receipts.size + 1}`,
name: body.name,
createdAt: "2026-07-26T00:00:00.000Z",
};
receipts.set(key, resource);
// The first attempt reaches the server; only its response is lost.
if (receipts.size === 1) return new HttpResponse(null, { status: 504 });
return HttpResponse.json(resource, { status: 201 });
}),
);
const composition = await createRuntimeComposition({
fetcher: absoluteFetch,
host: {},
});
window.history.pushState({}, "", "/examples/reference-resources/new");
render(<RuntimeApplication composition={composition} />);
await user.click(
await screen.findByRole("button", { name: "로그인 시작" }),
);
await user.type(
await screen.findByRole("textbox", { name: /새 항목 이름/ }),
"Slow write",
);
await user.click(screen.getByRole("button", { name: "저장" }));
await user.click(
await screen.findByRole("button", { name: "같은 요청으로 다시 보내기" }),
);
await waitFor(() => expect(idempotencyKeys).toHaveLength(2));
// After the 409 the user takes the next step the screen offers.
const next = await waitFor(() => {
const resend = screen.queryByRole("button", {
name: "같은 요청으로 다시 보내기",
});
if (resend) return resend;
const save = screen.getByRole("button", { name: "저장" });
expect(save).toBeEnabled();
return save;
});
const shownAfterInFlight = {
unknown: screen.queryByText("변경 결과를 확인할 수 없습니다.") !== null,
conflict: screen.queryAllByText(/충돌/).length > 0,
};
await user.click(next);
await waitFor(() => expect(idempotencyKeys).toHaveLength(3));
const [first] = idempotencyKeys;
expect(idempotencyKeys).toEqual([first, first, first]);
expect(receipts.size).toBe(1);
expect(shownAfterInFlight).toEqual({ unknown: true, conflict: false });
expect(await screen.findByText("저장했습니다.")).toBeVisible();
});
it.each([
// The demo session treats a server 401 as signed out; the route guard
// then asks for sign-in and the form is gone.
@@ -361,17 +361,17 @@ async function executeScenario(
}
describe("HTTP scenario catalog execution evidence", () => {
it("declares exactly the 54 behaviorally distinct operation scenarios", () => {
it("declares exactly the 57 behaviorally distinct operation scenarios", () => {
const executionIds = Object.entries(OPERATION_SCENARIO_CATALOG).flatMap(
([operationId, scenarioIds]) =>
scenarioIds.map((scenarioId) => `${operationId}::${scenarioId}`),
);
expect(OPERATION_SCENARIO_CATALOG.LIST_REFERENCE_RESOURCES).toHaveLength(19);
expect(OPERATION_SCENARIO_CATALOG.GET_REFERENCE_RESOURCE).toHaveLength(18);
expect(OPERATION_SCENARIO_CATALOG.CREATE_REFERENCE_RESOURCE).toHaveLength(17);
expect(executionIds).toHaveLength(54);
expect(new Set(executionIds)).toHaveLength(54);
expect(OPERATION_SCENARIO_CATALOG.LIST_REFERENCE_RESOURCES).toHaveLength(20);
expect(OPERATION_SCENARIO_CATALOG.GET_REFERENCE_RESOURCE).toHaveLength(19);
expect(OPERATION_SCENARIO_CATALOG.CREATE_REFERENCE_RESOURCE).toHaveLength(18);
expect(executionIds).toHaveLength(57);
expect(new Set(executionIds)).toHaveLength(57);
expect(executionIds).toEqual(HTTP_SCENARIO_EXECUTION_IDS);
});
@@ -410,7 +410,7 @@ describe("HTTP scenario catalog execution evidence", () => {
HTTP_SCENARIO_RECEIPT_SCHEMA_VERSION,
HTTP_SCENARIO_EXPECTATIONS,
),
catalogTotal: 54,
catalogTotal: 57,
executedIds: sortedRows.map((row) => row.executionId),
rows: sortedRows,
},
@@ -81,6 +81,11 @@ async function scenarioResponse(
if (scenario === "conflict-409") {
return HttpResponse.json(problem(409, "CONFLICT"), { status: 409 });
}
if (scenario === "in-flight-409") {
return HttpResponse.json(problem(409, "IDEMPOTENT_IN_FLIGHT"), {
status: 409,
});
}
if (scenario === "validation-422") {
return HttpResponse.json(
problem(422, "VALIDATION_REJECTED"),
+16
View File
@@ -30,6 +30,7 @@ export const HTTP_SCENARIO_IDS = Object.freeze([
"forbidden-403",
"not-found-404",
"conflict-409",
"in-flight-409",
"validation-422",
"rate-limited-429",
"server-retry-success",
@@ -271,6 +272,21 @@ function expectationFor(
),
];
break;
case "in-flight-409":
// 0929/03-01. The same key is still running: the command stays unknown.
statuses = [409];
kind = "PROBLEM";
detail = "409";
outcomeEffect = command ? "MAYBE_APPLIED" : "NOT_APPLIED";
observer = command ? "MAYBE_APPLIED" : "NOT_STARTED";
bodies = [
attemptBody(
"FULLY_READ_WITHIN_BOUND",
jsonBytes(problem(409, "IDEMPOTENT_IN_FLIGHT")),
65_536,
),
];
break;
case "validation-422":
statuses = [422];
kind = "PROBLEM";