fix: preserve logical mutation intent

tests/component/application-query.test.tsx

@@ -14,6 +14,8 @@ import {
   useApplicationMutation,
   useApplicationQuery,
 } from "../../src/presentation/adapters/query/application-query.ts";
+import type { MutationIntentFactory } from "../../src/application/ports/mutation-intent-factory.ts";
+import { MutationIntentProvider } from "../../src/presentation/adapters/query/mutation-intent-provider.tsx";
 import { QueryInvalidationProvider } from "../../src/presentation/adapters/query/query-invalidation-provider.tsx";
 import {
   defineQueryInvalidationTopic,
@@ -71,7 +73,28 @@ function queryClient() {
   });
 }
 
-function wrapper(client: QueryClient) {
+function deterministicMutationIntentFactory(): MutationIntentFactory {
+  let sequence = 0;
+  return Object.freeze({
+    create(input) {
+      sequence += 1;
+      return Object.freeze({
+        intentId: `intent-${sequence}`,
+        operationId: input.operationId,
+        canonicalInputIdentity: input.canonicalInputIdentity,
+        ...(input.requiresIdempotencyKey
+          ? { idempotencyKey: `key-${sequence}` }
+          : {}),
+        createdAtMonotonicMs: sequence,
+      });
+    },
+  });
+}
+
+function wrapper(
+  client: QueryClient,
+  mutationIntentFactory = deterministicMutationIntentFactory(),
+) {
   const coordinator: QueryInvalidationCoordinator = {
     async invalidate(topics) {
       for (const topic of topics) {
@@ -93,11 +116,13 @@ function wrapper(client: QueryClient) {
   };
   return function QueryWrapper({ children }: { children: ReactNode }) {
     return (
-      <QueryClientProvider client={client}>
-        <QueryInvalidationProvider coordinator={coordinator}>
-          {children}
-        </QueryInvalidationProvider>
-      </QueryClientProvider>
+      <MutationIntentProvider factory={mutationIntentFactory}>
+        <QueryClientProvider client={client}>
+          <QueryInvalidationProvider coordinator={coordinator}>
+            {children}
+          </QueryInvalidationProvider>
+        </QueryClientProvider>
+      </MutationIntentProvider>
     );
   };
 }
@@ -415,6 +440,7 @@ describe("scope-bound mutation fence", () => {
           definitionId: "fenced-mutation-v1",
           definitionVersion: 1,
           operationId: "CREATE_FENCED",
+          requiresIdempotencyKey: false,
           owner: "platform-test",
           duplicatePolicy: "REJECT_WHILE_ACTIVE",
           scope,
@@ -446,6 +472,7 @@ describe("scope-bound mutation fence", () => {
           definitionId: "late-mutation-v1",
           definitionVersion: 1,
           operationId: "CREATE_LATE",
+          requiresIdempotencyKey: false,
           owner: "platform-test",
           duplicatePolicy: "ALLOW_PARALLEL",
           scope,
@@ -488,6 +515,7 @@ describe("scope-bound mutation fence", () => {
           definitionId: "hung-mutation-v1",
           definitionVersion: 1,
           operationId: "CREATE_HUNG",
+          requiresIdempotencyKey: false,
           owner: "platform-test",
           duplicatePolicy: "REJECT_WHILE_ACTIVE",
           scope,
@@ -516,6 +544,128 @@ describe("scope-bound mutation fence", () => {
 });
 
 describe("application mutation inbound bridge", () => {
+  it("creates a distinct logical intent for each independently admitted submit", async () => {
+    const client = queryClient();
+    const scope = scopeSnapshot();
+    const observedIntents: unknown[] = [];
+    const execute = vi.fn(
+      async (
+        input: string,
+        context: Readonly<{ signal: AbortSignal; intent?: unknown }>,
+      ) => {
+        observedIntents.push(context.intent);
+        return { ok: true as const, value: input };
+      },
+    );
+    const hook = renderHook(
+      () =>
+        useApplicationMutation<string, string>({
+          definitionId: "independent-intent-v1",
+          definitionVersion: 1,
+          operationId: "CREATE_WITH_INTENT",
+          requiresIdempotencyKey: true,
+          owner: "platform-test",
+          duplicatePolicy: "ALLOW_PARALLEL",
+          scope,
+          execute,
+          invalidate: [],
+        }),
+      { wrapper: wrapper(client) },
+    );
+
+    await act(async () => {
+      await hook.result.current.submit("same-input");
+      await hook.result.current.submit("same-input");
+    });
+
+    expect(observedIntents).toHaveLength(2);
+    expect(observedIntents[0]).toMatchObject({
+      intentId: "intent-1",
+      operationId: "CREATE_WITH_INTENT",
+      idempotencyKey: "key-1",
+    });
+    expect(observedIntents[1]).toMatchObject({
+      intentId: "intent-2",
+      operationId: "CREATE_WITH_INTENT",
+      idempotencyKey: "key-2",
+    });
+    expect(observedIntents[0]).not.toEqual(observedIntents[1]);
+  });
+
+  it("creates no second intent when JOIN_IDENTICAL shares an admitted submit", async () => {
+    const client = queryClient();
+    const scope = scopeSnapshot();
+    const deterministicFactory = deterministicMutationIntentFactory();
+    const createIntent = vi.fn(deterministicFactory.create);
+    const factory: MutationIntentFactory = Object.freeze({
+      create: createIntent,
+    });
+    let complete: (value: ApplicationResult<string>) => void = () => {};
+    const execute = vi.fn(
+      () =>
+        new Promise<ApplicationResult<string>>((resolve) => {
+          complete = resolve;
+        }),
+    );
+    const hook = renderHook(
+      () =>
+        useApplicationMutation<string, string>({
+          definitionId: "joined-intent-v1",
+          definitionVersion: 1,
+          operationId: "CREATE_JOINED",
+          requiresIdempotencyKey: true,
+          owner: "platform-test",
+          duplicatePolicy: "JOIN_IDENTICAL",
+          scope,
+          execute,
+          invalidate: [],
+        }),
+      { wrapper: wrapper(client, factory) },
+    );
+
+    let first: Promise<ApplicationResult<string>> | null = null;
+    let joined: Promise<ApplicationResult<string>> | null = null;
+    act(() => {
+      first = hook.result.current.submit("same-input");
+      joined = hook.result.current.submit("same-input");
+    });
+
+    expect(first).toBe(joined);
+    await waitFor(() => expect(execute).toHaveBeenCalledOnce());
+    expect(createIntent).toHaveBeenCalledOnce();
+    expect(createIntent).toHaveBeenCalledWith({
+      operationId: "CREATE_JOINED",
+      canonicalInputIdentity:
+        "scope-fingerprint-0001:joined-intent-v1:scope-identity-token-0001",
+      requiresIdempotencyKey: true,
+    });
+
+    complete({ ok: true, value: "same-input" });
+    if (!first) throw new Error("expected admitted mutation");
+    await act(() => first);
+  });
+
+  it("keeps the legacy raw mutation path outside the intent factory", async () => {
+    const client = queryClient();
+    const createIntent = vi.fn<MutationIntentFactory["create"]>();
+    const factory: MutationIntentFactory = Object.freeze({
+      create: createIntent,
+    });
+    const execute = vi.fn(async (input: string) => ({
+      ok: true as const,
+      value: input,
+    }));
+    const hook = renderHook(
+      () => useApplicationMutation<string, string>({ execute }),
+      { wrapper: wrapper(client, factory) },
+    );
+
+    await act(() => hook.result.current.submit("legacy-input"));
+
+    expect(execute).toHaveBeenCalledOnce();
+    expect(createIntent).not.toHaveBeenCalled();
+  });
+
   it("rejects a duplicate submit by default while one is active", async () => {
     const client = queryClient();
     let complete: (value: ApplicationResult<string>) => void = () => {};

tests/component/server-state-generation-provider.test.tsx

@@ -43,6 +43,11 @@ describe("server-state generation provider", () => {
         `scope-generation-provider-${String(token++).padStart(4, "0")}`,
     });
     const renderedClients: QueryClient[] = [];
+    const mutationIntentFactory = Object.freeze({
+      create() {
+        throw new Error("mutation intent is unused by this provider test");
+      },
+    });
     function Probe() {
       renderedClients.push(useQueryClient());
       return <div>generation-content</div>;
@@ -52,6 +57,7 @@ describe("server-state generation provider", () => {
       <ServerStateGenerationProvider
         store={store}
         scope={scope}
+        mutationIntentFactory={mutationIntentFactory}
         transitionFallback={<div>scope-transition</div>}
       >
         <Probe />