create-ailk 0.22.0 → 0.24.0

package/templates/apps/mcp/__tests__/read_content.test.ts

@@ -2,12 +2,19 @@
  * Tests for the read_content MCP tool handler.
  *
  * Acceptance criteria verified here:
- * - readContentInputSchema validates correct inputs (type + slug)
- * - readContentInputSchema rejects unknown type values and malformed slugs
- * - ailkReadContent returns { slug, type, frontmatter, body } for a known slug
- * - ailkReadContent returns null (not throws) for an unknown slug
- * - Output validates against readContentOutputSchema
+ * - contentPageParamsSchema validates correct inputs (type + slug)
+ * - contentPageParamsSchema rejects unknown type values and malformed slugs,
+ *   a leading or trailing hyphen included (the route's grammar)
+ * - ailkReadContent returns the route's document — the page's JSON-LD at the
+ *   root, `page`, and `body` only with `include: "body"` — for a known slug
+ * - ailkReadContent returns the not-found body (not throws) for an unknown slug
+ * - Output validates against contentPageResultSchema
  * - No console.* calls in handler (structural test)
+ *
+ * #7169 (the operator's decision of 2026-10-19): the tool adopted its route's
+ * arguments (`include`) and result (the document, not
+ * `{ slug, type, frontmatter, body } | null`), so the cases below read
+ * `page`/`body` and expect the not-found body where they expected `null`.
  * - #6030 AC-1: BlogPosting and DocsDetail — the two types this issue admits —
  *   are readable through the adapter on both the MDX leg and the database
  *   leg, and both are asserted against the shared adapter seam
@@ -26,9 +33,11 @@ import {
 
 import {
   ailkReadContent,
-  readContentInputSchema,
-  readContentOutputSchema,
+  contentPageParamsSchema,
+  contentPageResultSchema,
+  type ContentPageResult,
 } from "../src/tools/read_content.js";
+import { notFoundError } from "../src/lib/errors.js";
 import {
   __setMcpPublicWorkspaceForTest,
   resetMcpPublicWorkspace,
@@ -38,6 +47,19 @@ const REPO_ROOT = resolve(__dirname, "../../..");
 const CONTENT_ROOT = join(REPO_ROOT, "content");
 const WORKSPACE_ID = "wksp_00000000-0000-7000-8000-000000000001";
 
+/** The body a missing page answers — the route's 404 message, the MCP code. */
+const NOT_FOUND = notFoundError("Page not found");
+
+/** Narrows a tool answer to the document, failing on the not-found body. */
+function document(
+  result: Awaited<ReturnType<typeof ailkReadContent>>,
+): ContentPageResult {
+  if (!("page" in result)) {
+    throw new Error(`read_content answered ${JSON.stringify(result)}`);
+  }
+  return result;
+}
+
 /**
  * A structural `ArtifactPrismaClient` stub (#5876 spec D11) — `artifact` and
  * `artifactVersion` jest.fn()s, injected directly, no database.
@@ -86,9 +108,9 @@ function makeArtifactPrismaClientStub(overrides: {
   };
 }
 
-describe("readContentInputSchema", () => {
+describe("contentPageParamsSchema", () => {
   it("accepts a valid type + slug", () => {
-    const result = readContentInputSchema.safeParse({
+    const result = contentPageParamsSchema.safeParse({
       type: "HomePage",
       slug: "home",
     });
@@ -96,7 +118,7 @@ describe("readContentInputSchema", () => {
   });
 
   it("accepts a HomePage slug", () => {
-    const result = readContentInputSchema.safeParse({
+    const result = contentPageParamsSchema.safeParse({
       type: "HomePage",
       slug: "home",
     });
@@ -104,19 +126,19 @@ describe("readContentInputSchema", () => {
   });
 
   it("rejects missing slug", () => {
-    const result = readContentInputSchema.safeParse({ type: "HomePage" });
+    const result = contentPageParamsSchema.safeParse({ type: "HomePage" });
     expect(result.success).toBe(false);
   });
 
   it("rejects missing type", () => {
-    const result = readContentInputSchema.safeParse({
+    const result = contentPageParamsSchema.safeParse({
       slug: "launching-ailk",
     });
     expect(result.success).toBe(false);
   });
 
   it("rejects an unknown type", () => {
-    const result = readContentInputSchema.safeParse({
+    const result = contentPageParamsSchema.safeParse({
       type: "NotAType",
       slug: "some-slug",
     });
@@ -124,7 +146,7 @@ describe("readContentInputSchema", () => {
   });
 
   it("rejects empty slug", () => {
-    const result = readContentInputSchema.safeParse({
+    const result = contentPageParamsSchema.safeParse({
       type: "HomePage",
       slug: "",
     });
@@ -132,7 +154,7 @@ describe("readContentInputSchema", () => {
   });
 
   it("rejects slug with path traversal characters", () => {
-    const result = readContentInputSchema.safeParse({
+    const result = contentPageParamsSchema.safeParse({
       type: "HomePage",
       slug: "../etc/passwd",
     });
@@ -140,68 +162,84 @@ describe("readContentInputSchema", () => {
   });
 
   it("rejects slug with forward slashes", () => {
-    const result = readContentInputSchema.safeParse({
+    const result = contentPageParamsSchema.safeParse({
       type: "HomePage",
       slug: "some/path",
     });
     expect(result.success).toBe(false);
   });
+
+  // The route's grammar (`SLUG_PATTERN`): no leading or trailing hyphen —
+  // refused here too since #7169 (the tool adopted the API's arguments).
+  it.each(["-a", "a-", "-"])("rejects slug %p (leading or trailing hyphen)", (slug) => {
+    const result = contentPageParamsSchema.safeParse({ type: "HomePage", slug });
+    expect(result.success).toBe(false);
+  });
+
+  it("accepts an interior hyphen", () => {
+    const result = contentPageParamsSchema.safeParse({
+      type: "HomePage",
+      slug: "a-b",
+    });
+    expect(result.success).toBe(true);
+  });
 });
 
 describe("ailkReadContent handler", () => {
-  it("returns slug, type, frontmatter, body for a known HomePage", async () => {
-    const result = await ailkReadContent(
-      { type: "HomePage", slug: "home" },
-      CONTENT_ROOT,
+  it("returns the HomePage document — the @graph envelope and page, no body without include", async () => {
+    const result = document(
+      await ailkReadContent({ type: "HomePage", slug: "home" }, CONTENT_ROOT),
     );
 
-    expect(result).not.toBeNull();
-    expect(result!.slug).toBe("home");
-    expect(result!.type).toBe("HomePage");
-    expect(typeof result!.frontmatter).toBe("object");
-    expect(typeof result!.body).toBe("string");
+    expect(result["@context"]).toBe("https://schema.org");
+    expect(Array.isArray(result["@graph"])).toBe(true);
+    expect(result.page.slug).toBe("home");
+    expect(result.page.type).toBe("HomePage");
+    expect(result).not.toHaveProperty("body");
+  });
+
+  it("attaches the raw MDX body only with include: body (#5890)", async () => {
+    const result = document(
+      await ailkReadContent(
+        { type: "HomePage", slug: "home", include: "body" },
+        CONTENT_ROOT,
+      ),
+    );
+    expect(result.page.slug).toBe("home");
+    expect(typeof result.body).toBe("string");
   });
 
-  it("returns null (not throws) for an unknown slug", async () => {
+  it("returns the not-found body (not throws) for an unknown slug", async () => {
     const result = await ailkReadContent(
       { type: "HomePage", slug: "does-not-exist" },
       CONTENT_ROOT,
     );
-    expect(result).toBeNull();
+    expect(result).toEqual(NOT_FOUND);
   });
 
-  it("returns null for a slug that exists in a different type", async () => {
+  it("returns the not-found body for a slug that exists in a different type", async () => {
     // home.mdx exists under HomePage, not AboutPage
     const result = await ailkReadContent(
       { type: "AboutPage", slug: "home" },
       CONTENT_ROOT,
     );
-    expect(result).toBeNull();
+    expect(result).toEqual(NOT_FOUND);
   });
 
-  it("returns null for a valid type with no files when given an unknown slug", async () => {
+  it("returns the not-found body for a valid type with no files when given an unknown slug", async () => {
     const result = await ailkReadContent(
       { type: "FAQPage", slug: "nonexistent" },
       CONTENT_ROOT,
     );
-    expect(result).toBeNull();
-  });
-
-  it("output shape validates against readContentOutputSchema when non-null", async () => {
-    const result = await ailkReadContent(
-      { type: "HomePage", slug: "home" },
-      CONTENT_ROOT,
-    );
-    const parsed = readContentOutputSchema.safeParse(result);
-    expect(parsed.success).toBe(true);
+    expect(result).toEqual(NOT_FOUND);
   });
 
-  it("null validates against readContentOutputSchema", async () => {
+  it("output shape validates against contentPageResultSchema", async () => {
     const result = await ailkReadContent(
-      { type: "HomePage", slug: "does-not-exist" },
+      { type: "HomePage", slug: "home", include: "body" },
       CONTENT_ROOT,
     );
-    const parsed = readContentOutputSchema.safeParse(result);
+    const parsed = contentPageResultSchema.safeParse(result);
     expect(parsed.success).toBe(true);
   });
 });
@@ -225,7 +263,7 @@ describe("ailkReadContent — CONTENT_ADAPTER=database (#5876)", () => {
     resetResolvedContentAdapter();
   });
 
-  it("AC-1: returns { slug, type, frontmatter, body } for a published page", async () => {
+  it("AC-1: returns the document with page and body for a published page", async () => {
     const stub = makeArtifactPrismaClientStub({
       artifact: { publishedVersionId: "version_1" },
       version: {
@@ -244,12 +282,13 @@ describe("ailkReadContent — CONTENT_ADAPTER=database (#5876)", () => {
       prisma: stub,
     });
 
-    const result = await ailkReadContent({ type: "HomePage", slug: "home" });
+    const result = document(
+      await ailkReadContent({ type: "HomePage", slug: "home", include: "body" }),
+    );
 
-    expect(result).not.toBeNull();
-    expect(result!.slug).toBe("home");
-    expect(result!.type).toBe("HomePage");
-    expect(result!.body).toBe("# Hello");
+    expect(result.page.slug).toBe("home");
+    expect(result.page.type).toBe("HomePage");
+    expect(result.body).toBe("# Hello");
     // The reach test (§5.2 AC-1) — the read is bound to the resolved workspace.
     expect(stub.artifact.findFirst).toHaveBeenCalledWith(
       expect.objectContaining({
@@ -258,7 +297,7 @@ describe("ailkReadContent — CONTENT_ADAPTER=database (#5876)", () => {
     );
   });
 
-  it("AC-1: returns null for a draft-only artifact (no published version)", async () => {
+  it("AC-1: returns the not-found body for a draft-only artifact (no published version)", async () => {
     const stub = makeArtifactPrismaClientStub({
       artifact: { publishedVersionId: null },
     });
@@ -270,10 +309,10 @@ describe("ailkReadContent — CONTENT_ADAPTER=database (#5876)", () => {
 
     const result = await ailkReadContent({ type: "HomePage", slug: "home" });
 
-    expect(result).toBeNull();
+    expect(result).toEqual(NOT_FOUND);
   });
 
-  it("AC-1: returns null for an unknown slug", async () => {
+  it("AC-1: returns the not-found body for an unknown slug", async () => {
     const stub = makeArtifactPrismaClientStub({ artifact: null });
     __setMcpPublicWorkspaceForTest({
       kind: "resolved",
@@ -286,16 +325,16 @@ describe("ailkReadContent — CONTENT_ADAPTER=database (#5876)", () => {
       slug: "does-not-exist",
     });
 
-    expect(result).toBeNull();
+    expect(result).toEqual(NOT_FOUND);
   });
 
-  it("AC-2: returns null when the workspace is unresolved, with no content lookup", async () => {
+  it("AC-2: returns the not-found body when the workspace is unresolved, with no content lookup", async () => {
     const stub = makeArtifactPrismaClientStub({});
     __setMcpPublicWorkspaceForTest({ kind: "unresolved", reason: "ambiguous" });
 
     const result = await ailkReadContent({ type: "HomePage", slug: "home" });
 
-    expect(result).toBeNull();
+    expect(result).toEqual(NOT_FOUND);
     expect(stub.artifact.findFirst).not.toHaveBeenCalled();
   });
 });
@@ -334,10 +373,12 @@ describe("ailkReadContent — BlogPosting and DocsDetail, MDX leg (#6030 AC-1)",
   });
 
   it.each(["BlogPosting", "DocsDetail"] as const)(
-    "returns the page for %s, deep-equal to the projection over getPageSource (D3)",
+    "returns the page for %s, with page and body equal to what getPageSource returns (D3)",
     async (type) => {
       const slug = type === "BlogPosting" ? "launch-post" : "getting-started";
-      const result = await ailkReadContent({ type, slug, locale: "en" }, root);
+      const result = document(
+        await ailkReadContent({ type, slug, locale: "en", include: "body" }, root),
+      );
 
       // The shared seam D3 asserts from both ends: read_content's payload is
       // derived from exactly what ContentAdapter.getPageSource(type, slug,
@@ -345,27 +386,22 @@ describe("ailkReadContent — BlogPosting and DocsDetail, MDX leg (#6030 AC-1)",
       const adapter = createMdxAdapter({ contentRoot: root });
       const source = await adapter.getPageSource(type, slug, "en");
       expect(source).not.toBeNull();
-      const expected = readContentOutputSchema.parse({
-        slug: source!.frontmatter.slug ?? slug,
-        type: source!.frontmatter.type ?? type,
-        frontmatter: source!.frontmatter,
-        body: source!.body,
-      });
 
-      expect(result).toEqual(expected);
-      expect(result!.slug).toBe(slug);
-      expect(result!.type).toBe(type);
+      expect(result.page).toEqual(source!.frontmatter);
+      expect(result.body).toBe(source!.body);
+      expect(result.page.slug).toBe(slug);
+      expect(result.page.type).toBe(type);
     },
   );
 
   it.each(["BlogPosting", "DocsDetail"] as const)(
-    "returns null for an absent slug of %s",
+    "returns the not-found body for an absent slug of %s",
     async (type) => {
       const result = await ailkReadContent(
         { type, slug: "does-not-exist", locale: "en" },
         root,
       );
-      expect(result).toBeNull();
+      expect(result).toEqual(NOT_FOUND);
     },
   );
 });
@@ -386,7 +422,7 @@ describe("ailkReadContent — BlogPosting and DocsDetail, CONTENT_ADAPTER=databa
   });
 
   it.each(["BlogPosting", "DocsDetail"] as const)(
-    "returns { slug, type, frontmatter, body } for a published %s",
+    "returns the document with page and body for a published %s",
     async (type) => {
       const slug = "probe";
       const stub = makeArtifactPrismaClientStub({
@@ -407,19 +443,20 @@ describe("ailkReadContent — BlogPosting and DocsDetail, CONTENT_ADAPTER=databa
         prisma: stub,
       });
 
-      const result = await ailkReadContent({ type, slug });
+      const result = document(
+        await ailkReadContent({ type, slug, include: "body" }),
+      );
 
-      expect(result).not.toBeNull();
-      expect(result!.slug).toBe(slug);
-      expect(result!.type).toBe(type);
-      expect(result!.body).toBe("# Published body");
+      expect(result.page.slug).toBe(slug);
+      expect(result.page.type).toBe(type);
+      expect(result.body).toBe("# Published body");
     },
   );
 
   // D4 — the publication guard must hold for every newly-admitted type, not
   // only HomePage's existing case.
   it.each(["BlogPosting", "DocsDetail"] as const)(
-    "returns null for a draft-only %s artifact (no published version)",
+    "returns the not-found body for a draft-only %s artifact (no published version)",
     async (type) => {
       const stub = makeArtifactPrismaClientStub({
         artifact: { publishedVersionId: null },
@@ -432,13 +469,13 @@ describe("ailkReadContent — BlogPosting and DocsDetail, CONTENT_ADAPTER=databa
 
       const result = await ailkReadContent({ type, slug: "probe" });
 
-      expect(result).toBeNull();
+      expect(result).toEqual(NOT_FOUND);
     },
   );
 
   // D4 — type-as-address: a page stored under a different frontmatter.type
   // than requested reads as absent, never as a cross-type hit.
-  it("returns null when the requested type does not match the stored frontmatter.type", async () => {
+  it("returns the not-found body when the requested type does not match the stored frontmatter.type", async () => {
     const stub = makeArtifactPrismaClientStub({
       artifact: { publishedVersionId: "version_1" },
       version: {
@@ -459,7 +496,7 @@ describe("ailkReadContent — BlogPosting and DocsDetail, CONTENT_ADAPTER=databa
 
     const result = await ailkReadContent({ type: "DocsDetail", slug: "probe" });
 
-    expect(result).toBeNull();
+    expect(result).toEqual(NOT_FOUND);
   });
 });
 

package/templates/apps/mcp/__tests__/request_callback.test.ts

@@ -1,13 +1,15 @@
 /**
  * Tests for the request_callback MCP tool handler.
  *
- * Acceptance criteria verified here:
+ * The tool takes the body `POST /v1/leads/callback` takes — `{ name, phone,
+ * preferredTime?, payload? }` — and returns the route's 201 body (#7173
+ * AC-11 — the tool adopted the API). Verified here:
  * 1. Malformed input → { ok: false, error: { kind: 'invalid_input', issues } }, api-client never called
- * 2. Happy path → forwards to apiClient.leads.callback, returns { ok: true, id, persisted }
- * 3. API 400 → { ok: false, error: { kind: 'api_error', status: 400 } }
- * 4. API 503 → { ok: false, error: { kind: 'api_error', status: 503 } }
- * 5. API 429 → { ok: false, error: { kind: 'api_error', status: 429 } }
- * 6. #8073 — forwards the trusted caller address + AILK_VISITOR_FORWARD_KEY
+ * 2. Happy path → posts exactly the parsed body to apiClient.leads.callback —
+ *    no `siteId`, whatever AILK_SITE_ID says, no stamped `payload: {}` — and
+ *    returns the route's body unchanged, `email` included
+ * 3. API 400 / 503 / 429 → { ok: false, error: { kind: 'api_error', status } }
+ * 4. #8073 — forwards the trusted caller address + AILK_VISITOR_FORWARD_KEY
  *    as the two visitor-forwarding headers only when both are present
  */
 
@@ -29,147 +31,89 @@ jest.mock("@working-theory/api-client", () => {
   };
 });
 
- 
+
 const { apiClient } = require("@working-theory/api-client") as {
   apiClient: { leads: { callback: jest.Mock } };
 };
 
-const VALID_INPUT = {
-  name: "Jane Smith",
-  phone: "+15555550100",
+/** The route body, as an agent sends it — the two required fields alone. */
+const VALID_INPUT = { name: "Jane Smith", phone: "+15555550100" };
+
+/** The route's 201 body, as the api-client hands it back. */
+const WIRE = {
+  id: "fallback-1700000000000-cb1",
+  persisted: "file",
+  email: { ok: false, error: "provider refused" },
 };
 
 beforeEach(() => {
   jest.clearAllMocks();
+  delete process.env.AILK_SITE_ID;
 });
 
 describe("ailkRequestCallback — input validation", () => {
-  it("rejects malformed input (missing required fields) without calling api-client", async () => {
-    const result = await ailkRequestCallback({} as never);
-
-    expect(result.ok).toBe(false);
-    if (!result.ok) {
-      expect(result.error.kind).toBe("invalid_input");
-      if (result.error.kind === "invalid_input") {
-        expect(Array.isArray(result.error.issues)).toBe(true);
-        expect(result.error.issues.length).toBeGreaterThan(0);
-      }
+  it.each([
+    ["missing required fields", {}],
+    ["a phone under the route's bound", { name: "Jane", phone: "12" }],
+  ])("rejects %s without calling api-client", async (_label, input) => {
+    const result = await ailkRequestCallback(input as never);
+
+    expect(result).toMatchObject({ ok: false, error: { kind: "invalid_input" } });
+    if (!result.ok && result.error.kind === "invalid_input") {
+      expect(result.error.issues.length).toBeGreaterThan(0);
     }
     expect(apiClient.leads.callback).not.toHaveBeenCalled();
   });
 });
 
 describe("ailkRequestCallback — happy path", () => {
-  it("forwards canonical body to api-client and returns ok:true with id and persisted", async () => {
-    apiClient.leads.callback.mockResolvedValueOnce({
-      ok: true,
-      body: { id: "fallback-1700000000000-cb1", persisted: "file" },
-    });
+  it("posts exactly the parsed body — no stamped payload — and returns the route's body unchanged, email included", async () => {
+    apiClient.leads.callback.mockResolvedValueOnce({ ok: true, body: WIRE });
 
     const result = await ailkRequestCallback(VALID_INPUT);
 
-    expect(apiClient.leads.callback).toHaveBeenCalledWith({
-      siteId: "default",
-      name: "Jane Smith",
-      phone: "+15555550100",
-      payload: {},
-    });
-    expect(result.ok).toBe(true);
-    if (result.ok) {
-      expect(result.id).toBe("fallback-1700000000000-cb1");
-      expect(result.persisted).toBe("file");
-    }
-  });
-});
-
-describe("ailkRequestCallback — API error mapping", () => {
-  it("maps API 400 to { ok: false, error: { kind: 'api_error', status: 400 } }", async () => {
-    apiClient.leads.callback.mockResolvedValueOnce({
-      ok: false,
-      status: 400,
-      body: { error: "bad_request" },
-    });
-
-    const result = await ailkRequestCallback(VALID_INPUT);
-
-    expect(result.ok).toBe(false);
-    if (!result.ok) {
-      expect(result.error.kind).toBe("api_error");
-      if (result.error.kind === "api_error") {
-        expect(result.error.status).toBe(400);
-      }
-    }
-  });
-
-  it("maps API 503 to { ok: false, error: { kind: 'api_error', status: 503 } }", async () => {
-    apiClient.leads.callback.mockResolvedValueOnce({
-      ok: false,
-      status: 503,
-      body: { error: "service_unavailable" },
-    });
-
-    const result = await ailkRequestCallback(VALID_INPUT);
-
-    expect(result.ok).toBe(false);
-    if (!result.ok) {
-      expect(result.error.kind).toBe("api_error");
-      if (result.error.kind === "api_error") {
-        expect(result.error.status).toBe(503);
-      }
-    }
+    expect(apiClient.leads.callback).toHaveBeenCalledWith(VALID_INPUT);
+    expect(result).toEqual(WIRE);
   });
 
-  it("maps API 429 to { ok: false, error: { kind: 'api_error', status: 429 } }", async () => {
-    apiClient.leads.callback.mockResolvedValueOnce({
-      ok: false,
-      status: 429,
-      body: { error: "rate_limited" },
-    });
+  it("passes preferredTime and payload through as sent", async () => {
+    apiClient.leads.callback.mockResolvedValueOnce({ ok: true, body: WIRE });
+    const full = {
+      ...VALID_INPUT,
+      preferredTime: "Tuesday afternoon",
+      payload: { notes: "Roof estimate" },
+    };
 
-    const result = await ailkRequestCallback(VALID_INPUT);
+    await ailkRequestCallback(full);
 
-    expect(result.ok).toBe(false);
-    if (!result.ok) {
-      expect(result.error.kind).toBe("api_error");
-      if (result.error.kind === "api_error") {
-        expect(result.error.status).toBe(429);
-      }
-    }
+    expect(apiClient.leads.callback).toHaveBeenCalledWith(full);
   });
-});
 
-describe("ailkRequestCallback — siteId default", () => {
-  it("uses siteId 'default' when AILK_SITE_ID is unset", async () => {
-    delete process.env.AILK_SITE_ID;
-    apiClient.leads.callback.mockResolvedValueOnce({
-      ok: true,
-      body: { id: "fallback-1700000000000-cb2", persisted: "file" },
-    });
+  it("never sends a siteId, whatever AILK_SITE_ID says, and strips one the agent sent", async () => {
+    process.env.AILK_SITE_ID = "site-abc";
+    apiClient.leads.callback.mockResolvedValueOnce({ ok: true, body: WIRE });
 
-    await ailkRequestCallback(VALID_INPUT);
+    await ailkRequestCallback({ ...VALID_INPUT, siteId: "site-xyz" } as never);
 
-    const call = apiClient.leads.callback.mock.calls[0][0] as { siteId: string };
-    expect(call.siteId).toBe("default");
+    expect(apiClient.leads.callback.mock.calls[0][0]).toEqual(VALID_INPUT);
   });
 });
 
-describe("ailkRequestCallback — siteId override", () => {
-  afterEach(() => {
-    delete process.env.AILK_SITE_ID;
-  });
-
-  it("uses AILK_SITE_ID env var when set", async () => {
-    process.env.AILK_SITE_ID = "site-abc";
-    apiClient.leads.callback.mockResolvedValueOnce({
-      ok: true,
-      body: { id: "fallback-1700000000000-cb3", persisted: "file" },
-    });
-
-    await ailkRequestCallback(VALID_INPUT);
-
-    const call = apiClient.leads.callback.mock.calls[0][0] as { siteId: string };
-    expect(call.siteId).toBe("site-abc");
-  });
+describe("ailkRequestCallback — API error mapping", () => {
+  it.each([400, 503, 429])(
+    "maps API %i to { ok: false, error: { kind: 'api_error', status } }",
+    async (status) => {
+      apiClient.leads.callback.mockResolvedValueOnce({
+        ok: false,
+        status,
+        body: { error: "refused" },
+      });
+
+      const result = await ailkRequestCallback(VALID_INPUT);
+
+      expect(result).toEqual({ ok: false, error: { kind: "api_error", status } });
+    },
+  );
 });
 
 describe("ailkRequestCallback — visitor-forwarding headers (#8073)", () => {
@@ -178,10 +122,7 @@ describe("ailkRequestCallback — visitor-forwarding headers (#8073)", () => {
   });
 
   it("calls api-client with exactly one argument when there is no trusted address", async () => {
-    apiClient.leads.callback.mockResolvedValueOnce({
-      ok: true,
-      body: { id: "fallback-1700000000000-e1", persisted: "file" },
-    });
+    apiClient.leads.callback.mockResolvedValueOnce({ ok: true, body: WIRE });
     process.env.AILK_VISITOR_FORWARD_KEY = "spoke-key";
 
     await ailkRequestCallback(VALID_INPUT);
@@ -190,10 +131,7 @@ describe("ailkRequestCallback — visitor-forwarding headers (#8073)", () => {
   });
 
   it("forwards the trusted address and the forward key as the two visitor headers", async () => {
-    apiClient.leads.callback.mockResolvedValueOnce({
-      ok: true,
-      body: { id: "fallback-1700000000000-e2", persisted: "file" },
-    });
+    apiClient.leads.callback.mockResolvedValueOnce({ ok: true, body: WIRE });
     process.env.AILK_VISITOR_FORWARD_KEY = "spoke-key";
 
     await trustedCallerAddress.run("203.0.113.9", () =>
@@ -210,10 +148,7 @@ describe("ailkRequestCallback — visitor-forwarding headers (#8073)", () => {
   });
 
   it("sends no headers when there is a trusted address but no forward key", async () => {
-    apiClient.leads.callback.mockResolvedValueOnce({
-      ok: true,
-      body: { id: "fallback-1700000000000-e3", persisted: "file" },
-    });
+    apiClient.leads.callback.mockResolvedValueOnce({ ok: true, body: WIRE });
     delete process.env.AILK_VISITOR_FORWARD_KEY;
 
     await trustedCallerAddress.run("203.0.113.9", () =>