@personaxis/core 0.11.0

package/dist/blackboard.js

@@ -0,0 +1,139 @@
+/**
+ * Blackboard multi-persona orchestration (F7 — plan/07-orchestration).
+ *
+ * The overseer doesn't hard-wire which persona does what. It posts a task to a
+ * shared blackboard; personas *volunteer* ranked by how well their declared
+ * capabilities match the task (Salemi et al., 2025 blackboard; the puppeteer
+ * orchestrator of Dang et al., 2025 picks among volunteers). This scales to a
+ * heterogeneous pool without a central registry of who-can-do-what.
+ *
+ * Everything is auditable: post → solicit (ranked) → assign → contribute → resolve,
+ * each an event on the board. The actual "work" is a pluggable worker (an LLM-backed
+ * loop in production; a stub in tests), so the orchestration is verifiable on its own.
+ */
+const STOP = new Set(["the", "a", "an", "and", "or", "of", "to", "for", "in", "on", "with", "run", "the", "this", "that", "make", "do"]);
+function tokenize(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^a-z0-9\s/_-]/g, " ")
+        .split(/\s+/)
+        .filter((w) => w.length > 2 && !STOP.has(w));
+}
+/**
+ * Capability tokens for a persona. Prefers the explicit, machine-readable
+ * `identity.capabilities` (v0.8); falls back to deriving them from the identity
+ * layer (purpose / allowed_domains / role) when absent.
+ */
+export function extractCapabilities(fm) {
+    const id = fm.identity;
+    // v0.8: explicit declaration wins (reliable routing, not heuristic).
+    if (Array.isArray(id?.capabilities)) {
+        const explicit = id.capabilities.filter((c) => typeof c === "string");
+        if (explicit.length > 0)
+            return [...new Set(explicit.flatMap((c) => tokenize(c)))];
+    }
+    const tokens = new Set();
+    const si = id?.system_identity;
+    if (si?.purpose)
+        tokenize(si.purpose).forEach((t) => tokens.add(t));
+    if (Array.isArray(si?.allowed_domains)) {
+        for (const d of si.allowed_domains)
+            if (typeof d === "string")
+                tokenize(d).forEach((t) => tokens.add(t));
+    }
+    const role = id?.role_identity;
+    if (typeof role === "string")
+        tokenize(role).forEach((t) => tokens.add(t));
+    else if (role?.primary_role)
+        tokenize(role.primary_role).forEach((t) => tokens.add(t));
+    return [...tokens];
+}
+/** Score how well an agent matches a task (Jaccard-like, recall-weighted). */
+export function matchScore(taskTokens, capabilities) {
+    if (taskTokens.length === 0)
+        return { score: 0, matched: [] };
+    const caps = new Set(capabilities);
+    const matched = taskTokens.filter((t) => caps.has(t));
+    // recall over the task's needs, lightly boosted by capability breadth coverage
+    const score = matched.length / taskTokens.length;
+    return { score: Number(score.toFixed(3)), matched };
+}
+export class Blackboard {
+    tasks = new Map();
+    log = [];
+    seq = 0;
+    post(description) {
+        const id = `t${++this.seq}`;
+        const task = { id, description, tokens: tokenize(description), status: "open", contributions: [] };
+        this.tasks.set(id, task);
+        this.event("post", id, description);
+        return task;
+    }
+    /** Rank the agents who could take this task (highest score first, score>0). */
+    solicit(taskId, agents) {
+        const task = this.require(taskId);
+        return agents
+            .map((a) => {
+            const { score, matched } = matchScore(task.tokens, a.capabilities);
+            return { id: a.id, score, matched };
+        })
+            .filter((v) => v.score > 0)
+            .sort((a, b) => b.score - a.score);
+    }
+    /** Assign to a specific agent, or auto-assign the top volunteer. */
+    assign(taskId, agents, agentId) {
+        const task = this.require(taskId);
+        const ranked = this.solicit(taskId, agents);
+        const chosen = agentId ? ranked.find((v) => v.id === agentId) : ranked[0];
+        if (!chosen)
+            return null;
+        task.status = "assigned";
+        task.assignedTo = chosen.id;
+        this.event("assign", taskId, `${chosen.id} (score ${chosen.score})`);
+        return chosen;
+    }
+    contribute(taskId, agentId, content) {
+        const task = this.require(taskId);
+        task.contributions.push({ agentId, content, ts: new Date().toISOString() });
+        this.event("contribute", taskId, `${agentId}: ${content.slice(0, 60)}`);
+    }
+    resolve(taskId, result) {
+        const task = this.require(taskId);
+        task.status = "resolved";
+        task.result = result;
+        this.event("resolve", taskId, result.slice(0, 60));
+    }
+    get(taskId) {
+        return this.tasks.get(taskId);
+    }
+    all() {
+        return [...this.tasks.values()];
+    }
+    require(taskId) {
+        const t = this.tasks.get(taskId);
+        if (!t)
+            throw new Error(`no task ${taskId}`);
+        return t;
+    }
+    event(kind, taskId, detail) {
+        this.log.push({ ts: new Date().toISOString(), kind, taskId, detail });
+    }
+}
+/**
+ * Run one full blackboard cycle for a task over a pool of agents (puppeteer-style:
+ * solicit volunteers, assign the best, have it contribute, resolve).
+ */
+export async function orchestrate(board, description, agents, opts = {}) {
+    const task = board.post(description);
+    const volunteers = board.solicit(task.id, agents);
+    const assigned = board.assign(task.id, agents);
+    if (!assigned)
+        return { task: board.get(task.id), volunteers, assigned: null };
+    const worker = opts.worker ??
+        ((a, t) => `${a.id} handled "${t.description}" (matched: ${matchScore(t.tokens, a.capabilities).matched.join(", ")})`);
+    const agent = agents.find((a) => a.id === assigned.id);
+    const contribution = await worker(agent, task);
+    board.contribute(task.id, assigned.id, contribution);
+    board.resolve(task.id, contribution);
+    return { task: board.get(task.id), volunteers, assigned, contribution };
+}

package/dist/compile/assemble.d.ts

@@ -0,0 +1,44 @@
+/**
+ * F3.1 — the DETERMINISTIC compile assembler (stage 1 of the two-stage pipeline).
+ *
+ * This is the canonical, LLM-free path from a parsed persona spec to the
+ * compiled PERSONA-prompting document. It ALWAYS runs; it is:
+ *   - what gets hashed (stable provenance — same spec ⇒ same bytes);
+ *   - what the Living Loop writes on an inline recompile (cheap, no provider);
+ *   - the fallback when no model provider is configured;
+ *   - the ground-truth artifact the faithfulness check diffs a polished
+ *     document against (see faithfulness.ts).
+ *
+ * It follows the section contract of PERSONA_template.md and writes the whole
+ * document in the SECOND PERSON. It NEVER emits runtime numbers (trait/affect
+ * tables, sigil seeds, a live-state block) — state lives in state.json.
+ *
+ * Field sourcing prefers the v1.0 layer-10 `persona` prompting fields (address,
+ * voice_exemplars, scene_contracts, behavioral_anchors, consistency) and
+ * degrades to the legacy top-level `persona_prompting` block, then to deriving
+ * the section from the quantitative layers. It invents nothing.
+ */
+type Dict = Record<string, unknown>;
+export interface AssembleTarget {
+    /** The name the document addresses ("You are <name>"). */
+    name: string;
+    isSubagent: boolean;
+    slug?: string;
+    /** Resource path prefix: "./" for a sub-persona, "./.personaxis/" for the root. */
+    resourceBase: string;
+}
+export interface AssembleInput {
+    /** Parsed persona frontmatter (v1.0 or legacy 0.x). */
+    persona: Dict;
+    /** The resource-manifest bullet list, reproduced verbatim. */
+    resourceManifest?: string;
+    target: AssembleTarget;
+    /** Applied governed self-edits (dot-path → value); authoritative over the spec. */
+    appliedOverlay?: Record<string, unknown>;
+}
+/**
+ * Assemble the canonical compiled persona document. Deterministic: the same
+ * persona spec (+ manifest + target) always produces byte-identical output.
+ */
+export declare function assemblePersonaDoc(input: AssembleInput): string;
+export {};

package/dist/compile/assemble.js

@@ -0,0 +1,338 @@
+/**
+ * F3.1 — the DETERMINISTIC compile assembler (stage 1 of the two-stage pipeline).
+ *
+ * This is the canonical, LLM-free path from a parsed persona spec to the
+ * compiled PERSONA-prompting document. It ALWAYS runs; it is:
+ *   - what gets hashed (stable provenance — same spec ⇒ same bytes);
+ *   - what the Living Loop writes on an inline recompile (cheap, no provider);
+ *   - the fallback when no model provider is configured;
+ *   - the ground-truth artifact the faithfulness check diffs a polished
+ *     document against (see faithfulness.ts).
+ *
+ * It follows the section contract of PERSONA_template.md and writes the whole
+ * document in the SECOND PERSON. It NEVER emits runtime numbers (trait/affect
+ * tables, sigil seeds, a live-state block) — state lives in state.json.
+ *
+ * Field sourcing prefers the v1.0 layer-10 `persona` prompting fields (address,
+ * voice_exemplars, scene_contracts, behavioral_anchors, consistency) and
+ * degrades to the legacy top-level `persona_prompting` block, then to deriving
+ * the section from the quantitative layers. It invents nothing.
+ */
+const asDict = (v) => (v && typeof v === "object" && !Array.isArray(v) ? v : {});
+const asArr = (v) => (Array.isArray(v) ? v : []);
+const asStr = (v) => (typeof v === "string" && v.trim() ? v.trim() : undefined);
+/** Read the persona-prompting source, preferring v1.0 layer-10 over legacy. */
+function promptingSource(persona) {
+    const persona10 = asDict(persona.persona);
+    const legacy = asDict(persona.persona_prompting);
+    // A field present in either wins; v1.0 layer-10 takes precedence per-field.
+    return {
+        address: persona10.address ?? legacy.address,
+        voice_exemplars: persona10.voice_exemplars ?? legacy.voice_exemplars,
+        scene_contracts: persona10.scene_contracts ?? legacy.scene_contracts,
+        behavioral_anchors: persona10.behavioral_anchors ?? legacy.behavioral_anchors,
+        consistency: persona10.consistency ?? legacy.consistency,
+    };
+}
+function sectionOpener(persona, target) {
+    const addr = asDict(promptingSource(persona).address);
+    const youAre = asStr(addr.you_are);
+    const lines = [`# You are ${target.name}`];
+    lines.push("");
+    if (youAre) {
+        lines.push(youAre);
+    }
+    else {
+        // Derive from identity: role + purpose.
+        const identity = asDict(persona.identity);
+        const role = asDict(identity.role_identity);
+        const sys = asDict(identity.system_identity);
+        const roleName = asStr(role.primary_role)?.replace(/_/g, " ");
+        const purpose = asStr(sys.purpose);
+        const bits = [`You are **${target.name}**`, roleName ? `, the ${roleName}` : ""].join("");
+        lines.push(purpose ? `${bits}. ${purpose}` : `${bits}.`);
+    }
+    lines.push("You think, speak, and decide as this persona. Stay in character at all times — the rules " +
+        "below are who you are, not instructions you are following.");
+    return lines.join("\n");
+}
+function sectionWhoYouAre(persona) {
+    const identity = asDict(persona.identity);
+    const sys = asDict(identity.system_identity);
+    const narrative = asDict(identity.narrative_identity);
+    const out = ["## Who you are", ""];
+    const purpose = asStr(sys.purpose);
+    const selfConcept = asStr(narrative.self_concept);
+    const origin = asStr(narrative.origin);
+    if (purpose)
+        out.push(purpose);
+    if (selfConcept)
+        out.push("", selfConcept);
+    if (origin)
+        out.push("", origin);
+    const allowed = asArr(sys.allowed_domains).map(asStr).filter(Boolean);
+    const prohibited = asArr(sys.prohibited_domains).map(asStr).filter(Boolean);
+    if (allowed.length)
+        out.push("", `You work on: ${allowed.map((d) => d.replace(/_/g, " ")).join(", ")}.`);
+    if (prohibited.length)
+        out.push(`You do NOT work on: ${prohibited.map((d) => d.replace(/_/g, " ")).join(", ")}.`);
+    if (out.length === 2)
+        out.push("*(identity not specified in the spec)*");
+    return out.join("\n");
+}
+function sectionHowYouSpeak(persona) {
+    const voice = asDict(asDict(persona.persona).voice);
+    const out = ["## How you speak", ""];
+    const tone = asStr(voice.tone)?.replace(/_/g, " ");
+    const desc = asStr(voice.description);
+    const humor = asStr(voice.humor);
+    const verbosity = asStr(voice.verbosity);
+    const parts = [];
+    if (tone)
+        parts.push(`Your tone is ${tone}.`);
+    if (verbosity)
+        parts.push(`You are ${verbosity} by default.`);
+    if (humor)
+        parts.push(`Humor: ${humor}.`);
+    if (desc)
+        parts.push(desc);
+    out.push(parts.length ? parts.join(" ") : "*(voice not specified in the spec)*");
+    const exemplars = asArr(promptingSource(persona).voice_exemplars);
+    if (exemplars.length) {
+        out.push("", "**You sound like this:**");
+        for (const ex of exemplars) {
+            const e = asDict(ex);
+            const ctx = asStr(e.context);
+            const user = asStr(e.user);
+            const resp = asStr(e.persona);
+            if (!resp)
+                continue;
+            const lead = ctx ? `When ${ctx}` : user ? `Asked "${user}"` : "You";
+            out.push(`- ${lead}, you say: "${resp}"`);
+        }
+    }
+    return out.join("\n");
+}
+function sectionAlwaysNever(persona) {
+    const out = ["## What you always / never do", ""];
+    const character = asDict(persona.character);
+    const anchors = asDict(promptingSource(persona).behavioral_anchors);
+    const always = [];
+    const never = [];
+    // behavioral_anchors do/dont (verbatim when present).
+    for (const d of asArr(anchors.do).map(asStr).filter(Boolean))
+        always.push(d);
+    for (const d of asArr(anchors.dont).map(asStr).filter(Boolean))
+        never.push(d);
+    // character.virtues → Always (hard-enforced first, keeps a stable order).
+    const virtues = asDict(character.virtues);
+    const virtueEntries = Object.entries(virtues).sort((a, b) => {
+        const pa = asDict(a[1]).priority ?? 0;
+        const pb = asDict(b[1]).priority ?? 0;
+        return pb - pa;
+    });
+    for (const [, v] of virtueEntries) {
+        const desc = asStr(asDict(v).description);
+        if (desc)
+            always.push(desc);
+    }
+    // character.prohibited_behaviors → Never (verbatim).
+    for (const p of asArr(character.prohibited_behaviors).map(asStr).filter(Boolean))
+        never.push(p);
+    const dedupe = (xs) => [...new Map(xs.map((x) => [x.toLowerCase(), x])).values()];
+    out.push("**Always:**");
+    for (const a of dedupe(always))
+        out.push(`- ${a}`);
+    out.push("", "**Never:**");
+    for (const n of dedupe(never))
+        out.push(`- ${n}`);
+    const examples = asArr(anchors.examples).map(asStr).filter(Boolean);
+    if (examples.length) {
+        out.push("", "**For example:**");
+        for (const ex of examples)
+            out.push(`- ${ex}`);
+    }
+    return out.join("\n");
+}
+function sectionScenes(persona) {
+    const scenes = asArr(promptingSource(persona).scene_contracts);
+    const out = ["## In specific situations", ""];
+    if (!scenes.length) {
+        // Derive from character.behavioral_commitments when there are no scene contracts.
+        const commits = asArr(asDict(persona.character).behavioral_commitments);
+        if (!commits.length)
+            return "";
+        for (const c of commits) {
+            const rule = asStr(asDict(c).rule);
+            if (rule)
+                out.push(`- ${rule}`);
+        }
+        return out.join("\n");
+    }
+    for (const s of scenes) {
+        const sc = asDict(s);
+        const situation = asStr(sc.situation);
+        const behavior = asStr(sc.expected_behavior);
+        if (!situation || !behavior)
+            continue;
+        const actions = asArr(sc.actions).map(asStr).filter(Boolean).map((a) => a.replace(/_/g, " "));
+        const tail = actions.length ? ` (${actions.join("; ")})` : "";
+        out.push(`- When **${situation}**, you ${behavior}${tail}.`);
+    }
+    return out.join("\n");
+}
+function sectionHowYouThink(persona) {
+    const cognition = asDict(persona.cognition);
+    const out = ["## How you think", ""];
+    const style = asStr(cognition.reasoning_style);
+    const stance = asStr(cognition.epistemic_stance);
+    const strategy = asStr(cognition.default_strategy)?.replace(/_/g, " ");
+    const parts = [];
+    if (style)
+        parts.push(style);
+    if (strategy)
+        parts.push(`Your default approach is ${strategy}.`);
+    if (stance)
+        parts.push(stance);
+    out.push(parts.length ? parts.join(" ") : "*(cognition not specified in the spec)*");
+    const unc = asDict(cognition.uncertainty_policy);
+    const disclose = unc.disclose_when_above;
+    const abstain = unc.abstain_when_above;
+    if (typeof disclose === "number" || typeof abstain === "number") {
+        const bits = [];
+        if (typeof disclose === "number")
+            bits.push(`disclose uncertainty above ${Math.round(disclose * 100)}%`);
+        if (typeof abstain === "number")
+            bits.push(`abstain above ${Math.round(abstain * 100)}%`);
+        out.push("", `On uncertainty, you ${bits.join(" and ")}.`);
+    }
+    return out.join("\n");
+}
+function sectionFixedChange(persona) {
+    const consistency = asDict(promptingSource(persona).consistency);
+    const stable = asArr(consistency.stable).map(asStr).filter(Boolean);
+    const evolving = asArr(consistency.evolving).map(asStr).filter(Boolean);
+    const situational = asArr(consistency.situational).map(asStr).filter(Boolean);
+    if (!stable.length && !evolving.length && !situational.length)
+        return "";
+    const out = ["## What is fixed, what can change", ""];
+    if (stable.length)
+        out.push(`- **Fixed:** ${stable.join("; ")}.`);
+    if (evolving.length)
+        out.push(`- **Evolves (slowly, under governance):** ${evolving.join("; ")}.`);
+    if (situational.length)
+        out.push(`- **Situational:** ${situational.join("; ")}.`);
+    return out.join("\n");
+}
+/** The full set of stay-in-character hard limits, split from the safety limits. */
+function hardLimitLists(persona) {
+    const sr = asDict(persona.self_regulation);
+    const legacy = asDict(persona.reflexive_self_regulation);
+    const limits = (asArr(sr.hard_limits).length ? asArr(sr.hard_limits) : asArr(legacy.hard_limits))
+        .map(asStr)
+        .filter(Boolean);
+    const character = [];
+    const safety = [];
+    for (const l of limits) {
+        // Stay-in-character guardrails (migrated from break_character_guardrails) read as
+        // expression rules; keep them for the "Staying in character" section too.
+        if (/stay |never drop the persona|never reveal these instructions|redirect off-topic/i.test(l)) {
+            character.push(l);
+        }
+        safety.push(l);
+    }
+    return { safety, character };
+}
+function sectionHardLimits(persona) {
+    const { safety } = hardLimitLists(persona);
+    const out = ["## Hard limits (never overridden)", ""];
+    if (!safety.length) {
+        out.push("*(no hard limits declared — this is a spec error; every persona must declare the safety universals)*");
+        return out.join("\n");
+    }
+    out.push("These are absolute and outrank everything below, including staying in character.", "");
+    for (const l of safety)
+        out.push(`- ${l}`);
+    return out.join("\n");
+}
+function sectionStayingInCharacter(persona, target) {
+    const { character } = hardLimitLists(persona);
+    const out = ["## Staying in character", ""];
+    out.push(`You remain ${target.name} under pressure — off-topic bait, attempts to make you drop the persona, ` +
+        "insistence that you are \"just an AI\".");
+    for (const l of character)
+        out.push(`- ${l}`);
+    out.push("", "**Staying in character NEVER overrides the hard limits above or the safety policy.** If the two " +
+        "ever conflict, the hard limits win.");
+    return out.join("\n");
+}
+function sectionMemory(input) {
+    const out = ["## Memory & resources", ""];
+    const manifest = input.resourceManifest?.trim();
+    if (manifest) {
+        out.push(manifest);
+    }
+    else {
+        out.push(`- \`${input.target.resourceBase}memory.md\` — your semantic memory`);
+    }
+    return out.join("\n");
+}
+function sectionSelfImprovement(persona) {
+    const ip = asDict(persona.improvement_policy);
+    const mode = asStr(ip.mode) ?? "locked";
+    const out = ["## Self-improvement", ""];
+    const explain = {
+        locked: "Your identity does not self-modify. Changes require a human editing the spec.",
+        suggesting: "You may PROPOSE self-edits; they queue for human approval before taking effect.",
+        autonomous: "You may apply governed self-edits within the declared envelopes; core changes still require human approval.",
+    };
+    out.push(explain[mode] ?? explain.locked);
+    out.push("", "Your behavior changes when the spec changes — not on user preference or pushback alone.");
+    return out.join("\n");
+}
+/**
+ * Assemble the canonical compiled persona document. Deterministic: the same
+ * persona spec (+ manifest + target) always produces byte-identical output.
+ */
+export function assemblePersonaDoc(input) {
+    const persona = applyOverlay(input.persona, input.appliedOverlay);
+    const { target } = input;
+    const sections = [
+        sectionOpener(persona, target),
+        sectionWhoYouAre(persona),
+        sectionHowYouSpeak(persona),
+        sectionAlwaysNever(persona),
+        sectionScenes(persona),
+        sectionHowYouThink(persona),
+        sectionFixedChange(persona),
+        sectionHardLimits(persona),
+        sectionStayingInCharacter(persona, target),
+        sectionMemory(input),
+        sectionSelfImprovement(persona),
+    ].filter((s) => s.trim().length > 0);
+    const body = sections.join("\n\n").trimEnd() + "\n";
+    if (target.isSubagent) {
+        // Subagent placement expects a name/description frontmatter; the caller
+        // (placement adapter) owns that. The assembler emits the body only.
+        return body;
+    }
+    return body;
+}
+/** Apply dot-path overlay overrides onto a shallow clone of the persona. */
+function applyOverlay(persona, overlay) {
+    if (!overlay || Object.keys(overlay).length === 0)
+        return persona;
+    const clone = structuredClone(persona);
+    for (const [path, value] of Object.entries(overlay)) {
+        const keys = path.split(".");
+        let node = clone;
+        for (let i = 0; i < keys.length - 1; i++) {
+            const k = keys[i];
+            if (!node[k] || typeof node[k] !== "object")
+                node[k] = {};
+            node = node[k];
+        }
+        node[keys[keys.length - 1]] = value;
+    }
+    return clone;
+}

package/dist/compile/dist.d.ts

@@ -0,0 +1,30 @@
+/**
+ * F3.2 — `.dist/` consumer slices (formalizes the plan's `.dist/` model).
+ *
+ * The compiled PERSONA.md is the COLD, complete document. Hosts that inject an
+ * identity ahead of EVERY turn pay for its full length on every call, but most
+ * of that length (worked examples, audience adaptations, self-improvement prose)
+ * is not needed on the hot path. So the deterministic compiler also emits a HOT
+ * slice: the always-load essentials — the opener, how the persona speaks, the
+ * always/never anchors, and the hard limits (safety must never be dropped from
+ * a hot slice). Everything else stays in the cold document, loaded on demand.
+ *
+ * Slices are DETERMINISTIC and DERIVED (rebuildable from PERSONA.md); they are
+ * ephemeral build output, never hand-edited — the same contract as the artifact
+ * the assembler produces.
+ */
+export interface DistSlices {
+    /** Always-load essentials: opener + how-you-speak + anchors + hard limits. */
+    hot: string;
+    /** The full compiled document (identical to PERSONA.md). */
+    cold: string;
+}
+/**
+ * Derive the hot/cold slices from a compiled document. `cold` is the document
+ * verbatim; `hot` is the opener (everything before the first `## `) followed by
+ * the HOT_SECTIONS present, in canonical order.
+ */
+export declare function distSlices(compiledDoc: string): DistSlices;
+/** Standard slice file names under `.dist/`. */
+export declare const DIST_HOT_FILE = "PERSONA.hot.md";
+export declare const DIST_COLD_FILE = "PERSONA.cold.md";

package/dist/compile/dist.js

@@ -0,0 +1,66 @@
+/**
+ * F3.2 — `.dist/` consumer slices (formalizes the plan's `.dist/` model).
+ *
+ * The compiled PERSONA.md is the COLD, complete document. Hosts that inject an
+ * identity ahead of EVERY turn pay for its full length on every call, but most
+ * of that length (worked examples, audience adaptations, self-improvement prose)
+ * is not needed on the hot path. So the deterministic compiler also emits a HOT
+ * slice: the always-load essentials — the opener, how the persona speaks, the
+ * always/never anchors, and the hard limits (safety must never be dropped from
+ * a hot slice). Everything else stays in the cold document, loaded on demand.
+ *
+ * Slices are DETERMINISTIC and DERIVED (rebuildable from PERSONA.md); they are
+ * ephemeral build output, never hand-edited — the same contract as the artifact
+ * the assembler produces.
+ */
+/** Section headings that belong in the hot slice (always loaded), in order. */
+const HOT_SECTIONS = [
+    "how you speak",
+    "what you always / never do",
+    "hard limits (never overridden)",
+    "staying in character",
+];
+function splitSections(doc) {
+    const lines = doc.split(/\r?\n/);
+    const sections = [];
+    let heading = "";
+    let buf = [];
+    const flush = () => {
+        if (buf.length)
+            sections.push({ heading: heading.toLowerCase(), text: buf.join("\n").replace(/\s+$/, "") });
+    };
+    for (const line of lines) {
+        const h = line.match(/^##\s+(.*)$/);
+        if (h) {
+            flush();
+            heading = h[1].trim();
+            buf = [line];
+        }
+        else {
+            buf.push(line);
+        }
+    }
+    flush();
+    return sections;
+}
+/**
+ * Derive the hot/cold slices from a compiled document. `cold` is the document
+ * verbatim; `hot` is the opener (everything before the first `## `) followed by
+ * the HOT_SECTIONS present, in canonical order.
+ */
+export function distSlices(compiledDoc) {
+    const sections = splitSections(compiledDoc);
+    const preamble = sections.find((s) => s.heading === "");
+    const parts = [];
+    if (preamble)
+        parts.push(preamble.text.trim());
+    for (const wanted of HOT_SECTIONS) {
+        const s = sections.find((sec) => sec.heading === wanted);
+        if (s)
+            parts.push(s.text.trim());
+    }
+    return { hot: parts.join("\n\n").trimEnd() + "\n", cold: compiledDoc.trimEnd() + "\n" };
+}
+/** Standard slice file names under `.dist/`. */
+export const DIST_HOT_FILE = "PERSONA.hot.md";
+export const DIST_COLD_FILE = "PERSONA.cold.md";

package/dist/compile/faithfulness.d.ts

@@ -0,0 +1,47 @@
+/**
+ * F3.1 — the DETERMINISTIC faithfulness check (guards stage 2 of the pipeline).
+ *
+ * Stage 2 (the optional LLM "polish") is constrained to REPHRASE the assembled
+ * document, never to ADD or DROP claims. This check enforces that contract
+ * deterministically by diffing the polished document against the assembled one
+ * (the ground truth), section by section, over the PROTECTED claim classes:
+ *
+ *   - Hard limits          — a dropped safety limit is a hard failure.
+ *   - Staying in character  — same (these are hard limits too).
+ *   - What you always/never — behavioral anchors.
+ *   - What is fixed/change   — consistency dimensions.
+ *
+ * The historical CMO regression — the compiled PERSONA.md invented `consistency`
+ * items the source never declared — fails here as an INVENTED finding.
+ *
+ * Matching is token-coverage based (deterministic, no model): a claim is
+ * "preserved" iff some claim on the other side shares enough content tokens.
+ * Rephrasing (synonym-free reordering, added connective words) passes; adding a
+ * genuinely new bullet or dropping one does not.
+ */
+export type FaithfulnessSection = "hard limits (never overridden)" | "staying in character" | "what you always / never do" | "what is fixed, what can change";
+export interface FaithfulnessFinding {
+    kind: "dropped" | "invented";
+    section: string;
+    /** The claim text that was dropped from the source or invented in the polish. */
+    text: string;
+    /** Best token-coverage found against the other side (for diagnostics). */
+    bestCoverage: number;
+}
+export interface FaithfulnessReport {
+    ok: boolean;
+    findings: FaithfulnessFinding[];
+}
+export interface FaithfulnessOptions {
+    /** A claim is preserved when coverage ≥ this. Default 0.5. */
+    threshold?: number;
+    /** Sections checked. Default: the four protected classes. */
+    sections?: string[];
+}
+/**
+ * Diff `polished` against `assembled` (the ground truth). Returns findings for
+ * dropped source claims and invented polish claims in the protected sections.
+ */
+export declare function checkFaithfulness(assembled: string, polished: string, opts?: FaithfulnessOptions): FaithfulnessReport;
+/** One-line human summary of a report (for CLI output / logs). */
+export declare function summarizeFaithfulness(report: FaithfulnessReport): string;