@personaxis/core 0.11.0

package/dist/governance.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Governance gate — the spec's safety boundary over autonomous evolution.
+ *
+ * The model's appraisal signal is a *proposal*. Before anything is applied, the
+ * gate decides which proposed mutations are admissible. Clamping handles range;
+ * the gate handles policy:
+ *   - unknown / non-mutable fields are rejected outright;
+ *   - fields tied to hard-enforced virtues are never mutable at runtime;
+ *   - per-step drift is bounded (anti-runaway, anti-self-reinforcement);
+ *   - in `locked` mode, only human-actor mutations pass.
+ *
+ * Nothing here is a black box: every decision yields an auditable verdict.
+ */
+import { type EnvelopeLookup } from "./envelopes.js";
+import type { ProposedMutation } from "./appraisal.js";
+export type ImprovementMode = "locked" | "suggesting" | "autonomous";
+export interface GovernanceConfig {
+    mode: ImprovementMode;
+    /** Max absolute delta admitted per step (drift guard). Default 0.15. */
+    maxStepDelta: number;
+    /**
+     * True when the mutation is a deliberate human action (`state mutate
+     * --actor human-operator`), not autonomous evolution. Human-directed mutations
+     * bypass the mode lock and the drift bound — that is this gate's documented
+     * intent ("in locked mode, only human-directed mutations pass"). Envelope
+     * membership and hard-virtue immutability still apply to EVERY actor.
+     */
+    humanDirected?: boolean;
+}
+export declare const DEFAULT_GOVERNANCE: GovernanceConfig;
+export interface Verdict {
+    field: string;
+    admitted: boolean;
+    /** Delta after drift-bounding (still subject to envelope clamp downstream). */
+    delta: number;
+    reason: string;
+}
+export interface GovernanceDecision {
+    verdicts: Verdict[];
+    admitted: ProposedMutation[];
+    rejected: Verdict[];
+}
+export declare function governMutations(proposals: ProposedMutation[], env: EnvelopeLookup, cfg?: GovernanceConfig): GovernanceDecision;
+/**
+ * Govern a QUALITATIVE self-edit (prose) by improvement_policy.mode. This is a SEPARATE
+ * layer from `judge` (which governs numeric envelope mutations): qualitative edits to the
+ * spec's character material are higher-stakes, so the mode means something different here —
+ *   locked      → block (no proposal at all);
+ *   suggesting  → queue the proposal for human review (/review), never auto-apply;
+ *   autonomous  → auto-apply, still gated by consensus verifiers + the protected-path list.
+ * (Envelope mutations remain reversible/clamped, so suggesting==autonomous for them — see
+ * `judge`. Decoupling avoids weakening the numeric drift guard while making prose evolution
+ * actually respect the posture.)
+ */
+export declare function governQualitative(mode: ImprovementMode): "block" | "queue" | "auto";
+/**
+ * Read the improvement mode. v1.0 precedence (SPEC.md §7.2): the INLINE
+ * `improvement_policy.mode` in personaxis.md is authoritative; when a
+ * `personaPath` is given, the sibling policy.yaml may only RESTRICT it — the
+ * more conservative of the two wins (min-wins). Inline absent → policy.yaml
+ * governs; both absent → locked.
+ */
+export declare function readMode(frontmatter: Record<string, unknown>, personaPath?: string): ImprovementMode;
+/** v0.8: read governance.max_step_delta from frontmatter; falls back to the default. */
+export declare function readMaxStepDelta(frontmatter: Record<string, unknown>): number;
+export type StopCondition = "goal_met" | "tool_denied" | "execution_error" | "low_confidence" | "no_progress";
+export interface AgentBudgetConfig {
+    maxSteps: number;
+    maxTokens?: number;
+    maxCostUsd?: number;
+    maxWallSeconds?: number;
+    stopConditions: StopCondition[];
+    onExhaust: "stop" | "summarize_and_stop";
+}
+export declare const DEFAULT_AGENT_BUDGET: AgentBudgetConfig;
+/** Per-1M-token USD prices (input+output averaged) for cost estimation. Best-effort. */
+export declare const MODEL_PRICES_PER_MTOK: Record<string, number>;
+export declare function estimateCostUsd(model: string, tokens: number): number;
+export interface AgentBudgetSpent {
+    steps: number;
+    tokens: number;
+    costUsd: number;
+    wallSeconds: number;
+    deniedCount: number;
+    errorCount: number;
+    /** Net progress signal since last step (0 = stalled). */
+    progress: number;
+    /** The model's last reported confidence in [0,1], if any. */
+    confidence?: number;
+    /** True if the model signalled completion (finish). */
+    goalMet?: boolean;
+}
+export interface BudgetVerdict {
+    field: string;
+    exceeded: boolean;
+    value: number;
+    limit: number | null;
+    reason: string;
+}
+export interface BudgetCheck {
+    verdicts: BudgetVerdict[];
+    shouldStop: boolean;
+    stopReason: string | null;
+}
+/** Decide whether the agent loop must halt, given what it has spent so far. */
+export declare function checkAgentBudget(spent: AgentBudgetSpent, budget?: AgentBudgetConfig): BudgetCheck;
+/** Read the spec `agent_budget` block from frontmatter; falls back to the default. */
+export declare function readAgentBudget(frontmatter: Record<string, unknown>): AgentBudgetConfig;

package/dist/governance.js

@@ -0,0 +1,204 @@
+/**
+ * Governance gate — the spec's safety boundary over autonomous evolution.
+ *
+ * The model's appraisal signal is a *proposal*. Before anything is applied, the
+ * gate decides which proposed mutations are admissible. Clamping handles range;
+ * the gate handles policy:
+ *   - unknown / non-mutable fields are rejected outright;
+ *   - fields tied to hard-enforced virtues are never mutable at runtime;
+ *   - per-step drift is bounded (anti-runaway, anti-self-reinforcement);
+ *   - in `locked` mode, only human-actor mutations pass.
+ *
+ * Nothing here is a black box: every decision yields an auditable verdict.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { load as loadYaml } from "js-yaml";
+import { resolveField } from "./envelopes.js";
+export const DEFAULT_GOVERNANCE = {
+    mode: "locked",
+    maxStepDelta: 0.15,
+};
+export function governMutations(proposals, env, cfg = DEFAULT_GOVERNANCE) {
+    const verdicts = [];
+    for (const p of proposals) {
+        const v = judge(p, env, cfg);
+        verdicts.push(v);
+    }
+    const admitted = verdicts
+        .filter((v) => v.admitted)
+        .map((v) => ({ field: v.field, delta: v.delta, reason: v.reason }));
+    const rejected = verdicts.filter((v) => !v.admitted);
+    return { verdicts, admitted, rejected };
+}
+function judge(p, env, cfg) {
+    // Accept either key form (short ≤0.10 / full-dot-path 1.0) — resolve onto the
+    // persona's canonical envelope key before judging.
+    const field = resolveField(p.field, env.envelopes);
+    // Autonomous evolution is only ever allowed for state-envelope fields.
+    if (!(field in env.envelopes)) {
+        return { field, admitted: false, delta: 0, reason: `not a mutable envelope field` };
+    }
+    // A trait backing a hard-enforced virtue is immutable at runtime — for every
+    // actor, human included (change the spec, not the state, to move it).
+    // v1.0: protectedFields carries the exact keys (incl. refs-derived ones);
+    // legacy lookups without it fall back to the name-match rule.
+    if (env.protectedFields) {
+        if (env.protectedFields.includes(field)) {
+            return { field, admitted: false, delta: 0, reason: `field backs a hard-enforced virtue` };
+        }
+    }
+    else {
+        const traitName = field.startsWith("traits.")
+            ? field.slice("traits.".length)
+            : field.startsWith("personality.traits.")
+                ? field.slice("personality.traits.".length)
+                : null;
+        if (traitName && env.hardEnforcedVirtues.includes(traitName)) {
+            return { field, admitted: false, delta: 0, reason: `field backs a hard-enforced virtue` };
+        }
+    }
+    // Deliberate human mutations are not autonomous evolution: no mode lock, no
+    // drift bound (the envelope clamp downstream still applies).
+    if (cfg.humanDirected) {
+        return { field, admitted: true, delta: p.delta, reason: p.reason };
+    }
+    // In locked mode, the actor LLM cannot self-evolve; only human-directed
+    // mutations (applied via the CLI, not the loop) change state.
+    if (cfg.mode === "locked") {
+        return { field, admitted: false, delta: 0, reason: `improvement_policy=locked` };
+    }
+    // Drift guard: bound the per-step magnitude.
+    const bounded = Math.max(-cfg.maxStepDelta, Math.min(cfg.maxStepDelta, p.delta));
+    const note = bounded !== p.delta ? ` (drift-bounded from ${p.delta})` : "";
+    return { field, admitted: true, delta: bounded, reason: p.reason + note };
+}
+/**
+ * Govern a QUALITATIVE self-edit (prose) by improvement_policy.mode. This is a SEPARATE
+ * layer from `judge` (which governs numeric envelope mutations): qualitative edits to the
+ * spec's character material are higher-stakes, so the mode means something different here —
+ *   locked      → block (no proposal at all);
+ *   suggesting  → queue the proposal for human review (/review), never auto-apply;
+ *   autonomous  → auto-apply, still gated by consensus verifiers + the protected-path list.
+ * (Envelope mutations remain reversible/clamped, so suggesting==autonomous for them — see
+ * `judge`. Decoupling avoids weakening the numeric drift guard while making prose evolution
+ * actually respect the posture.)
+ */
+export function governQualitative(mode) {
+    if (mode === "locked")
+        return "block";
+    if (mode === "autonomous")
+        return "auto";
+    return "queue"; // suggesting
+}
+const MODE_RANK = { locked: 0, suggesting: 1, autonomous: 2 };
+function normalizeMode(m) {
+    if (m === "locked" || m === "suggesting" || m === "autonomous")
+        return m;
+    if (m === "auto")
+        return "autonomous"; // legacy policy.yaml enum value
+    return undefined;
+}
+/** Mode declared by the sibling policy.yaml, if any (undefined when absent/unreadable). */
+function readPolicyMode(personaPath) {
+    try {
+        const p = join(dirname(personaPath), "policy.yaml");
+        if (!existsSync(p))
+            return undefined;
+        const doc = loadYaml(readFileSync(p, "utf-8"));
+        return normalizeMode(doc?.improvement_policy?.mode);
+    }
+    catch {
+        return undefined; // a malformed policy.yaml must not crash mode resolution
+    }
+}
+/**
+ * Read the improvement mode. v1.0 precedence (SPEC.md §7.2): the INLINE
+ * `improvement_policy.mode` in personaxis.md is authoritative; when a
+ * `personaPath` is given, the sibling policy.yaml may only RESTRICT it — the
+ * more conservative of the two wins (min-wins). Inline absent → policy.yaml
+ * governs; both absent → locked.
+ */
+export function readMode(frontmatter, personaPath) {
+    const ip = frontmatter.improvement_policy;
+    const inline = normalizeMode(ip?.mode);
+    if (!personaPath)
+        return inline ?? "locked";
+    const policy = readPolicyMode(personaPath);
+    if (inline === undefined)
+        return policy ?? "locked";
+    if (policy === undefined)
+        return inline;
+    return MODE_RANK[policy] < MODE_RANK[inline] ? policy : inline;
+}
+/** v0.8: read governance.max_step_delta from frontmatter; falls back to the default. */
+export function readMaxStepDelta(frontmatter) {
+    const g = frontmatter.governance;
+    const v = g?.max_step_delta;
+    return typeof v === "number" && v > 0 && v <= 1 ? v : DEFAULT_GOVERNANCE.maxStepDelta;
+}
+export const DEFAULT_AGENT_BUDGET = {
+    maxSteps: 20,
+    stopConditions: [],
+    onExhaust: "stop",
+};
+/** Per-1M-token USD prices (input+output averaged) for cost estimation. Best-effort. */
+export const MODEL_PRICES_PER_MTOK = {
+    "command-a": 5, "command-r-plus": 5, "command-r": 0.6,
+    "gpt-5": 7, "gpt-4o": 5, "claude-opus": 18, "claude-sonnet": 9, "claude-haiku": 2,
+    "gemini-2.5-pro": 5, "deepseek": 0.4, "qwen": 0.2, "llama": 0.2, "default": 3,
+};
+export function estimateCostUsd(model, tokens) {
+    const key = Object.keys(MODEL_PRICES_PER_MTOK).find((k) => k !== "default" && model.toLowerCase().includes(k));
+    const price = MODEL_PRICES_PER_MTOK[key ?? "default"];
+    return (tokens / 1_000_000) * price;
+}
+/** Decide whether the agent loop must halt, given what it has spent so far. */
+export function checkAgentBudget(spent, budget = DEFAULT_AGENT_BUDGET) {
+    const verdicts = [];
+    const cap = (field, value, limit) => {
+        const exceeded = typeof limit === "number" && value >= limit;
+        verdicts.push({ field, exceeded, value, limit: limit ?? null, reason: exceeded ? `${field} cap reached (${value} ≥ ${limit})` : `${field} ok` });
+        return exceeded;
+    };
+    let stopReason = null;
+    if (cap("steps", spent.steps, budget.maxSteps))
+        stopReason ??= "max_steps";
+    if (cap("tokens", spent.tokens, budget.maxTokens))
+        stopReason ??= "max_tokens";
+    if (cap("cost_usd", Number(spent.costUsd.toFixed(4)), budget.maxCostUsd))
+        stopReason ??= "max_cost_usd";
+    if (cap("wall_seconds", Math.floor(spent.wallSeconds), budget.maxWallSeconds))
+        stopReason ??= "max_wall_seconds";
+    // Declarative stop-conditions (checked only if listed).
+    const sc = budget.stopConditions;
+    if (sc.includes("goal_met") && spent.goalMet)
+        stopReason ??= "goal_met";
+    if (sc.includes("tool_denied") && spent.deniedCount > 0)
+        stopReason ??= "tool_denied";
+    if (sc.includes("execution_error") && spent.errorCount > 0)
+        stopReason ??= "execution_error";
+    if (sc.includes("low_confidence") && typeof spent.confidence === "number" && spent.confidence < 0.2)
+        stopReason ??= "low_confidence";
+    if (sc.includes("no_progress") && spent.steps > 1 && spent.progress === 0)
+        stopReason ??= "no_progress";
+    return { verdicts, shouldStop: stopReason !== null, stopReason };
+}
+/** Read the spec `agent_budget` block from frontmatter; falls back to the default. */
+export function readAgentBudget(frontmatter) {
+    const b = frontmatter.agent_budget;
+    if (!b)
+        return { ...DEFAULT_AGENT_BUDGET };
+    const num = (v) => (typeof v === "number" && v > 0 ? v : undefined);
+    const conds = Array.isArray(b.stop_conditions)
+        ? (b.stop_conditions.filter((c) => ["goal_met", "tool_denied", "execution_error", "low_confidence", "no_progress"].includes(c)))
+        : [];
+    return {
+        maxSteps: num(b.max_steps) ?? DEFAULT_AGENT_BUDGET.maxSteps,
+        maxTokens: num(b.max_tokens),
+        maxCostUsd: typeof b.max_cost_usd === "number" && b.max_cost_usd >= 0 ? b.max_cost_usd : undefined,
+        maxWallSeconds: num(b.max_wall_seconds),
+        stopConditions: conds,
+        onExhaust: b.on_exhaust === "summarize_and_stop" ? "summarize_and_stop" : "stop",
+    };
+}

package/dist/heuristic-appraiser.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Heuristic appraiser — deterministic, offline Appraiser.
+ *
+ * Lets the Living Loop run with zero model dependency (tests, demos, air-gapped
+ * use, MCP hosts that don't pass a model). It proposes only small bounded nudges;
+ * the governance gate + envelope clamp decide what actually applies. The
+ * LLM-backed appraiser (constrained decoding, plan/04-small-models) implements
+ * the same `Appraiser` interface, so the loop is unchanged.
+ */
+import type { AppraiseInput, AppraisalSignal, Appraiser } from "./appraisal.js";
+export declare class HeuristicAppraiser implements Appraiser {
+    appraise(input: AppraiseInput): Promise<AppraisalSignal>;
+}

package/dist/heuristic-appraiser.js

@@ -0,0 +1,48 @@
+/**
+ * Heuristic appraiser — deterministic, offline Appraiser.
+ *
+ * Lets the Living Loop run with zero model dependency (tests, demos, air-gapped
+ * use, MCP hosts that don't pass a model). It proposes only small bounded nudges;
+ * the governance gate + envelope clamp decide what actually applies. The
+ * LLM-backed appraiser (constrained decoding, plan/04-small-models) implements
+ * the same `Appraiser` interface, so the loop is unchanged.
+ */
+const POSITIVE = /\b(good|great|love|nice|thanks|excellent|win|happy|success|works?|fixed|clean|elegant)\b/gi;
+const NEGATIVE = /\b(bad|hate|angry|fail|failed|broken|bug|error|slow|ugly|wrong|stuck|frustrat\w*)\b/gi;
+function count(re, s) {
+    return (s.match(re) ?? []).length;
+}
+export class HeuristicAppraiser {
+    async appraise(input) {
+        const pos = count(POSITIVE, input.observation);
+        const neg = count(NEGATIVE, input.observation);
+        const net = pos - neg;
+        const magnitude = Math.min(0.12, Math.abs(net) * 0.04);
+        const dir = Math.sign(net);
+        const mutations = [];
+        if (dir !== 0) {
+            if (input.mutableFields.includes("mood.tone")) {
+                mutations.push({ field: "mood.tone", delta: dir * magnitude, reason: "tone of observation" });
+            }
+            if (input.mutableFields.includes("affect.valence")) {
+                mutations.push({
+                    field: "affect.valence",
+                    delta: dir * magnitude,
+                    reason: "affective valence of observation",
+                });
+            }
+        }
+        const memories = [
+            { content: input.observation.slice(0, 480), source: input.source, tags: ["episode", input.source] },
+        ];
+        const confidence = Math.max(0.2, Math.min(0.9, 0.4 + Math.abs(net) * 0.15));
+        return {
+            appraisal: net === 0
+                ? "Neutral observation; holding baseline."
+                : `Observation reads ${net > 0 ? "positive" : "negative"} (net ${net}); nudging affect within envelope.`,
+            mutations,
+            memories,
+            confidence,
+        };
+    }
+}

package/dist/hooks.d.ts

@@ -0,0 +1,52 @@
+/**
+ * FR.4 — inbound hooks v2: the shell-out contract.
+ *
+ * Users extend the engine WITHOUT forking it: a hook is any executable that
+ * receives the event payload as JSON on stdin and answers with its exit code —
+ *   exit 0  → ok (stdout MAY carry a JSON decision, e.g. {"decision":"block"})
+ *   exit 2  → BLOCK the action (blocking events only)
+ *   other   → warning; never blocks
+ * (Claude Code's contract; OpenClaw/Hermes use the same folder+manifest idea.)
+ *
+ * Six initial events. Only PreToolUse and UserPromptSubmit are BLOCKING-capable
+ * (awaited, bounded by a timeout that fails OPEN to "continue with warning" —
+ * a hook must never hang the pipeline). The rest are fire-and-forget.
+ *
+ * Config: `.personaxis/hooks.json` beside the persona (project scope), same
+ * structural shape as Claude Code's settings hooks block.
+ */
+export type HookEvent = "PreToolUse" | "PostToolUse" | "UserPromptSubmit" | "Stop" | "SessionStart" | "SessionEnd";
+export declare const BLOCKING_EVENTS: readonly HookEvent[];
+export interface HookSpec {
+    type: "command";
+    command: string;
+    /** Per-hook timeout (ms) for blocking events. Default 5000. */
+    timeout?: number;
+}
+export interface HookGroup {
+    /** Regex matched against the payload's `matcher_target` (e.g. tool name). */
+    matcher?: string;
+    hooks: HookSpec[];
+}
+export interface HooksConfig {
+    hooks?: Partial<Record<HookEvent, HookGroup[]>>;
+}
+export interface HookOutcome {
+    command: string;
+    /** "ok" | "block" | "warn" — block only possible on blocking events. */
+    result: "ok" | "block" | "warn";
+    exitCode: number | null;
+    /** Parsed JSON stdout decision, when the hook emitted one. */
+    decision?: Record<string, unknown>;
+}
+/** Load `.personaxis/hooks.json` for a persona ({} when absent/corrupt). */
+export declare function readHooksConfig(personaPath: string): HooksConfig;
+/**
+ * Run every hook configured for `event`. Blocking events await all matched
+ * hooks and report `blocked` when ANY says block; fire-and-forget events
+ * return immediately (`blocked: false` always).
+ */
+export declare function runHooks(event: HookEvent, payload: Record<string, unknown>, config: HooksConfig, matcherTarget?: string): Promise<{
+    blocked: boolean;
+    outcomes: HookOutcome[];
+}>;

package/dist/hooks.js

@@ -0,0 +1,122 @@
+/**
+ * FR.4 — inbound hooks v2: the shell-out contract.
+ *
+ * Users extend the engine WITHOUT forking it: a hook is any executable that
+ * receives the event payload as JSON on stdin and answers with its exit code —
+ *   exit 0  → ok (stdout MAY carry a JSON decision, e.g. {"decision":"block"})
+ *   exit 2  → BLOCK the action (blocking events only)
+ *   other   → warning; never blocks
+ * (Claude Code's contract; OpenClaw/Hermes use the same folder+manifest idea.)
+ *
+ * Six initial events. Only PreToolUse and UserPromptSubmit are BLOCKING-capable
+ * (awaited, bounded by a timeout that fails OPEN to "continue with warning" —
+ * a hook must never hang the pipeline). The rest are fire-and-forget.
+ *
+ * Config: `.personaxis/hooks.json` beside the persona (project scope), same
+ * structural shape as Claude Code's settings hooks block.
+ */
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+export const BLOCKING_EVENTS = ["PreToolUse", "UserPromptSubmit"];
+/** Load `.personaxis/hooks.json` for a persona ({} when absent/corrupt). */
+export function readHooksConfig(personaPath) {
+    const p = join(dirname(personaPath), "hooks.json");
+    if (!existsSync(p))
+        return {};
+    try {
+        return JSON.parse(readFileSync(p, "utf-8"));
+    }
+    catch {
+        return {}; // a corrupt hooks file must never break the engine
+    }
+}
+function matching(config, event, matcherTarget) {
+    const groups = config.hooks?.[event] ?? [];
+    const out = [];
+    for (const g of groups) {
+        if (g.matcher) {
+            try {
+                if (!new RegExp(g.matcher).test(matcherTarget))
+                    continue;
+            }
+            catch {
+                continue; // invalid matcher regex: skip the group, never crash
+            }
+        }
+        out.push(...(g.hooks ?? []));
+    }
+    return out;
+}
+function runOne(spec, payload, awaitResult) {
+    return new Promise((resolve) => {
+        const child = spawn(spec.command, {
+            shell: true,
+            stdio: ["pipe", "pipe", "ignore"],
+            windowsHide: true,
+        });
+        const outcome = (result, exitCode, stdout = "") => {
+            let decision;
+            if (stdout.trim()) {
+                try {
+                    decision = JSON.parse(stdout);
+                }
+                catch {
+                    /* non-JSON stdout is fine */
+                }
+            }
+            // A JSON {"decision":"block"} on exit 0 also blocks (blocking events).
+            if (awaitResult && decision?.decision === "block" && result === "ok")
+                result = "block";
+            resolve({ command: spec.command, result, exitCode, decision });
+        };
+        if (!awaitResult) {
+            // Fire-and-forget: detach outcome from the pipeline entirely.
+            child.on("error", () => { });
+            try {
+                child.stdin.write(JSON.stringify(payload));
+                child.stdin.end();
+            }
+            catch {
+                /* a dead stdin must not throw into the engine */
+            }
+            resolve({ command: spec.command, result: "ok", exitCode: null });
+            return;
+        }
+        let stdout = "";
+        child.stdout.on("data", (c) => (stdout += String(c)));
+        const timer = setTimeout(() => {
+            child.kill();
+            outcome("warn", null, stdout); // timeout fails OPEN: warn, never hang
+        }, spec.timeout ?? 5_000);
+        child.on("error", () => {
+            clearTimeout(timer);
+            outcome("warn", null);
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            outcome(code === 0 ? "ok" : code === 2 ? "block" : "warn", code, stdout);
+        });
+        try {
+            child.stdin.write(JSON.stringify(payload));
+            child.stdin.end();
+        }
+        catch {
+            /* the close handler still fires */
+        }
+    });
+}
+/**
+ * Run every hook configured for `event`. Blocking events await all matched
+ * hooks and report `blocked` when ANY says block; fire-and-forget events
+ * return immediately (`blocked: false` always).
+ */
+export async function runHooks(event, payload, config, matcherTarget = "") {
+    const specs = matching(config, event, matcherTarget);
+    if (specs.length === 0)
+        return { blocked: false, outcomes: [] };
+    const awaitResult = BLOCKING_EVENTS.includes(event);
+    const body = { hook_event: event, ...payload };
+    const outcomes = await Promise.all(specs.map((s) => runOne(s, body, awaitResult)));
+    return { blocked: awaitResult && outcomes.some((o) => o.result === "block"), outcomes };
+}

package/dist/index.d.ts

@@ -0,0 +1,53 @@
+/**
+ * @personaxis/core — the governed Living-Persona engine.
+ *
+ * Framework-agnostic, spec-faithful primitives shared by every entry point
+ * (CLI REPL, MCP server, TUI, HTTP). The engine never prints; it emits events.
+ */
+export * from "./persona.js";
+export * from "./lock.js";
+export * from "./envelopes.js";
+export * from "./state-engine.js";
+export * from "./state-rebuild.js";
+export * from "./spec-edit.js";
+export * from "./appraisal.js";
+export * from "./evolution-view.js";
+export * from "./heuristic-appraiser.js";
+export * from "./llm-appraiser.js";
+export * from "./responder.js";
+export * from "./governance.js";
+export * from "./verification.js";
+export * from "./self-evolution.js";
+export * from "./recompile-marker.js";
+export * from "./registry.js";
+export * from "./model-config.js";
+export * from "./blackboard.js";
+export * from "./live-sync.js";
+export * from "./sync.js";
+export * from "./skill-review.js";
+export * from "./skill-lifecycle.js";
+export * from "./memory.js";
+export * from "./memory-kinds.js";
+export * from "./sessions.js";
+export * from "./session-writer.js";
+export * from "./provenance.js";
+export * from "./injection.js";
+export * from "./config-scan.js";
+export * from "./config-layers.js";
+export * from "./compile/index.js";
+export * from "./ports/index.js";
+export * from "./sandbox.js";
+export * from "./hooks.js";
+export * from "./approval.js";
+export * from "./tool-repair.js";
+export * from "./sigil.js";
+export * from "./persona-theme.js";
+export * from "./events.js";
+export * from "./context.js";
+export * from "./trace.js";
+export * from "./loop.js";
+export * from "./tools/exec.js";
+export * from "./tools/registry.js";
+export * from "./tool-calling.js";
+export * from "./agent.js";
+export { CORE_VERSION } from "./generated/version.js";

package/dist/index.js

@@ -0,0 +1,53 @@
+/**
+ * @personaxis/core — the governed Living-Persona engine.
+ *
+ * Framework-agnostic, spec-faithful primitives shared by every entry point
+ * (CLI REPL, MCP server, TUI, HTTP). The engine never prints; it emits events.
+ */
+export * from "./persona.js";
+export * from "./lock.js";
+export * from "./envelopes.js";
+export * from "./state-engine.js";
+export * from "./state-rebuild.js";
+export * from "./spec-edit.js";
+export * from "./appraisal.js";
+export * from "./evolution-view.js";
+export * from "./heuristic-appraiser.js";
+export * from "./llm-appraiser.js";
+export * from "./responder.js";
+export * from "./governance.js";
+export * from "./verification.js";
+export * from "./self-evolution.js";
+export * from "./recompile-marker.js";
+export * from "./registry.js";
+export * from "./model-config.js";
+export * from "./blackboard.js";
+export * from "./live-sync.js";
+export * from "./sync.js";
+export * from "./skill-review.js";
+export * from "./skill-lifecycle.js";
+export * from "./memory.js";
+export * from "./memory-kinds.js";
+export * from "./sessions.js";
+export * from "./session-writer.js";
+export * from "./provenance.js";
+export * from "./injection.js";
+export * from "./config-scan.js";
+export * from "./config-layers.js";
+export * from "./compile/index.js";
+export * from "./ports/index.js";
+export * from "./sandbox.js";
+export * from "./hooks.js";
+export * from "./approval.js";
+export * from "./tool-repair.js";
+export * from "./sigil.js";
+export * from "./persona-theme.js";
+export * from "./events.js";
+export * from "./context.js";
+export * from "./trace.js";
+export * from "./loop.js";
+export * from "./tools/exec.js";
+export * from "./tools/registry.js";
+export * from "./tool-calling.js";
+export * from "./agent.js";
+export { CORE_VERSION } from "./generated/version.js";