create-ailk 0.1.0 → 0.2.0

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

@@ -0,0 +1,398 @@
+/**
+ * @file playbook-compile.ts
+ * @description FEAT-074 U4a (#4715) — compiles a scored `targeting-maturity`
+ * signup into a person-scoped Playbook and persists it append-only.
+ *
+ * `compilePlaybook` is a PURE function (`rules/execution-substrate.md` — the
+ * compile is a payload, never a per-respondent model call): given a scored
+ * `WaitlistScore` row's facts (`{id, tier, ruleTrace}`), the play library,
+ * and the lead id, it returns `{source, markdown}` — no Prisma, no network,
+ * no clock, no filesystem read of its own. `source` validates against
+ * `vendor/playbook-method/playbook-source.schema.json` (U1) and passes
+ * `vendor/playbook-method/check-playbook.py` — see this file's own test
+ * suite, which runs the vendored checker against every golden.
+ *
+ * `compileAndStorePlaybook` is the thin, fail-soft Prisma-touching wrapper —
+ * the sibling to A2's `waitlist-scoring.ts` glue. It loads the vendored
+ * play library LAZILY, memoized, on first use inside its own try block (a
+ * `readFileSync`, not a static `import … from "*.json"` — `apps/api`'s
+ * `tsconfig.json` sets `rootDir: "./src"` + `composite: true`, and the
+ * vendored library lives at the repo root, outside that boundary;
+ * `apps-paid/design-reference-gallery/lib/corpus.ts` is this repo's own
+ * precedent for reading vendored repo-root content via `readFileSync`
+ * rather than a cross-boundary static import). Deliberately NOT at module
+ * scope (security-review finding M1, PR #4727): a missing/corrupt vendored
+ * file must degrade like any other compile failure (D4), never throw at
+ * import time where no catch in this file can reach it. `compilePlaybook`
+ * itself never touches the filesystem.
+ *
+ * The path is resolved via `process.cwd()`-relative candidate probing
+ * (`apps/api/src/lib/locales.ts`'s own `resolveProjectYamlPath` pattern),
+ * NOT `import.meta.url` — Jest's ts-jest preset here compiles to CommonJS
+ * (`jest.config.js`), which cannot execute `import.meta` (Node throws
+ * `SyntaxError: Cannot use 'import.meta' outside a module`); this repo's own
+ * `moduleNameMapper` comment on `@working-theory/database` names the exact
+ * same v7 prisma-client `import.meta.url` incompatibility and mocks around
+ * it. `process.cwd()` has no such split — it resolves correctly whether the
+ * process was started from `apps/api/` (dev/build) or from this package's
+ * own test run.
+ *
+ * The unlock map (`unlocks_next`) is LIBRARY-DECLARED, resolved from
+ * `levels[level].unlocks_next` — NEVER computed as `level + 1` (the
+ * method's map is not monotonic: Level 5 unlocks Level 7, Level 8 unlocks
+ * Level 7 — spec §2.1, U3 Clarifications).
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import type { Prisma } from "@working-theory/database";
+import { logger } from "@working-theory/observability";
+
+import { prisma } from "../lib/prisma.js";
+
+// ─── Play-library types (the vendored targeting-maturity.plays.json shape) ──
+
+export interface PlaybookPlay {
+  id: string;
+  title: string;
+  text: string;
+}
+
+export interface PlaybookLevelEntry {
+  level: number;
+  name?: string;
+  use_if?: string;
+  cautions?: string[];
+  plays: PlaybookPlay[];
+  unlocks_next: number | null;
+}
+
+export interface PlayLibrary {
+  version: string;
+  method: string;
+  /** A bare pointer object at level 0 in the authored shape (D4) — the Gate's
+   * own plays live in `levels[]` at `level: 0`; consulted only as a fallback
+   * when `levels[]` carries no level-0 entry (mirrors
+   * `check-playbook.py`'s `_library_entry_for_level`). */
+  gate?: { level: number; plays?: PlaybookPlay[]; unlocks_next?: number | null };
+  levels: PlaybookLevelEntry[];
+}
+
+// ─── The vendored play library — lazy-loaded, memoized (see header) ─────────
+
+const VENDORED_LIBRARY_RELATIVE = "vendor/playbook-method/targeting-maturity.plays.json";
+
+/** Probes `[cwd, cwd/.., cwd/../..]` for the vendored library — apps run
+ * from their own dir in dev/build (`apps/api/`) but this package's own
+ * tests may run from either `apps/api/` or the repo root (mirrors
+ * `apps/api/src/lib/locales.ts`'s `resolveProjectYamlPath`). Falls back to
+ * the cwd-relative path so a genuine miss's error names the expected
+ * location. */
+export function resolveVendoredLibraryPath(cwd = process.cwd()): string {
+  const candidates = [
+    join(cwd, VENDORED_LIBRARY_RELATIVE),
+    join(cwd, "..", VENDORED_LIBRARY_RELATIVE),
+    join(cwd, "..", "..", VENDORED_LIBRARY_RELATIVE),
+  ];
+  for (const candidate of candidates) {
+    try {
+      readFileSync(candidate, "utf8");
+      return candidate;
+    } catch {
+      // continue
+    }
+  }
+  return candidates[0]!;
+}
+
+export function loadVendoredPlayLibrary(): PlayLibrary {
+  return JSON.parse(readFileSync(resolveVendoredLibraryPath(), "utf8")) as PlayLibrary;
+}
+
+// LAZY + memoized (security-review finding M1, PR #4727): loading the
+// library at MODULE SCOPE would let a missing/corrupt vendored file throw
+// at import time — outside every try/catch this file adds, and outside the
+// fail-soft contract this whole unit exists to uphold. On a bundler that
+// cannot statically resolve the `process.cwd()`-relative repo-root path
+// (e.g. a serverless target with no `functions.includeFiles` entry for
+// `vendor/**`), that import-time throw would 500 EVERY request through this
+// module's static import chain (`waitlist-scoring.ts` → `flow-engine.ts` →
+// the route layer → the server entrypoint) — not merely fail to compile a
+// Playbook. Deferring the read to first use inside `compileAndStorePlaybook`'s
+// own try block (below) means a missing/corrupt file degrades exactly like
+// any other compile failure (D4: logged, the score is unaffected) instead of
+// taking the process down. Memoized so the read still happens at most once.
+let vendoredPlayLibraryCache: PlayLibrary | undefined;
+function vendoredPlayLibrary(): PlayLibrary {
+  if (!vendoredPlayLibraryCache) {
+    vendoredPlayLibraryCache = loadVendoredPlayLibrary();
+  }
+  return vendoredPlayLibraryCache;
+}
+
+/** The one experiment this compile hooks (D4) — every other experiment's
+ * `scoreCompletedSignup` completion never reaches this module. */
+export const TARGETING_MATURITY_EXPERIMENT_KEY = "targeting-maturity";
+
+// ─── compilePlaybook — the pure payload (D1) ────────────────────────────────
+
+export interface PlaybookSource {
+  artifact_type: "playbook";
+  scope: "person";
+  scope_ref: string;
+  method: string;
+  level: number;
+  plays: string[];
+  unlocks_next?: string[];
+  compiled_from: string;
+}
+
+/** The WaitlistScore facts `compilePlaybook` reads — a subset of the Prisma
+ * row, never the row itself (the pure function takes no Prisma type). */
+export interface CompilePlaybookScoreInput {
+  /** `WaitlistScore.id` — becomes `source.compiled_from` (D2). */
+  id: string;
+  /** `WaitlistScore.tier` — a `level_N` string. */
+  tier: string;
+  /** `WaitlistScore.ruleTrace` — opaque at this boundary, mirroring
+   * `packages/validation`'s own `ruleTrace: z.unknown()` convention; parsed
+   * defensively for the Level-1 loop-back framing only (see
+   * `decidingRefNames`). */
+  ruleTrace: unknown;
+}
+
+export interface CompilePlaybookInput {
+  score: CompilePlaybookScoreInput;
+  plays: PlayLibrary;
+  leadId: string;
+}
+
+export interface CompilePlaybookResult {
+  source: PlaybookSource;
+  markdown: string;
+}
+
+/** A `compilePlaybook` input that cannot be compiled — the library declares
+ * no Level for the score's tier, or that Level has no plays (spec §5.3 — the
+ * play-library owner's defect, never a compile branch). */
+export class PlaybookCompileError extends Error {}
+
+const TIER_LEVEL_RE = /^level_(\d+)$/;
+
+/** The library entry for `level` — `levels[]` first, the `gate` pointer as a
+ * level-0 fallback only (mirrors `check-playbook.py`'s `_library_entry_for_level`,
+ * the #8496 amendment). */
+function levelEntryFor(library: PlayLibrary, level: number): PlaybookLevelEntry | undefined {
+  const fromLevels = library.levels.find((entry) => entry.level === level);
+  if (fromLevels) return fromLevels;
+  if (level === 0 && library.gate?.plays && library.gate.plays.length > 0) {
+    return {
+      level: 0,
+      plays: library.gate.plays,
+      unlocks_next: library.gate.unlocks_next ?? null,
+    };
+  }
+  return undefined;
+}
+
+/**
+ * The `ref(<name>)` def names that DECIDED the matched tier — every
+ * `kind: "predicate"` trace entry whose `tier` equals the matched tier AND
+ * whose `result` is `true`, with every `ref(...)` segment in its `path`
+ * extracted (`RuleTraceEntry.path` embeds each traversed def as
+ * `ref(<name>)`, per `evaluatePredicateNode`'s own path-building — there is
+ * no separate `def` field to read instead). Duck-typed, not
+ * `ruleTraceEntrySchema`-parsed: `ruleTrace` is `unknown` at every boundary
+ * this function is reached from (Prisma `Json`, the dashboard's own
+ * `z.unknown()`), and this compile never needs the full shape — only
+ * whether a specific ref fired true for this tier.
+ */
+function decidingRefNames(ruleTrace: unknown, tier: string): Set<string> {
+  const names = new Set<string>();
+  if (!Array.isArray(ruleTrace)) return names;
+  for (const entry of ruleTrace) {
+    if (typeof entry !== "object" || entry === null) continue;
+    const e = entry as Record<string, unknown>;
+    if (e["kind"] !== "predicate" || e["tier"] !== tier || e["result"] !== true) continue;
+    const path = e["path"];
+    if (typeof path !== "string") continue;
+    for (const m of path.matchAll(/ref\(([^)]+)\)/g)) {
+      names.add(m[1]!);
+    }
+  }
+  return names;
+}
+
+function renderPlaybookMarkdown(args: {
+  source: PlaybookSource;
+  entry: PlaybookLevelEntry;
+  unlockEntry: PlaybookLevelEntry | undefined;
+  isLoopBackCohort: boolean;
+}): string {
+  const { source, entry, unlockEntry, isLoopBackCohort } = args;
+  const heading = entry.name ? `Level ${source.level} — ${entry.name}` : `Level ${source.level}`;
+  const lines: string[] = [];
+
+  lines.push(`# Playbook — ${heading}`, "");
+
+  if (isLoopBackCohort) {
+    lines.push(
+      "> You reached Level 1 via the Level-6 loop-back — a confirmed-Fit " +
+        "cohort (not paying customers) put you here. Once this Level has " +
+        "given you a validated ICP filter, revisit at Level 7 or 8.",
+      "",
+    );
+  }
+
+  lines.push(
+    "## §1. Identity",
+    "",
+    `**artifact_type:** \`${source.artifact_type}\``,
+    `**scope:** \`${source.scope}\``,
+    `**scope_ref:** \`${source.scope_ref}\``,
+    `**method:** \`${source.method}\``,
+    `**level:** \`${source.level}\``,
+    `**compiled_from:** \`${source.compiled_from}\``,
+    "",
+    "<!-- machine-region -->",
+    `<!-- playbook-source:\n${JSON.stringify(source)}\n-->`,
+    "<!-- /machine-region -->",
+    "",
+    "---",
+    "",
+    "## §2. Plays",
+    "",
+    `### Level ${source.level}`,
+    "",
+  );
+  for (const play of entry.plays) {
+    lines.push(`- \`${play.id}\` — ${play.title}`);
+  }
+
+  if (unlockEntry && source.unlocks_next) {
+    lines.push(
+      "",
+      "---",
+      "",
+      "## §3. Unlocks next",
+      "",
+      `### Level ${unlockEntry.level}`,
+      "",
+    );
+    for (const play of unlockEntry.plays) {
+      lines.push(`- \`${play.id}\` — ${play.title}`);
+    }
+  }
+
+  return lines.join("\n") + "\n";
+}
+
+/**
+ * Compile a scored `targeting-maturity` signup into a person-scoped
+ * Playbook — pure, deterministic, no I/O (D1). Throws `PlaybookCompileError`
+ * when the library declares no Level for the score's tier, or that Level
+ * has no plays — the caller (`compileAndStorePlaybook`) is fail-soft over
+ * this throw (D4, spec §5.3).
+ */
+export function compilePlaybook(input: CompilePlaybookInput): CompilePlaybookResult {
+  const { score, plays, leadId } = input;
+
+  const match = TIER_LEVEL_RE.exec(score.tier);
+  if (!match) {
+    throw new PlaybookCompileError(
+      `cannot compile a Playbook for tier "${score.tier}" — not a level_N tier`,
+    );
+  }
+  const level = Number(match[1]);
+
+  const entry = levelEntryFor(plays, level);
+  if (!entry || entry.plays.length === 0) {
+    throw new PlaybookCompileError(
+      `the play library declares no plays for Level ${level} — a library defect, not a compile branch (spec §5.3)`,
+    );
+  }
+
+  let unlockEntry: PlaybookLevelEntry | undefined;
+  let unlockIds: string[] | undefined;
+  if (entry.unlocks_next !== null && entry.unlocks_next !== undefined) {
+    unlockEntry = levelEntryFor(plays, entry.unlocks_next);
+    if (unlockEntry && unlockEntry.plays.length > 0) {
+      unlockIds = unlockEntry.plays.map((play) => play.id);
+    }
+  }
+
+  const source: PlaybookSource = {
+    artifact_type: "playbook",
+    scope: "person",
+    scope_ref: leadId,
+    method: plays.method,
+    level,
+    plays: entry.plays.map((play) => play.id),
+    ...(unlockIds ? { unlocks_next: unlockIds } : {}),
+    compiled_from: score.id,
+  };
+
+  const isLoopBackCohort =
+    level === 1 && decidingRefNames(score.ruleTrace, score.tier).has("has_confirmed_fit_cohort");
+
+  const markdown = renderPlaybookMarkdown({ source, entry, unlockEntry, isLoopBackCohort });
+
+  return { source, markdown };
+}
+
+// ─── compileAndStorePlaybook — the fail-soft Prisma-touching wrapper (D4) ───
+
+export interface CompileAndStorePlaybookInput {
+  siteId: string;
+  leadId: string;
+  experimentKey: string;
+  scoreId: string;
+  tier: string;
+  ruleTrace: unknown;
+}
+
+/**
+ * Compile + append a `PlaybookInstance` row. Fail-soft over BOTH the pure
+ * compile (`PlaybookCompileError` or any other throw) and the Prisma write —
+ * a compile/store failure is logged and never fails the signup or the score
+ * (D4). The caller (`waitlist-scoring.ts`) awaits this unconditionally; it
+ * never throws.
+ */
+export async function compileAndStorePlaybook(
+  input: CompileAndStorePlaybookInput,
+): Promise<void> {
+  const { siteId, leadId, experimentKey, scoreId, tier, ruleTrace } = input;
+  try {
+    const { source, markdown } = compilePlaybook({
+      score: { id: scoreId, tier, ruleTrace },
+      plays: vendoredPlayLibrary(),
+      leadId,
+    });
+
+    await prisma.playbookInstance.create({
+      data: {
+        siteId,
+        leadId,
+        experimentKey,
+        scoreId,
+        tier,
+        level: source.level,
+        ruleTrace: (ruleTrace ?? null) as unknown as Prisma.InputJsonValue,
+        source: source as unknown as Prisma.InputJsonValue,
+        markdown,
+      },
+    });
+  } catch (err) {
+    logger.error(
+      {
+        siteId,
+        experimentKey,
+        leadId,
+        kind: "playbook_compile_failed",
+        errKind: err instanceof Error ? err.constructor.name : typeof err,
+      },
+      "[playbook-compile] compile/store failed — the score is unaffected",
+    );
+  }
+}

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

@@ -0,0 +1,263 @@
+/**
+ * @file playbook-render.ts
+ * @description FEAT-074 U4b (#4718) — renders a stored `PlaybookInstance` to
+ * a customer-facing PDF, on request.
+ *
+ * `renderPlaybookPdf({source, markdown, locale})` is a pure-TypeScript
+ * renderer (D2, spec §3): a small typed template lays out the Level/Gate
+ * heading, the Level's bound plays (title + body, resolved from `source`'s
+ * `plays`/`unlocks_next` id lists against the LIVE vendored play library —
+ * D1's "a template or renderer fix improves every already-issued Playbook"
+ * intent, so this deliberately reads the library fresh at render time
+ * rather than trusting anything frozen into the stored `markdown` snapshot),
+ * and the unlocks-next block. `markdown` is accepted per the spec's literal
+ * `{source, markdown, locale}` signature (matching `compilePlaybook`'s own
+ * `{source, markdown}` output pair, the exact shape `PlaybookInstance`
+ * persists) but is NOT parsed for content in this unit — `source`'s id
+ * lists plus a live library lookup already carry everything §2.1 requires
+ * (the Level label, the bound plays, the unlocks-next block); reserved for
+ * a future direct-render use.
+ *
+ * Renderer choice (D2, recorded per the dispatch's own requirement): PDF.js
+ * (mozilla's) sibling project `pdf-lib` (v1.17.1, MIT) — pure TypeScript,
+ * zero native dependencies (its own runtime deps —
+ * `@pdf-lib/standard-fonts`, `@pdf-lib/upng`, `pako`, `tslib` — are all pure
+ * JS/TS too), no headless browser, no postinstall download. It embeds the
+ * 14 PDF standard fonts (Helvetica here) with no external font files, and
+ * exposes `font.widthOfTextAtSize` for the manual word-wrap this file
+ * implements (pdf-lib has no built-in text-flow/wrap primitive — a small
+ * typed template has no need for one).
+ *
+ * A play id from `source.plays`/`source.unlocks_next` that the CURRENT
+ * vendored library no longer declares is a library defect, never a render
+ * branch — mirrors `playbook-compile.ts`'s own `PlaybookCompileError`
+ * posture ("a library defect, not a compile branch") applied symmetrically
+ * to render.
+ *
+ * Every CHROME label (the Level/Gate heading text, the "Plays"/"Unlocks
+ * next" section titles) is a `LocalizedString` resolved via
+ * `resolveLocalizedString` (`@working-theory/validation`, the ONE shared
+ * resolution rule — flow-i18n.ts's own header) against the request
+ * `locale`. Play TITLES/BODIES are read straight from the vendored library,
+ * which carries no `LocalizedString` shape of its own (English-only at the
+ * source, the same convention `compilePlaybook`'s stored `markdown` already
+ * uses) — the i18n requirement (spec §2.1) scopes to the renderer's own
+ * chrome, not to library content. `renderPlaybookPdf`'s fixed
+ * `{source, markdown, locale}` signature carries no separate flow
+ * `defaultLocale` field, so this file's label table declares `en` as its
+ * sole `defaultLocale` (a module constant, `LABEL_DEFAULT_LOCALE` below) —
+ * every label below currently declares only `en`, so this is presently a
+ * no-op fallback, kept for structural correctness against a future
+ * multi-locale label table.
+ *
+ * The Gate (Level 0) is labelled "Gate," never "Level 0" (spec §2.1's
+ * never-say-Level-0 rule — mirrors the operator dashboard's own
+ * `waitlistDashboard.level.gate` key, U4a D5, and the AC-1 Gate filename
+ * convention `playbook-gate.pdf`).
+ */
+
+import { resolveLocalizedString } from "@working-theory/validation";
+import { PDFDocument, PageSizes, StandardFonts, type PDFFont, type PDFPage } from "pdf-lib";
+
+import { loadVendoredPlayLibrary, type PlaybookPlay, type PlaybookSource, type PlayLibrary } from "./playbook-compile.js";
+
+// ─── Chrome labels — the CUSTOMER-FACING structural text (spec §2.1) ──────
+
+const LABEL_DEFAULT_LOCALE = "en";
+
+const LABELS = {
+  documentTitle: { en: "Your Playbook" },
+  gate: { en: "Gate" },
+  /** `{n}` is a literal placeholder — substituted after resolution. */
+  levelLabel: { en: "Level {n}" },
+  plays: { en: "Plays" },
+  unlocksNext: { en: "Unlocks next" },
+} as const satisfies Record<string, Record<string, string>>;
+
+function label(key: keyof typeof LABELS, locale: string): string {
+  return resolveLocalizedString(LABELS[key], locale, LABEL_DEFAULT_LOCALE);
+}
+
+/** Level 0 is "Gate," never "Level 0" (spec §2.1 — the never-say-Level-0 rule). */
+function levelHeading(level: number, locale: string): string {
+  if (level === 0) return label("gate", locale);
+  return label("levelLabel", locale).replace("{n}", String(level));
+}
+
+// ─── The vendored play library — a per-play id index ───────────────────────
+
+interface IndexedPlay {
+  play: PlaybookPlay;
+  level: number;
+  levelName: string | undefined;
+}
+
+/** A `source.plays`/`source.unlocks_next` id the CURRENT vendored library no
+ * longer declares — a library defect, never a render branch (mirrors
+ * `PlaybookCompileError`'s identical posture in `playbook-compile.ts`). */
+export class PlaybookRenderError extends Error {}
+
+/** Flattens every Level's `plays[]` into one id-keyed index, carrying each
+ * play's owning Level number + name — so an unlocks-next play id resolves
+ * both its own title/text AND which Level it belongs to, with no need to
+ * parse a `tm-<level>.<n>` id-format convention the schema does not
+ * guarantee. */
+function buildPlayIndex(library: PlayLibrary): Map<string, IndexedPlay> {
+  const index = new Map<string, IndexedPlay>();
+  for (const entry of library.levels) {
+    for (const play of entry.plays) {
+      index.set(play.id, { play, level: entry.level, levelName: entry.name });
+    }
+  }
+  return index;
+}
+
+function resolvePlays(index: Map<string, IndexedPlay>, ids: string[]): IndexedPlay[] {
+  return ids.map((id) => {
+    const entry = index.get(id);
+    if (!entry) {
+      throw new PlaybookRenderError(
+        `the vendored play library declares no play "${id}" — a library defect, never a render branch (mirrors playbook-compile.ts's PlaybookCompileError posture)`,
+      );
+    }
+    return entry;
+  });
+}
+
+// ─── Word wrap + pagination (pdf-lib has no built-in text-flow primitive) ──
+
+const PAGE_SIZE = PageSizes.Letter; // [612, 792]
+const MARGIN = 54; // 0.75in
+const CONTENT_WIDTH = PAGE_SIZE[0] - MARGIN * 2;
+const TOP_Y = PAGE_SIZE[1] - MARGIN;
+const BOTTOM_Y = MARGIN;
+
+/** Greedy word-wrap against a font's measured width — pdf-lib exposes
+ * `font.widthOfTextAtSize` but no wrap primitive of its own. */
+function wrapLine(text: string, font: PDFFont, size: number, maxWidth: number): string[] {
+  const words = text.split(/\s+/).filter((w) => w.length > 0);
+  const lines: string[] = [];
+  let current = "";
+  for (const word of words) {
+    const candidate = current.length > 0 ? `${current} ${word}` : word;
+    if (font.widthOfTextAtSize(candidate, size) <= maxWidth) {
+      current = candidate;
+    } else {
+      if (current.length > 0) lines.push(current);
+      current = word;
+    }
+  }
+  if (current.length > 0) lines.push(current);
+  return lines;
+}
+
+interface PdfWriter {
+  heading(text: string, size: number): void;
+  subheading(text: string, size: number): void;
+  paragraph(text: string, size: number): void;
+  spacer(height: number): void;
+  save(): Promise<Uint8Array>;
+}
+
+/** A closure-scoped writer (`@working-theory/design-system/no-undisciplined-class`
+ * forbids `this`-bearing stateful classes) — the mutable page/y cursor lives
+ * in this function's own local variables, never on an instance. */
+async function createPdfWriter(): Promise<PdfWriter> {
+  const doc = await PDFDocument.create();
+  const regular = await doc.embedFont(StandardFonts.Helvetica);
+  const bold = await doc.embedFont(StandardFonts.HelveticaBold);
+
+  let page: PDFPage = doc.addPage(PAGE_SIZE);
+  let y = TOP_Y;
+
+  function ensureSpace(height: number): void {
+    if (y - height < BOTTOM_Y) {
+      page = doc.addPage(PAGE_SIZE);
+      y = TOP_Y;
+    }
+  }
+
+  function drawLines(lines: string[], font: PDFFont, size: number, lineHeight: number): void {
+    for (const line of lines) {
+      ensureSpace(lineHeight);
+      page.drawText(line, { x: MARGIN, y: y - size, size, font });
+      y -= lineHeight;
+    }
+  }
+
+  return {
+    heading(text, size) {
+      ensureSpace(size * 1.6 + 8);
+      drawLines(wrapLine(text, bold, size, CONTENT_WIDTH), bold, size, size * 1.4);
+      y -= 8;
+    },
+    subheading(text, size) {
+      ensureSpace(size * 1.6 + 6);
+      drawLines(wrapLine(text, bold, size, CONTENT_WIDTH), bold, size, size * 1.35);
+      y -= 6;
+    },
+    paragraph(text, size) {
+      drawLines(wrapLine(text, regular, size, CONTENT_WIDTH), regular, size, size * 1.4);
+      y -= 6;
+    },
+    spacer(height) {
+      y -= height;
+    },
+    async save() {
+      return doc.save();
+    },
+  };
+}
+
+// ─── renderPlaybookPdf ───────────────────────────────────────────────────────
+
+export interface RenderPlaybookPdfInput {
+  source: PlaybookSource;
+  /** Accepted per the spec's literal signature; not parsed for content in
+   * this unit — see the file header. */
+  markdown: string;
+  locale: string;
+}
+
+/**
+ * Renders a stored `PlaybookInstance` to a PDF: the Level/Gate heading, the
+ * Level's bound plays (title + body from the LIVE vendored library), and
+ * the unlocks-next block (spec §2.1). Throws `PlaybookRenderError` when the
+ * current library no longer declares a play `source` names — a library
+ * defect, never a render branch.
+ */
+export async function renderPlaybookPdf(input: RenderPlaybookPdfInput): Promise<Uint8Array> {
+  const { source, locale } = input;
+
+  const library = loadVendoredPlayLibrary();
+  const index = buildPlayIndex(library);
+
+  const currentPlays = resolvePlays(index, source.plays);
+  const unlockPlays = source.unlocks_next ? resolvePlays(index, source.unlocks_next) : [];
+
+  const writer = await createPdfWriter();
+
+  writer.heading(label("documentTitle", locale), 20);
+  writer.subheading(levelHeading(source.level, locale), 15);
+  writer.spacer(4);
+
+  writer.subheading(label("plays", locale), 13);
+  renderPlays(writer, currentPlays);
+
+  if (unlockPlays.length > 0) {
+    writer.spacer(10);
+    const unlockLevel = unlockPlays[0]!.level;
+    writer.subheading(`${label("unlocksNext", locale)} — ${levelHeading(unlockLevel, locale)}`, 13);
+    renderPlays(writer, unlockPlays);
+  }
+
+  return writer.save();
+}
+
+function renderPlays(writer: PdfWriter, plays: IndexedPlay[]): void {
+  for (const { play } of plays) {
+    writer.paragraph(`• ${play.title}`, 11);
+    writer.paragraph(play.text, 10);
+    writer.spacer(4);
+  }
+}