create-ailk 0.1.0 → 0.2.0

package/templates/apps/api/src/services/__tests__/aeo-score.test.ts

@@ -0,0 +1,475 @@
+/**
+ * #4666 — the instant AEO score service (D3/D4/D5).
+ *
+ * Dimension derivation, `lowestTwo` ordering + findings, union states, and
+ * fixture loading (AC1, AC3-AC7).
+ */
+import {
+  AEO_SCORE_RULES,
+  AEO_DIMENSION_SEVERITY,
+  AEO_SCORE_DEFAULT_BUDGET_MS,
+  AEO_SCORE_MAX_BUDGET_MS,
+  resolveScoreBudgetMs,
+  scoreCrawl,
+  scoreUrl,
+  loadExampleScore,
+} from "../aeo-score";
+import { aeoScoreResultSchema } from "@working-theory/validation";
+import type { CrawlResult } from "@working-theory/aeo/fetch";
+
+/** Typed as the platform signature so it assigns to `ScoreUrlDeps.fetchImpl` with no cast. */
+type FetchStub = jest.Mock<Promise<Response>, [RequestInfo | URL, RequestInit?]>;
+
+import expectedResult from "../../../../../packages/aeo/__tests__/fixtures/example-score/result.json";
+
+function page(
+  path: string,
+  type: string,
+  expectedType: string,
+  jsonLd: unknown[],
+): CrawlResult["pages"][number] {
+  return { path, type, expectedType, url: `https://example.com${path}`, jsonLd };
+}
+
+/**
+ * A `fetch`-shaped stub that resolves after `delayMs` with `body`, UNLESS
+ * `init.signal` aborts first — mirroring how the real Fetch API honors
+ * `AbortController` (the service's own `fetchPage` relies on this to make
+ * its per-fetch timeout actually bound the wait; a mock that ignores the
+ * signal would never let the budget win the race).
+ */
+function delayedResponse(delayMs: number, body: string) {
+  return (_input: RequestInfo | URL, init?: RequestInit): Promise<Response> =>
+    new Promise((resolve, reject) => {
+      const timer = setTimeout(() => resolve(new Response(body)), delayMs);
+      init?.signal?.addEventListener("abort", () => {
+        clearTimeout(timer);
+        reject(new DOMException("Aborted", "AbortError"));
+      });
+    });
+}
+
+describe("AEO_SCORE_RULES", () => {
+  it("is exactly the four content rules — never the example/schema-correctness rules (AC4)", () => {
+    expect(AEO_SCORE_RULES.map((r) => r.id)).toEqual([
+      "schema-coverage",
+      "jsonld-validity",
+      "entity-markup",
+      "faq-howto-incentive",
+    ]);
+    expect(AEO_SCORE_RULES.map((r) => r.id)).not.toContain("always-passes");
+    expect(AEO_SCORE_RULES.map((r) => r.id)).not.toContain("always-fails");
+    expect(AEO_SCORE_RULES.map((r) => r.id)).not.toContain("schema-correctness");
+  });
+
+  it("matches the prospect-audit-site severity table verbatim", () => {
+    expect(AEO_DIMENSION_SEVERITY).toEqual({
+      "schema-coverage": "high",
+      "entity-markup": "high",
+      "jsonld-validity": "medium",
+      "faq-howto-incentive": "low",
+    });
+  });
+});
+
+describe("resolveScoreBudgetMs", () => {
+  it("defaults to 6000 when unset", () => {
+    expect(resolveScoreBudgetMs(undefined)).toBe(AEO_SCORE_DEFAULT_BUDGET_MS);
+  });
+
+  it("uses the given value when within bounds", () => {
+    expect(resolveScoreBudgetMs("8000")).toBe(8000);
+  });
+
+  it("falls back to the default and logs when above the 15000ms cap", () => {
+    const warn = jest.fn();
+    expect(resolveScoreBudgetMs("20000", { warn })).toBe(AEO_SCORE_DEFAULT_BUDGET_MS);
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(warn.mock.calls[0]?.[0]).toContain(String(AEO_SCORE_MAX_BUDGET_MS));
+  });
+
+  it("falls back silently on an unparseable/non-positive value", () => {
+    const warn = jest.fn();
+    expect(resolveScoreBudgetMs("not-a-number", { warn })).toBe(AEO_SCORE_DEFAULT_BUDGET_MS);
+    expect(resolveScoreBudgetMs("-5", { warn })).toBe(AEO_SCORE_DEFAULT_BUDGET_MS);
+    expect(warn).not.toHaveBeenCalled();
+  });
+});
+
+describe("scoreCrawl", () => {
+  it("returns unavailable/no_pages_fetched for an empty crawl", () => {
+    const crawl: CrawlResult = { base: "https://example.com", pages: [], skipped: [] };
+    const result = scoreCrawl(crawl);
+    expect(result).toEqual({
+      status: "unavailable",
+      reason: "no_pages_fetched",
+      message: "No pages were fetched.",
+    });
+  });
+
+  it("(AC5) lowestTwo is [schema-coverage(high), entity-markup(high)] when every page fails those two and one fails jsonld-validity", () => {
+    const crawl: CrawlResult = {
+      base: "https://example.com",
+      pages: [
+        page("/", "homepage", "HomePage", []), // no JSON-LD at all — fails coverage + entity
+        page("/about", "about", "AboutPage", [
+          { "@type": "WebPage", name: "About" }, // wrong type, malformed-ish (missing recommended fields is fine)
+        ]),
+      ],
+      skipped: [],
+    };
+    const result = scoreCrawl(crawl);
+    if (result.status !== "ready") throw new Error("expected ready");
+    const ids = result.lowestTwo.map((d) => d.id);
+    expect(ids).toContain("schema-coverage");
+    expect(ids).toContain("entity-markup");
+    const sc = result.dimensions.find((d) => d.id === "schema-coverage");
+    expect(sc?.severity).toBe("high");
+  });
+
+  it("(AC5) faq-howto-incentive scores 0, enters lowestTwo, and carries the fixed opportunity finding when no page has FAQ/HowTo markup", () => {
+    const crawl: CrawlResult = {
+      base: "https://example.com",
+      pages: [
+        page("/", "homepage", "HomePage", [
+          { "@type": "HomePage", name: "Home", url: "https://example.com" },
+          { "@type": "Organization", name: "Example Co" },
+        ]),
+      ],
+      skipped: [],
+    };
+    const result = scoreCrawl(crawl);
+    if (result.status !== "ready") throw new Error("expected ready");
+    const faq = result.dimensions.find((d) => d.id === "faq-howto-incentive");
+    expect(faq?.score).toBe(0);
+    expect(faq?.finding).toMatch(/no FAQPage or HowTo structured data/);
+    expect(faq?.finding).toMatch(/a visibility opportunity, not a defect/);
+    expect(result.lowestTwo.map((d) => d.id)).toContain("faq-howto-incentive");
+  });
+
+  it("sets meta.partial true when a page was skipped for budget_exceeded", () => {
+    const crawl: CrawlResult = {
+      base: "https://example.com",
+      pages: [page("/", "homepage", "HomePage", [{ "@type": "HomePage", name: "Home" }])],
+      skipped: [{ path: "/about", url: "https://example.com/about", reason: "budget_exceeded" }],
+    };
+    const result = scoreCrawl(crawl);
+    if (result.status !== "ready") throw new Error("expected ready");
+    expect(result.meta.partial).toBe(true);
+    expect(result.meta.skipped).toHaveLength(1);
+  });
+
+  it("result satisfies aeoScoreResultSchema (AC7)", () => {
+    const crawl: CrawlResult = {
+      base: "https://example.com",
+      pages: [page("/", "homepage", "HomePage", [{ "@type": "HomePage", name: "Home" }])],
+      skipped: [],
+    };
+    const result = scoreCrawl(crawl);
+    expect(() => aeoScoreResultSchema.parse(result)).not.toThrow();
+  });
+
+  // AILK #5110 — mirrors the #4707 fix for the top-level unavailable/
+  // ssrf_blocked path: the per-path SSRF-guard rejection detail
+  // (assertUrlSafe's raw `reason`, which can disclose a resolved internal
+  // host/IP) must never reach a ready response's meta.skipped[].reason.
+  describe("meta.skipped[].reason SSRF-guard scrub (#5110)", () => {
+    let warnSpy: jest.SpyInstance;
+
+    beforeEach(() => {
+      warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    });
+
+    afterEach(() => {
+      warnSpy.mockRestore();
+    });
+
+    it("redacts a raw assertUrlSafe rejection reason to the ssrf_blocked sentinel", () => {
+      const crawl: CrawlResult = {
+        base: "https://example.com",
+        pages: [page("/", "homepage", "HomePage", [{ "@type": "HomePage", name: "Home" }])],
+        skipped: [
+          {
+            path: "/admin",
+            url: "http://169.254.169.254/admin",
+            reason: "Host 169.254.169.254 resolves to a blocked address: 169.254.169.254",
+          },
+        ],
+      };
+      const result = scoreCrawl(crawl);
+      if (result.status !== "ready") throw new Error("expected ready");
+      expect(result.meta.skipped).toHaveLength(1);
+      expect(result.meta.skipped[0]?.reason).toBe("ssrf_blocked");
+      expect(result.meta.skipped[0]?.reason).not.toMatch(/169\.254\.169\.254/);
+      expect(result.meta.skipped[0]?.reason).not.toMatch(/resolves to a blocked address/i);
+    });
+
+    it("(AC-2) logs the raw per-path rejection detail server-side before redacting it", () => {
+      const crawl: CrawlResult = {
+        base: "https://example.com",
+        pages: [page("/", "homepage", "HomePage", [{ "@type": "HomePage", name: "Home" }])],
+        skipped: [
+          {
+            path: "/admin",
+            url: "http://169.254.169.254/admin",
+            reason: "Host 169.254.169.254 resolves to a blocked address: 169.254.169.254",
+          },
+        ],
+      };
+      scoreCrawl(crawl);
+      expect(warnSpy).toHaveBeenCalledTimes(1);
+      const [message, meta] = warnSpy.mock.calls[0] as [string, Record<string, unknown>];
+      expect(message).toMatch(/aeo-score/);
+      expect(meta).toMatchObject({
+        path: "/admin",
+        url: "http://169.254.169.254/admin",
+        reason: "Host 169.254.169.254 resolves to a blocked address: 169.254.169.254",
+      });
+    });
+
+    it("leaves a non-SSRF skip reason (budget_exceeded, an HTTP failure) unchanged", () => {
+      const crawl: CrawlResult = {
+        base: "https://example.com",
+        pages: [page("/", "homepage", "HomePage", [{ "@type": "HomePage", name: "Home" }])],
+        skipped: [
+          { path: "/about", url: "https://example.com/about", reason: "budget_exceeded" },
+          {
+            path: "/blog",
+            url: "https://example.com/blog",
+            reason: "HTTP 404: https://example.com/blog",
+          },
+        ],
+      };
+      const result = scoreCrawl(crawl);
+      if (result.status !== "ready") throw new Error("expected ready");
+      expect(result.meta.skipped).toEqual([
+        { path: "/about", url: "https://example.com/about", reason: "budget_exceeded" },
+        {
+          path: "/blog",
+          url: "https://example.com/blog",
+          reason: "HTTP 404: https://example.com/blog",
+        },
+      ]);
+      expect(warnSpy).not.toHaveBeenCalled();
+    });
+
+    it("end-to-end via scoreUrl: a path blocked mid-crawl (simulated DNS rebinding) never surfaces its raw reason on a ready result", async () => {
+      let calls = 0;
+      const resolver = async () => {
+        calls += 1;
+        // Call 1 is scoreUrl's own top-level pre-flight assertUrlSafe check;
+        // call 2 is crawlSite's first per-path re-check (whichever path
+        // processOne reaches first) — both resolve safely. Every subsequent
+        // per-path call — standing in for DNS rebinding mid-crawl —
+        // resolves to an internal address, so at least one page succeeds
+        // and at least one is SSRF-skipped.
+        return calls <= 2 ? ["93.184.216.34"] : ["10.1.2.3"];
+      };
+      const fetchImpl: FetchStub = jest.fn(
+        async () =>
+          new Response(
+            '<html><script type="application/ld+json">{"@type":"HomePage","name":"Home"}</script></html>',
+          ),
+      );
+
+      const result = await scoreUrl("https://example.com", { fetchImpl, resolver });
+
+      if (result.status !== "ready") {
+        throw new Error(`expected ready, got ${JSON.stringify(result)}`);
+      }
+      expect(result.meta.skipped.length).toBeGreaterThan(0);
+      for (const skip of result.meta.skipped) {
+        expect(skip.reason).toBe("ssrf_blocked");
+        expect(skip.reason).not.toMatch(/10\.1\.2\.3/);
+        expect(skip.reason).not.toMatch(/resolves to a blocked address/i);
+      }
+    });
+  });
+});
+
+describe("aeoScoreResultSchema (AC7)", () => {
+  it("parses ready, computing, and each unavailable reason", () => {
+    expect(() =>
+      aeoScoreResultSchema.parse({
+        status: "ready",
+        score: 50,
+        dimensions: [
+          { id: "schema-coverage", label: "x", weight: 10, score: 50, severity: "high", finding: null, pagesPassing: 1, pagesTotal: 2 },
+          { id: "jsonld-validity", label: "x", weight: 10, score: 50, severity: "medium", finding: null, pagesPassing: 1, pagesTotal: 2 },
+          { id: "entity-markup", label: "x", weight: 1, score: 50, severity: "high", finding: null, pagesPassing: 1, pagesTotal: 2 },
+          { id: "faq-howto-incentive", label: "x", weight: 0, score: 50, severity: "low", finding: null, pagesPassing: 1, pagesTotal: 2 },
+        ],
+        lowestTwo: [
+          { id: "schema-coverage", label: "x", weight: 10, score: 50, severity: "high", finding: null, pagesPassing: 1, pagesTotal: 2 },
+          { id: "entity-markup", label: "x", weight: 1, score: 50, severity: "high", finding: null, pagesPassing: 1, pagesTotal: 2 },
+        ],
+        meta: {
+          auditedAt: new Date().toISOString(),
+          pagesAudited: 2,
+          partial: false,
+          skipped: [],
+          schemaVersion: "1.0.0",
+          registryVersion: "1.0.0",
+        },
+      }),
+    ).not.toThrow();
+
+    expect(() => aeoScoreResultSchema.parse({ status: "computing" })).not.toThrow();
+
+    for (const reason of ["ssrf_blocked", "no_pages_fetched", "crawl_failed"] as const) {
+      expect(() =>
+        aeoScoreResultSchema.parse({ status: "unavailable", reason, message: "x" }),
+      ).not.toThrow();
+    }
+  });
+
+  it("rejects a status that mixes an unavailable discriminant with a ready-only field name absent from the schema", () => {
+    const parsed = aeoScoreResultSchema.safeParse({
+      status: "unavailable",
+      // missing required `reason` / `message` — the mixed/malformed shape.
+      score: 50,
+    });
+    expect(parsed.success).toBe(false);
+  });
+});
+
+describe("scoreUrl", () => {
+  it("returns unavailable/ssrf_blocked without ever calling fetch, for a blocked host", async () => {
+    const fetchImpl: FetchStub = jest.fn();
+    const result = await scoreUrl("http://127.0.0.1/", { fetchImpl });
+    expect(result).toEqual({
+      status: "unavailable",
+      reason: "ssrf_blocked",
+      message: expect.stringMatching(/Blocked host/i),
+    });
+    expect(fetchImpl).not.toHaveBeenCalled();
+  });
+
+  it("(AC1) issues the five default paths concurrently — a 2s-delay fetchImpl completes well under 10s", async () => {
+    const fetchImpl: FetchStub = jest.fn(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 2000));
+      return new Response("<html><script type=\"application/ld+json\">{\"@type\":\"HomePage\",\"name\":\"x\"}</script></html>");
+    });
+
+    const t0 = Date.now();
+    const result = await scoreUrl("https://example.com", {
+      fetchImpl,
+      resolver: async () => ["93.184.216.34"],
+    });
+    const elapsed = Date.now() - t0;
+
+    expect(elapsed).toBeLessThan(5000);
+    expect(result.status).toBe("ready");
+  }, 10_000);
+
+  it("(AC1) with budgetMs 500 and a 2s-delay fetchImpl, returns quickly as unavailable/no_pages_fetched", async () => {
+    const fetchImpl: FetchStub = jest.fn(delayedResponse(2000, "<html></html>"));
+
+    const t0 = Date.now();
+    const result = await scoreUrl("https://example.com", {
+      fetchImpl,
+      resolver: async () => ["93.184.216.34"],
+      budgetMs: 500,
+    });
+    const elapsed = Date.now() - t0;
+
+    // Spec AC1: "returns inside ~600 ms" — tight enough to prove the abort
+    // actually fired at the 500ms budget rather than merely finishing
+    // before the 2000ms fetchImpl delay or the 10s jest timeout.
+    expect(elapsed).toBeLessThan(1000);
+    expect(result).toEqual({
+      status: "unavailable",
+      reason: "no_pages_fetched",
+      message: expect.any(String),
+    });
+  }, 10_000);
+
+  it("(AC1) one fast + four slow pages returns ready with meta.partial true and budget_exceeded skips", async () => {
+    const homeResponse = delayedResponse(
+      0,
+      "<html><script type=\"application/ld+json\">{\"@type\":\"HomePage\",\"name\":\"x\"}</script></html>",
+    );
+    const slowResponse = delayedResponse(5000, "<html></html>");
+    const fetchImpl: FetchStub = jest.fn((input: RequestInfo | URL, init?: RequestInit) => {
+      const isHome = String(input).endsWith("example.com/");
+      return isHome ? homeResponse(input, init) : slowResponse(input, init);
+    });
+
+    const result = await scoreUrl("https://example.com", {
+      fetchImpl,
+      resolver: async () => ["93.184.216.34"],
+      budgetMs: 800,
+    });
+
+    if (result.status !== "ready") throw new Error(`expected ready, got ${JSON.stringify(result)}`);
+    expect(result.meta.partial).toBe(true);
+    // Spec AC1: one fast + FOUR slow pages — all four abort at the budget.
+    expect(result.meta.skipped.filter((s) => s.reason === "budget_exceeded").length).toBe(4);
+    expect(result.meta.pagesAudited).toBe(1);
+  }, 10_000);
+
+  it("returns a well-formed unavailable result (never a rejected promise) when a per-page fetch throws", async () => {
+    const fetchImpl: FetchStub = jest.fn(() => {
+      throw new Error("boom");
+    });
+    const result = await scoreUrl("https://example.com", {
+      fetchImpl,
+      resolver: async () => ["93.184.216.34"],
+    });
+    // A per-page fetch throw is caught INSIDE crawlSite as a skipped page, not
+    // a crawlSite-level throw — so this surfaces as no_pages_fetched.
+    expect(result).toEqual({
+      status: "unavailable",
+      reason: "no_pages_fetched",
+      message: expect.any(String),
+    });
+  });
+});
+
+describe("loadExampleScore (AC6, D6)", () => {
+  it("returns a ready result with meta.example true, sourceUrl set, and a non-empty annotation on every dimension — no fs on the request path", () => {
+    const result = loadExampleScore();
+    expect(result.status).toBe("ready");
+    if (result.status !== "ready") return;
+    expect(result.meta.example).toBe(true);
+    expect(result.meta.sourceUrl).toBe("https://ailaunchkit.ai");
+    for (const d of result.dimensions) {
+      expect(typeof d.annotation).toBe("string");
+      expect((d.annotation ?? "").length).toBeGreaterThan(0);
+    }
+  });
+
+  it("(acceptance-review finding) surfaces meta.illustrative on the wire — today's hand-authored fixture is not a genuine crawl of sourceUrl", () => {
+    const result = loadExampleScore();
+    if (result.status !== "ready") throw new Error("expected ready");
+    // Sourced from EXAMPLE_SCORE_META, not hardcoded — flips to false the
+    // moment the fixture is regenerated from a real crawl.
+    expect(result.meta.illustrative).toBe(true);
+    expect(() => aeoScoreResultSchema.parse(result)).not.toThrow();
+  });
+
+  it("deep-equals the committed fixture (minus auditedAt, plus annotations/meta) — proves the service's rule set never diverges from the generator's", () => {
+    const result = loadExampleScore();
+    if (result.status !== "ready") throw new Error("expected ready");
+    const { auditedAt: _auditedAt, ...metaWithoutAuditedAt } = result.meta;
+    void _auditedAt;
+    const stripAnnotation = (d: (typeof result.dimensions)[number]) => {
+      const { annotation: _annotation, ...rest } = d;
+      void _annotation;
+      return rest;
+    };
+    expect({
+      status: result.status,
+      score: result.score,
+      dimensions: result.dimensions.map(stripAnnotation),
+      lowestTwo: result.lowestTwo.map(stripAnnotation),
+      meta: {
+        pagesAudited: metaWithoutAuditedAt.pagesAudited,
+        partial: metaWithoutAuditedAt.partial,
+        skipped: metaWithoutAuditedAt.skipped,
+        schemaVersion: metaWithoutAuditedAt.schemaVersion,
+        registryVersion: metaWithoutAuditedAt.registryVersion,
+      },
+    }).toEqual(expectedResult);
+  });
+});

package/templates/apps/api/src/services/__tests__/answer-distributions.test.ts

@@ -0,0 +1,132 @@
+/**
+ * @file answer-distributions.test.ts
+ *
+ * Direct unit cover for the extracted bucketer (#4771 D4) — the "(other)"
+ * bucket for off-register values, the never-charted `text`/`email`/`url`
+ * types, `multi` counting per selected value (not per respondent), and the
+ * `MAX_AGGREGATION_ROWS` cap. The behavior itself is byte-identical to what
+ * `waitlist-dashboard.test.ts`'s `getExperimentComparison` suite already
+ * exercises through the service layer — this file covers the bucketer
+ * directly, over already-flattened answer maps rather than `Lead` rows.
+ */
+import {
+  computeAnswerDistributions,
+  MAX_AGGREGATION_ROWS,
+  readPayloadAnswer,
+} from "../answer-distributions";
+
+describe("readPayloadAnswer", () => {
+  it("returns a string answer", () => {
+    expect(readPayloadAnswer({ role: "founder" }, "role")).toBe("founder");
+  });
+
+  it("returns a non-empty string array for a multi answer", () => {
+    expect(
+      readPayloadAnswer({ channels: ["search", "referral"] }, "channels"),
+    ).toEqual(["search", "referral"]);
+  });
+
+  it("returns undefined for a missing key, an empty string, and an empty array", () => {
+    expect(readPayloadAnswer({}, "role")).toBeUndefined();
+    expect(readPayloadAnswer({ role: "" }, "role")).toBeUndefined();
+    expect(readPayloadAnswer({ channels: [] }, "channels")).toBeUndefined();
+  });
+
+  it("returns undefined for a non-object payload", () => {
+    expect(readPayloadAnswer(null, "role")).toBeUndefined();
+    expect(readPayloadAnswer("not-an-object", "role")).toBeUndefined();
+  });
+});
+
+describe("computeAnswerDistributions", () => {
+  const QUESTIONS = [
+    {
+      id: "role",
+      answerType: "single" as const,
+      options: [{ value: "founder" }, { value: "other" }],
+    },
+    {
+      id: "channels",
+      answerType: "multi" as const,
+      options: [{ value: "search" }, { value: "referral" }],
+    },
+    { id: "notes", answerType: "text" as const },
+  ];
+
+  it("buckets a single-select question's counts, summing to answered", () => {
+    const answerSets = [
+      { role: "founder" },
+      { role: "founder" },
+      { role: "other" },
+      {},
+    ];
+    const [roleDist] = computeAnswerDistributions(QUESTIONS, answerSets);
+    expect(roleDist).toEqual({
+      questionId: "role",
+      answerType: "single",
+      answered: 3,
+      options: [
+        { value: "founder", count: 2, share: 2 / 3 },
+        { value: "other", count: 1, share: 1 / 3 },
+      ],
+    });
+  });
+
+  it("does NOT sum a multi-select question's counts to answered when respondents pick more than one", () => {
+    const answerSets = [
+      { channels: ["search", "referral"] },
+      { channels: ["search"] },
+    ];
+    const [, channelsDist] = computeAnswerDistributions(QUESTIONS, answerSets);
+    expect(channelsDist?.answered).toBe(2);
+    const byValue = new Map(channelsDist?.options.map((o) => [o.value, o]));
+    expect(byValue.get("search")?.count).toBe(2);
+    expect(byValue.get("referral")?.count).toBe(1);
+    // 2 + 1 = 3, not 2 (answered) — multi counts per selected value.
+    const total = channelsDist?.options.reduce((sum, o) => sum + o.count, 0);
+    expect(total).toBe(3);
+  });
+
+  it('buckets an off-register value under "(other)"', () => {
+    const answerSets = [{ role: "founder" }, { role: "weird-value" }];
+    const [roleDist] = computeAnswerDistributions(QUESTIONS, answerSets);
+    const byValue = new Map(roleDist?.options.map((o) => [o.value, o]));
+    expect(byValue.get("(other)")).toEqual({
+      value: "(other)",
+      count: 1,
+      share: 0.5,
+    });
+  });
+
+  it("never charts text/email/url — empty options, answered still populated", () => {
+    const answerSets = [{ notes: "hello" }, { notes: "world" }, {}];
+    const [, , notesDist] = computeAnswerDistributions(QUESTIONS, answerSets);
+    expect(notesDist).toEqual({
+      questionId: "notes",
+      answerType: "text",
+      answered: 2,
+      options: [],
+    });
+  });
+
+  it("returns answered: 0 and options: [] when nobody answered a declared question", () => {
+    const [roleDist] = computeAnswerDistributions(QUESTIONS, [{}, {}]);
+    expect(roleDist).toEqual({
+      questionId: "role",
+      answerType: "single",
+      answered: 0,
+      options: [],
+    });
+  });
+
+  it("returns [] for an empty question list", () => {
+    expect(computeAnswerDistributions([], [{ role: "founder" }])).toEqual([]);
+  });
+});
+
+describe("MAX_AGGREGATION_ROWS", () => {
+  it("is a positive integer", () => {
+    expect(Number.isInteger(MAX_AGGREGATION_ROWS)).toBe(true);
+    expect(MAX_AGGREGATION_ROWS).toBeGreaterThan(0);
+  });
+});

package/templates/apps/api/src/services/__tests__/consent-migration.test.ts

@@ -0,0 +1,65 @@
+/**
+ * @file consent-migration.test.ts
+ * @description Drift guard between the consent_grants migration's BACKFILL
+ * and the consent service (#5275, spec §5.1 last bullet + §5.3 second
+ * boundary): every pre-existing listing gets one grant marked
+ * wording-UNRECOVERABLE — the exact `UNRECOVERABLE_CONSENT_STATEMENT`
+ * literal, so a later reader can match it — stamped at the listing's own
+ * consent_at, and project_listings itself is never touched.
+ */
+import { readFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+
+import { SITE_CONSENT_CONFIG_DEFAULTS } from "@working-theory/validation";
+
+import { UNRECOVERABLE_CONSENT_STATEMENT } from "../consent";
+
+const MIGRATION = join(
+  resolve(__dirname, "..", "..", "..", "..", ".."),
+  "database",
+  "migrations",
+  "20260911180000_consent_grants",
+  "migration.sql",
+);
+
+describe("consent_grants migration backfill (#5275 D11)", () => {
+  const sql = readFileSync(MIGRATION, "utf-8");
+
+  it("creates the table with its two indexes", () => {
+    expect(sql).toContain('CREATE TABLE "consent_grants"');
+    expect(sql).toContain('("site_id", "subject_type", "subject_id")');
+    expect(sql).toContain('("site_id", "purpose_id")');
+  });
+
+  it("inserts one row per pre-existing project_listings row", () => {
+    expect(sql).toContain('INSERT INTO "consent_grants"');
+    expect(sql).toMatch(/FROM "project_listings"/);
+    expect(sql).toContain("'project_listing'");
+    expect(sql).toContain("'service_terms'");
+  });
+
+  it("marks every backfilled row with the exact unrecoverable sentinel and a COMPUTED hash", () => {
+    expect(sql).toContain(`'${UNRECOVERABLE_CONSENT_STATEMENT}'`);
+    expect(sql).toContain(
+      `encode(sha256(convert_to('${UNRECOVERABLE_CONSENT_STATEMENT}', 'UTF8')), 'hex')`,
+    );
+    expect(sql).toContain("'und'");
+  });
+
+  it("sources created_at from the listing's own consent_at", () => {
+    const insert = sql.slice(sql.indexOf('INSERT INTO "consent_grants"'));
+    expect(insert).toContain('"consent_at"');
+    expect(insert).toContain('"created_at"');
+  });
+
+  it("never UPDATEs or ALTERs project_listings — consent_at stays as it was", () => {
+    expect(sql).not.toMatch(/UPDATE\s+"project_listings"/i);
+    expect(sql).not.toMatch(/ALTER\s+TABLE\s+"project_listings"/i);
+  });
+
+  it("never stamps today's default wording onto a grant nobody read", () => {
+    expect(sql).not.toContain("You agree to being contacted");
+    const defaultStatement = SITE_CONSENT_CONFIG_DEFAULTS.purposes[0]!.label["en"]!;
+    expect(sql).not.toContain(defaultStatement);
+  });
+});