fix: reject invalid keyed mutation intents

tests/integration/http-execution-contract.test.ts

@@ -1,10 +1,12 @@
 import { describe, expect, it, vi } from "vitest";
 
 import { createHttpClient } from "../../src/adapters/http/client.ts";
+import { createContractHttpExecutor } from "../../src/adapters/http/http-execution-v3.ts";
 import {
   entityQueryKeys,
   TEST_HTTP_CONTRACT,
 } from "../helpers/http-contract-fixture.ts";
+import { TEST_CREATE_HTTP_CONTRACT } from "../helpers/external-contract-fixture.ts";
 
 function successResponse(data: unknown) {
   return Response.json({
@@ -48,6 +50,79 @@ function testClient(options: HttpDependencies) {
 }
 
 describe("HTTP operation execution contract", () => {
+  it("permits a keyless command intent but rejects an unexpected key before dispatch", async () => {
+    const attachCredentials = vi.fn(() => ({
+      kind: "READY" as const,
+      headers: {},
+      credentials: "omit" as const,
+    }));
+    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(
+          { id: "created", name: "Created" },
+          { status: 201 },
+        );
+      },
+    );
+    const executor = createContractHttpExecutor({
+      baseUrl: "https://api.example/",
+      maxRetryAttempts: 0,
+      attachCredentials,
+      fetcher,
+    });
+    const nonKeyedCommand = {
+      ...TEST_CREATE_HTTP_CONTRACT,
+      contract: {
+        ...TEST_CREATE_HTTP_CONTRACT.contract,
+        retrySemantics: "NEVER" as const,
+        commandRecovery: null,
+      },
+    };
+    const scope = Object.freeze({
+      generation: 1,
+      fingerprint: "scope-1",
+      identities: Object.freeze({}) as never,
+      signal: new AbortController().signal,
+      isCurrent: () => true,
+    });
+    const intent = Object.freeze({
+      intentId: "intent-1",
+      operationId: "TEST_CREATE_ENTITY",
+      canonicalInputIdentity: "opaque-input-identity",
+      createdAtMonotonicMs: 1,
+    });
+
+    await expect(
+      executor.execute(
+        nonKeyedCommand,
+        { name: "created" },
+        { scope, intent },
+      ),
+    ).resolves.toMatchObject({ kind: "SUCCESS" });
+    expect(observedKeys).toEqual([null]);
+
+    attachCredentials.mockClear();
+    fetcher.mockClear();
+    await expect(
+      executor.execute(
+        nonKeyedCommand,
+        { name: "created" },
+        { scope, intent: { ...intent, idempotencyKey: "unexpected-key" } },
+      ),
+    ).resolves.toMatchObject({
+      kind: "CONTRACT_VIOLATION",
+      violation: {
+        kind: "UNEXPECTED_IDEMPOTENCY_KEY",
+        operation: "REQUEST",
+      },
+      effect: "NOT_STARTED",
+    });
+    expect(attachCredentials).not.toHaveBeenCalled();
+    expect(fetcher).not.toHaveBeenCalled();
+  });
+
   it("fails auth-required execution before fetch when the session integration is unavailable", async () => {
     const fetcher = vi.fn();
     const client = testClient({

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

@@ -22,15 +22,19 @@ const createInstalled: InstalledHttpContract<unknown, unknown, unknown> =
   TEST_CREATE_HTTP_CONTRACT;
 
 function mutationIntent(
-  overrides: Readonly<{ intentId?: string; idempotencyKey?: string }> = {},
+  overrides: Readonly<{
+    intentId?: string;
+    operationId?: string;
+    idempotencyKey?: string | null;
+  }> = {},
 ) {
   return Object.freeze({
     intentId: overrides.intentId ?? "intent-1",
-    operationId: "TEST_CREATE_ENTITY",
+    operationId: overrides.operationId ?? "TEST_CREATE_ENTITY",
     canonicalInputIdentity: "opaque-input-identity",
-    ...(overrides.idempotencyKey === undefined
-      ? { idempotencyKey: "key-1" }
-      : { idempotencyKey: overrides.idempotencyKey }),
+    ...(overrides.idempotencyKey === null
+      ? {}
+      : { idempotencyKey: overrides.idempotencyKey ?? "key-1" }),
     createdAtMonotonicMs: 1,
   });
 }
@@ -61,6 +65,85 @@ async function flushMicrotasks(): Promise<void> {
 }
 
 describe("descriptor-driven HTTP execution lifetime", () => {
+  it.each([
+    ["absent intent", () => undefined],
+    ["empty key", () => mutationIntent({ idempotencyKey: "" })],
+    ["control-character key", () => mutationIntent({ idempotencyKey: "key\u0000private" })],
+    ["over-budget key", () => mutationIntent({ idempotencyKey: "k".repeat(257) })],
+    [
+      "wrong operation",
+      () => mutationIntent({ operationId: "TEST_OTHER_COMMAND" }),
+    ],
+  ])(
+    "rejects a KEYED command with %s before credentials or fetch",
+    async (_label, intentFactory) => {
+      const attachCredentials = vi.fn(() => ({
+        kind: "READY" as const,
+        headers: {},
+        credentials: "omit" as const,
+      }));
+      const fetcher = vi.fn();
+      const executor = createContractHttpExecutor({
+        baseUrl: "https://api.example/",
+        maxRetryAttempts: 0,
+        attachCredentials,
+        fetcher,
+      });
+      const intent = intentFactory();
+
+      await expect(
+        executor.execute(
+          createInstalled,
+          { name: "created" },
+          { scope, ...(intent === undefined ? {} : { intent }) },
+        ),
+      ).resolves.toMatchObject({
+        kind: "CONTRACT_VIOLATION",
+        violation: {
+          kind: "MISSING_IDEMPOTENCY_KEY",
+          operation: "REQUEST",
+        },
+        effect: "NOT_STARTED",
+      });
+      expect(attachCredentials).not.toHaveBeenCalled();
+      expect(fetcher).not.toHaveBeenCalled();
+    },
+  );
+
+  it.each([
+    ["an intent without a key", mutationIntent({ idempotencyKey: null })],
+    ["an intent with a key", mutationIntent()],
+  ])(
+    "rejects a query carrying %s before credentials or fetch",
+    async (_label, intent) => {
+      const attachCredentials = vi.fn(() => ({
+        kind: "READY" as const,
+        headers: {},
+        credentials: "omit" as const,
+      }));
+      const fetcher = vi.fn();
+      const executor = createContractHttpExecutor({
+        baseUrl: "https://api.example/",
+        maxRetryAttempts: 0,
+        attachCredentials,
+        fetcher,
+      });
+
+      await expect(
+        executor.execute(installed, { limit: 20 }, { scope, intent }),
+      ).resolves.toMatchObject({
+        kind: "CONTRACT_VIOLATION",
+        violation: {
+          kind: "UNEXPECTED_IDEMPOTENCY_KEY",
+          operation: "REQUEST",
+        },
+        effect: "NOT_STARTED",
+      });
+      expect(attachCredentials).not.toHaveBeenCalled();
+      expect(fetcher).not.toHaveBeenCalled();
+    },
+  );
+
   it("reuses one supplied idempotency key across every physical retry", async () => {
     const observedKeys: Array<string | null> = [];
     let attempt = 0;