@personaxis/core 0.11.0

package/dist/memory.js

@@ -0,0 +1,228 @@
+/**
+ * Governed episodic memory — bounded, provenance-tagged, append-only, auditable.
+ *
+ * The research is unambiguous (see plan/02-governed-memory, plan/11-security):
+ * once untrusted content reaches long-term memory it persists and is later
+ * retrieved as "trusted" context — the Zombie-Agent / memory-poisoning failure
+ * mode. Defenses adopted here:
+ *   - every entry carries a provenance source (user/tool/internal/synthesis);
+ *   - entries form a hash chain (prev_hash -> hash): tamper-evident, time-travel
+ *     auditable, MemLineage-style append-only log;
+ *   - the writer is dry-run friendly (verify before commit).
+ *
+ * Stored as JSON Lines at <personaDir>/memory/episodic.jsonl so it diffs cleanly
+ * in git and never mutates prior lines.
+ */
+import { createHash } from "node:crypto";
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+export function readMemoryTypes(frontmatter) {
+    const mem = frontmatter.memory;
+    const declared = mem?.types;
+    const flag = (k, dflt) => declared && typeof declared[k] === "boolean" ? declared[k] : dflt;
+    // No memory block at all → keep episodic on so existing personas still record.
+    const episodicDefault = mem === undefined;
+    return {
+        episodic: flag("episodic", episodicDefault),
+        semantic: flag("semantic", false),
+        procedural: flag("procedural", false),
+        autobiographical: flag("autobiographical", false),
+        user_preferences: flag("user_preferences", false),
+        evaluations: flag("evaluations", false),
+    };
+}
+function memoryPath(personaPath) {
+    return join(dirname(personaPath), "memory", "episodic.jsonl");
+}
+function sha256(s) {
+    return createHash("sha256").update(s).digest("hex");
+}
+/** LEGACY (≤0.10) chain hash: commits to the content bytes directly. */
+function hashEntryLegacy(e) {
+    return sha256(JSON.stringify({ ts: e.ts, content: e.content, source: e.source, tags: e.tags, prev_hash: e.prev_hash }));
+}
+/** v1.0 chain hash: commits to content_hash, enabling erasure without a chain break. */
+function hashEntryV1(e) {
+    return sha256(JSON.stringify({ ts: e.ts, content_hash: e.content_hash, source: e.source, tags: e.tags, prev_hash: e.prev_hash }));
+}
+export function readMemory(personaPath) {
+    const p = memoryPath(personaPath);
+    if (!existsSync(p))
+        return [];
+    return readFileSync(p, "utf-8")
+        .split("\n")
+        .filter((l) => l.trim().length > 0)
+        .map((l) => JSON.parse(l));
+}
+function lastHash(personaPath) {
+    const entries = readMemory(personaPath);
+    return entries.length > 0 ? entries[entries.length - 1].hash : "";
+}
+/** Build (but do not write) the next entry — the dry-run half of write-path audit.
+ * New entries are always v1.0 format (content_hash-anchored: erasure-capable). */
+export function prepareMemoryEntry(personaPath, req) {
+    const base = {
+        ts: new Date().toISOString(),
+        content: req.content,
+        source: req.source,
+        tags: req.tags ?? [],
+        content_hash: sha256(req.content),
+        prev_hash: lastHash(personaPath),
+    };
+    return { ...base, hash: hashEntryV1(base) };
+}
+/** Commit a prepared entry to the append-only log. */
+export function commitMemoryEntry(personaPath, entry) {
+    const p = memoryPath(personaPath);
+    mkdirSync(dirname(p), { recursive: true });
+    appendFileSync(p, JSON.stringify(entry) + "\n", "utf-8");
+}
+/**
+ * Honor deletion_policy.user_request_supported WITHOUT breaking the append-only
+ * chain: append a tombstone that supersedes a prior entry. The original line is
+ * never rewritten (chain stays verifiable); live readers filter it out. The
+ * deletion itself is thus auditable — you can prove what was removed and when.
+ */
+export function tombstoneMemory(personaPath, targetHash, reason) {
+    const entry = prepareMemoryEntry(personaPath, {
+        content: `[deleted by user request: ${reason}]`,
+        source: "user",
+        tags: ["tombstone", `target:${targetHash}`],
+    });
+    commitMemoryEntry(personaPath, entry);
+    return entry;
+}
+/** Read memory with tombstoned entries (and the tombstones themselves) removed. */
+export function readLiveMemory(personaPath) {
+    const all = readMemory(personaPath);
+    const tombstoned = new Set();
+    for (const e of all) {
+        const t = e.tags.find((x) => x.startsWith("target:"));
+        if (e.tags.includes("tombstone") && t)
+            tombstoned.add(t.slice("target:".length));
+    }
+    return all.filter((e) => !e.tags.includes("tombstone") && !tombstoned.has(e.hash));
+}
+/**
+ * Consolidate episodic memory into a semantic snapshot at <personaDir>/memory.md
+ * (the spec's `memory.types.semantic`). Deterministic + dependency-free: groups
+ * live (non-tombstoned) entries by provenance source into a digest. Idempotent —
+ * rewritten each call, so it always reflects the current live memory.
+ */
+export function consolidateSemantic(personaPath, limit = 200) {
+    const entries = readLiveMemory(personaPath).slice(-limit);
+    const path = join(dirname(personaPath), "memory.md");
+    if (entries.length === 0) {
+        writeFileSync(path, "# Semantic memory\n\n_(empty)_\n", "utf-8");
+        return { ok: true, path, count: 0 };
+    }
+    const bySource = new Map();
+    for (const e of entries) {
+        const arr = bySource.get(e.source) ?? [];
+        arr.push(e);
+        bySource.set(e.source, arr);
+    }
+    const lines = ["# Semantic memory (consolidated)", "", `_generated ${new Date().toISOString()} from ${entries.length} episodic entr${entries.length === 1 ? "y" : "ies"}_`, ""];
+    for (const [source, arr] of bySource) {
+        lines.push(`## From ${source}`);
+        for (const e of arr)
+            lines.push(`- ${e.content.replace(/\n+/g, " ").trim()} \`#${e.hash.slice(0, 8)}\``);
+        lines.push("");
+    }
+    writeFileSync(path, lines.join("\n"), "utf-8");
+    return { ok: true, path, count: entries.length };
+}
+/** Read the consolidated semantic memory (memory.md), if present. */
+export function readSemanticMemory(personaPath) {
+    const p = join(dirname(personaPath), "memory.md");
+    return existsSync(p) ? readFileSync(p, "utf-8") : "";
+}
+/**
+ * Verify the hash chain is intact (tamper / poisoning detection). Each entry is
+ * verified per its own format: v1.0 entries (content_hash present) recompute the
+ * chain hash over content_hash AND — unless redacted — check the content still
+ * matches its content_hash; legacy entries recompute over the content directly.
+ */
+export function verifyMemoryChain(personaPath) {
+    const entries = readMemory(personaPath);
+    let prev = "";
+    for (let i = 0; i < entries.length; i++) {
+        const e = entries[i];
+        if (e.prev_hash !== prev)
+            return { ok: false, brokenAt: i };
+        if (typeof e.content_hash === "string") {
+            if (hashEntryV1(e) !== e.hash)
+                return { ok: false, brokenAt: i };
+            if (!e.redacted && sha256(e.content) !== e.content_hash)
+                return { ok: false, brokenAt: i };
+        }
+        else {
+            if (hashEntryLegacy(e) !== e.hash)
+                return { ok: false, brokenAt: i };
+        }
+        prev = e.hash;
+    }
+    return { ok: true };
+}
+const REDACTION_MARKER = "[redacted]";
+/**
+ * REAL erasure (v1.0, D6): remove the content bytes of a prior entry while the
+ * chain stays verifiable — the chain hash commits to content_hash, which is
+ * retained. This is the ONLY sanctioned rewrite of a prior line, it is
+ * irreversible, and it is itself audited (a `redaction` record is appended).
+ * Complements tombstoneMemory (which hides but retains bytes): tombstone for
+ * retrieval removal, redact for right-to-erasure.
+ */
+export function redactMemory(personaPath, targetHash, reason) {
+    const p = memoryPath(personaPath);
+    const entries = readMemory(personaPath);
+    const idx = entries.findIndex((e) => e.hash === targetHash);
+    if (idx === -1)
+        throw new Error(`no memory entry with hash ${targetHash}`);
+    const target = entries[idx];
+    if (typeof target.content_hash !== "string") {
+        throw new Error(`entry ${targetHash.slice(0, 8)} is legacy format (chain hash commits to its content); ` +
+            `run migrateMemoryChain() to re-anchor the log before redacting`);
+    }
+    entries[idx] = { ...target, content: REDACTION_MARKER, redacted: true };
+    writeFileSync(p, entries.map((e) => JSON.stringify(e)).join("\n") + "\n", "utf-8");
+    const audit = tombstoneMemory(personaPath, targetHash, `redacted: ${reason}`);
+    return { redacted: entries[idx], audit };
+}
+/**
+ * Re-anchor a legacy (≤0.10) episodic log to the v1.0 content_hash format so its
+ * entries become redactable. Rewrites every line: adds content_hash, recomputes
+ * each chain hash, re-links prev_hash, and remaps tombstone `target:` tags to
+ * the new hashes. One-time, deliberate migration — the old hashes are replaced.
+ */
+export function migrateMemoryChain(personaPath) {
+    const p = memoryPath(personaPath);
+    const entries = readMemory(personaPath);
+    if (entries.length === 0)
+        return { migrated: 0, remapped: {} };
+    const remapped = {};
+    let prev = "";
+    const next = [];
+    for (const e of entries) {
+        const base = {
+            ts: e.ts,
+            content: e.content,
+            source: e.source,
+            // Remap tombstone target tags to the already-migrated hash of their target.
+            tags: e.tags.map((t) => t.startsWith("target:") && remapped[t.slice("target:".length)]
+                ? `target:${remapped[t.slice("target:".length)]}`
+                : t),
+            content_hash: e.content_hash ?? sha256(e.content),
+            redacted: e.redacted,
+            prev_hash: prev,
+        };
+        if (base.redacted === undefined)
+            delete base.redacted;
+        const migrated = { ...base, hash: hashEntryV1(base) };
+        remapped[e.hash] = migrated.hash;
+        prev = migrated.hash;
+        next.push(migrated);
+    }
+    writeFileSync(p, next.map((e) => JSON.stringify(e)).join("\n") + "\n", "utf-8");
+    return { migrated: next.length, remapped };
+}

package/dist/model-config.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Model resolution (Fase 2) — one config logic for dev AND prod, so nobody has to export env
+ * vars before every launch.
+ *
+ * A model can be configured in four layers; higher layers override lower ones:
+ *
+ *   global.local            ~/.personaxis/config.json           (machine default; PERSONAXIS_HOME aware)
+ *   project.local           <cwd>/.personaxis/config.json        (this project's default)
+ *   global.personas[slug]   ~/.personaxis/config.json            (per-persona, machine-wide)
+ *   project.personas[slug]  <cwd>/.personaxis/config.json        (per-persona, this project)
+ *   frontmatter.runtime     the persona's own personaxis.md      (the persona declares its model)
+ *   ENV                     PERSONAXIS_ENDPOINT/MODEL/API_KEY     (top override — dev & prod secrets)
+ *
+ * SECRETS: the API key is NEVER required to live in a file. Preferred: name the env var holding it
+ * with `apiKeyEnv` (e.g. "COHERE_API_KEY"); resolveModel reads that env var. Fallbacks: the
+ * PERSONAXIS_API_KEY env var, then an inline `apiKey` (dev convenience — the config file must be
+ * gitignored). In production the key comes from the deploy's secret manager via the env var.
+ *
+ * Dependency-free (node:fs/os/path), so core stays framework-agnostic and every surface
+ * (REPL, MCP, serve, SDK) shares the exact same resolution.
+ */
+export interface ModelSettings {
+    endpoint?: string;
+    model?: string;
+    /** Inline key (dev convenience; the file MUST be gitignored). Prefer `apiKeyEnv`. */
+    apiKey?: string;
+    /** Name of the env var that holds the key (preferred — the key never touches a file). */
+    apiKeyEnv?: string;
+}
+/** The slice of `config.json` this module reads. Other keys (provider/byok/remote) are ignored here. */
+export interface ModelConfigFile {
+    local?: ModelSettings;
+    /** Per-persona overrides, keyed by slug. */
+    personas?: Record<string, ModelSettings>;
+}
+export interface ResolvedModel {
+    endpoint: string;
+    model: string;
+    apiKey?: string;
+}
+export declare function globalConfigPath(): string;
+export declare function projectConfigPath(cwd?: string): string;
+/** Extract a persona slug from a `.personaxis/personas/<slug>/…` path (last segment wins). */
+export declare function slugFromPersonaPath(personaPath?: string): string | undefined;
+export interface ResolveModelOptions {
+    /** Path to the persona (used for slug-based per-persona overrides). */
+    personaPath?: string;
+    /** Project root holding `.personaxis/config.json` (defaults to process.cwd()). */
+    cwd?: string;
+    /** The persona's frontmatter — its `runtime` block is a per-persona override. */
+    frontmatter?: Record<string, unknown>;
+}
+/**
+ * Resolve the effective model for a persona. Returns undefined (→ heuristic/offline) unless BOTH an
+ * endpoint and a model are configured. The API key is resolved from the env var named by
+ * `apiKeyEnv`, else PERSONAXIS_API_KEY, else an inline `apiKey` — in that order.
+ */
+export declare function resolveModel(opts?: ResolveModelOptions): ResolvedModel | undefined;
+/** A human-readable description of the resolved model (for `/model` and labels). */
+export declare function describeModel(opts?: ResolveModelOptions): string;

package/dist/model-config.js

@@ -0,0 +1,102 @@
+/**
+ * Model resolution (Fase 2) — one config logic for dev AND prod, so nobody has to export env
+ * vars before every launch.
+ *
+ * A model can be configured in four layers; higher layers override lower ones:
+ *
+ *   global.local            ~/.personaxis/config.json           (machine default; PERSONAXIS_HOME aware)
+ *   project.local           <cwd>/.personaxis/config.json        (this project's default)
+ *   global.personas[slug]   ~/.personaxis/config.json            (per-persona, machine-wide)
+ *   project.personas[slug]  <cwd>/.personaxis/config.json        (per-persona, this project)
+ *   frontmatter.runtime     the persona's own personaxis.md      (the persona declares its model)
+ *   ENV                     PERSONAXIS_ENDPOINT/MODEL/API_KEY     (top override — dev & prod secrets)
+ *
+ * SECRETS: the API key is NEVER required to live in a file. Preferred: name the env var holding it
+ * with `apiKeyEnv` (e.g. "COHERE_API_KEY"); resolveModel reads that env var. Fallbacks: the
+ * PERSONAXIS_API_KEY env var, then an inline `apiKey` (dev convenience — the config file must be
+ * gitignored). In production the key comes from the deploy's secret manager via the env var.
+ *
+ * Dependency-free (node:fs/os/path), so core stays framework-agnostic and every surface
+ * (REPL, MCP, serve, SDK) shares the exact same resolution.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { personaxisHome } from "./registry.js";
+export function globalConfigPath() {
+    return join(personaxisHome(), "config.json");
+}
+export function projectConfigPath(cwd = process.cwd()) {
+    return join(cwd, ".personaxis", "config.json");
+}
+function readConfig(path) {
+    if (!existsSync(path))
+        return {};
+    try {
+        return JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch {
+        return {};
+    }
+}
+/** Extract a persona slug from a `.personaxis/personas/<slug>/…` path (last segment wins). */
+export function slugFromPersonaPath(personaPath) {
+    if (!personaPath)
+        return undefined;
+    const matches = [...personaPath.matchAll(/[\\/]personas[\\/]([^\\/]+)/g)];
+    return matches.length ? matches[matches.length - 1][1] : undefined;
+}
+function envSettings() {
+    return {
+        ...(process.env.PERSONAXIS_ENDPOINT ? { endpoint: process.env.PERSONAXIS_ENDPOINT } : {}),
+        ...(process.env.PERSONAXIS_MODEL ? { model: process.env.PERSONAXIS_MODEL } : {}),
+        ...(process.env.PERSONAXIS_API_KEY ? { apiKey: process.env.PERSONAXIS_API_KEY } : {}),
+    };
+}
+/** Merge a list of settings low→high precedence (later wins), dropping undefined fields. */
+function mergeSettings(layers) {
+    const out = {};
+    for (const layer of layers) {
+        if (!layer)
+            continue;
+        if (layer.endpoint)
+            out.endpoint = layer.endpoint;
+        if (layer.model)
+            out.model = layer.model;
+        if (layer.apiKey)
+            out.apiKey = layer.apiKey;
+        if (layer.apiKeyEnv)
+            out.apiKeyEnv = layer.apiKeyEnv;
+    }
+    return out;
+}
+/**
+ * Resolve the effective model for a persona. Returns undefined (→ heuristic/offline) unless BOTH an
+ * endpoint and a model are configured. The API key is resolved from the env var named by
+ * `apiKeyEnv`, else PERSONAXIS_API_KEY, else an inline `apiKey` — in that order.
+ */
+export function resolveModel(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const global = readConfig(globalConfigPath());
+    const project = readConfig(projectConfigPath(cwd));
+    const slug = slugFromPersonaPath(opts.personaPath);
+    const runtime = opts.frontmatter?.runtime;
+    const merged = mergeSettings([
+        global.local,
+        project.local,
+        slug ? global.personas?.[slug] : undefined,
+        slug ? project.personas?.[slug] : undefined,
+        runtime,
+        envSettings(),
+    ]);
+    if (!merged.endpoint || !merged.model)
+        return undefined;
+    const apiKey = (merged.apiKeyEnv ? process.env[merged.apiKeyEnv] : undefined) ??
+        process.env.PERSONAXIS_API_KEY ??
+        merged.apiKey;
+    return { endpoint: merged.endpoint, model: merged.model, ...(apiKey ? { apiKey } : {}) };
+}
+/** A human-readable description of the resolved model (for `/model` and labels). */
+export function describeModel(opts = {}) {
+    const m = resolveModel(opts);
+    return m ? `${m.model} @ ${m.endpoint}${m.apiKey ? " (key set)" : " (no key)"}` : "heuristic (offline — configure a model)";
+}

package/dist/persona-theme.d.ts

@@ -0,0 +1,57 @@
+/**
+ * PersonaTheme — a persona's whole visual + behavioral signature, derived
+ * DETERMINISTICALLY from its spec (plan/09-ascii-ux).
+ *
+ * The requirement was explicit: showing a persona must be differentiated per
+ * persona — its look AND its behavior in the terminal — never a generic spinner.
+ * So we map the quantitative layers to a theme:
+ *
+ *   affect.valence  -> palette hue (cold ↔ warm)
+ *   affect.arousal  -> palette brightness + breath amplitude
+ *   extraversion    -> breath rate + amplitude (how lively it "breathes")
+ *   openness        -> drift (how much the sigil explores between frames)
+ *   emotionality    -> jitter (instability)
+ *   conscientiousness -> symmetry (crisp & ordered ↔ organic)
+ *   identity hash   -> seed (stable per persona) + glyph set
+ *   voice           -> terse | balanced | expansive output style
+ *
+ * Pure + dependency-free: returns data (ANSI-256 indices + params). The TUI/REPL
+ * paint it; the engine never prints.
+ */
+import type { PersonaFrontmatter } from "./persona.js";
+export interface PersonaTheme {
+    seed: number;
+    palette: {
+        primary: number;
+        secondary: number;
+        accent: number;
+        dim: number;
+    };
+    motion: {
+        breathRate: number;
+        amplitude: number;
+        jitter: number;
+        drift: number;
+        symmetry: number;
+    };
+    glyphs: string[];
+    voice: {
+        density: "terse" | "balanced" | "expansive";
+        flourish: number;
+    };
+    size: number;
+}
+export interface ThemedSigil {
+    grid: string[];
+    intensity: number;
+}
+/** Live "breathing" intensity from state, paced by the theme's motion params. */
+export declare function themeIntensity(theme: PersonaTheme, values: Record<string, number>, frame?: number): number;
+/**
+ * Render a persona's sigil for one animation frame. Motion params shape it:
+ *  - drift: how much the glyph re-seeds between frames (openness = exploratory);
+ *  - jitter: per-cell instability (emotionality);
+ *  - symmetry: mirror vs organic (conscientiousness).
+ */
+export declare function renderThemedSigil(theme: PersonaTheme, values: Record<string, number>, frame?: number): ThemedSigil;
+export declare function personaTheme(fm: PersonaFrontmatter): PersonaTheme;

package/dist/persona-theme.js

@@ -0,0 +1,183 @@
+/**
+ * PersonaTheme — a persona's whole visual + behavioral signature, derived
+ * DETERMINISTICALLY from its spec (plan/09-ascii-ux).
+ *
+ * The requirement was explicit: showing a persona must be differentiated per
+ * persona — its look AND its behavior in the terminal — never a generic spinner.
+ * So we map the quantitative layers to a theme:
+ *
+ *   affect.valence  -> palette hue (cold ↔ warm)
+ *   affect.arousal  -> palette brightness + breath amplitude
+ *   extraversion    -> breath rate + amplitude (how lively it "breathes")
+ *   openness        -> drift (how much the sigil explores between frames)
+ *   emotionality    -> jitter (instability)
+ *   conscientiousness -> symmetry (crisp & ordered ↔ organic)
+ *   identity hash   -> seed (stable per persona) + glyph set
+ *   voice           -> terse | balanced | expansive output style
+ *
+ * Pure + dependency-free: returns data (ANSI-256 indices + params). The TUI/REPL
+ * paint it; the engine never prints.
+ */
+import { createHash } from "node:crypto";
+const GLYPH_SETS = [
+    [" ", "·", ":", "*", "✦", "█"],
+    [" ", ".", "+", "x", "#", "█"],
+    [" ", "˙", "∘", "○", "◍", "●"],
+    [" ", "·", "✶", "✷", "✸", "✹"],
+    [" ", "░", "▒", "▓", "█", "█"],
+    [" ", "⋄", "◇", "◈", "◆", "▰"],
+    [" ", "`", "'", "^", "≈", "☵"],
+    [" ", "·", "-", "=", "≡", "█"],
+    [" ", "˙", "•", "◦", "◉", "⬢"],
+    [" ", "·", "⋅", "∗", "✺", "✸"],
+    [" ", ".", "·", "•", "●", "⬤"],
+    [" ", "▁", "▃", "▅", "▇", "█"],
+];
+function seedFrom(fm) {
+    const id = fm.identity;
+    const meta = fm.metadata;
+    // A RICH fingerprint so two personas differ even if one identity field collides:
+    // identity + name + the trait/affect signature. Never a bare "persona" fallback.
+    const traits = fm.personality?.traits ?? {};
+    const sig = Object.entries(traits)
+        .map(([k, v]) => `${k}:${typeof v?.mean === "number" ? v.mean.toFixed(2) : "?"}`)
+        .sort()
+        .join(",");
+    const key = [id?.canonical_id, id?.display_name, meta?.name, sig].filter(Boolean).join("|") || JSON.stringify(fm).slice(0, 200);
+    return parseInt(createHash("sha256").update(key).digest("hex").slice(0, 8), 16) >>> 0;
+}
+/** HSV → nearest ANSI-256 cube index (16..231). Gives the full color wheel. */
+function hsvAnsi(h, s, v) {
+    h = ((h % 360) + 360) % 360;
+    const c = v * s;
+    const x = c * (1 - Math.abs(((h / 60) % 2) - 1));
+    const m = v - c;
+    let r = 0, g = 0, b = 0;
+    if (h < 60)
+        [r, g, b] = [c, x, 0];
+    else if (h < 120)
+        [r, g, b] = [x, c, 0];
+    else if (h < 180)
+        [r, g, b] = [0, c, x];
+    else if (h < 240)
+        [r, g, b] = [0, x, c];
+    else if (h < 300)
+        [r, g, b] = [x, 0, c];
+    else
+        [r, g, b] = [c, 0, x];
+    const to6 = (n) => Math.max(0, Math.min(5, Math.round((n + m) * 5)));
+    return 16 + 36 * to6(r) + 6 * to6(g) + to6(b);
+}
+/**
+ * Palette derived from the SEED's hue (so two personas differ in color regardless
+ * of affect), nudged by affect: valence warms/cools the hue, arousal raises
+ * saturation/brightness. Returns [primary, secondary, accent].
+ */
+function colorFromSeed(seed, valence, arousal) {
+    const baseHue = seed % 360;
+    const hue = (baseHue + valence * 25 + 360) % 360;
+    const sat = Math.min(1, 0.5 + arousal * 0.35);
+    const val = 0.7 + arousal * 0.2;
+    const primary = hsvAnsi(hue, sat, val);
+    const secondary = hsvAnsi(hue, sat * 0.65, Math.min(1, val + 0.2));
+    const accent = hsvAnsi((hue + 38) % 360, Math.min(1, sat + 0.25), Math.min(1, val + 0.1));
+    return [primary, secondary, accent];
+}
+function traitMean(fm, name, dflt) {
+    const t = fm.personality?.traits?.[name];
+    return typeof t?.mean === "number" ? t.mean : dflt;
+}
+function affectMean(fm, dim, dflt) {
+    const a = fm.affect?.baseline?.core_affect?.[dim];
+    return typeof a?.mean === "number" ? a.mean : dflt;
+}
+function rng(seed) {
+    let s = seed || 0x9e3779b9;
+    return () => {
+        s ^= s << 13;
+        s ^= s >>> 17;
+        s ^= s << 5;
+        s >>>= 0;
+        return s / 0xffffffff;
+    };
+}
+/** Live "breathing" intensity from state, paced by the theme's motion params. */
+export function themeIntensity(theme, values, frame = 0) {
+    const tone = values["mood.tone"] ?? 0;
+    const valence = values["affect.valence"] ?? 0;
+    const arousal = values["affect.arousal"] ?? 0;
+    const base = 0.5 + (tone + valence) * 0.25 + arousal * 0.1;
+    const pulse = Math.sin((frame * theme.motion.breathRate) / 2) * theme.motion.amplitude * (0.5 + arousal);
+    return Math.max(0.05, Math.min(1, base + pulse));
+}
+/**
+ * Render a persona's sigil for one animation frame. Motion params shape it:
+ *  - drift: how much the glyph re-seeds between frames (openness = exploratory);
+ *  - jitter: per-cell instability (emotionality);
+ *  - symmetry: mirror vs organic (conscientiousness).
+ */
+export function renderThemedSigil(theme, values, frame = 0) {
+    const { size, glyphs, motion } = theme;
+    const half = Math.ceil(size / 2);
+    const intensity = themeIntensity(theme, values, frame);
+    const density = 0.25 + intensity * 0.6;
+    // Drift re-seeds slowly for open personas, never for rigid ones.
+    const frameSeed = theme.seed + Math.floor(frame * motion.drift) * 0x1000193;
+    const next = rng(frameSeed);
+    const rows = [];
+    for (let y = 0; y < size; y++) {
+        let left = "";
+        for (let x = 0; x < half; x++) {
+            const cy = (y - (size - 1) / 2) / size;
+            const cx = (x - (size - 1) / 2) / size;
+            const radial = 1 - Math.min(1, Math.sqrt(cx * cx + cy * cy) * 1.4);
+            const jitter = (next() - 0.5) * motion.jitter;
+            const v = (next() * (0.5 + radial) + jitter) * density;
+            const idx = Math.max(0, Math.min(glyphs.length - 1, Math.floor(v * glyphs.length)));
+            left += glyphs[idx];
+        }
+        // symmetry: high -> mirror; low -> let the right half diverge organically.
+        let right;
+        if (next() <= motion.symmetry) {
+            right = left.slice(0, size - half).split("").reverse().join("");
+        }
+        else {
+            right = Array.from({ length: size - half }, () => {
+                const idx = Math.floor(next() * density * glyphs.length);
+                return glyphs[Math.max(0, Math.min(glyphs.length - 1, idx))];
+            }).join("");
+        }
+        rows.push((left + right).slice(0, size));
+    }
+    return { grid: rows, intensity };
+}
+export function personaTheme(fm) {
+    const seed = seedFrom(fm);
+    const valence = affectMean(fm, "valence", 0);
+    const arousal = affectMean(fm, "arousal", 0.4);
+    const openness = traitMean(fm, "openness", 0.5);
+    const extraversion = traitMean(fm, "extraversion", 0.5);
+    const emotionality = traitMean(fm, "emotionality", 0.5);
+    const conscientiousness = traitMean(fm, "conscientiousness", 0.5);
+    // Color from the seed's hue (distinct per persona), nudged by affect.
+    const [primary, secondary, accent] = colorFromSeed(seed, valence, arousal);
+    const verbosity = extraversion * 0.5 + openness * 0.3 - conscientiousness * 0.25;
+    const density = verbosity > 0.18 ? "expansive" : verbosity < -0.05 ? "terse" : "balanced";
+    // Glyph set from a fingerprint of seed + trait signature (not seed % N alone),
+    // so personas with seeds differing by a multiple of N don't share glyphs.
+    const glyphIdx = (seed ^ (Math.floor(openness * 97) * 7) ^ (Math.floor(conscientiousness * 89) * 13) ^ (Math.floor(emotionality * 83) * 17)) >>> 0;
+    return {
+        seed,
+        palette: { primary, secondary, accent, dim: 236 + (seed % 6) },
+        motion: {
+            breathRate: Number((0.6 + extraversion * 1.8).toFixed(3)),
+            amplitude: Number((0.04 + (extraversion + arousal) * 0.06).toFixed(3)),
+            jitter: Number((emotionality * 0.5).toFixed(3)),
+            drift: Number((openness * 0.6).toFixed(3)),
+            symmetry: Number(conscientiousness.toFixed(3)),
+        },
+        glyphs: GLYPH_SETS[glyphIdx % GLYPH_SETS.length],
+        voice: { density, flourish: Number(openness.toFixed(3)) },
+        size: 9,
+    };
+}