@codespar/cli 0.14.0 → 0.16.0

package/templates/collections-agent/packages/agent-runtime/test/whatsapp-cloud-api.test.ts

@@ -0,0 +1,232 @@
+/**
+ * The official backend, without Meta.
+ *
+ * Nothing here reaches the network. What is driven is the half where a
+ * mistake is silent: the signature check (a wrong one that passes is an open
+ * webhook), the webhook parse (a shape misread is a message never answered),
+ * the verification handshake, and the request builder. The send itself is one
+ * `fetch` over a request these functions built, and the one test that touches
+ * `deliver` injects a fetch that asserts what it was handed — so a regression
+ * that started calling Meta would fail here instead of dialling out.
+ *
+ * The shapes come from Meta's published documentation. Nobody on this repo
+ * has a Business account, so none of this has been run against Meta, and the
+ * README says so in those words rather than implying otherwise.
+ */
+import { createHmac } from "node:crypto";
+import { describe, expect, it } from "vitest";
+import {
+  buildSendRequest,
+  isMetaBaseUrl,
+  loadCloudApiConfig,
+  parseInbound,
+  verifyChallenge,
+  verifyWebhookSignature,
+  WhatsAppCloudApi,
+  type CloudApiConfig,
+} from "../src/channels/whatsapp/cloud-api.js";
+
+const CONFIG: CloudApiConfig = {
+  baseUrl: "https://graph.facebook.com",
+  phoneNumberId: "111222333",
+  accessToken: "test-token-not-a-credential",
+  verifyToken: "verify-me",
+  appSecret: "app-secret-for-the-test",
+  apiVersion: "v21.0",
+  webhookPort: 3111,
+};
+
+const sign = (body: string, secret = CONFIG.appSecret) => `sha256=${createHmac("sha256", secret).update(body, "utf8").digest("hex")}`;
+
+describe("credentials are absent by default", () => {
+  it("names every variable that is missing rather than saying 'misconfigured'", () => {
+    const { config, missing } = loadCloudApiConfig({});
+    expect(config).toBeUndefined();
+    expect(missing).toEqual(["WHATSAPP_PHONE_NUMBER_ID", "WHATSAPP_ACCESS_TOKEN", "WHATSAPP_VERIFY_TOKEN", "WHATSAPP_APP_SECRET"]);
+  });
+
+  it("treats an empty value as absent: a commented-out .env.example must not half-configure a channel", () => {
+    const { config, missing } = loadCloudApiConfig({ WHATSAPP_PHONE_NUMBER_ID: "  ", WHATSAPP_ACCESS_TOKEN: "", WHATSAPP_VERIFY_TOKEN: "v", WHATSAPP_APP_SECRET: "s" });
+    expect(config).toBeUndefined();
+    expect(missing).toEqual(["WHATSAPP_PHONE_NUMBER_ID", "WHATSAPP_ACCESS_TOKEN"]);
+  });
+
+  it("defaults the version, the port and Meta's own host, and nothing else", () => {
+    const { config } = loadCloudApiConfig({ WHATSAPP_PHONE_NUMBER_ID: "1", WHATSAPP_ACCESS_TOKEN: "2", WHATSAPP_VERIFY_TOKEN: "3", WHATSAPP_APP_SECRET: "4" });
+    expect(config?.apiVersion).toBe("v21.0");
+    expect(config?.webhookPort).toBe(3111);
+    expect(config?.baseUrl).toBe("https://graph.facebook.com");
+  });
+});
+
+describe("live is decided by the base URL, and only by it", () => {
+  it("is Meta's host and nothing that merely looks like it", () => {
+    expect(isMetaBaseUrl("https://graph.facebook.com")).toBe(true);
+    expect(isMetaBaseUrl("https://graph.facebook.com/")).toBe(true);
+    expect(isMetaBaseUrl("http://127.0.0.1:4290")).toBe(false);
+    expect(isMetaBaseUrl("https://graph.facebook.com.evil.test")).toBe(false);
+    expect(isMetaBaseUrl("not a url")).toBe(false);
+  });
+
+  it("names itself `emulator` and reports `live: false` off Meta, which is what the evidence builder refuses on", () => {
+    const options = { conversation: { contact: "+5511987654321" }, say: () => undefined, fetchImpl: async () => new Response("{}") };
+    const emulator = new WhatsAppCloudApi({ ...options, config: { ...CONFIG, baseUrl: "http://127.0.0.1:4290" } });
+    expect(emulator.live).toBe(false);
+    expect(emulator.name).toBe("emulator");
+    const meta = new WhatsAppCloudApi({ ...options, config: CONFIG });
+    expect(meta.live).toBe(true);
+    expect(meta.name).toBe("cloud-api");
+  });
+
+  it("builds the send against whichever base URL it was given, with the path unchanged", () => {
+    const request = buildSendRequest({ ...CONFIG, baseUrl: "http://127.0.0.1:4290", apiVersion: "v22.0" }, "+5511987654321", { kind: "text", text: "oi" });
+    if ("unsupported" in request) throw new Error("expected a request");
+    expect(request.url).toBe("http://127.0.0.1:4290/v22.0/111222333/messages");
+  });
+});
+
+describe("a delivery is trusted only when it is signed", () => {
+  const body = JSON.stringify({ object: "whatsapp_business_account" });
+
+  it("accepts the app secret's own signature over the RAW body", () => {
+    expect(verifyWebhookSignature(CONFIG.appSecret, sign(body), body)).toEqual({ ok: true });
+  });
+
+  it("refuses a body that was re-serialized: the signature is over bytes", () => {
+    const reserialized = JSON.stringify(JSON.parse(body), null, 2);
+    expect(verifyWebhookSignature(CONFIG.appSecret, sign(body), reserialized).ok).toBe(false);
+  });
+
+  it("refuses another secret, a missing header and a malformed one", () => {
+    expect(verifyWebhookSignature(CONFIG.appSecret, sign(body, "someone-else"), body).ok).toBe(false);
+    expect(verifyWebhookSignature(CONFIG.appSecret, undefined, body)).toEqual({ ok: false, reason: "missing X-Hub-Signature-256" });
+    expect(verifyWebhookSignature(CONFIG.appSecret, "sha1=abc", body).ok).toBe(false);
+    expect(verifyWebhookSignature(CONFIG.appSecret, "nonsense", body).ok).toBe(false);
+  });
+});
+
+describe("the registration handshake", () => {
+  it("echoes the challenge for the right verify token", () => {
+    expect(verifyChallenge(CONFIG, { "hub.mode": "subscribe", "hub.verify_token": "verify-me", "hub.challenge": "12345" })).toEqual({ status: 200, body: "12345" });
+  });
+
+  it("refuses a wrong token and a wrong mode", () => {
+    expect(verifyChallenge(CONFIG, { "hub.mode": "subscribe", "hub.verify_token": "nope", "hub.challenge": "1" }).status).toBe(403);
+    expect(verifyChallenge(CONFIG, { "hub.mode": "unsubscribe", "hub.verify_token": "verify-me" }).status).toBe(400);
+  });
+});
+
+describe("reading what Meta delivers", () => {
+  const delivery = {
+    object: "whatsapp_business_account",
+    entry: [
+      {
+        changes: [
+          {
+            field: "messages",
+            value: {
+              messaging_product: "whatsapp",
+              metadata: { phone_number_id: "111222333" },
+              messages: [
+                { id: "wamid.HBgNNTUxMTk4NzY1NDMyMRUCABIYEjND", from: "5511987654321", timestamp: "1758643200", type: "text", text: { body: "fechado, pago à vista" } },
+                { id: "wamid.SECOND", from: "5511987654321", timestamp: "1758643260", type: "image", image: { id: "media_1" } },
+              ],
+            },
+          },
+        ],
+      },
+    ],
+  };
+
+  it("reads the text messages and puts the plus back on the number", () => {
+    const { messages } = parseInbound(delivery);
+    expect(messages).toEqual([{ id: "wamid.HBgNNTUxMTk4NzY1NDMyMRUCABIYEjND", from: "+5511987654321", text: "fechado, pago à vista", timestamp: 1758643200 }]);
+  });
+
+  it("names what it dropped instead of turning it into an empty message", () => {
+    expect(parseInbound(delivery).ignored).toEqual([{ id: "wamid.SECOND", type: "image" }]);
+  });
+
+  it("reads a delivery that carries only status updates as no messages", () => {
+    expect(parseInbound({ entry: [{ changes: [{ value: { statuses: [{ id: "wamid.X", status: "delivered" }] } }] }] }).messages).toEqual([]);
+    expect(parseInbound({}).messages).toEqual([]);
+  });
+});
+
+describe("the request that would go to Meta", () => {
+  it("builds the documented /messages call for a text", () => {
+    const request = buildSendRequest(CONFIG, "+5511987654321", { kind: "text", text: "Oi, Joana!" });
+    expect("unsupported" in request).toBe(false);
+    if ("unsupported" in request) return;
+    expect(request.url).toBe("https://graph.facebook.com/v21.0/111222333/messages");
+    expect(request.headers["authorization"]).toBe("Bearer test-token-not-a-credential");
+    expect(JSON.parse(request.body)).toEqual({ messaging_product: "whatsapp", recipient_type: "individual", to: "5511987654321", type: "text", text: { preview_url: false, body: "Oi, Joana!" } });
+  });
+
+  it("sends a copy-and-paste as its own plain text message: a code inside a paragraph cannot be tapped", () => {
+    const request = buildSendRequest(CONFIG, "+5511987654321", { kind: "instrument", instrument: "pix_copy_paste", value: "00020126580014br.gov.bcb.pix" });
+    if ("unsupported" in request) throw new Error("expected a request");
+    expect(JSON.parse(request.body).text.body).toBe("00020126580014br.gov.bcb.pix");
+  });
+
+  it("builds a template with its body parameters", () => {
+    const request = buildSendRequest(CONFIG, "+5511987654321", { kind: "template", template: "cobranca_lembrete", language: "pt_BR", variables: ["Joana", "1042"] });
+    if ("unsupported" in request) throw new Error("expected a request");
+    expect(JSON.parse(request.body).template).toEqual({
+      name: "cobranca_lembrete",
+      language: { code: "pt_BR" },
+      components: [{ type: "body", parameters: [{ type: "text", text: "Joana" }, { type: "text", text: "1042" }] }],
+    });
+  });
+
+  it("says outright that it cannot send an image, instead of pretending", () => {
+    expect(buildSendRequest(CONFIG, "+5511987654321", { kind: "media", media: "qr", data: "00020126" })).toEqual({ unsupported: "media_upload_unimplemented" });
+  });
+});
+
+describe("deliver, with the network replaced by an assertion", () => {
+  it("posts the request the builder produced and returns the provider's message id", async () => {
+    const calls: Array<{ url: string; init: RequestInit | undefined }> = [];
+    const backend = new WhatsAppCloudApi({
+      config: CONFIG,
+      conversation: { contact: "+5511987654321" },
+      say: () => undefined,
+      fetchImpl: async (url, init) => {
+        calls.push({ url: String(url), init });
+        return new Response(JSON.stringify({ messages: [{ id: "wamid.SENT" }] }), { status: 200 });
+      },
+    });
+    const sent = await backend.deliver("+5511987654321", { kind: "text", text: "Oi!" });
+    expect(sent).toEqual({ id: "wamid.SENT", state: "sent" });
+    expect(calls).toHaveLength(1);
+    expect(calls[0]!.url).toBe("https://graph.facebook.com/v21.0/111222333/messages");
+  });
+
+  it("refuses an image without reaching for the network at all", async () => {
+    let called = false;
+    const backend = new WhatsAppCloudApi({
+      config: CONFIG,
+      conversation: { contact: "+5511987654321" },
+      say: () => undefined,
+      fetchImpl: async () => {
+        called = true;
+        return new Response("{}", { status: 200 });
+      },
+    });
+    const sent = await backend.deliver("+5511987654321", { kind: "media", media: "qr", data: "00020126" });
+    expect(sent.refused?.rule).toBe("media_upload_unimplemented");
+    expect(called).toBe(false);
+  });
+
+  it("reports a provider refusal as a failure and never as a send", async () => {
+    const backend = new WhatsAppCloudApi({
+      config: CONFIG,
+      conversation: { contact: "+5511987654321" },
+      say: () => undefined,
+      fetchImpl: async () => new Response(JSON.stringify({ error: { message: "Invalid parameter" } }), { status: 400 }),
+    });
+    const sent = await backend.deliver("+5511987654321", { kind: "text", text: "Oi!" });
+    expect(sent.state).toBe("failed");
+    expect(sent.refused?.rule).toBe("provider_refused");
+  });
+});

package/templates/collections-agent/packages/agent-runtime/test/whatsapp-emulator.integration.test.ts

@@ -0,0 +1,204 @@
+/**
+ * What the emulator does, measured rather than assumed — and what it does NOT
+ * do, which is the more useful half.
+ *
+ * These run against `dyvit-wa-sim` (https://github.com/fabianocruz/whatsapp-simulator,
+ * MIT) at the version `scripts/whatsapp-emulator.mjs` pins. They SKIP when it is
+ * not listening, so `npm test` is green on a machine that never started it; the
+ * CI starts it, and `npm run whatsapp:gate` fails loudly rather than skipping,
+ * so nothing important hides behind a skip.
+ *
+ * Two kinds of assertion live here and they are not the same thing.
+ *
+ *   What the emulator gets RIGHT, which our adapter depends on: the Cloud API
+ *   response shape, the signed webhook, the controllable clock. If one of these
+ *   breaks, our channel breaks.
+ *
+ *   What the emulator does NOT do, which our channel has to cover itself. Those
+ *   assertions are written to FAIL the day the emulator closes the gap — which
+ *   is what we want, because the pin means it can only change when we move it,
+ *   and the failure is the notification. They are a spec for the repo's owner,
+ *   not a complaint: `docs/OPEN_QUESTIONS.md` §46 carries the same list in
+ *   prose with the payloads.
+ */
+import { describe, expect, it } from "vitest";
+import { EmulatorDriver } from "../src/channels/whatsapp/emulator.js";
+import { buildSendRequest, type CloudApiConfig } from "../src/channels/whatsapp/cloud-api.js";
+
+const URL_BASE = process.env["WHATSAPP_SIM_URL"] ?? "http://127.0.0.1:4290";
+
+/**
+ * Probed at MODULE level, not in a `beforeAll`: `describe.skipIf` is read when
+ * the file is collected, which is before any hook has run, so a flag set in a
+ * hook would skip every case on a machine where the emulator is up.
+ */
+const up = await (async () => {
+  try {
+    return (await fetch(`${URL_BASE}/health`, { signal: AbortSignal.timeout(2000) })).ok;
+  } catch {
+    return false;
+  }
+})();
+if (!up) process.stderr.write(`[whatsapp] no emulator at ${URL_BASE}; its integration cases are skipped. Start it with \`npm run whatsapp:emulator\`.\n`);
+
+/** A fresh phone-number id per case, because the emulator keys a conversation on it. */
+const pnid = () => `9${String(Math.floor(Math.random() * 1e11)).padStart(11, "0")}`;
+const TO = "5511987654321";
+
+const config = (phoneNumberId: string): CloudApiConfig => ({
+  baseUrl: URL_BASE,
+  phoneNumberId,
+  accessToken: "emulator",
+  verifyToken: "emulator",
+  appSecret: "dev",
+  apiVersion: "v22.0",
+  webhookPort: 0,
+});
+
+async function send(phoneNumberId: string, body: Parameters<typeof buildSendRequest>[2]) {
+  const request = buildSendRequest(config(phoneNumberId), `+${TO}`, body);
+  if ("unsupported" in request) return { status: 0, unsupported: request.unsupported, body: null as unknown };
+  const response = await fetch(request.url, { method: request.method, headers: request.headers, body: request.body });
+  return { status: response.status, unsupported: null, body: (await response.json()) as Record<string, unknown> };
+}
+
+async function raw(path: string, init?: RequestInit) {
+  const response = await fetch(`${URL_BASE}${path}`, init);
+  return { status: response.status, body: (await response.json().catch(() => null)) as Record<string, unknown> | null };
+}
+
+describe.skipIf(!up)("what our adapter depends on, and the emulator provides", () => {
+  it("answers our text send with the Cloud API's own response shape", async () => {
+    const id = pnid();
+    const result = await send(id, { kind: "text", text: "Oi, Joana!" });
+    expect(result.status).toBe(200);
+    expect(result.body).toMatchObject({ messaging_product: "whatsapp" });
+    const messages = (result.body as { messages: Array<{ id: string; message_status: string }> }).messages;
+    expect(messages[0]!.id).toMatch(/^wamid\./);
+    expect(messages[0]!.message_status).toBe("accepted");
+  });
+
+  it("takes the Pix copy-and-paste as a plain text message: the string that pays goes through unchanged", async () => {
+    const brcode = "00020126580014br.gov.bcb.pix0136stub-chg_abc5204000053039865802BR5909CODESPAR6009SAO PAULO62070503***6304STUB";
+    const result = await send(pnid(), { kind: "instrument", instrument: "pix_copy_paste", value: brcode });
+    expect(result.status).toBe(200);
+  });
+
+  it("takes a template with its body parameters", async () => {
+    const result = await send(pnid(), { kind: "template", template: "cobranca_lembrete", language: "pt_BR", variables: ["Joana"] });
+    expect(result.status).toBe(200);
+  });
+
+  it("has a conversation clock we can pin and move, which is the only way a 24h window ever closes in a replay", async () => {
+    const driver = new EmulatorDriver(URL_BASE);
+    const pinned = (await driver.pin(new Date("2026-09-23T17:00:00.000Z"))) as { now: string };
+    expect(pinned.now).toBe("2026-09-23T17:00:00.000Z");
+    const moved = (await driver.advanceHours(26)) as { now: string };
+    expect(Date.parse(moved.now) - Date.parse(pinned.now)).toBeGreaterThanOrEqual(26 * 3600 * 1000);
+  });
+
+  it("delivers an inbound message as a webhook our own parser reads", async () => {
+    const id = pnid();
+    const driver = new EmulatorDriver(URL_BASE);
+    await driver.inbound({ phoneNumberId: id, from: `+${TO}`, text: "oi, recebi a mensagem" });
+    const { body } = await raw("/_sim/webhooks");
+    const deliveries = (body as { deliveries: Array<{ body: unknown }> }).deliveries;
+    const mine = deliveries.map((d) => d.body).filter((b) => JSON.stringify(b).includes(id));
+    expect(mine.length).toBeGreaterThan(0);
+  });
+});
+
+/**
+ * The gaps. Each one is the exact payload that failed, so the assertion doubles
+ * as the report. They are written against the PINNED sha: a green run here
+ * means the gap is still open, and a red one means it was closed and our own
+ * cover for it can be reconsidered.
+ */
+describe.skipIf(!up)("what the emulator does not do, measured", () => {
+  it("GAP: accepts a free-form message outside the 24h window that Meta refuses with 131047 — and it already knows", async () => {
+    const id = pnid();
+    const driver = new EmulatorDriver(URL_BASE);
+    await driver.pin(new Date("2026-09-23T17:00:00.000Z"));
+    await driver.inbound({ phoneNumberId: id, from: `+${TO}`, text: "oi" });
+    expect((await send(id, { kind: "text", text: "dentro da janela" })).status).toBe(200);
+
+    await driver.advanceHours(26);
+    const outside = await send(id, { kind: "text", text: "Recebemos, acordo quitado." });
+    // The real Cloud API answers 400 with error 131047 and sends nothing.
+    expect(outside.status).toBe(200);
+
+    // And this is what makes it a one-line fix rather than a feature: the
+    // pricing engine has ALREADY decided the message is invalid there.
+    const state = (await raw(`/_sim/state?key=${id}:${TO}`)).body as {
+      messages: Array<{ id: string }>;
+      priced: { byMessageId: Record<string, { reasonCode: string }> };
+    };
+    const last = state.messages[state.messages.length - 1]!;
+    expect(state.priced.byMessageId[last.id]!.reasonCode).toBe("INVALID_NON_TEMPLATE_OUTSIDE_CSW");
+  });
+
+  it("GAP: has no way to redeliver or reorder a webhook, so duplicate and out-of-order delivery cannot be driven", async () => {
+    for (const path of ["/_sim/replay", "/_sim/webhooks/replay", "/_sim/redeliver"]) {
+      const { status } = await raw(path, { method: "POST", headers: { "content-type": "application/json" }, body: "{}" });
+      expect(status, path).toBe(404);
+    }
+    // `GET /_sim/webhooks` is a read-only log; nothing re-dispatches from it.
+    const { status, body } = await raw("/_sim/webhooks");
+    expect(status).toBe(200);
+    expect(Array.isArray((body as { deliveries: unknown[] }).deliveries)).toBe(true);
+  });
+
+  it("GAP: an inbound interactive reply degrades to an empty text message, so a debtor cannot tap a button", async () => {
+    const id = pnid();
+    const { status, body } = await raw("/_sim/inbound", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        phone_number_id: id,
+        from: `+${TO}`,
+        type: "interactive",
+        interactive: { type: "button_reply", button_reply: { id: "avista", title: "À vista" } },
+      }),
+    });
+    expect(status).toBe(200);
+    const message = (body as { message: { contentType: string; bodyPreview: string } }).message;
+    // The interactive payload is dropped: outbound buttons work, the reply to one does not exist.
+    expect(message.contentType).toBe("text");
+    expect(message.bodyPreview).toBe("");
+  });
+
+  it("GAP: only `sent` and `delivered` are ever emitted, so a channel cannot observe a read receipt or a failure", async () => {
+    const id = pnid();
+    await send(id, { kind: "text", text: "uma mensagem" });
+    const { body } = await raw("/_sim/webhooks");
+    const statuses = (body as { deliveries: Array<{ body: unknown }> }).deliveries
+      .map((d) => d.body as { entry?: Array<{ id?: string; changes?: Array<{ value?: { statuses?: Array<{ status: string }> } }> }> })
+      .filter((b) => b.entry?.[0]?.id === id)
+      .flatMap((b) => b.entry?.[0]?.changes?.[0]?.value?.statuses ?? [])
+      .map((s) => s.status);
+    expect(statuses).toEqual(["sent", "delivered"]);
+  });
+
+  it("GAP: a `+` on one side and none on the other splits one person into two conversations", async () => {
+    const id = pnid();
+    const driver = new EmulatorDriver(URL_BASE);
+    // Our driver strips the `+` precisely to avoid this; done by hand here, it splits.
+    await raw("/_sim/inbound", {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({ phone_number_id: id, from: `+${TO}`, text: "oi" }),
+    });
+    await send(id, { kind: "text", text: "resposta" });
+    const miss = await raw(`/_sim/state?key=${id}:not-a-conversation`);
+    const keys = (miss.body as { keys: string[] }).keys;
+    expect(keys).toContain(`${id}:+${TO}`);
+    expect(keys).toContain(`${id}:${TO}`);
+
+    // With our driver, which strips it, there is one conversation and the window opens.
+    const same = pnid();
+    await driver.inbound({ phoneNumberId: same, from: `+${TO}`, text: "oi" });
+    await send(same, { kind: "text", text: "resposta" });
+    const keysAfter = ((await raw(`/_sim/state?key=${same}:not-a-conversation`)).body as { keys: string[] }).keys;
+    expect(keysAfter.filter((k) => k.startsWith(`${same}:`))).toEqual([`${same}:${TO}`]);
+  });
+});

package/templates/collections-agent/packages/agent-runtime/test/whatsapp-evidence.test.ts

@@ -0,0 +1,94 @@
+/**
+ * Decision 19a: `attestation.evidence` on the consent submit, built from what
+ * a conversation channel can honestly say it observed (ent#1615).
+ *
+ * The first test is the important one and it asserts a REFUSAL. A simulated
+ * conversation was observed by nobody, and signing a counter as a provider
+ * message id would put a made-up fact inside a record whose whole value is
+ * that it is observed. The seam is wired; the simulator declines to use it.
+ *
+ * The rest hold the shape to the API's own rule, so a change here fails in
+ * the repo instead of failing as a 400 at the consent submit.
+ */
+import { describe, expect, it } from "vitest";
+import { evidenceFor, WHATSAPP_EVIDENCE_KEYS } from "../src/channels/whatsapp/evidence.js";
+import type { InboundMessage } from "../src/channels/types.js";
+
+const AT = (iso: string) => Math.floor(Date.parse(iso) / 1000);
+const NOW = () => new Date("2026-09-23T17:00:00Z");
+const REAL: InboundMessage = {
+  id: "wamid.HBgNNTUxMTk4NzY1NDMyMRUCABIYEjND",
+  from: "+5511987654321",
+  text: "sim, autorizo",
+  timestamp: AT("2026-09-23T17:00:00Z"),
+};
+
+describe("what an emulated conversation may attest", () => {
+  it("refuses, and says why in a sentence somebody can act on", () => {
+    const result = evidenceFor({ live: false, message: { ...REAL, id: "wamid.sim.9f1c" }, now: NOW });
+    expect(result.attestable).toBe(false);
+    if (result.attestable) return;
+    expect(result.reason).toContain("emulator");
+    expect(result.reason).toContain("no phone was involved");
+  });
+
+  it("refuses even when the emulated message wears a provider-shaped id, because the id is not what decides", () => {
+    expect(evidenceFor({ live: false, message: REAL, now: NOW }).attestable).toBe(false);
+  });
+});
+
+describe("what a live conversation attests", () => {
+  it("builds the submit's attestation with the four keys the whatsapp channel may carry", () => {
+    const result = evidenceFor({ live: true, message: REAL, sessionId: "conv_1042", reference: "acordo-1042", now: NOW });
+    expect(result.attestable).toBe(true);
+    if (!result.attestable) return;
+    expect(result.attestation).toEqual({
+      method: "partner_session",
+      asserted_at: AT("2026-09-23T17:00:00Z"),
+      reference: "acordo-1042",
+      evidence: {
+        channel: "whatsapp",
+        contact: "+5511987654321",
+        message_id: "wamid.HBgNNTUxMTk4NzY1NDMyMRUCABIYEjND",
+        session_id: "conv_1042",
+        provider_ts: AT("2026-09-23T17:00:00Z"),
+      },
+    });
+  });
+
+  it("carries the contact in the clear, because the API hashes it under a key a partner cannot compute", () => {
+    const result = evidenceFor({ live: true, message: REAL, now: NOW });
+    if (!result.attestable) throw new Error("expected evidence");
+    expect(result.attestation.evidence.contact).toBe("+5511987654321");
+    expect(result.attestation.evidence).not.toHaveProperty("contact_hash");
+  });
+
+  it("never carries an ip, a user agent, a device id or a geo: on this channel each of those was inferred", () => {
+    const result = evidenceFor({ live: true, message: REAL, now: NOW });
+    if (!result.attestable) throw new Error("expected evidence");
+    const keys = Object.keys(result.attestation.evidence).filter((k) => k !== "channel");
+    expect(keys.every((k) => (WHATSAPP_EVIDENCE_KEYS as readonly string[]).includes(k))).toBe(true);
+    for (const forbidden of ["ip", "user_agent", "device_id_hash", "geo"]) expect(result.attestation.evidence).not.toHaveProperty(forbidden);
+  });
+
+  it("separates the partner's clock from the provider's: asserted_at is ours, provider_ts is theirs", () => {
+    const result = evidenceFor({ live: true, message: { ...REAL, timestamp: AT("2026-09-23T15:00:00Z") }, now: () => new Date("2026-09-23T17:00:05Z") });
+    if (!result.attestable) throw new Error("expected evidence");
+    expect(result.attestation.asserted_at).toBe(AT("2026-09-23T17:00:05Z"));
+    expect(result.attestation.evidence.provider_ts).toBe(AT("2026-09-23T15:00:00Z"));
+  });
+
+  it("refuses a reference with a dot: the canonical signing string joins segments, and a wamid goes in message_id", () => {
+    const result = evidenceFor({ live: true, message: REAL, reference: "wamid.HBgN", now: NOW });
+    expect(result.attestable).toBe(false);
+  });
+
+  it("refuses a message id or a session id the API's opaque-id shape would reject", () => {
+    expect(evidenceFor({ live: true, message: { ...REAL, id: "wamid with spaces" }, now: NOW }).attestable).toBe(false);
+    expect(evidenceFor({ live: true, message: REAL, sessionId: "conv 1042", now: NOW }).attestable).toBe(false);
+  });
+
+  it("refuses a message the provider gave no timestamp for", () => {
+    expect(evidenceFor({ live: true, message: { ...REAL, timestamp: 0 }, now: NOW }).attestable).toBe(false);
+  });
+});