create-ailk 0.1.0 → 0.1.1

package/templates/apps/api/src/services/__tests__/playbook-compile.test.ts

@@ -0,0 +1,406 @@
+// oss: false
+/**
+ * @file playbook-compile.test.ts
+ * @description Golden tests for FEAT-074 U4a's compile (#4715).
+ *
+ * Every golden's `source` is run through the VENDORED
+ * `check-playbook.py --self-test`-verified checker (`vendor/playbook-method/`)
+ * against the REAL vendored play library — AC-1/AC-6. `check-playbook.py`
+ * takes `--playbook PATH` (a markdown FILE carrying the
+ * `<!-- playbook-source: {...} -->` block), not a bare object, so each
+ * assertion writes `result.markdown` (which already contains that exact
+ * block — `compilePlaybook` renders it) to a temp file and runs the checker
+ * against it.
+ *
+ * `compileAndStorePlaybook`'s own suite mocks `@working-theory/database`
+ * (via `__mocks__/prisma.ts`, mirroring waitlist-scoring.test.ts) and
+ * `@working-theory/observability`'s logger, so its Prisma write shape,
+ * append-only behavior, and fail-soft catch are directly assertable without
+ * a live database.
+ */
+// eslint-disable-next-line no-restricted-syntax -- prisma is a DB boundary; __mocks__/prisma.ts activates the auto-mock (Jest requires explicit call for local files)
+jest.mock("../../lib/prisma.js");
+
+const mockLoggerError = jest.fn();
+jest.mock("@working-theory/observability", () => ({
+  logger: {
+    info: jest.fn(),
+    warn: jest.fn(),
+    error: (...args: unknown[]) => mockLoggerError(...args),
+    debug: jest.fn(),
+  },
+}));
+
+import { createHash } from "node:crypto";
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+
+import { prisma } from "../../lib/prisma.js";
+import {
+  compileAndStorePlaybook,
+  compilePlaybook,
+  loadVendoredPlayLibrary,
+  PlaybookCompileError,
+  resolveVendoredLibraryPath,
+  type PlayLibrary,
+} from "../playbook-compile.js";
+
+// Never `import.meta.url` here (see playbook-compile.ts's header — ts-jest
+// compiles this file to CommonJS, which cannot execute `import.meta`).
+// `resolveVendoredLibraryPath` already does the cwd-relative probing this
+// test needs; the vendor directory is that resolved file's own dirname.
+const VENDOR_DIR = dirname(resolveVendoredLibraryPath());
+const CHECKER_PATH = join(VENDOR_DIR, "check-playbook.py");
+const SCHEMA_PATH = join(VENDOR_DIR, "playbook-source.schema.json");
+const PLAYS_PATH = join(VENDOR_DIR, "targeting-maturity.plays.json");
+
+const LIBRARY: PlayLibrary = loadVendoredPlayLibrary();
+
+/** Runs the vendored checker against one golden's rendered markdown. Throws
+ * (failing the test) on a non-zero exit — `execFileSync` throws on exit != 0. */
+function runCheckerOnMarkdown(markdown: string): void {
+  const dir = mkdtempSync(join(tmpdir(), "playbook-checker-"));
+  const playbookPath = join(dir, "PLAYBOOK-golden.md");
+  try {
+    writeFileSync(playbookPath, markdown, "utf8");
+    execFileSync(
+      "python3",
+      [CHECKER_PATH, "--playbook", playbookPath, "--plays", PLAYS_PATH, "--schema", SCHEMA_PATH],
+      { stdio: "pipe" },
+    );
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/** A `predicate`-kind ruleTrace entry, the shape `evaluateWaitlistScoring`
+ * produces (`RuleTraceEntry`, `@working-theory/validation`) — hand-built
+ * here (not run through the real evaluator) since only the `tier`/`path`/
+ * `result` fields matter to `compilePlaybook`'s loop-back detection. */
+function predicateEntry(tier: string, refName: string, result: boolean) {
+  return {
+    kind: "predicate" as const,
+    tier,
+    path: `allOf[0].ref(level1_only).allOf[0].ref(level1_signal).anyOf[0].ref(${refName}).eq`,
+    node: {},
+    result,
+    detail: `${refName} = ${result}`,
+  };
+}
+
+describe("compilePlaybook (D1) — goldens", () => {
+  it("Level 0 (the Gate) compiles, unlocks_next = Level 1's ids, passes the vendored checker (AC-1, AC-6)", () => {
+    const { source, markdown } = compilePlaybook({
+      score: { id: "wlscore_gate", tier: "level_0", ruleTrace: [] },
+      plays: LIBRARY,
+      leadId: "lead_gate",
+    });
+
+    expect(source).toMatchObject({
+      artifact_type: "playbook",
+      scope: "person",
+      scope_ref: "lead_gate",
+      method: "targeting-maturity",
+      level: 0,
+      compiled_from: "wlscore_gate",
+    });
+    expect(source.plays).toEqual(["tm-0.1", "tm-0.2"]);
+    expect(source.unlocks_next).toEqual(["tm-1.1", "tm-1.2", "tm-1.3", "tm-1.4", "tm-1.5", "tm-1.6"]);
+    expect(markdown).toContain('"level":0');
+
+    runCheckerOnMarkdown(markdown);
+  });
+
+  it("Level 1 via paying customers compiles, unlocks_next = Level 2's ids, no loop-back framing, passes the checker (AC-1)", () => {
+    const { source, markdown } = compilePlaybook({
+      score: {
+        id: "wlscore_l1_customers",
+        tier: "level_1",
+        ruleTrace: [predicateEntry("level_1", "has_customers", true)],
+      },
+      plays: LIBRARY,
+      leadId: "lead_l1_customers",
+    });
+
+    expect(source.level).toBe(1);
+    expect(source.plays).toEqual(["tm-1.1", "tm-1.2", "tm-1.3", "tm-1.4", "tm-1.5", "tm-1.6"]);
+    expect(source.unlocks_next).toEqual(["tm-2.1", "tm-2.2", "tm-2.3"]);
+    expect(markdown).not.toContain("loop-back");
+
+    runCheckerOnMarkdown(markdown);
+  });
+
+  it("Level 1 via a confirmed-Fit cohort renders the Level-6 loop-back framing, source otherwise identical (AC-1)", () => {
+    const { source, markdown } = compilePlaybook({
+      score: {
+        id: "wlscore_l1_cohort",
+        tier: "level_1",
+        ruleTrace: [predicateEntry("level_1", "has_confirmed_fit_cohort", true)],
+      },
+      plays: LIBRARY,
+      leadId: "lead_l1_cohort",
+    });
+
+    expect(source.level).toBe(1);
+    expect(source.plays).toEqual(["tm-1.1", "tm-1.2", "tm-1.3", "tm-1.4", "tm-1.5", "tm-1.6"]);
+    expect(source.unlocks_next).toEqual(["tm-2.1", "tm-2.2", "tm-2.3"]);
+    expect(markdown).toContain("loop-back");
+
+    runCheckerOnMarkdown(markdown);
+  });
+
+  it("Level 5 compiles, unlocks_next = Level 7's ids (never 6, which the method has no such Level for) (AC-1)", () => {
+    const { source, markdown } = compilePlaybook({
+      score: { id: "wlscore_l5", tier: "level_5", ruleTrace: [] },
+      plays: LIBRARY,
+      leadId: "lead_l5",
+    });
+
+    expect(source.level).toBe(5);
+    expect(source.plays).toEqual(["tm-5.1", "tm-5.2", "tm-5.3", "tm-5.4", "tm-5.5", "tm-5.6"]);
+    expect(source.unlocks_next).toEqual([
+      "tm-7.1",
+      "tm-7.2",
+      "tm-7.3",
+      "tm-7.4",
+      "tm-7.5",
+      "tm-7.6",
+    ]);
+
+    runCheckerOnMarkdown(markdown);
+  });
+
+  it("Level 8 compiles, unlocks_next = Level 7's ids — library-declared, never level + 1 = 9 (AC-1)", () => {
+    const { source, markdown } = compilePlaybook({
+      score: { id: "wlscore_l8", tier: "level_8", ruleTrace: [] },
+      plays: LIBRARY,
+      leadId: "lead_l8",
+    });
+
+    expect(source.level).toBe(8);
+    expect(source.plays).toEqual(["tm-8.1", "tm-8.2", "tm-8.3", "tm-8.4"]);
+    expect(source.unlocks_next).toEqual([
+      "tm-7.1",
+      "tm-7.2",
+      "tm-7.3",
+      "tm-7.4",
+      "tm-7.5",
+      "tm-7.6",
+    ]);
+
+    runCheckerOnMarkdown(markdown);
+  });
+});
+
+describe("compilePlaybook — determinism (AC-2)", () => {
+  it("compiling the same score twice yields byte-identical markdown and deep-equal source", () => {
+    const input = {
+      score: {
+        id: "wlscore_det",
+        tier: "level_7",
+        ruleTrace: [predicateEntry("level_7", "validated_icp", true)],
+      },
+      plays: LIBRARY,
+      leadId: "lead_det",
+    };
+
+    const first = compilePlaybook(input);
+    const second = compilePlaybook(input);
+
+    expect(second.markdown).toBe(first.markdown);
+    expect(second.source).toEqual(first.source);
+  });
+});
+
+describe("compilePlaybook — fail-soft compile errors (AC-4, spec §5.3)", () => {
+  it("throws PlaybookCompileError for an unrecognized tier", () => {
+    expect(() =>
+      compilePlaybook({
+        score: { id: "wlscore_bad", tier: "level_unresolved", ruleTrace: [] },
+        plays: LIBRARY,
+        leadId: "lead_bad",
+      }),
+    ).toThrow(PlaybookCompileError);
+  });
+
+  it("throws PlaybookCompileError when the library declares no plays for the tier's Level", () => {
+    const emptyLibrary: PlayLibrary = { version: "1.0.0", method: "targeting-maturity", levels: [] };
+    expect(() =>
+      compilePlaybook({
+        score: { id: "wlscore_empty", tier: "level_3", ruleTrace: [] },
+        plays: emptyLibrary,
+        leadId: "lead_empty",
+      }),
+    ).toThrow(PlaybookCompileError);
+  });
+});
+
+describe("compileAndStorePlaybook (D4) — the Prisma-touching wrapper", () => {
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  it("creates exactly one PlaybookInstance row carrying the compiled source + markdown (AC-3)", async () => {
+    (prisma.playbookInstance.create as jest.Mock).mockResolvedValue({ id: "pbk_1" });
+
+    await compileAndStorePlaybook({
+      siteId: "site-abc",
+      leadId: "lead-1",
+      experimentKey: "targeting-maturity",
+      scoreId: "wlscore_1",
+      tier: "level_1",
+      ruleTrace: [],
+    });
+
+    expect(prisma.playbookInstance.create).toHaveBeenCalledTimes(1);
+    const [call] = (prisma.playbookInstance.create as jest.Mock).mock.calls[0]!;
+    expect(call.data).toMatchObject({
+      siteId: "site-abc",
+      leadId: "lead-1",
+      experimentKey: "targeting-maturity",
+      scoreId: "wlscore_1",
+      tier: "level_1",
+      level: 1,
+    });
+    expect(call.data.source).toMatchObject({ level: 1, compiled_from: "wlscore_1", scope_ref: "lead-1" });
+    expect(typeof call.data.markdown).toBe("string");
+    expect(call.data.markdown).toContain("playbook-source");
+  });
+
+  it("append-only: a second call for the same lead creates a SECOND row, never an update/upsert (AC-3)", async () => {
+    (prisma.playbookInstance.create as jest.Mock)
+      .mockResolvedValueOnce({ id: "pbk_1" })
+      .mockResolvedValueOnce({ id: "pbk_2" });
+
+    await compileAndStorePlaybook({
+      siteId: "site-abc",
+      leadId: "lead-1",
+      experimentKey: "targeting-maturity",
+      scoreId: "wlscore_1",
+      tier: "level_1",
+      ruleTrace: [],
+    });
+    await compileAndStorePlaybook({
+      siteId: "site-abc",
+      leadId: "lead-1",
+      experimentKey: "targeting-maturity",
+      scoreId: "wlscore_2",
+      tier: "level_2",
+      ruleTrace: [],
+    });
+
+    // Two calls -> two creates, distinct rows (the second scoreId), never a
+    // single row mutated in place — the append-only contract (D2).
+    expect(prisma.playbookInstance.create).toHaveBeenCalledTimes(2);
+    const [firstCall] = (prisma.playbookInstance.create as jest.Mock).mock.calls[0]!;
+    const [secondCall] = (prisma.playbookInstance.create as jest.Mock).mock.calls[1]!;
+    expect(firstCall.data.scoreId).toBe("wlscore_1");
+    expect(secondCall.data.scoreId).toBe("wlscore_2");
+  });
+
+  it("a compile failure (an unrecognized tier) is logged and never throws — the score is unaffected (AC-4)", async () => {
+    await expect(
+      compileAndStorePlaybook({
+        siteId: "site-abc",
+        leadId: "lead-1",
+        experimentKey: "targeting-maturity",
+        scoreId: "wlscore_1",
+        tier: "level_unresolved",
+        ruleTrace: [],
+      }),
+    ).resolves.toBeUndefined();
+
+    expect(prisma.playbookInstance.create).not.toHaveBeenCalled();
+    expect(mockLoggerError).toHaveBeenCalledWith(
+      expect.objectContaining({
+        siteId: "site-abc",
+        experimentKey: "targeting-maturity",
+        leadId: "lead-1",
+        kind: "playbook_compile_failed",
+      }),
+      expect.any(String),
+    );
+  });
+
+  it("a Prisma write failure is logged and never throws (AC-4)", async () => {
+    (prisma.playbookInstance.create as jest.Mock).mockRejectedValue(new Error("db down"));
+
+    await expect(
+      compileAndStorePlaybook({
+        siteId: "site-abc",
+        leadId: "lead-1",
+        experimentKey: "targeting-maturity",
+        scoreId: "wlscore_1",
+        tier: "level_1",
+        ruleTrace: [],
+      }),
+    ).resolves.toBeUndefined();
+
+    expect(mockLoggerError).toHaveBeenCalledWith(
+      expect.objectContaining({ kind: "playbook_compile_failed" }),
+      expect.any(String),
+    );
+  });
+
+  it("a missing vendored library file degrades like any other compile failure — never throws at import or at call time (security review M1, AC-4)", async () => {
+    // A fresh module instance (its own memoization cache) with process.cwd()
+    // pointed at a path with no vendor/ tree above it, so every candidate in
+    // resolveVendoredLibraryPath's probe misses and the fallback readFileSync
+    // throws ENOENT — exactly M1's failure mode, exercised WITHOUT mocking
+    // node:fs (a real missing-file read, not a simulated one).
+    let freshCompileAndStorePlaybook!: typeof compileAndStorePlaybook;
+    jest.isolateModules(() => {
+      freshCompileAndStorePlaybook = require("../playbook-compile.js").compileAndStorePlaybook;
+    });
+
+    // The load is LAZY (M1) — it happens on the CALL below, not at the
+    // require() above — so the cwd mock must still be active here, and is
+    // restored only after the call that exercises it.
+    const cwdSpy = jest.spyOn(process, "cwd").mockReturnValue("/nonexistent-root-for-m1-test");
+    let result: unknown;
+    try {
+      result = await freshCompileAndStorePlaybook({
+        siteId: "site-abc",
+        leadId: "lead-1",
+        experimentKey: "targeting-maturity",
+        scoreId: "wlscore_missing_lib",
+        tier: "level_1",
+        ruleTrace: [],
+      });
+    } finally {
+      cwdSpy.mockRestore();
+    }
+    expect(result).toBeUndefined();
+
+    expect(prisma.playbookInstance.create).not.toHaveBeenCalled();
+    expect(mockLoggerError).toHaveBeenCalledWith(
+      expect.objectContaining({
+        siteId: "site-abc",
+        experimentKey: "targeting-maturity",
+        leadId: "lead-1",
+        kind: "playbook_compile_failed",
+      }),
+      expect.any(String),
+    );
+  });
+});
+
+describe("vendored checker self-test + provenance (AC-6)", () => {
+  it("check-playbook.py --self-test exits 0", () => {
+    expect(() => execFileSync("python3", [CHECKER_PATH, "--self-test"], { stdio: "pipe" })).not.toThrow();
+  });
+
+  it("each vendored file's sha256 equals the hash recorded in PROVENANCE.md", () => {
+    const provenance = readFileSync(join(VENDOR_DIR, "PROVENANCE.md"), "utf8");
+    for (const file of [
+      "check-playbook.py",
+      "playbook-source.schema.json",
+      "targeting-maturity.plays.json",
+    ]) {
+      const actual = createHash("sha256").update(readFileSync(join(VENDOR_DIR, file))).digest("hex");
+      expect(provenance).toContain(actual);
+    }
+  });
+});

package/templates/apps/api/src/services/__tests__/playbook-render.test.ts

@@ -0,0 +1,290 @@
+/**
+ * @file playbook-render.test.ts
+ * @description Golden tests for FEAT-074 U4b's renderer (#4718, AC-1/AC-2/AC-6).
+ *
+ * Reuses `compilePlaybook` (U4a) to produce a real `{source, markdown}` pair
+ * from the vendored play library for each golden — the SAME goldens
+ * `playbook-compile.test.ts` exercises (Level 0, Level 1 via paying
+ * customers, Level 1 via the confirmed-Fit cohort loop-back, Level 5, Level
+ * 8), so the render is proven against the real compile output, not a
+ * hand-rolled `source`/`markdown` pair.
+ *
+ * PDF page count is read via `pdf-lib` itself (`PDFDocument.load`, already a
+ * production dependency — no ESM friction under Jest). PDF TEXT is read by
+ * shelling out to a standalone Node ESM script that drives `pdfjs-dist`'s
+ * legacy Node build: `pdfjs-dist/legacy/build/pdf.mjs` uses `import.meta.url`
+ * internally, which Jest's CommonJS-compiled test runner cannot load via a
+ * dynamic `import()` (verified: `SyntaxError: Cannot use 'import.meta'
+ * outside a module`) — mirrors `playbook-compile.test.ts`'s own
+ * `execFileSync`-a-real-separate-process pattern (there, `check-playbook.py`;
+ * here, a small Node ESM extractor script written to a temp file per call).
+ */
+import { execFileSync } from "node:child_process";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { PDFDocument } from "pdf-lib";
+
+import {
+  compilePlaybook,
+  loadVendoredPlayLibrary,
+  type PlayLibrary,
+} from "../playbook-compile.js";
+import { PlaybookRenderError, renderPlaybookPdf } from "../playbook-render.js";
+
+const LIBRARY: PlayLibrary = loadVendoredPlayLibrary();
+
+/** A `predicate`-kind ruleTrace entry (mirrors playbook-compile.test.ts's
+ * own `predicateEntry` helper — only `tier`/`path`/`result` matter to
+ * `compilePlaybook`'s loop-back detection). */
+function predicateEntry(tier: string, refName: string, result: boolean) {
+  return {
+    kind: "predicate" as const,
+    tier,
+    path: `allOf[0].ref(level1_only).allOf[0].ref(level1_signal).anyOf[0].ref(${refName}).eq`,
+    node: {},
+    result,
+    detail: `${refName} = ${result}`,
+  };
+}
+
+// ─── Extraction helper — a standalone Node ESM child process ──────────────
+
+const EXTRACT_SCRIPT = `
+import { readFileSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+// pdfjs-dist's legacy Node build (getDocument) calls Promise.withResolvers(),
+// a Node 22 API. CI pins Node 20.19 (no Promise.withResolvers), so guard it
+// here -- before the pdfjs dynamic import below -- with a spec-compliant
+// polyfill (https://tc39.es/proposal-promise-with-resolvers/).
+if (typeof Promise.withResolvers !== "function") {
+  Promise.withResolvers = function () {
+    let resolve, reject;
+    const promise = new Promise((res, rej) => {
+      resolve = res;
+      reject = rej;
+    });
+    return { promise, resolve, reject };
+  };
+}
+const bytes = new Uint8Array(readFileSync(process.argv[2]));
+const pdfjs = await import(pathToFileURL(process.argv[3]).href);
+const doc = await pdfjs.getDocument({
+  data: bytes,
+  useWorkerFetch: false,
+  isEvalSupported: false,
+  useSystemFonts: true,
+}).promise;
+const pageTexts = [];
+for (let i = 1; i <= doc.numPages; i++) {
+  const page = await doc.getPage(i);
+  const textContent = await page.getTextContent();
+  pageTexts.push(textContent.items.map((it) => it.str).join(" "));
+}
+process.stdout.write(JSON.stringify({ text: pageTexts.join("\\n") }));
+`;
+
+/**
+ * Absolute path to pdfjs-dist's legacy Node entry, resolved from THIS
+ * (CommonJS-compiled, per ts-jest's `module: 'commonjs'` preset — see the
+ * file header) test module's own `require`. Passed to the child process by
+ * absolute path — never a bare `"pdfjs-dist/..."` specifier — because the
+ * extractor script is written to a temp directory outside this workspace's
+ * `node_modules` resolution chain, where a bare specifier cannot resolve.
+ */
+const PDFJS_LEGACY_ENTRY = require.resolve("pdfjs-dist/legacy/build/pdf.mjs");
+
+/** Extracts the concatenated text of every page of a PDF's bytes. */
+function extractPdfText(bytes: Uint8Array): string {
+  const dir = mkdtempSync(join(tmpdir(), "playbook-pdf-extract-"));
+  try {
+    const scriptPath = join(dir, "extract.mjs");
+    const pdfPath = join(dir, "playbook.pdf");
+    writeFileSync(scriptPath, EXTRACT_SCRIPT, "utf8");
+    writeFileSync(pdfPath, bytes);
+    const out = execFileSync(
+      "node",
+      [scriptPath, pdfPath, PDFJS_LEGACY_ENTRY],
+      { encoding: "utf8" },
+    );
+    return (JSON.parse(out) as { text: string }).text;
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+async function pageCount(bytes: Uint8Array): Promise<number> {
+  const doc = await PDFDocument.load(bytes);
+  return doc.getPageCount();
+}
+
+/** Renders and asserts the AC-6 <= 2s bound on EVERY golden call site, not
+ * only one -- a per-golden bound, since the PDF renders per-request inside
+ * the download route and the largest golden (Level 5, 6 own plays + 6
+ * unlock plays) is exactly the case the bound exists to guard. */
+async function renderTimed(
+  input: Parameters<typeof renderPlaybookPdf>[0],
+): Promise<Uint8Array> {
+  const start = Date.now();
+  const bytes = await renderPlaybookPdf(input);
+  expect(Date.now() - start).toBeLessThanOrEqual(2000);
+  return bytes;
+}
+
+/** Every play title the library declares for `level` — used to assert the
+ * rendered PDF's extracted text contains all of them (never hand-duplicated
+ * as a literal string list, so this test can't drift from the library). */
+function titlesForLevel(level: number): string[] {
+  const entry = LIBRARY.levels.find((l) => l.level === level);
+  if (!entry) throw new Error(`no fixture level ${level} in the vendored library`);
+  return entry.plays.map((p) => p.title);
+}
+
+/** The play ids the library declares for `level` — used to assert
+ * `compilePlaybook`'s `source.unlocks_next` matches the library exactly
+ * (mirrors playbook-compile.test.ts's own equivalent assertions). */
+function idsForLevel(level: number): string[] {
+  const entry = LIBRARY.levels.find((l) => l.level === level);
+  if (!entry) throw new Error(`no fixture level ${level} in the vendored library`);
+  return entry.plays.map((p) => p.id);
+}
+
+// ─── The forbidden-token matcher (spec §2.1/AC-2) ──────────────────────────
+
+const WHOLE_WORD_FORBIDDEN = /\b(tier|cell|coefficient|stage)\b/;
+const SUBSTRING_FORBIDDEN = "level_";
+
+function assertNoForbiddenTokens(text: string): void {
+  const lower = text.toLowerCase();
+  expect(WHOLE_WORD_FORBIDDEN.test(lower)).toBe(false);
+  expect(lower).not.toContain(SUBSTRING_FORBIDDEN);
+}
+
+// ─── Goldens — Level 0, 1 (both routes), 5, 8 — mirrors playbook-compile.test.ts ──
+
+describe("renderPlaybookPdf — goldens (AC-1, AC-2, AC-6)", () => {
+  it("Level 0 (the Gate): labelled 'Gate', never 'Level 0'; every Level-0 play title present; no forbidden tokens; <= 6 pages; <= 2s", async () => {
+    const { source, markdown } = compilePlaybook({
+      score: { id: "wlscore_gate", tier: "level_0", ruleTrace: [] },
+      plays: LIBRARY,
+      leadId: "lead_gate",
+    });
+
+    const bytes = await renderTimed({ source, markdown, locale: "en" });
+
+    expect(await pageCount(bytes)).toBeLessThanOrEqual(6);
+
+    const text = extractPdfText(bytes);
+    expect(text).toContain("Gate");
+    expect(text).not.toContain("Level 0");
+    for (const title of titlesForLevel(0)) {
+      expect(text).toContain(title);
+    }
+    assertNoForbiddenTokens(text);
+  });
+
+  it("Level 1 via paying customers: labelled 'Level 1'; every Level-1 play title present; no forbidden tokens; <= 2s", async () => {
+    const { source, markdown } = compilePlaybook({
+      score: {
+        id: "wlscore_l1_customers",
+        tier: "level_1",
+        ruleTrace: [predicateEntry("level_1", "has_customers", true)],
+      },
+      plays: LIBRARY,
+      leadId: "lead_l1_customers",
+    });
+
+    const bytes = await renderTimed({ source, markdown, locale: "en" });
+    expect(await pageCount(bytes)).toBeLessThanOrEqual(6);
+
+    const text = extractPdfText(bytes);
+    expect(text).toContain("Level 1");
+    for (const title of titlesForLevel(1)) {
+      expect(text).toContain(title);
+    }
+    assertNoForbiddenTokens(text);
+  });
+
+  it("Level 1 via the confirmed-Fit cohort loop-back: same Level-1 render contract as the paying-customers golden; <= 2s", async () => {
+    const { source, markdown } = compilePlaybook({
+      score: {
+        id: "wlscore_l1_cohort",
+        tier: "level_1",
+        ruleTrace: [predicateEntry("level_1", "has_confirmed_fit_cohort", true)],
+      },
+      plays: LIBRARY,
+      leadId: "lead_l1_cohort",
+    });
+
+    const bytes = await renderTimed({ source, markdown, locale: "en" });
+    expect(await pageCount(bytes)).toBeLessThanOrEqual(6);
+
+    const text = extractPdfText(bytes);
+    expect(text).toContain("Level 1");
+    for (const title of titlesForLevel(1)) {
+      expect(text).toContain(title);
+    }
+    assertNoForbiddenTokens(text);
+  });
+
+  it("Level 5 (unlocks Level 7 -- never 6, the largest golden: 6 own plays + 6 unlock plays): every title present in both sections, no forbidden tokens, <= 6 pages, <= 2s", async () => {
+    const { source, markdown } = compilePlaybook({
+      score: { id: "wlscore_l5", tier: "level_5", ruleTrace: [] },
+      plays: LIBRARY,
+      leadId: "lead_l5",
+    });
+    expect(source.unlocks_next).toEqual(idsForLevel(7));
+
+    const bytes = await renderTimed({ source, markdown, locale: "en" });
+    expect(await pageCount(bytes)).toBeLessThanOrEqual(6);
+
+    const text = extractPdfText(bytes);
+    expect(text).toContain("Level 5");
+    expect(text).toContain("Level 7");
+    for (const title of [...titlesForLevel(5), ...titlesForLevel(7)]) {
+      expect(text).toContain(title);
+    }
+    assertNoForbiddenTokens(text);
+  });
+
+  it("Level 8 (unlocks Level 7, never 9 -- library-declared, non-monotonic): every title present, no forbidden tokens; <= 2s", async () => {
+    const { source, markdown } = compilePlaybook({
+      score: { id: "wlscore_l8", tier: "level_8", ruleTrace: [] },
+      plays: LIBRARY,
+      leadId: "lead_l8",
+    });
+    expect(source.unlocks_next).toEqual(idsForLevel(7));
+
+    const bytes = await renderTimed({ source, markdown, locale: "en" });
+    expect(await pageCount(bytes)).toBeLessThanOrEqual(6);
+
+    const text = extractPdfText(bytes);
+    expect(text).toContain("Level 8");
+    expect(text).toContain("Level 7");
+    for (const title of [...titlesForLevel(8), ...titlesForLevel(7)]) {
+      expect(text).toContain(title);
+    }
+    assertNoForbiddenTokens(text);
+  });
+});
+
+// ─── A play id the current library no longer declares — a library defect ──
+
+describe("renderPlaybookPdf — library-defect posture (mirrors PlaybookCompileError)", () => {
+  it("throws PlaybookRenderError when source names a play id the current library does not declare", async () => {
+    const source = {
+      artifact_type: "playbook" as const,
+      scope: "person" as const,
+      scope_ref: "lead_defect",
+      method: "targeting-maturity",
+      level: 0,
+      plays: ["tm-0.1", "tm-999.999"],
+      compiled_from: "wlscore_defect",
+    };
+
+    await expect(
+      renderPlaybookPdf({ source, markdown: "", locale: "en" }),
+    ).rejects.toThrow(PlaybookRenderError);
+  });
+});