@markbrutx/promptbook-core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 markbrutx
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,53 @@
+# @markbrutx/promptbook-core
+
+Agnostic, deterministic core for composing prompts from reusable fragments via
+declarative rules. No CLI, no UI, no domain knowledge — it only **selects**,
+**orders** and **interpolates** fragments, and explains what it did.
+
+## Model
+
+- **fragment** (WHAT) — a reusable micro-prompt: a Markdown file with YAML
+  frontmatter (`id`, optional `kind`/`tags`) and a body that may contain
+  `${path}` placeholders.
+- **composition** — a full system prompt declared in `rules/<name>.yaml`:
+  an ordered `base` list of fragment ids, an optional `order`, and `rules`.
+- **rule** (WHEN) — `when <context> → one action`. Actions: `add` (optionally
+  `after: <id>`), `replace` (old → new), `forbid`, `order`. Empty `when` always
+  fires.
+- **context** — a flat bag of scalar facts. Any computed value (digests,
+  scores, sorted lists) is pre-computed by the caller and passed in.
+
+## Folder layout
+
+```
+prompts/
+├─ fragments/   *.md   (text + frontmatter)
+└─ rules/       *.yaml  (composition + rules)
+```
+
+## Usage
+
+```ts
+import { resolve } from "@markbrutx/promptbook-core";
+
+const { text, trace } = await resolve({
+  promptsDir: "./prompts",
+  prompt: "assistant",
+  context: { mode: "terse", locale: "ru", subjectName: "Ada" },
+});
+```
+
+`resolve` returns `{ text, trace }`. `text` is the fragments joined with `\n\n`,
+in final order, with `${...}` substituted. `trace` is the explain output: every
+rule (fired + why), the final id order, what was replaced/added/forbidden,
+context axes no rule matched, and warnings.
+
+## Guarantees
+
+- **Deterministic.** Same folder contents + input → byte-identical `text`.
+- **Never throws on data.** A missing `${var}` renders empty and is recorded in
+  `trace.warnings`; an unknown fragment reference is a warning, not a crash.
+- **Conflict strategy.** Rules apply in order, later wins (cascade). `forbid` is
+  the one exception: it is a final filter and always wins.
+- **Runtime-agnostic.** Pure functions; the filesystem is injectable
+  (`FsAdapter`), so it runs under Node, Deno and Bun.

package/dist/annotations.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The viewer→agent feedback queue: the annotation data shape plus the JSONL
+ * (de)serialization both ends share. The on-disk file is the cross-process
+ * contract — the viewer writes it, an agent's CLI reads and clears it — so the
+ * schema lives in one place. These helpers are pure and deterministic; the
+ * non-deterministic parts (id/timestamp generation, disk IO) live in the
+ * writer, not here.
+ */
+import type { Context } from "./types.js";
+/** Queue directory, relative to the prompts folder — the cross-process contract. */
+export declare const ANNOTATION_QUEUE_DIR = ".annotations";
+/** Queue file inside {@link ANNOTATION_QUEUE_DIR}, one annotation per line. */
+export declare const ANNOTATION_QUEUE_FILE = "inbox.jsonl";
+/** An annotation is open until an agent resolves it. */
+export type AnnotationStatus = "open" | "resolved";
+/** What an annotation points at: a composition variant or a standalone fragment. */
+export interface AnnotationTarget {
+    /** Composition the annotated variant was assembled from. */
+    prompt?: string;
+    /** Context the variant was resolved under (present alongside `prompt`). */
+    context?: Context;
+    /** A fragment id, when annotating a fragment directly rather than a variant. */
+    fragmentId?: string;
+    /** Source file of the fragment/composition, to help the agent locate it. */
+    sourceFile?: string;
+}
+/** Where, inside the source text, the comment is anchored. */
+export interface AnnotationAnchor {
+    /** Fragment whose body carries the selected text. */
+    fragmentId: string;
+    /** The exact text the user selected. */
+    anchorText: string;
+    /** Optional character offset within the fragment body, for disambiguation. */
+    offset?: number;
+}
+/** One queued piece of human feedback, waiting for an agent to act on it. */
+export interface Annotation {
+    id: string;
+    /** ISO-8601 creation time. */
+    createdAt: string;
+    target: AnnotationTarget;
+    anchor: AnnotationAnchor;
+    comment: string;
+    status: AnnotationStatus;
+}
+/**
+ * Parse the inbox JSONL: one annotation per non-empty line. Malformed lines are
+ * skipped rather than thrown — the queue must never crash on data, so a single
+ * bad line cannot block the rest.
+ */
+export declare function parseInbox(text: string): Annotation[];
+/** Serialize one annotation as a single append-safe JSONL line (with newline). */
+export declare function serializeAnnotationLine(annotation: Annotation): string;
+/** Serialize a whole queue back to JSONL, used when removing/rewriting entries. */
+export declare function serializeInbox(annotations: Annotation[]): string;
+//# sourceMappingURL=annotations.d.ts.map

package/dist/annotations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotations.d.ts","sourceRoot":"","sources":["../src/annotations.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C,oFAAoF;AACpF,eAAO,MAAM,oBAAoB,iBAAiB,CAAC;AACnD,+EAA+E;AAC/E,eAAO,MAAM,qBAAqB,gBAAgB,CAAC;AAEnD,wDAAwD;AACxD,MAAM,MAAM,gBAAgB,GAAG,MAAM,GAAG,UAAU,CAAC;AAEnD,oFAAoF;AACpF,MAAM,WAAW,gBAAgB;IAC/B,4DAA4D;IAC5D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,gFAAgF;IAChF,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,8DAA8D;AAC9D,MAAM,WAAW,gBAAgB;IAC/B,qDAAqD;IACrD,UAAU,EAAE,MAAM,CAAC;IACnB,wCAAwC;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,6EAA6E;AAC7E,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,8BAA8B;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,gBAAgB,CAAC;IACzB,MAAM,EAAE,gBAAgB,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,gBAAgB,CAAC;CAC1B;AAkBD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,EAAE,CAiBrD;AAED,kFAAkF;AAClF,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,UAAU,GAAG,MAAM,CAEtE;AAED,mFAAmF;AACnF,wBAAgB,cAAc,CAAC,WAAW,EAAE,UAAU,EAAE,GAAG,MAAM,CAEhE"}

package/dist/annotations.js

@@ -0,0 +1,50 @@
+/** Queue directory, relative to the prompts folder — the cross-process contract. */
+export const ANNOTATION_QUEUE_DIR = ".annotations";
+/** Queue file inside {@link ANNOTATION_QUEUE_DIR}, one annotation per line. */
+export const ANNOTATION_QUEUE_FILE = "inbox.jsonl";
+/** True when `value` has the minimal required shape of an {@link Annotation}. */
+function isAnnotation(value) {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const record = value;
+    const anchor = record.anchor;
+    return (typeof record.id === "string" &&
+        typeof record.comment === "string" &&
+        typeof anchor === "object" &&
+        anchor !== null &&
+        typeof anchor.fragmentId === "string");
+}
+/**
+ * Parse the inbox JSONL: one annotation per non-empty line. Malformed lines are
+ * skipped rather than thrown — the queue must never crash on data, so a single
+ * bad line cannot block the rest.
+ */
+export function parseInbox(text) {
+    const annotations = [];
+    for (const line of text.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (trimmed === "") {
+            continue;
+        }
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (isAnnotation(parsed)) {
+                annotations.push(parsed);
+            }
+        }
+        catch {
+            // skip a malformed line; the rest of the queue stays usable
+        }
+    }
+    return annotations;
+}
+/** Serialize one annotation as a single append-safe JSONL line (with newline). */
+export function serializeAnnotationLine(annotation) {
+    return `${JSON.stringify(annotation)}\n`;
+}
+/** Serialize a whole queue back to JSONL, used when removing/rewriting entries. */
+export function serializeInbox(annotations) {
+    return annotations.map(serializeAnnotationLine).join("");
+}
+//# sourceMappingURL=annotations.js.map

package/dist/annotations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotations.js","sourceRoot":"","sources":["../src/annotations.ts"],"names":[],"mappings":"AAUA,oFAAoF;AACpF,MAAM,CAAC,MAAM,oBAAoB,GAAG,cAAc,CAAC;AACnD,+EAA+E;AAC/E,MAAM,CAAC,MAAM,qBAAqB,GAAG,aAAa,CAAC;AAsCnD,iFAAiF;AACjF,SAAS,YAAY,CAAC,KAAc;IAClC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAChD,OAAO,KAAK,CAAC;IACf,CAAC;IACD,MAAM,MAAM,GAAG,KAAgC,CAAC;IAChD,MAAM,MAAM,GAAG,MAAM,CAAC,MAA6C,CAAC;IACpE,OAAO,CACL,OAAO,MAAM,CAAC,EAAE,KAAK,QAAQ;QAC7B,OAAO,MAAM,CAAC,OAAO,KAAK,QAAQ;QAClC,OAAO,MAAM,KAAK,QAAQ;QAC1B,MAAM,KAAK,IAAI;QACf,OAAO,MAAM,CAAC,UAAU,KAAK,QAAQ,CACtC,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,IAAY;IACrC,MAAM,WAAW,GAAiB,EAAE,CAAC;IACrC,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;QACvC,MAAM,OAAO,GAAG,IAAI,CAAC,IAAI,EAAE,CAAC;QAC5B,IAAI,OAAO,KAAK,EAAE,EAAE,CAAC;YACnB,SAAS;QACX,CAAC;QACD,IAAI,CAAC;YACH,MAAM,MAAM,GAAY,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YAC5C,IAAI,YAAY,CAAC,MAAM,CAAC,EAAE,CAAC;gBACzB,WAAW,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;YAC3B,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,4DAA4D;QAC9D,CAAC;IACH,CAAC;IACD,OAAO,WAAW,CAAC;AACrB,CAAC;AAED,kFAAkF;AAClF,MAAM,UAAU,uBAAuB,CAAC,UAAsB;IAC5D,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC;AAC3C,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,cAAc,CAAC,WAAyB;IACtD,OAAO,WAAW,CAAC,GAAG,CAAC,uBAAuB,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;AAC3D,CAAC"}

package/dist/bundle.d.ts

@@ -0,0 +1,44 @@
+import type { PromptBook } 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;
+}
+/**
+ * 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 declare function serializeBookExpression(book: PromptBook): string;
+/**
+ * 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 declare function serializeBook(book: PromptBook, options?: SerializeBookOptions): string;
+/**
+ * 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 declare function serializeBookJson(book: PromptBook): string;
+//# sourceMappingURL=bundle.d.ts.map

package/dist/bundle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle.d.ts","sourceRoot":"","sources":["../src/bundle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAuD,UAAU,EAAQ,MAAM,YAAY,CAAC;AAExG,yCAAyC;AACzC,MAAM,WAAW,oBAAoB;IACnC,wGAAwG;IACxG,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AA+FD;;;;;;;;;GASG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAMhE;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,GAAE,oBAAyB,GAAG,MAAM,CAY1F;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAK1D"}

package/dist/bundle.js

@@ -0,0 +1,135 @@
+/** Locale-independent string order so serialized output is byte-stable across machines. */
+function compareKeys(a, b) {
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/** Map entries sorted by key with a locale-independent comparator. */
+function sortedEntries(map) {
+    return [...map.entries()].sort((a, b) => compareKeys(a[0], b[0]));
+}
+/** Drop keys whose value is `undefined`, preserving insertion (declaration) order. */
+function compact(obj) {
+    const out = {};
+    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) {
+    const ordered = {
+        id: fragment.id,
+        kind: fragment.kind,
+        tags: fragment.tags,
+        body: fragment.body,
+        sourceFile: fragment.sourceFile,
+    };
+    return compact(ordered);
+}
+function canonicalRule(rule) {
+    const ordered = {
+        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) {
+    const ordered = {
+        name: composition.name,
+        base: composition.base,
+        order: composition.order,
+        rules: composition.rules.map(canonicalRule),
+        sourceFile: composition.sourceFile,
+    };
+    return compact(ordered);
+}
+function canonicalCodePromptSample(sample) {
+    const ordered = {
+        label: sample.label,
+        context: sample.context,
+        output: sample.output,
+    };
+    return compact(ordered);
+}
+function canonicalCodePrompt(codePrompt) {
+    const ordered = {
+        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(entries, canonical) {
+    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) {
+    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, options = {}) {
+    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) {
+    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`;
+}
+//# sourceMappingURL=bundle.js.map

package/dist/bundle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bundle.js","sourceRoot":"","sources":["../src/bundle.ts"],"names":[],"mappings":"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"}

package/dist/edge/index.js

@@ -0,0 +1,192 @@
+// Generated by `npm run build:edge`; do not edit by hand.
+
+// dist/interpolate.js
+var VAR_RE = /(\\?)\$\{([^}]+)\}/g;
+function interpolate(body, context, onMissing) {
+  return body.replace(VAR_RE, (_match, backslash, expr) => {
+    if (backslash) {
+      return `\${${expr}}`;
+    }
+    const key = expr.trim();
+    const value = context[key];
+    if (value === void 0) {
+      onMissing(key);
+      return "";
+    }
+    return String(value);
+  });
+}
+
+// dist/resolve-book.js
+function resolveBook(book, prompt, context) {
+  const composition = book.compositions.get(prompt);
+  if (!composition) {
+    const available = [...book.compositions.keys()].sort().join(", ") || "(none)";
+    throw new Error(`Unknown prompt "${prompt}". Available compositions: ${available}.`);
+  }
+  const warnings = [...book.warnings];
+  const ruleTraces = [];
+  const replaced = [];
+  const added = [];
+  const forbidden = [];
+  const forbiddenIds = /* @__PURE__ */ new Set();
+  const working = [...composition.base];
+  let orderOverride = composition.order ? [...composition.order] : void 0;
+  for (const rule of composition.rules) {
+    const match = matchWhen(rule.when, context);
+    const trace2 = {
+      index: rule.index,
+      action: rule.action,
+      when: rule.when,
+      fired: match.fired
+    };
+    if (!match.fired) {
+      trace2.reason = match.reason;
+      ruleTraces.push(trace2);
+      continue;
+    }
+    switch (rule.action) {
+      case "replace": {
+        const effects = [];
+        for (const [from, to] of Object.entries(rule.replace ?? {})) {
+          const at = working.indexOf(from);
+          if (at === -1) {
+            warnings.push(`Rule #${rule.index} cannot replace "${from}": it is not present in "${prompt}".`);
+            continue;
+          }
+          working[at] = to;
+          replaced.push({ from, to, ruleIndex: rule.index });
+          effects.push(`${from} -> ${to}`);
+        }
+        trace2.effect = `replace ${effects.join(", ")}`;
+        break;
+      }
+      case "add": {
+        const ids = rule.add ?? [];
+        const after = rule.after;
+        const at = insertionPoint(working, after, rule.index, prompt, warnings);
+        working.splice(at, 0, ...ids);
+        for (const id of ids) {
+          added.push(after !== void 0 ? { id, after, ruleIndex: rule.index } : { id, ruleIndex: rule.index });
+        }
+        trace2.effect = `add ${ids.join(", ")}${after !== void 0 ? ` after ${after}` : ""}`;
+        break;
+      }
+      case "forbid": {
+        const ids = rule.forbid ?? [];
+        for (const id of ids) {
+          forbiddenIds.add(id);
+          forbidden.push({ id, ruleIndex: rule.index });
+        }
+        trace2.effect = `forbid ${ids.join(", ")}`;
+        break;
+      }
+      case "order": {
+        orderOverride = [...rule.order ?? []];
+        trace2.effect = `order ${orderOverride.join(", ")}`;
+        break;
+      }
+    }
+    ruleTraces.push(trace2);
+  }
+  const ordered = applyOrder(working, orderOverride);
+  const selected = ordered.filter((id) => !forbiddenIds.has(id));
+  const parts = [];
+  const finalOrder = [];
+  for (const id of selected) {
+    const fragment = book.fragments.get(id);
+    if (!fragment) {
+      warnings.push(`Fragment "${id}" referenced by "${prompt}" was not found.`);
+      continue;
+    }
+    parts.push(interpolate(fragment.body, context, (key) => {
+      warnings.push(`Missing variable "${key}" while rendering fragment "${id}".`);
+    }));
+    finalOrder.push(id);
+  }
+  const trace = {
+    prompt,
+    context,
+    rules: ruleTraces,
+    finalOrder,
+    replaced,
+    added,
+    forbidden,
+    unmatchedAxes: computeUnmatchedAxes(composition, context),
+    warnings
+  };
+  return { text: parts.join("\n\n"), trace };
+}
+function matchWhen(when, context) {
+  for (const [key, expected] of Object.entries(when)) {
+    const actual = context[key];
+    if (actual === void 0) {
+      return { fired: false, reason: `context.${key} is unset, rule expects "${expected}"` };
+    }
+    if (!valuesEqual(expected, actual)) {
+      return { fired: false, reason: `context.${key}="${actual}" does not equal expected "${expected}"` };
+    }
+  }
+  return { fired: true };
+}
+function valuesEqual(a, b) {
+  return String(a) === String(b);
+}
+function insertionPoint(working, after, ruleIndex, prompt, warnings) {
+  if (after === void 0) {
+    return Math.max(working.length - 1, 0);
+  }
+  const at = working.indexOf(after);
+  if (at === -1) {
+    warnings.push(`Rule #${ruleIndex} add anchor "${after}" not found in "${prompt}"; appending at end.`);
+    return working.length;
+  }
+  return at + 1;
+}
+function applyOrder(working, orderOverride) {
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  const push = (id) => {
+    if (!seen.has(id)) {
+      seen.add(id);
+      result.push(id);
+    }
+  };
+  if (orderOverride) {
+    const present = new Set(working);
+    for (const id of orderOverride) {
+      if (present.has(id)) {
+        push(id);
+      }
+    }
+  }
+  for (const id of working) {
+    push(id);
+  }
+  return result;
+}
+function computeUnmatchedAxes(composition, context) {
+  const result = [];
+  for (const key of Object.keys(context)) {
+    let referenced = false;
+    let matched = false;
+    for (const rule of composition.rules) {
+      if (Object.hasOwn(rule.when, key)) {
+        referenced = true;
+        const expected = rule.when[key];
+        if (expected !== void 0 && valuesEqual(expected, context[key])) {
+          matched = true;
+          break;
+        }
+      }
+    }
+    if (referenced && !matched) {
+      result.push({ key, value: context[key] });
+    }
+  }
+  return result;
+}
+export {
+  interpolate,
+  resolveBook
+};

package/dist/edge.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 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";
+//# sourceMappingURL=edge.d.ts.map

package/dist/edge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge.d.ts","sourceRoot":"","sources":["../src/edge.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC"}

package/dist/edge.js

@@ -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";
+//# sourceMappingURL=edge.js.map

package/dist/edge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"edge.js","sourceRoot":"","sources":["../src/edge.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/eval/assertions.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 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 { AssertionRegistry } from "./types.js";
+/**
+ * The built-in assertion registry. Pass a merged/replaced object to
+ * {@link evaluate} to customize: `{ ...defaultAssertions(), myType: fn }`.
+ */
+export declare function defaultAssertions(): AssertionRegistry;
+//# sourceMappingURL=assertions.d.ts.map

package/dist/eval/assertions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"assertions.d.ts","sourceRoot":"","sources":["../../src/eval/assertions.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAA0B,iBAAiB,EAAmB,MAAM,YAAY,CAAC;AAsJ7F;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,iBAAiB,CAWrD"}