@markbrutx/promptbook-core 0.1.0

package/src/bundle.ts

@@ -0,0 +1,163 @@
+import type { CodePrompt, CodePromptSample, Composition, Fragment, PromptBook, Rule } from "./types.js";
+
+/** Options for {@link serializeBook}. */
+export interface SerializeBookOptions {
+  /** Module specifier for the `import type { PromptBook }` line. Default `@markbrutx/promptbook-core`. */
+  importSpecifier?: string;
+  /**
+   * Emit the `import type { PromptBook }` line and the `: PromptBook`
+   * annotation. Default `true`. Set `false` for a plain, inference-typed
+   * module — useful for runtimes that cannot resolve the type-only import
+   * (e.g. Deno consuming the raw build), where the value still resolves fine.
+   */
+  typed?: boolean;
+}
+
+/** Locale-independent string order so serialized output is byte-stable across machines. */
+function compareKeys(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/** Map entries sorted by key with a locale-independent comparator. */
+function sortedEntries<T>(map: Map<string, T>): [string, T][] {
+  return [...map.entries()].sort((a, b) => compareKeys(a[0], b[0]));
+}
+
+/** Drop keys whose value is `undefined`, preserving insertion (declaration) order. */
+function compact(obj: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (value !== undefined) {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+
+// The canonical builders below list every key explicitly via a
+// `Record<keyof Required<…>>` literal: adding a field to the data model is then
+// a compile error here until it is serialized, so the bundler never silently
+// drops data. Key order follows the type declaration; absent optionals are
+// compacted away. `JSON.stringify` of the result is a deterministic literal.
+
+function canonicalFragment(fragment: Fragment): Record<string, unknown> {
+  const ordered: Record<keyof Required<Fragment>, unknown> = {
+    id: fragment.id,
+    kind: fragment.kind,
+    tags: fragment.tags,
+    body: fragment.body,
+    sourceFile: fragment.sourceFile,
+  };
+  return compact(ordered);
+}
+
+function canonicalRule(rule: Rule): Record<string, unknown> {
+  const ordered: Record<keyof Required<Rule>, unknown> = {
+    index: rule.index,
+    when: rule.when,
+    action: rule.action,
+    add: rule.add,
+    after: rule.after,
+    replace: rule.replace,
+    forbid: rule.forbid,
+    order: rule.order,
+  };
+  return compact(ordered);
+}
+
+function canonicalComposition(composition: Composition): Record<string, unknown> {
+  const ordered: Record<keyof Required<Composition>, unknown> = {
+    name: composition.name,
+    base: composition.base,
+    order: composition.order,
+    rules: composition.rules.map(canonicalRule),
+    sourceFile: composition.sourceFile,
+  };
+  return compact(ordered);
+}
+
+function canonicalCodePromptSample(sample: CodePromptSample): Record<string, unknown> {
+  const ordered: Record<keyof Required<CodePromptSample>, unknown> = {
+    label: sample.label,
+    context: sample.context,
+    output: sample.output,
+  };
+  return compact(ordered);
+}
+
+function canonicalCodePrompt(codePrompt: CodePrompt): Record<string, unknown> {
+  const ordered: Record<keyof Required<CodePrompt>, unknown> = {
+    name: codePrompt.name,
+    description: codePrompt.description,
+    samples: codePrompt.samples.map(canonicalCodePromptSample),
+    sourceFile: codePrompt.sourceFile,
+  };
+  return compact(ordered);
+}
+
+/** Emit `new Map([...])` with one `[key, value]` entry per line (entries pre-sorted). */
+function serializeMap<T>(entries: [string, T][], canonical: (value: T) => unknown): string {
+  if (entries.length === 0) {
+    return "new Map([])";
+  }
+  const lines = entries.map(
+    ([key, value]) => `    [${JSON.stringify(key)}, ${JSON.stringify(canonical(value))}],`,
+  );
+  return `new Map([\n${lines.join("\n")}\n  ])`;
+}
+
+/**
+ * Serialize a {@link PromptBook} to a deterministic, evaluable expression:
+ * `{ fragments: new Map([...]), compositions: new Map([...]),
+ *    codePrompts: new Map([...]), warnings: [...] }`.
+ *
+ * The result is pure JavaScript (only `new Map`, arrays, object and scalar
+ * literals) so it can be embedded in a module or reconstructed directly. Map
+ * entries are sorted by key and optional fields are omitted when absent, so the
+ * same book always produces byte-identical output.
+ */
+export function serializeBookExpression(book: PromptBook): string {
+  const fragments = serializeMap(sortedEntries(book.fragments), canonicalFragment);
+  const compositions = serializeMap(sortedEntries(book.compositions), canonicalComposition);
+  const codePrompts = serializeMap(sortedEntries(book.codePrompts), canonicalCodePrompt);
+  const warnings = JSON.stringify(book.warnings);
+  return `{\n  fragments: ${fragments},\n  compositions: ${compositions},\n  codePrompts: ${codePrompts},\n  warnings: ${warnings},\n}`;
+}
+
+/**
+ * Serialize a {@link PromptBook} to an importable TypeScript module exporting
+ * `book: PromptBook`. Folding a prompts folder into a single module lets a
+ * runtime (e.g. a Deno edge function) import the book instead of reading the
+ * disk. Deterministic: the same book yields the same module text.
+ *
+ * The `: PromptBook` annotation is required so literal rule actions narrow to
+ * `RuleAction` via contextual typing; pass `typed: false` (or use
+ * {@link serializeBookExpression}) for the annotation-free value.
+ */
+export function serializeBook(book: PromptBook, options: SerializeBookOptions = {}): string {
+  const typed = options.typed !== false;
+  const importSpecifier = options.importSpecifier ?? "@markbrutx/promptbook-core";
+  return [
+    "// Code generated by `promptbook bundle`; do not edit by hand.",
+    ...(typed ? [`import type { PromptBook } from "${importSpecifier}";`] : []),
+    "",
+    `export const book${typed ? ": PromptBook" : ""} = ${serializeBookExpression(book)};`,
+    "",
+    "export default book;",
+    "",
+  ].join("\n");
+}
+
+/**
+ * Serialize a {@link PromptBook} to a deterministic JSON dump: fragments,
+ * compositions and code-prompts as key-sorted arrays of their canonical objects,
+ * plus warnings.
+ * Shares the canonical key order and locale-independent sort with
+ * {@link serializeBook}, so the JSON and module outputs never drift.
+ */
+export function serializeBookJson(book: PromptBook): string {
+  const fragments = sortedEntries(book.fragments).map(([, value]) => canonicalFragment(value));
+  const compositions = sortedEntries(book.compositions).map(([, value]) => canonicalComposition(value));
+  const codePrompts = sortedEntries(book.codePrompts).map(([, value]) => canonicalCodePrompt(value));
+  return `${JSON.stringify({ fragments, compositions, codePrompts, warnings: book.warnings }, null, 2)}\n`;
+}

package/src/edge.ts

@@ -0,0 +1,11 @@
+/**
+ * Self-contained entrypoint for edge / Deno runtimes that only need to resolve
+ * an already-bundled book at request time (no folder loading). Its module graph
+ * is just {@link resolveBook} + {@link interpolate} — zero filesystem, YAML, or
+ * Node builtins — so `scripts/build-edge.mjs` bundles it to one portable ESM
+ * file with no external imports. Consumers (e.g. a Supabase edge function) vendor
+ * that file and pair it with a `promptbook bundle` book.
+ */
+export { interpolate } from "./interpolate.js";
+export { resolveBook } from "./resolve-book.js";
+export type { Context, PromptBook, ResolveResult, Trace } from "./types.js";

package/src/eval/assertions.ts

@@ -0,0 +1,174 @@
+/**
+ * Built-in, pluggable assertions for the eval engine.
+ *
+ * Each checker is pure: it inspects a model output against an {@link Assertion}
+ * spec and returns an {@link AssertionResult}. Callers can pass their own
+ * registry to {@link evaluate} to add or replace checkers, exactly like lint
+ * rules. The `language` checker is a script heuristic, not an LLM judge.
+ */
+import type { Assertion, AssertionFn, AssertionRegistry, AssertionResult } from "./types.js";
+
+const EXCERPT_LIMIT = 160;
+
+/** A short, single-line excerpt of the output for failure messages. */
+function excerpt(text: string): string {
+  const collapsed = text.replace(/\s+/g, " ").trim();
+  return collapsed.length > EXCERPT_LIMIT ? `${collapsed.slice(0, EXCERPT_LIMIT)}…` : collapsed;
+}
+
+function result(type: string, pass: boolean, message: string, output: string): AssertionResult {
+  return { type, pass, message, excerpt: excerpt(output) };
+}
+
+/** Require a spec field to be present, with a clear error when it is not. */
+function need<T>(value: T | undefined, type: string, field: string): T {
+  if (value === undefined) {
+    throw new Error(`assertion "${type}" requires a "${field}" field.`);
+  }
+  return value;
+}
+
+function buildRegex(assertion: Assertion): RegExp {
+  const pattern = need(assertion.pattern, assertion.type, "pattern");
+  try {
+    return new RegExp(pattern, assertion.flags);
+  } catch (error) {
+    throw new Error(`assertion "${assertion.type}" has an invalid pattern: ${(error as Error).message}`);
+  }
+}
+
+const contains: AssertionFn = (output, a) => {
+  const value = need(a.value, "contains", "value");
+  const pass = output.includes(value);
+  return result("contains", pass, pass ? `contains "${value}"` : `missing "${value}"`, output);
+};
+
+const notContains: AssertionFn = (output, a) => {
+  const value = need(a.value, "not-contains", "value");
+  const pass = !output.includes(value);
+  return result(
+    "not-contains",
+    pass,
+    pass ? `does not contain "${value}"` : `unexpectedly contains "${value}"`,
+    output,
+  );
+};
+
+const matches: AssertionFn = (output, a) => {
+  const re = buildRegex({ ...a, type: "matches" });
+  const pass = re.test(output);
+  return result("matches", pass, pass ? `matches /${re.source}/` : `does not match /${re.source}/`, output);
+};
+
+const notMatches: AssertionFn = (output, a) => {
+  const re = buildRegex({ ...a, type: "not-matches" });
+  const pass = !re.test(output);
+  return result(
+    "not-matches",
+    pass,
+    pass ? `does not match /${re.source}/` : `unexpectedly matches /${re.source}/`,
+    output,
+  );
+};
+
+const equals: AssertionFn = (output, a) => {
+  const value = need(a.value, "equals", "value");
+  const pass = output.trim() === value.trim();
+  return result("equals", pass, pass ? "equals expected text" : "does not equal expected text", output);
+};
+
+const jsonValid: AssertionFn = (output) => {
+  try {
+    JSON.parse(output);
+    return result("json-valid", true, "output is valid JSON", output);
+  } catch (error) {
+    return result("json-valid", false, `output is not valid JSON: ${(error as Error).message}`, output);
+  }
+};
+
+const maxLength: AssertionFn = (output, a) => {
+  const max = need(a.max, "max-length", "max");
+  const pass = output.length <= max;
+  return result(
+    "max-length",
+    pass,
+    pass ? `length ${output.length} within ${max}` : `length ${output.length} exceeds ${max}`,
+    output,
+  );
+};
+
+/** Map common language tags to the script the `language` heuristic checks. */
+const SCRIPT_BY_LANGUAGE: Record<string, "cyrillic" | "latin"> = {
+  ru: "cyrillic",
+  uk: "cyrillic",
+  be: "cyrillic",
+  bg: "cyrillic",
+  sr: "cyrillic",
+  mk: "cyrillic",
+  en: "latin",
+  fr: "latin",
+  es: "latin",
+  de: "latin",
+  it: "latin",
+  pt: "latin",
+  nl: "latin",
+  pl: "latin",
+  cs: "latin",
+  ro: "latin",
+  tr: "latin",
+  sv: "latin",
+  da: "latin",
+  no: "latin",
+  fi: "latin",
+};
+
+const CYRILLIC = /\p{Script=Cyrillic}/gu;
+const LATIN = /\p{Script=Latin}/gu;
+
+function count(text: string, re: RegExp): number {
+  return text.match(re)?.length ?? 0;
+}
+
+/**
+ * `language`: script-based heuristic. Resolves the spec `lang` to a script
+ * ("cyrillic"/"latin", either directly or via a language tag) and passes when
+ * that script has at least one letter and is at least as frequent as the
+ * other. Not an LLM judge — it detects script, not fluency.
+ */
+const language: AssertionFn = (output, a) => {
+  const lang = need(a.lang, "language", "lang").toLowerCase();
+  const script = SCRIPT_BY_LANGUAGE[lang] ?? lang;
+  if (script !== "cyrillic" && script !== "latin") {
+    return result("language", false, `unsupported language "${a.lang}" (no script heuristic)`, output);
+  }
+  const cyrillic = count(output, CYRILLIC);
+  const latin = count(output, LATIN);
+  const expected = script === "cyrillic" ? cyrillic : latin;
+  const other = script === "cyrillic" ? latin : cyrillic;
+  const pass = expected > 0 && expected >= other;
+  return result(
+    "language",
+    pass,
+    pass
+      ? `output is predominantly ${script}`
+      : `expected predominantly ${script} (cyrillic=${cyrillic}, latin=${latin})`,
+    output,
+  );
+};
+
+/**
+ * The built-in assertion registry. Pass a merged/replaced object to
+ * {@link evaluate} to customize: `{ ...defaultAssertions(), myType: fn }`.
+ */
+export function defaultAssertions(): AssertionRegistry {
+  return {
+    contains,
+    "not-contains": notContains,
+    matches,
+    "not-matches": notMatches,
+    equals,
+    "json-valid": jsonValid,
+    "max-length": maxLength,
+    language,
+  };
+}

package/src/eval/evaluate.ts

@@ -0,0 +1,84 @@
+import { resolveBook } from "../resolve-book.js";
+import { defaultAssertions } from "./assertions.js";
+import type {
+  Assertion,
+  AssertionRegistry,
+  AssertionResult,
+  EvalInput,
+  EvalReport,
+  Fixture,
+  FixtureResult,
+} from "./types.js";
+
+/** Run every assertion of a fixture against one model output. */
+function runAssertions(output: string, asserts: Assertion[], registry: AssertionRegistry): AssertionResult[] {
+  return asserts.map((assertion) => {
+    const fn = registry[assertion.type];
+    if (fn === undefined) {
+      return { type: assertion.type, pass: false, message: `unknown assertion type "${assertion.type}"` };
+    }
+    return fn(output, assertion);
+  });
+}
+
+/**
+ * Run fixtures through a model adapter and report pass-rate.
+ *
+ * For each fixture: assemble the system prompt once via {@link resolveBook}
+ * (deterministic — every sample of a fixture sees the same prompt), then take
+ * N samples through `adapter.complete` and run the assertions on each. A sample
+ * passes only when all its assertions pass; `passRate = passes / samples`. A
+ * fixture meets the gate when `passRate >= passThreshold` (default 1).
+ *
+ * The engine is pure given the adapter: its control flow is deterministic and
+ * the only stochasticity/IO is `adapter.complete`. It makes no network calls.
+ */
+export async function evaluate(input: EvalInput): Promise<EvalReport> {
+  const registry = input.assertions ?? defaultAssertions();
+  const defaultSamples = input.samples ?? 1;
+  const threshold = input.passThreshold ?? 1;
+
+  const results: FixtureResult[] = [];
+  for (const fixture of input.fixtures) {
+    results.push(await runFixture(fixture, input, registry, defaultSamples));
+  }
+
+  const passed = results.filter((r) => r.passRate >= threshold).length;
+  return {
+    results,
+    passed,
+    failed: results.length - passed,
+    passRate: results.length === 0 ? 1 : passed / results.length,
+  };
+}
+
+async function runFixture(
+  fixture: Fixture,
+  input: EvalInput,
+  registry: AssertionRegistry,
+  defaultSamples: number,
+): Promise<FixtureResult> {
+  const { text: system } = resolveBook(input.book, fixture.prompt, fixture.context ?? {});
+  const samples = fixture.samples ?? defaultSamples;
+
+  let passes = 0;
+  const failures: AssertionResult[] = [];
+  for (let i = 0; i < samples; i += 1) {
+    const response = await input.adapter.complete({ system, input: fixture.input });
+    const sampleResults = runAssertions(response.text, fixture.assert, registry);
+    const failed = sampleResults.filter((r) => !r.pass);
+    if (failed.length === 0) {
+      passes += 1;
+    } else {
+      failures.push(...failed);
+    }
+  }
+
+  return {
+    name: fixture.name,
+    samples,
+    passes,
+    passRate: samples === 0 ? 0 : passes / samples,
+    failures,
+  };
+}

package/src/eval/load-fixtures.ts

@@ -0,0 +1,91 @@
+import { nodeFs } from "../fs.js";
+import { isContextValue, isMapping } from "../guards.js";
+import { joinPath, listFiles, stripExt } from "../paths.js";
+import type { Context, FsAdapter } from "../types.js";
+import type { Assertion, Fixture } from "./types.js";
+
+function parseContext(raw: unknown, file: string): Context | undefined {
+  if (raw === undefined) {
+    return undefined;
+  }
+  if (!isMapping(raw)) {
+    throw new Error(`Fixture "${file}" has a "context" that is not an object.`);
+  }
+  const context: Context = {};
+  for (const [key, value] of Object.entries(raw)) {
+    if (!isContextValue(value)) {
+      throw new Error(`Fixture "${file}" context key "${key}" must be a string, number or boolean.`);
+    }
+    context[key] = value;
+  }
+  return context;
+}
+
+function parseAssertions(raw: unknown, file: string): Assertion[] {
+  if (!Array.isArray(raw) || raw.length === 0) {
+    throw new Error(`Fixture "${file}" must declare a non-empty "assert" array.`);
+  }
+  return raw.map((entry, index) => {
+    if (!isMapping(entry) || typeof entry.type !== "string" || entry.type === "") {
+      throw new Error(`Fixture "${file}" assertion #${index} must be an object with a string "type".`);
+    }
+    return entry as unknown as Assertion;
+  });
+}
+
+function parseFixture(raw: unknown, file: string, fallbackName: string): Fixture {
+  if (!isMapping(raw)) {
+    throw new Error(`Fixture "${file}" is not a JSON object.`);
+  }
+  if (typeof raw.prompt !== "string" || raw.prompt === "") {
+    throw new Error(`Fixture "${file}" must declare a string "prompt".`);
+  }
+  if (typeof raw.input !== "string") {
+    throw new Error(`Fixture "${file}" must declare a string "input".`);
+  }
+  const name = typeof raw.name === "string" && raw.name !== "" ? raw.name : fallbackName;
+  const fixture: Fixture = {
+    name,
+    prompt: raw.prompt,
+    input: raw.input,
+    assert: parseAssertions(raw.assert, file),
+    sourceFile: file,
+  };
+  const context = parseContext(raw.context, file);
+  if (context !== undefined) {
+    fixture.context = context;
+  }
+  if (raw.samples !== undefined) {
+    if (typeof raw.samples !== "number" || !Number.isInteger(raw.samples) || raw.samples <= 0) {
+      throw new Error(`Fixture "${file}" "samples" must be a positive integer.`);
+    }
+    fixture.samples = raw.samples;
+  }
+  return fixture;
+}
+
+/**
+ * Load eval fixtures from `<dir>/fixtures/*.json` into {@link Fixture}s.
+ *
+ * Mirrors {@link loadPrompts}: the same `dir` that holds `fragments/` and
+ * `rules/` also holds `fixtures/`. A missing `fixtures/` folder yields an empty
+ * list; a malformed fixture throws with its file path so the caller can report
+ * it. Files are read in sorted order for deterministic results.
+ */
+export async function loadFixtures(dir: string, fs: FsAdapter = nodeFs()): Promise<Fixture[]> {
+  const fixturesDir = joinPath(dir, "fixtures");
+  const files = await listFiles(fs, fixturesDir, [".json"]);
+  const fixtures: Fixture[] = [];
+  for (const file of files) {
+    const full = joinPath(fixturesDir, file);
+    const raw = await fs.readFile(full);
+    let doc: unknown;
+    try {
+      doc = JSON.parse(raw);
+    } catch (error) {
+      throw new Error(`Fixture "${full}" is not valid JSON: ${(error as Error).message}`);
+    }
+    fixtures.push(parseFixture(doc, full, stripExt(file)));
+  }
+  return fixtures;
+}

package/src/eval/types.ts

@@ -0,0 +1,134 @@
+/**
+ * Public types for the eval engine.
+ *
+ * Eval is the one place stochasticity enters the system, and it is locked
+ * behind an injectable {@link ModelAdapter}. The engine's control flow is
+ * deterministic: given the same adapter outputs it returns the same report.
+ * The core ships no adapter and makes no network calls — a concrete adapter
+ * (e.g. `@markbrutx/promptbook-openrouter`) lives in its own package.
+ */
+import type { Context, PromptBook } from "../types.js";
+
+/** Token accounting, when an adapter reports it. Provider-agnostic shape. */
+export interface ModelUsage {
+  promptTokens?: number;
+  completionTokens?: number;
+  totalTokens?: number;
+}
+
+/** One model call: the assembled system prompt plus the user input. */
+export interface ModelRequest {
+  /** The assembled system prompt from {@link resolveBook}. */
+  system: string;
+  /** The user input that accompanies the system prompt. */
+  input: string;
+  /** Optional per-request model override; adapters define the default. */
+  model?: string;
+}
+
+/** A model's reply. `raw` carries the provider payload for debugging. */
+export interface ModelResponse {
+  text: string;
+  usage?: ModelUsage;
+  raw?: unknown;
+}
+
+/**
+ * The seam stochasticity is locked behind. Implementations perform IO/network;
+ * the eval engine only ever calls `complete`, so it stays pure given a fake.
+ */
+export interface ModelAdapter {
+  complete(request: ModelRequest): Promise<ModelResponse>;
+}
+
+/**
+ * A single assertion spec as authored in a fixture JSON. `type` selects the
+ * checker from the assertion registry; the remaining fields are its params.
+ */
+export interface Assertion {
+  /** Registry key, e.g. "contains" or "language". */
+  type: string;
+  /** Substring (contains/not-contains) or exact text (equals). */
+  value?: string;
+  /** Regex source for matches/not-matches. */
+  pattern?: string;
+  /** Regex flags for matches/not-matches. */
+  flags?: string;
+  /** Character ceiling for max-length. */
+  max?: number;
+  /** Expected language tag or script for `language` (e.g. "ru", "latin"). */
+  lang?: string;
+}
+
+/** The outcome of running one assertion against one model output. */
+export interface AssertionResult {
+  /** The assertion `type` that produced this result. */
+  type: string;
+  pass: boolean;
+  /** Human-readable, domain-agnostic explanation. */
+  message: string;
+  /** A short excerpt of the output relevant to the assertion. */
+  excerpt?: string;
+}
+
+/** A checker for one assertion type. Pure: same output + spec, same result. */
+export type AssertionFn = (output: string, assertion: Assertion) => AssertionResult;
+
+/** Map of assertion `type` to its checker. Callers may supply their own. */
+export type AssertionRegistry = Record<string, AssertionFn>;
+
+/** A single eval test case loaded from a `fixtures/*.json` file. */
+export interface Fixture {
+  /** Lookup name; defaults to the file stem when omitted in JSON. */
+  name: string;
+  /** Composition name to assemble for this case. */
+  prompt: string;
+  /** Facts to resolve the composition under. */
+  context?: Context;
+  /** User input sent alongside the assembled system prompt. */
+  input: string;
+  /** Assertions every sample's output must satisfy. */
+  assert: Assertion[];
+  /** Per-fixture sample count; overrides the run-level default. */
+  samples?: number;
+  /** File the fixture was loaded from. */
+  sourceFile?: string;
+}
+
+/** Per-fixture aggregate over its samples. */
+export interface FixtureResult {
+  name: string;
+  /** Number of samples taken. */
+  samples: number;
+  /** Samples where every assertion passed. */
+  passes: number;
+  /** `passes / samples` (0 when `samples` is 0). */
+  passRate: number;
+  /** Every failing assertion across all samples, with messages/excerpts. */
+  failures: AssertionResult[];
+}
+
+/** The aggregated outcome of an eval run. */
+export interface EvalReport {
+  results: FixtureResult[];
+  /** Fraction of fixtures that met the threshold gate (`passed / total`). */
+  passRate: number;
+  /** Fixtures whose `passRate >= passThreshold`. */
+  passed: number;
+  /** Fixtures whose `passRate < passThreshold`. */
+  failed: number;
+}
+
+/** Input to {@link evaluate}. */
+export interface EvalInput {
+  book: PromptBook;
+  fixtures: Fixture[];
+  /** The injected model seam; all stochasticity/IO lives here. */
+  adapter: ModelAdapter;
+  /** Assertion checkers; defaults to {@link defaultAssertions}. */
+  assertions?: AssertionRegistry;
+  /** Default sample count when a fixture sets none. Defaults to 1. */
+  samples?: number;
+  /** A fixture passes when `passRate >= passThreshold`. Defaults to 1. */
+  passThreshold?: number;
+}

package/src/frontmatter.ts

@@ -0,0 +1,28 @@
+import { parse as parseYaml } from "yaml";
+import { isMapping } from "./guards.js";
+
+export interface ParsedFrontmatter {
+  data: Record<string, unknown>;
+  body: string;
+}
+
+/** Matches a leading `---\n ... \n---` YAML frontmatter block. */
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?/;
+
+/**
+ * Split a Markdown file into YAML frontmatter (parsed) and the body text.
+ *
+ * Intentionally dependency-light: a single YAML parser, no extra frontmatter
+ * library, so the core stays small and easy to run anywhere.
+ */
+export function parseFrontmatter(raw: string): ParsedFrontmatter {
+  const match = raw.match(FRONTMATTER_RE);
+  if (!match) {
+    return { data: {}, body: raw };
+  }
+  const yamlText = match[1] ?? "";
+  const parsed = parseYaml(yamlText) as unknown;
+  const data = isMapping(parsed) ? parsed : {};
+  const body = raw.slice(match[0].length);
+  return { data, body };
+}