create-ailk 0.22.0 → 0.24.0

package/templates/apps/api/src/routes/content/__tests__/shown-offerings.test.ts

@@ -0,0 +1,762 @@
+/**
+ * @file shown-offerings.test.ts
+ * GET /v1/content/shown-offerings — the `/pricing` page's Offerings read
+ * (#8924, spec docs/specs/8924-the-anonymous-pricing-read-the-spec.md
+ * AC-1 to AC-6).
+ *
+ * The route runs on a bare Fastify with a log stream, over #8876's real
+ * services, `createInMemoryPrisma()` and the D9 seed at `FIXTURE_NOW`. The
+ * resolver and the commerce claim are mocked; the services module is wrapped
+ * by a counting factory whose two readers are `jest.fn`s over the real ones,
+ * so a case can count, spy or fail them; the `@working-theory/observability`
+ * logger the services write through is captured beside the request log.
+ */
+import * as fs from "fs";
+import * as path from "path";
+import { Writable } from "node:stream";
+
+import { workspaceShownSetSchema } from "@working-theory/validation";
+import Fastify from "fastify";
+import type { FastifyInstance } from "fastify";
+
+/** While `watching`, every key read from the services module, `__esModule` included. */
+const mockOfferingsModule = { watching: false, reads: [] as string[] };
+const mockLog = jest.fn();
+const mockResolvePublicWorkspace = jest.fn();
+const mockResolveCommerceClaim = jest.fn();
+
+// eslint-disable-next-line no-restricted-syntax -- lib/prisma.ts wraps the external DB boundary (PrismaClient requires a live connection); the in-memory double is the repo-standard where-honouring test double for it.
+jest.mock("../../../lib/prisma.js", () =>
+  jest
+    .requireActual<
+      typeof import("../../../__tests__/factories/in-memory-prisma")
+    >("../../../__tests__/factories/in-memory-prisma")
+    .createInMemoryPrisma(),
+);
+
+jest.mock("@working-theory/observability", () => ({
+  logger: {
+    error: (...args: unknown[]) => mockLog("error", ...args),
+    warn: (...args: unknown[]) => mockLog("warn", ...args),
+    info: (...args: unknown[]) => mockLog("info", ...args),
+    debug: (...args: unknown[]) => mockLog("debug", ...args),
+  },
+}));
+
+// eslint-disable-next-line no-restricted-syntax -- the resolver reads the spoke registry and the content adapter; this suite's job is the route's own arms
+jest.mock("../../../services/public-site-resolver.js", () => ({
+  __esModule: true,
+  resolvePublicWorkspace: (...args: unknown[]) =>
+    mockResolvePublicWorkspace(...args),
+  resolvePublicContentAdapter: jest.fn(),
+}));
+
+// eslint-disable-next-line no-restricted-syntax -- the claim reads the licence (an external JWT boundary)
+jest.mock("../../../lib/require-commerce-claim.js", () => ({
+  __esModule: true,
+  resolveCommerceClaim: () => mockResolveCommerceClaim(),
+}));
+
+// The real services behind a read recorder, with the two readers the route
+// calls wrapped in `jest.fn` so a case can spy on or fail them. The `import()`
+// interop reads the module's `__esModule`, so a case that watches the module
+// sees the route's late import itself, not only a call.
+// eslint-disable-next-line no-restricted-syntax -- not a stand-in: the real module behind a read recorder, which is how AC-2 proves the route touches it only after the claim reads `claimed`
+jest.mock("../../../services/offerings/index.js", () => {
+  const actual = jest.requireActual<
+    typeof import("../../../services/offerings/index.js")
+  >("../../../services/offerings/index.js");
+  const exports: Record<string, unknown> = {
+    ...actual,
+    getWorkspaceShownSet: jest.fn(actual.getWorkspaceShownSet),
+    refreshWorkspaceSnapshot: jest.fn(actual.refreshWorkspaceSnapshot),
+  };
+  return new Proxy(exports, {
+    get(target, key) {
+      if (mockOfferingsModule.watching && typeof key === "string") {
+        mockOfferingsModule.reads.push(key);
+      }
+      return target[key as string];
+    },
+  });
+});
+
+import { prisma } from "../../../lib/prisma.js";
+import {
+  getWorkspaceShownSet,
+  LAST_GOOD_MAX_AGE_MS,
+  refreshWorkspaceSnapshot,
+  resetOfferingsRefreshStateForTests,
+  type OfferingsSourceFor,
+} from "../../../services/offerings/index.js";
+import {
+  EXPECTED_SHOWN_SET,
+  FIXTURE_NOW,
+  FIXTURE_ORG,
+  FIXTURE_ORG_2_WS,
+  FIXTURE_WS,
+  FIXTURE_WS_2,
+  OFFERINGS_FIXTURE_CATALOG,
+  seedOfferings,
+} from "../../../services/offerings/__tests__/fixtures.js";
+import { contentRoutes } from "../index";
+import {
+  SHOWN_OFFERINGS_REFRESH_BUDGET_MS,
+  shownOfferingsRoute,
+  type ShownOfferingsRouteOptions,
+} from "../shown-offerings";
+
+type Row = Record<string, unknown>;
+// The in-memory double exposes its store and its recorded calls, which the
+// PrismaClient type the import carries does not name, so it is named here once.
+// eslint-disable-next-line no-restricted-syntax -- justified above
+const db = prisma as unknown as {
+  __db: Record<string, Row[]>;
+  __calls: Array<{ model: string; op: string }>;
+};
+
+const mockGetShownSet = jest.mocked(getWorkspaceShownSet);
+const mockRefresh = jest.mocked(refreshWorkspaceSnapshot);
+
+const SECOND = 1000;
+const at = (offsetMs: number) => new Date(FIXTURE_NOW.getTime() + offsetMs);
+
+const ROUTE_FILE = path.join(__dirname, "..", "shown-offerings.ts");
+const REPO_ROOT = path.join(__dirname, "..", "..", "..", "..", "..", "..");
+
+/** A `sourceFor` that answers the fixture catalog and counts each source call. */
+function countingSourceFor(
+  answer: () => Promise<typeof OFFERINGS_FIXTURE_CATALOG> = async () =>
+    structuredClone(OFFERINGS_FIXTURE_CATALOG),
+) {
+  const calls: string[] = [];
+  const sourceFor: OfferingsSourceFor = (organizationId) => ({
+    listActiveCatalog: () => {
+      calls.push(organizationId);
+      return answer();
+    },
+  });
+  return { sourceFor, calls };
+}
+
+/** Waits, a macrotask at a time, until `done()` holds (at most a second). */
+async function until(done: () => boolean): Promise<void> {
+  for (let i = 0; i < 200 && !done(); i += 1) {
+    await new Promise((resolve) => setTimeout(resolve, 5));
+  }
+}
+
+let logLines: string[] = [];
+let apps: FastifyInstance[] = [];
+
+/** The suite's Fastify, with `Vary: Origin` written before the route, as CORS does. */
+async function buildApp(
+  options: ShownOfferingsRouteOptions = {},
+): Promise<FastifyInstance> {
+  const stream = new Writable({
+    write(chunk: Buffer, _encoding, callback) {
+      logLines.push(chunk.toString());
+      callback();
+    },
+  });
+  const app = Fastify({ logger: { level: "trace", stream } });
+  app.addHook("onRequest", async (_request, reply) => {
+    reply.header("Vary", "Origin");
+  });
+  await app.register(shownOfferingsRoute, options);
+  apps.push(app);
+  return app;
+}
+
+async function get(app: FastifyInstance, url = "/v1/content/shown-offerings") {
+  const response = await app.inject({ method: "GET", url });
+  return { response, body: JSON.parse(response.body) as Row };
+}
+
+function resolvedTo(workspaceId: string): void {
+  mockResolvePublicWorkspace.mockResolvedValue({
+    kind: "resolved",
+    workspaceId,
+  });
+}
+
+/** Every line the request log and the services' logger wrote in this case. */
+function capturedLogText(): string {
+  return [
+    ...logLines,
+    ...mockLog.mock.calls.map((call) => JSON.stringify(call)),
+  ].join("\n");
+}
+
+/** Lines of the request log whose `outcome` is `outcome`. */
+function linesWithOutcome(outcome: string): Row[] {
+  return logLines
+    .map((line) => JSON.parse(line) as Row)
+    .filter((line) => line.outcome === outcome);
+}
+
+/** Every product name, description, feature string and id in the fixture catalog. */
+const FIXTURE_TEXT: string[] = [
+  ...OFFERINGS_FIXTURE_CATALOG.products.flatMap((product) => [
+    product.name,
+    ...(product.description ? [product.description] : []),
+    ...(product.marketing_features ?? []).map((feature) => feature.name),
+    product.id,
+  ]),
+  ...OFFERINGS_FIXTURE_CATALOG.prices.map((price) => price.id),
+  "prod_",
+  "price_",
+];
+
+beforeEach(async () => {
+  for (const key of Object.keys(db.__db)) delete db.__db[key];
+  logLines = [];
+  mockLog.mockClear();
+  mockGetShownSet.mockClear();
+  mockRefresh.mockClear();
+  mockResolvePublicWorkspace.mockReset();
+  mockResolveCommerceClaim.mockReset().mockResolvedValue("claimed");
+  resetOfferingsRefreshStateForTests();
+  await seedOfferings(prisma, { now: FIXTURE_NOW });
+  db.__calls.length = 0;
+  resolvedTo(FIXTURE_WS);
+});
+
+afterEach(async () => {
+  // AC-6 (T6): across every case, no log line carries Stripe text.
+  const text = capturedLogText();
+  for (const fragment of FIXTURE_TEXT) expect(text).not.toContain(fragment);
+  await Promise.all(apps.map((app) => app.close()));
+  apps = [];
+});
+
+describe("the three answers (AC-1)", () => {
+  it("serves a resolved, connected workspace its shown set, the five fields the schema parses", async () => {
+    const app = await buildApp({ now: () => FIXTURE_NOW });
+    const { response, body } = await get(app);
+    expect(response.statusCode).toBe(200);
+    const data = body.data as { status: string; shownSet: Row };
+    expect(body.ok).toBe(true);
+    expect(data.status).toBe("shown");
+    expect(Object.keys(data.shownSet).sort()).toEqual([
+      "offerings",
+      "productIds",
+      "recommended",
+      "snapshotAt",
+      "state",
+    ]);
+    expect(
+      workspaceShownSetSchema.parse({
+        ...data.shownSet,
+        workspaceId: FIXTURE_WS,
+        organizationId: FIXTURE_ORG,
+      }),
+    ).toEqual(EXPECTED_SHOWN_SET);
+  });
+
+  it("answers an unresolved request the fail-closed empty answer, reading no Offerings data", async () => {
+    mockResolvePublicWorkspace.mockResolvedValue({
+      kind: "unresolved",
+      reason: "spoke-refused",
+    });
+    const app = await buildApp();
+    const { response, body } = await get(app);
+    expect(response.statusCode).toBe(200);
+    expect(body).toEqual({ ok: true, data: { status: "empty" } });
+    expect(db.__calls).toEqual([]);
+    expect(mockGetShownSet).not.toHaveBeenCalled();
+    expect(mockResolveCommerceClaim).not.toHaveBeenCalled();
+    expect(linesWithOutcome("license_undetermined")).toEqual([]);
+    expect(
+      logLines
+        .map((line) => JSON.parse(line) as Row)
+        .filter((line) => line.reason === "spoke-refused"),
+    ).toHaveLength(1);
+  });
+
+  it("answers not-required (a non-database content adapter) unconnected", async () => {
+    mockResolvePublicWorkspace.mockResolvedValue({ kind: "not-required" });
+    const app = await buildApp();
+    const { response, body } = await get(app);
+    expect(response.statusCode).toBe(200);
+    expect(body).toEqual({ ok: true, data: { status: "unconnected" } });
+    expect(db.__calls).toEqual([]);
+  });
+
+  it.each([
+    ["a workspace with no selection", FIXTURE_WS_2],
+    ["a workspace whose Organization has no connection", FIXTURE_ORG_2_WS],
+  ])(
+    "answers %s an explicit unconnected answer",
+    async (_name, workspaceId) => {
+      resolvedTo(workspaceId);
+      const app = await buildApp({ now: () => FIXTURE_NOW });
+      const { response, body } = await get(app);
+      expect(response.statusCode).toBe(200);
+      expect(body).toEqual({ ok: true, data: { status: "unconnected" } });
+    },
+  );
+
+  it("answers a resolver that throws 500 internal_error, with the fixed body", async () => {
+    mockResolvePublicWorkspace.mockRejectedValue(
+      new Error("database unreachable"),
+    );
+    const app = await buildApp();
+    const { response, body } = await get(app);
+    expect(response.statusCode).toBe(500);
+    expect(body).toEqual({
+      ok: false,
+      error: { code: "internal_error", message: "Internal server error" },
+    });
+    expect(capturedLogText()).not.toContain("database unreachable");
+  });
+});
+
+describe("the claim gates every Offerings read (AC-2)", () => {
+  it.each([
+    ["unclaimed", { status: "unconnected" }],
+    ["undetermined", { status: "empty" }],
+  ] as const)("a %s licence reads no Offerings data", async (claim, data) => {
+    mockResolveCommerceClaim.mockResolvedValue(claim);
+    const app = await buildApp();
+    const { response, body } = await get(app);
+    expect(response.statusCode).toBe(200);
+    expect(body).toEqual({ ok: true, data });
+    expect(db.__calls).toEqual([]);
+    expect(mockGetShownSet).not.toHaveBeenCalled();
+    expect(mockRefresh).not.toHaveBeenCalled();
+    expect(linesWithOutcome("license_undetermined")).toHaveLength(
+      claim === "undetermined" ? 1 : 0,
+    );
+  });
+
+  /** The keys the route reads from the services module during one request. */
+  async function servicesReadDuring(app: FastifyInstance): Promise<string[]> {
+    mockOfferingsModule.reads = [];
+    mockOfferingsModule.watching = true;
+    try {
+      await get(app);
+    } finally {
+      mockOfferingsModule.watching = false;
+    }
+    return mockOfferingsModule.reads;
+  }
+
+  it.each(["unclaimed", "undetermined"] as const)(
+    "a %s licence never imports the services module",
+    async (claim) => {
+      mockResolveCommerceClaim.mockResolvedValue(claim);
+      const app = await buildApp();
+      expect(await servicesReadDuring(app)).toEqual([]);
+    },
+  );
+
+  it("a claimed licence imports the services module only then", async () => {
+    const app = await buildApp({ now: () => FIXTURE_NOW });
+    expect(await servicesReadDuring(app)).toEqual(
+      expect.arrayContaining(["__esModule", "getWorkspaceShownSet"]),
+    );
+  });
+
+  it("the route file holds no static import of the services", () => {
+    const source = fs.readFileSync(ROUTE_FILE, "utf8");
+    expect(source).not.toMatch(/^import (?!type )[^;]*services\/offerings/m);
+  });
+
+  it("a claimed licence is served", async () => {
+    const app = await buildApp({ now: () => FIXTURE_NOW });
+    const { body } = await get(app);
+    expect((body.data as Row).status).toBe("shown");
+  });
+});
+
+describe("the refresh is bounded and never overrides the minute (AC-3, T7)", () => {
+  it("a snapshot 30 seconds old is served with no refresh", async () => {
+    const { sourceFor, calls } = countingSourceFor();
+    const app = await buildApp({ sourceFor, now: () => at(30 * SECOND) });
+    const { body } = await get(app);
+    expect((body.data as Row).status).toBe("shown");
+    expect(mockRefresh).not.toHaveBeenCalled();
+    expect(calls).toEqual([]);
+  });
+
+  it("five concurrent stale requests cost one catalog read, and a sixth 30 seconds later none", async () => {
+    // The catalog read is held open until all five requests have asked to
+    // refresh, so every one of them meets the read in flight.
+    let release!: () => void;
+    const held = new Promise<void>((resolve) => (release = resolve));
+    const { sourceFor, calls } = countingSourceFor(async () => {
+      await held;
+      return structuredClone(OFFERINGS_FIXTURE_CATALOG);
+    });
+    let now = at(61 * SECOND);
+    const app = await buildApp({ sourceFor, now: () => now });
+
+    const pending = Promise.all(Array.from({ length: 5 }, () => get(app)));
+    await until(() => mockRefresh.mock.calls.length === 5);
+    release();
+    const answers = await pending;
+    expect(calls).toEqual([FIXTURE_ORG]);
+    for (const { response, body } of answers) {
+      expect(response.statusCode).toBe(200);
+      const data = body.data as { status: string; shownSet: Row };
+      expect(data.status).toBe("shown");
+      expect(data.shownSet.snapshotAt).toBe(at(61 * SECOND).toISOString());
+    }
+
+    now = at(91 * SECOND);
+    const sixth = await get(app);
+    expect((sixth.body.data as Row).status).toBe("shown");
+    expect(calls).toEqual([FIXTURE_ORG]);
+
+    expect(mockRefresh).toHaveBeenCalledTimes(5);
+    for (const call of mockRefresh.mock.calls) {
+      expect(call[0]).toBe(FIXTURE_WS);
+      expect(call[2]).not.toHaveProperty("force");
+    }
+  });
+
+  it("the route file holds no force token", () => {
+    expect(fs.readFileSync(ROUTE_FILE, "utf8")).not.toMatch(/\bforce\b/);
+  });
+
+  it("registered with no sourceFor, a stale snapshot is served and never refreshed", async () => {
+    const app = await buildApp({ now: () => at(61 * SECOND) });
+    const { body } = await get(app);
+    const data = body.data as { status: string; shownSet: Row };
+    expect(data.status).toBe("shown");
+    expect(data.shownSet.snapshotAt).toBe(FIXTURE_NOW.toISOString());
+    expect(mockRefresh).not.toHaveBeenCalled();
+  });
+});
+
+describe("a failed refresh leaves the last good copy served (AC-4)", () => {
+  function storedSnapshot(): { snapshot: unknown; snapshotAt: unknown } {
+    const row = db.__db.workspaceOfferings!.find(
+      (r) => r.workspaceId === FIXTURE_WS,
+    )!;
+    return {
+      snapshot: structuredClone(row.snapshot),
+      snapshotAt: row.snapshotAt,
+    };
+  }
+
+  function expectSeededAnswer(body: Row): void {
+    const data = body.data as { status: string; shownSet: Row };
+    expect(data.status).toBe("shown");
+    expect(data.shownSet.offerings).toEqual(EXPECTED_SHOWN_SET.offerings);
+    expect(data.shownSet.snapshotAt).toBe(FIXTURE_NOW.toISOString());
+  }
+
+  it("a source that rejects serves the seeded snapshot and writes nothing", async () => {
+    const before = storedSnapshot();
+    const { sourceFor, calls } = countingSourceFor(async () => {
+      throw new Error("upstream failed");
+    });
+    const app = await buildApp({ sourceFor, now: () => at(61 * SECOND) });
+    const { response, body } = await get(app);
+    expect(response.statusCode).toBe(200);
+    expectSeededAnswer(body);
+    expect(calls).toEqual([FIXTURE_ORG]);
+    expect(storedSnapshot()).toEqual(before);
+  });
+
+  it(
+    "a source that never settles is answered within the budget, logged refresh_over_budget",
+    async () => {
+      const { sourceFor } = countingSourceFor(
+        () => new Promise(() => undefined),
+      );
+      const app = await buildApp({ sourceFor, now: () => at(61 * SECOND) });
+      const started = Date.now();
+      const { response, body } = await get(app);
+      expect(Date.now() - started).toBeLessThan(
+        SHOWN_OFFERINGS_REFRESH_BUDGET_MS + 500,
+      );
+      expect(response.statusCode).toBe(200);
+      expectSeededAnswer(body);
+      expect(linesWithOutcome("refresh_over_budget")).toEqual([
+        expect.objectContaining({ workspaceId: FIXTURE_WS }),
+      ]);
+    },
+    SHOWN_OFFERINGS_REFRESH_BUDGET_MS + 5000,
+  );
+
+  it("a refresh that rejects is logged refresh_failed with its class name", async () => {
+    mockRefresh.mockRejectedValueOnce(
+      new TypeError("Growth prod_fixture_growth"),
+    );
+    const { sourceFor } = countingSourceFor();
+    const app = await buildApp({ sourceFor, now: () => at(61 * SECOND) });
+    const { response, body } = await get(app);
+    expect(response.statusCode).toBe(200);
+    expectSeededAnswer(body);
+    expect(linesWithOutcome("refresh_failed")).toEqual([
+      expect.objectContaining({
+        workspaceId: FIXTURE_WS,
+        errName: "TypeError",
+      }),
+    ]);
+  });
+
+  it(
+    "a refresh that rejects after the budget is still caught and logged refresh_failed",
+    async () => {
+      mockRefresh.mockImplementationOnce(
+        () =>
+          new Promise((_resolve, reject) =>
+            setTimeout(
+              () => reject(new TypeError("late")),
+              SHOWN_OFFERINGS_REFRESH_BUDGET_MS + 100,
+            ),
+          ),
+      );
+      const { sourceFor } = countingSourceFor();
+      const app = await buildApp({ sourceFor, now: () => at(61 * SECOND) });
+      const { response, body } = await get(app);
+      expect(response.statusCode).toBe(200);
+      expectSeededAnswer(body);
+      expect(linesWithOutcome("refresh_over_budget")).toHaveLength(1);
+      expect(linesWithOutcome("refresh_failed")).toEqual([]);
+
+      // The rejection lands after the answer was sent: only a handler attached
+      // before the race sees it.
+      await until(() => linesWithOutcome("refresh_failed").length > 0);
+      expect(linesWithOutcome("refresh_failed")).toEqual([
+        expect.objectContaining({
+          workspaceId: FIXTURE_WS,
+          errName: "TypeError",
+        }),
+      ]);
+    },
+    SHOWN_OFFERINGS_REFRESH_BUDGET_MS + 5000,
+  );
+
+  it("a re-read that rejects after refreshed serves the first read, logged reread_failed", async () => {
+    const { sourceFor } = countingSourceFor();
+    const app = await buildApp({ sourceFor, now: () => at(61 * SECOND) });
+    mockGetShownSet
+      .mockImplementationOnce(mockGetShownSet.getMockImplementation()!)
+      .mockRejectedValueOnce(new RangeError("For a growing practice."));
+    const { response, body } = await get(app);
+    expect(response.statusCode).toBe(200);
+    expect(await mockRefresh.mock.results[0]!.value).toBe("refreshed");
+    expectSeededAnswer(body);
+    expect(linesWithOutcome("reread_failed")).toEqual([
+      expect.objectContaining({
+        workspaceId: FIXTURE_WS,
+        errName: "RangeError",
+      }),
+    ]);
+  });
+
+  it("a snapshot 25 hours old with a rejecting source is served as expired", async () => {
+    const { sourceFor } = countingSourceFor(async () => {
+      throw new Error("upstream failed");
+    });
+    const app = await buildApp({
+      sourceFor,
+      now: () => at(25 * 60 * 60 * SECOND),
+    });
+    const { response, body } = await get(app);
+    expect(response.statusCode).toBe(200);
+    const data = body.data as { status: string; shownSet: Row };
+    expect(data.status).toBe("shown");
+    expect(data.shownSet.state).toBe("expired");
+    expect(data.shownSet.offerings).toEqual([]);
+  });
+});
+
+describe("the production registration refreshes (#9124)", () => {
+  const SERVER_FILE = path.join(__dirname, "..", "..", "..", "server.ts");
+  const STALE_PAST_LAST_GOOD = LAST_GOOD_MAX_AGE_MS + 60 * 60 * SECOND;
+
+  // A text check, like the registration check below: building the whole
+  // server for one options object is out of proportion. It names no source:
+  // architecture.yaml confines that identifier to its reviewed callers.
+  it("server.ts registers the three shown-set routes with one options object that carries a sourceFor", () => {
+    const server = fs.readFileSync(SERVER_FILE, "utf8");
+    expect(server).toContain('from "./services/offerings/source.js";');
+    expect(server).toMatch(
+      /shownSetRouteOptions: ShownOfferingsRouteOptions = \{\s*sourceFor:/,
+    );
+    for (const route of [
+      "offeringsRoute",
+      "pricingRoute",
+      "shownOfferingsRoute",
+    ]) {
+      expect(server).toContain(
+        `await server.register(${route}, shownSetRouteOptions);`,
+      );
+    }
+  });
+
+  it("a snapshot past LAST_GOOD_MAX_AGE_MS refreshes through sourceFor and answers shown, not expired", async () => {
+    // The shape server.ts registers: a sourceFor and no other option.
+    const { sourceFor, calls } = countingSourceFor();
+    const options: ShownOfferingsRouteOptions = { sourceFor };
+    const now = at(STALE_PAST_LAST_GOOD);
+    const app = await buildApp({ ...options, now: () => now });
+    const { response, body } = await get(app);
+    expect(response.statusCode).toBe(200);
+    expect(mockRefresh).toHaveBeenCalledTimes(1);
+    expect(mockRefresh.mock.calls[0]![0]).toBe(FIXTURE_WS);
+    expect(calls).toEqual([FIXTURE_ORG]);
+    const data = body.data as { status: string; shownSet: Row };
+    expect(data.status).toBe("shown");
+    expect(data.shownSet.state).toBe("current");
+    expect(data.shownSet.snapshotAt).toBe(now.toISOString());
+    expect(data.shownSet.offerings).not.toEqual([]);
+  });
+
+  it("the pre-fix registration (no sourceFor) answers the same snapshot expired and never refreshes", async () => {
+    const app = await buildApp({ now: () => at(STALE_PAST_LAST_GOOD) });
+    const { response, body } = await get(app);
+    expect(response.statusCode).toBe(200);
+    expect(mockRefresh).not.toHaveBeenCalled();
+    const data = body.data as { status: string; shownSet: Row };
+    expect(data.status).toBe("shown");
+    expect(data.shownSet.state).toBe("expired");
+    expect(data.shownSet.offerings).toEqual([]);
+  });
+});
+
+describe("the workspace is the resolver's alone (AC-5)", () => {
+  it("ignores a workspace named in the query and a header", async () => {
+    const app = await buildApp({ now: () => FIXTURE_NOW });
+    const response = await app.inject({
+      method: "GET",
+      url: `/v1/content/shown-offerings?workspaceId=${FIXTURE_ORG_2_WS}`,
+      headers: { "x-ailk-workspace-id": FIXTURE_ORG_2_WS },
+    });
+    const data = (JSON.parse(response.body) as Row).data as {
+      status: string;
+      shownSet: Row;
+    };
+    expect(data.status).toBe("shown");
+    expect(data.shownSet.productIds).toEqual(EXPECTED_SHOWN_SET.productIds);
+    expect(mockResolvePublicWorkspace).toHaveBeenCalledTimes(1);
+    const [request] = mockResolvePublicWorkspace.mock.calls[0] as [
+      { url: string },
+    ];
+    expect(request.url).toBe(
+      `/v1/content/shown-offerings?workspaceId=${FIXTURE_ORG_2_WS}`,
+    );
+  });
+
+  it("the route file reads no request input of its own", () => {
+    const source = fs.readFileSync(ROUTE_FILE, "utf8");
+    for (const input of [
+      "request.query",
+      "request.params",
+      "request.body",
+      "request.headers",
+    ]) {
+      expect(source).not.toContain(input);
+    }
+  });
+
+  it.each([
+    ["shown", () => resolvedTo(FIXTURE_WS)],
+    [
+      "empty",
+      () =>
+        mockResolvePublicWorkspace.mockResolvedValue({
+          kind: "unresolved",
+          reason: "ambiguous",
+        }),
+    ],
+    [
+      "unconnected",
+      () =>
+        mockResolvePublicWorkspace.mockResolvedValue({ kind: "not-required" }),
+    ],
+    [
+      "the 500",
+      () => mockResolvePublicWorkspace.mockRejectedValue(new Error("boom")),
+    ],
+  ])(
+    "%s carries x-ailk-spoke-key in Vary beside Origin",
+    async (_name, arrange) => {
+      arrange();
+      const app = await buildApp({ now: () => FIXTURE_NOW });
+      const { response } = await get(app);
+      const vary = String(response.headers.vary)
+        .split(",")
+        .map((value) => value.trim().toLowerCase());
+      expect(vary).toEqual(
+        expect.arrayContaining(["origin", "x-ailk-spoke-key"]),
+      );
+      expect(response.headers["cache-control"]).toBeUndefined();
+    },
+  );
+});
+
+describe("nothing leaks, and nothing else moves (AC-6, T6)", () => {
+  it("a source error naming a product and a key, and a reader error naming a description, reach no log or body", async () => {
+    const keyText = `rk_test_${"51Fixture8924Body".padEnd(24, "x")}`;
+    const { sourceFor } = countingSourceFor(async () => {
+      throw new Error(`Growth rejected ${keyText}`);
+    });
+    const app = await buildApp({ sourceFor, now: () => at(61 * SECOND) });
+    const failedSource = await get(app);
+    expect(failedSource.response.statusCode).toBe(200);
+
+    mockGetShownSet.mockRejectedValueOnce(new Error("One site, set up once."));
+    const failedReader = await get(app);
+    expect(failedReader.response.statusCode).toBe(500);
+    expect(failedReader.body).toEqual({
+      ok: false,
+      error: { code: "internal_error", message: "Internal server error" },
+    });
+
+    const text = capturedLogText();
+    for (const fragment of [
+      keyText,
+      "rk_test_",
+      "Growth rejected",
+      "One site, set up once.",
+    ]) {
+      expect(text).not.toContain(fragment);
+      expect(failedReader.response.body).not.toContain(fragment);
+    }
+  });
+
+  it("is served through contentRoutes with the D2 envelope, not a page list", async () => {
+    const app = Fastify();
+    apps.push(app);
+    await app.register(contentRoutes);
+    const response = await app.inject({
+      method: "GET",
+      url: "/v1/content/shown-offerings",
+    });
+    expect(response.statusCode).toBe(200);
+    const body = JSON.parse(response.body) as Row;
+    expect(body.ok).toBe(true);
+    expect((body.data as Row).status).toBe("shown");
+  });
+
+  it("server.ts registers the route", () => {
+    const server = fs.readFileSync(
+      path.join(__dirname, "..", "..", "..", "server.ts"),
+      "utf8",
+    );
+    expect(server).toMatch(/await server\.register\(shownOfferingsRoute/);
+  });
+
+  // `tests/parity/` is the monorepo's own API ↔ MCP guard, which no scaffold
+  // carries (#9179), so this half runs only where that guard is. The gate is
+  // the guard's registry, never the README itself, so a deleted or renamed
+  // README fails here instead of skipping.
+  const PARITY_GUARD = path.join(REPO_ROOT, "tests", "parity", "api-parity");
+  const PARITY_README = path.join(REPO_ROOT, "tests", "parity", "README.md");
+  (fs.existsSync(PARITY_GUARD) ? it : it.skip)(
+    "the parity README records the route",
+    () => {
+      const readme = fs.readFileSync(PARITY_README, "utf8");
+      expect(readme).toMatch(
+        /^\| `GET \/v1\/content\/shown-offerings` +\| `apps\/api\/src\/routes\/content\/shown-offerings\.ts` +\|/m,
+      );
+    },
+  );
+});