fix(mercury): forward idempotencyKey as Idempotency-Key HTTP header (PR #108 review C1)

Mercury's ACH/wire/check transaction API dedupes creations by the
`Idempotency-Key` HTTP header, not by a field in the JSON body. Prior
to this fix, `createPayment` sent the key only in the body, so a
transport-level retry (network blip, edge timeout, etc.) could create a
duplicate ACH transfer — money out twice.

Changes:
- `mercuryClient.post` accepts an `opts.idempotencyKey` and sets the
  `Idempotency-Key` HTTP header on the outbound fetch when present.
- `createPayment` strips `idempotencyKey` from the request body and
  forwards it via `opts`, so the header is set on every Mercury POST.
- Regression test in `tests/meta/executors/mercury-payment-failures.spec.ts`
  captures the outbound `Request` via the existing injected-fetch pattern
  and asserts `headers.get('Idempotency-Key')` equals the executor's
  computed idempotency key. No mocks beyond the FetchImpl injection
  already used by the file.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: chitcommit

src/lib/integrations.ts

@@ -599,12 +599,25 @@ export function mercuryClient(token: string, fetchImpl: FetchImpl = fetch) {
    * audit row can show what Mercury returned without leaking secrets (body is
    * Mercury's payment object — no token in it).
    */
-  async function post<T>(path: string, body: unknown): Promise<MercuryPostResult<T>> {
+  async function post<T>(
+    path: string,
+    body: unknown,
+    opts?: { idempotencyKey?: string },
+  ): Promise<MercuryPostResult<T>> {
     let res: Response;
     try {
+      const headers: Record<string, string> = {
+        Authorization: `Bearer ${token}`,
+        'Content-Type': 'application/json',
+        Accept: 'application/json',
+      };
+      // Mercury dedupes ACH/wire/check creations by the `Idempotency-Key` HTTP
+      // header. Putting the key only in the JSON body lets a transport retry
+      // create duplicate transfers — money out twice. Forward as header.
+      if (opts?.idempotencyKey) headers['Idempotency-Key'] = opts.idempotencyKey;
       res = await fetchImpl(`${baseUrl}${path}`, {
         method: 'POST',
-        headers: { Authorization: `Bearer ${token}`, 'Content-Type': 'application/json', Accept: 'application/json' },
+        headers,
         body: JSON.stringify(body),
       });
     } catch (err) {
@@ -655,7 +668,16 @@ export function mercuryClient(token: string, fetchImpl: FetchImpl = fetch) {
       paymentMethod: 'ach' | 'wire' | 'check';
       idempotencyKey: string;
       note?: string;
-    }) => post<{ id: string; status: string; amount: number }>(`/account/${accountId}/transactions`, payment),
+    }) => {
+      // Mercury expects `Idempotency-Key` as an HTTP header, not in the body.
+      // Strip from body and forward via opts so transport retries dedupe.
+      const { idempotencyKey, ...bodyWithoutKey } = payment;
+      return post<{ id: string; status: string; amount: number }>(
+        `/account/${accountId}/transactions`,
+        bodyWithoutKey,
+        { idempotencyKey },
+      );
+    },
   };
 }
 

tests/meta/executors/mercury-payment-failures.spec.ts

@@ -242,6 +242,42 @@ describe('chat-surface tool — refuses Mercury payments unconditionally', () =>
   });
 });
 
+describe('mercury-payment — idempotency forwarded as HTTP header (PR #108 review C1)', () => {
+  it('createPayment sends Idempotency-Key as a request header, not just in body', async () => {
+    const captured: { url: string; headers: Headers; bodyText: string }[] = [];
+    const idemKey = 'i'.repeat(64);
+
+    const capturingFetch: typeof fetch = (async (
+      input: RequestInfo | URL,
+      init?: RequestInit,
+    ) => {
+      const req = new Request(input as RequestInfo, init);
+      const bodyText = await req.text();
+      captured.push({ url: req.url, headers: req.headers, bodyText });
+      return new Response(
+        JSON.stringify({ id: 'tx_hdr_001', status: 'sent', amount: 1.0 }),
+        { status: 200, headers: { 'Content-Type': 'application/json' } },
+      );
+    }) as unknown as typeof fetch;
+
+    const run = await runMercuryPayment({
+      env: envFor(KV_WITH_TOKEN),
+      payload: VALID_PAYLOAD,
+      sovereignty: FRESH_ASSESSMENT,
+      idempotencyKey: idemKey,
+      fetchImpl: capturingFetch,
+    });
+
+    expect(run.ok).toBe(true);
+    expect(captured.length).toBeGreaterThan(0);
+    const post = captured.find((c) => c.url.includes('/transactions'));
+    expect(post, 'expected a POST to /transactions to be captured').toBeDefined();
+    // The Idempotency-Key HTTP header is what Mercury uses to dedupe transfers
+    // on transport retry. Without it, a retried POST creates a duplicate ACH.
+    expect(post!.headers.get('Idempotency-Key')).toBe(idemKey);
+  });
+});
+
 // MERCURY_SOVEREIGNTY_FRESHNESS_MS import kept to ensure the constant remains
 // public (other tests / runbook docs reference it).
 void MERCURY_SOVEREIGNTY_FRESHNESS_MS;