fix: preserve logical mutation intent

tests/unit/http-execution-v3.test.ts

@@ -21,6 +21,20 @@ const scope = Object.freeze({
 const createInstalled: InstalledHttpContract<unknown, unknown, unknown> =
   TEST_CREATE_HTTP_CONTRACT;
 
+function mutationIntent(
+  overrides: Readonly<{ intentId?: string; idempotencyKey?: string }> = {},
+) {
+  return Object.freeze({
+    intentId: overrides.intentId ?? "intent-1",
+    operationId: "TEST_CREATE_ENTITY",
+    canonicalInputIdentity: "opaque-input-identity",
+    ...(overrides.idempotencyKey === undefined
+      ? { idempotencyKey: "key-1" }
+      : { idempotencyKey: overrides.idempotencyKey }),
+    createdAtMonotonicMs: 1,
+  });
+}
+
 function operation(
   overrides: Readonly<{
     deadlineMs?: number;
@@ -47,6 +61,129 @@ async function flushMicrotasks(): Promise<void> {
 }
 
 describe("descriptor-driven HTTP execution lifetime", () => {
+  it("reuses one supplied idempotency key across every physical retry", async () => {
+    const observedKeys: Array<string | null> = [];
+    let attempt = 0;
+    const fetcher = vi.fn((_input: RequestInfo | URL, init?: RequestInit) => {
+      observedKeys.push(new Headers(init?.headers).get("Idempotency-Key"));
+      attempt += 1;
+      if (attempt === 1) throw new TypeError("synchronous pre-dispatch failure");
+      return Promise.resolve(
+        Response.json(
+          { id: "created", name: "Created" },
+          { status: 201 },
+        ),
+      );
+    });
+    const executor = createContractHttpExecutor({
+      baseUrl: "https://api.example/",
+      maxRetryAttempts: 1,
+      attachCredentials: () => ({
+        kind: "READY",
+        headers: {},
+        credentials: "omit",
+      }),
+      fetcher,
+      sleep: async () => {},
+      random: () => 0,
+    });
+    const retryingCreate = {
+      ...createInstalled,
+      frontend: {
+        ...createInstalled.frontend,
+        retryBudget: 1 as const,
+      },
+    };
+
+    await expect(
+      executor.execute(
+        retryingCreate,
+        { name: "created" },
+        { scope, intent: mutationIntent({ idempotencyKey: "logical-key" }) },
+      ),
+    ).resolves.toMatchObject({ kind: "SUCCESS" });
+    expect(fetcher).toHaveBeenCalledTimes(2);
+    expect(observedKeys).toEqual(["logical-key", "logical-key"]);
+  });
+
+  it("never emits a mutation idempotency header for a query", async () => {
+    const observedKeys: Array<string | null> = [];
+    const fetcher = vi.fn(
+      async (_input: RequestInfo | URL, init?: RequestInit) => {
+        observedKeys.push(
+          new Headers(init?.headers).get("Idempotency-Key"),
+        );
+        return Response.json([]);
+      },
+    );
+    const executor = createContractHttpExecutor({
+      baseUrl: "https://api.example/",
+      maxRetryAttempts: 0,
+      attachCredentials: () => ({
+        kind: "READY",
+        headers: {},
+        credentials: "omit",
+      }),
+      fetcher,
+    });
+
+    await expect(
+      executor.execute(
+        installed,
+        { limit: 20 },
+        { scope },
+      ),
+    ).resolves.toMatchObject({ kind: "SUCCESS" });
+    expect(fetcher).toHaveBeenCalledOnce();
+    expect(observedKeys).toEqual([null]);
+  });
+
+  it("keeps intent identities out of request URLs and safe observations", async () => {
+    const urls: string[] = [];
+    const observations: unknown[] = [];
+    const executor = createContractHttpExecutor({
+      baseUrl: "https://api.example/",
+      maxRetryAttempts: 0,
+      attachCredentials: () => ({
+        kind: "READY",
+        headers: {},
+        credentials: "omit",
+      }),
+      fetcher: vi.fn(async (input) => {
+        urls.push(String(input));
+        return Response.json(
+          { id: "created", name: "Created" },
+          { status: 201 },
+        );
+      }),
+      observe: (observation) => observations.push(observation),
+    });
+
+    await expect(
+      executor.execute(
+        createInstalled,
+        { name: "created" },
+        {
+          scope,
+          intent: Object.freeze({
+            intentId: "private-intent-id",
+            operationId: "TEST_CREATE_ENTITY",
+            canonicalInputIdentity: "private-canonical-input",
+            idempotencyKey: "private-idempotency-key",
+            createdAtMonotonicMs: 1,
+          }),
+        },
+      ),
+    ).resolves.toMatchObject({ kind: "SUCCESS" });
+
+    const safeEvidence = JSON.stringify({ urls, observations });
+    expect(urls).toEqual(["https://api.example/api/test-entities"]);
+    expect(observations).toHaveLength(1);
+    expect(safeEvidence).not.toContain("private-intent-id");
+    expect(safeEvidence).not.toContain("private-canonical-input");
+    expect(safeEvidence).not.toContain("private-idempotency-key");
+  });
+
   it.each([
     [{}, "limit=20"],
     [{ limit: "7" }, "limit=7"],
@@ -127,7 +264,7 @@ describe("descriptor-driven HTTP execution lifetime", () => {
         { name: "created" },
         {
           scope,
-          intent: { intentId: "intent-1", startedBy: "USER", idempotencyKey: "key-1" },
+          intent: mutationIntent(),
         },
       ),
     ).resolves.toMatchObject({
@@ -169,7 +306,7 @@ describe("descriptor-driven HTTP execution lifetime", () => {
         { name: "created" },
         {
           scope: fencedScope,
-          intent: { intentId: "intent-2", startedBy: "USER", idempotencyKey: "key-2" },
+          intent: mutationIntent({ intentId: "intent-2", idempotencyKey: "key-2" }),
         },
       ),
     ).resolves.toMatchObject({