diff --git a/docs/manual/01-add-a-feature.md b/docs/manual/01-add-a-feature.md
index f9285207..2d258ddc 100644
--- a/docs/manual/01-add-a-feature.md
+++ b/docs/manual/01-add-a-feature.md
@@ -504,7 +504,7 @@ projectRequest: (input) => Object.freeze({
① **정할 것**
- 페이지 템플릿. [02 결정표 6절](02-decision-tables.md#6-페이지-템플릿)
-- 쓰기가 있으면 결과 불명 화면. `AsyncSurface`의 `onReconcileUnknownEffect`(확인), `onResendUnknownEffect`(같은 키로 다시 보내기). 다시 보내기 버튼은 키가 있는 요청(`KEYED`)에만 그려진다. `NEVER` 쓰기는 확인만 남는다.
+- 쓰기가 있으면 결과 불명 화면. `AsyncSurface`의 `onReconcileUnknownEffect`(확인), `onResendUnknownEffect`(같은 키로 다시 보내기). 다시 보내기 버튼은 키가 있는 요청(`KEYED`)에만 그려진다. `NEVER` 쓰기는 확인만 남는다. 폼 밖에서 `mutation.submit`을 부르는 화면도 `NEVER` 쓰기의 같은 입력을 다시 보낼 수 없다. 훅이 `DUPLICATE_IN_FLIGHT`(code `UNKNOWN_EFFECT_PENDING`)로 거절한다. `AsyncSurface`에 손으로 만든 상태를 넘기면 재전송 버튼은 그려지지 않는다(코디네이터의 `state`를 넘긴다).
- 폼이면 서버 필드 오류를 받을 필드(`useAppForm`의 `allowedServerFields`). 짝 백엔드는 필드 검증 거절을 400 `VALIDATION_FAILED`와 `details[{field, code}]`로 보낸다(422가 아니다). 공유 MSW 시나리오에는 짝 백엔드가 보내지 않는 `validation-422`만 있고, Envelope operation에서 그 답은 결과 불명이다. 짝 백엔드 모양의 필드 오류 테스트는 생성된 작성 폼 테스트(`-create-page.test.tsx`)처럼 400 본문을 손으로 적는다.
② **기준**
diff --git a/docs/operations/api-contract-and-server-state-recovery.md b/docs/operations/api-contract-and-server-state-recovery.md
index c4576711..ba60984a 100644
--- a/docs/operations/api-contract-and-server-state-recovery.md
+++ b/docs/operations/api-contract-and-server-state-recovery.md
@@ -257,7 +257,11 @@ diagnostics에만 남고 `api.request.failed`에는 세지 않는다(03-07). 그
key다. 자동 재전송은 없다(`src/presentation/adapters/query/application-query.ts`
`submit`·`resendUnknownEffect`, 화면 `src/presentation/components/async-surface.tsx`).
키가 없는 command(`NEVER`)는 서버가 두 번째 요청을 가려내지 못하므로 재전송 버튼을
- 그리지 않는다(`canResendUnknownEffect`, 0929/03-03).
+ 그리지 않는다(`canResendUnknownEffect`, 0929/03-03). 같은 canonical input의 재저장도
+ 보내지 않는다. 훅의 `submit`이 `NOT_STARTED` `DUPLICATE_IN_FLIGHT`(code
+ `UNKNOWN_EFFECT_PENDING`)를 돌려주고, 결과 불명 요청이 확인될 때까지 그대로다. 폼
+ 밖에서 `submit`을 부르는 화면도 같다. 화면은 상태에 `unknownEffectResendable: true`가
+ 있을 때만 재전송 버튼을 그린다.
5. backend status/receipt로 `COMMITTED`면 cache reconcile/invalidate한다. 화면의
"변경됨으로 확인"이 이 경로다.
6. `NOT_APPLIED`가 증명된 경우만 정책에 따라 retry한다. 화면은 근거 없는
diff --git a/src/application/view-models/async-state.ts b/src/application/view-models/async-state.ts
index ecf72aa8..02f2a4f5 100644
--- a/src/application/view-models/async-state.ts
+++ b/src/application/view-models/async-state.ts
@@ -86,7 +86,9 @@ export type AsyncState = Readonly<{
/**
* 0929/03-03. Only with `indicator: "mutation-effect-unknown"`, when the
* coordinator said: `false` means the request has no idempotency key, so
- * sending it again is a second, unprotected request and no resend is drawn.
+ * sending it again is a second, unprotected request. A resend is drawn
+ * only for `true`; absent (a state built without the coordinator) draws
+ * none.
*/
unknownEffectResendable?: boolean;
}>;
diff --git a/src/presentation/adapters/query/application-query.ts b/src/presentation/adapters/query/application-query.ts
index 2f6daace..49750c6c 100644
--- a/src/presentation/adapters/query/application-query.ts
+++ b/src/presentation/adapters/query/application-query.ts
@@ -243,6 +243,13 @@ export type LegacyMutationOptions = LegacyMutationBase = Readonly<{
state: AsyncState;
+ /**
+ * D-1. The same canonical input as an unknown-effect request is the same
+ * logical request: a keyed command sends it again with that request's
+ * key. 0929/03-03. Without a key it is not sent: the result is a
+ * `NOT_STARTED` `DUPLICATE_IN_FLIGHT` failure with code
+ * `UNKNOWN_EFFECT_PENDING` until the unknown request is reconciled.
+ */
submit(input: Input): Promise>;
resolveConflict(): Promise;
/**
@@ -559,6 +566,21 @@ export function useApplicationMutation(
candidate.state === "UNKNOWN" &&
candidate.intent?.canonicalInputIdentity === identity,
);
+ // 0929/03-03. Without an idempotency key the server cannot tell that
+ // request from this one, so saving the same input again could apply it
+ // twice. The unknown request is settled first (reconcileUnknownEffect),
+ // never repeated; a page that calls submit outside the form meets this
+ // too.
+ if (replayed && replayed.intent?.idempotencyKey === undefined) {
+ identityLease?.release();
+ return Promise.resolve({
+ ok: false,
+ error: createFailure("DUPLICATE_IN_FLIGHT", definitionId, 0, {
+ code: "UNKNOWN_EFFECT_PENDING",
+ effect: "NOT_STARTED",
+ }),
+ });
+ }
const admission: MutationAdmission = {
sequence: unknownEffectChannel.nextSequence++,
state: "ACTIVE",
diff --git a/src/presentation/components/async-surface.tsx b/src/presentation/components/async-surface.tsx
index b6028b5f..041d3072 100644
--- a/src/presentation/components/async-surface.tsx
+++ b/src/presentation/components/async-surface.tsx
@@ -128,8 +128,10 @@ export type AsyncSurfaceProps = Readonly<{
onReconcileUnknownEffect?: (resolution: "APPLIED") => void;
/**
* D-1. Resends the unknown request with its original intent and key.
- * 0929/03-03. Not drawn when `state.unknownEffectResendable` is `false`:
- * a request without a key would go out as a second, unprotected one.
+ * 0929/03-03. Drawn only when `state.unknownEffectResendable` is `true`
+ * (the coordinator's `canResendUnknownEffect`): a request without a key
+ * would go out as a second, unprotected one, and a state built by hand
+ * without that answer draws no resend either.
*/
onResendUnknownEffect?: () => void;
/** 08-05. Title level of the empty and failure surfaces it renders. */
@@ -224,7 +226,7 @@ export function AsyncSurface({
) : null}
{state.indicator === "mutation-effect-unknown" &&
onResendUnknownEffect &&
- state.unknownEffectResendable !== false ? (
+ state.unknownEffectResendable === true ? (
diff --git a/tests/component/application-mutation-admission.test.tsx b/tests/component/application-mutation-admission.test.tsx
index f52334af..b62cff0c 100644
--- a/tests/component/application-mutation-admission.test.tsx
+++ b/tests/component/application-mutation-admission.test.tsx
@@ -555,6 +555,43 @@ describe("application mutation intent admission", () => {
expect(hook.result.current.state.indicator).toBe("mutation-effect-unknown");
});
+ // 0929/03-03. Saving the same input again reuses the unknown request's
+ // intent. Without a key that is a second request the server cannot tell
+ // from the first, so the hook refuses it before sending, whatever page
+ // calls it (review experiment X1: keys [null, null]).
+ it("refuses to send a keyless unknown request again for the same input", async () => {
+ const { hook, execute } = renderKeyedCreate([unknown], { keyed: false });
+ await act(() => hook.result.current.submit("keyless-input"));
+ expect(hook.result.current.state.indicator).toBe("mutation-effect-unknown");
+
+ let again: ApplicationResult | undefined;
+ await act(async () => {
+ again = await hook.result.current.submit("keyless-input");
+ });
+
+ expect(again).toMatchObject({
+ ok: false,
+ error: {
+ kind: "DUPLICATE_IN_FLIGHT",
+ code: "UNKNOWN_EFFECT_PENDING",
+ effect: "NOT_STARTED",
+ },
+ });
+ expect(execute).toHaveBeenCalledOnce();
+ expect(hook.result.current.state.indicator).toBe("mutation-effect-unknown");
+ });
+
+ it("still sends another input while a keyless request is unknown", async () => {
+ const { hook, execute } = renderKeyedCreate([unknown], { keyed: false });
+ await act(() => hook.result.current.submit("first-input"));
+ await act(() => hook.result.current.submit("changed-input"));
+
+ expect(execute.mock.calls.map(([input]) => input)).toEqual([
+ "first-input",
+ "changed-input",
+ ]);
+ });
+
it("offers the same-key resend for an unknown keyed request", async () => {
const { hook } = renderKeyedCreate([unknown]);
expect(hook.result.current.canResendUnknownEffect).toBe(false);
diff --git a/tests/component/async-surface.test.tsx b/tests/component/async-surface.test.tsx
index 6b3ab630..3eceb061 100644
--- a/tests/component/async-surface.test.tsx
+++ b/tests/component/async-surface.test.tsx
@@ -65,9 +65,11 @@ describe("async UI state matrix", () => {
const retry = vi.fn();
const reconcile = vi.fn();
const resend = vi.fn();
+ // 0929/03-03. The coordinator says the request carries a key.
const state = deriveAsyncState({
data: ["value"],
hasMutationEffectUnknown: true,
+ isUnknownEffectResendable: true,
});
render(
@@ -123,6 +125,23 @@ describe("async UI state matrix", () => {
expect(screen.getByRole("button", { name: "변경됨으로 확인" })).toBeInTheDocument();
});
+ // 0929/03-03. A state built by hand without the coordinator's answer does
+ // not know the request has a key, so it draws no resend (review X3).
+ it("draws no resend for an unknown state that does not say it can be resent", () => {
+ render(
+ ,
+ );
+
+ expect(
+ screen.queryByRole("button", { name: "같은 요청으로 다시 보내기" }),
+ ).not.toBeInTheDocument();
+ expect(screen.getByRole("button", { name: "변경됨으로 확인" })).toBeInTheDocument();
+ });
+
it("keeps the resend state to an unknown mutation only", () => {
expect(
deriveAsyncState({ data: ["value"], isUnknownEffectResendable: false }),