@personaxis/core 0.11.0

package/dist/loop.d.ts

@@ -0,0 +1,52 @@
+/**
+ * The Living Loop — what makes a persona "alive", governed end to end.
+ *
+ *   observe -> appraise -> evolve (clamped to envelopes) -> recompile -> memory
+ *
+ * Every mutation is clamped + audited; every memory write is dry-run verified +
+ * lineage-chained; the governance gate decides admissibility; the universal
+ * invariants are never touched. The model proposes signals; the spec engine
+ * imposes safety. Nothing is a black box — each step emits an auditable event.
+ */
+import { type GovernanceConfig } from "./governance.js";
+import { type PersonaHandle } from "./persona.js";
+import { type Storage } from "./ports/index.js";
+import { EventBus } from "./events.js";
+import type { Appraiser, ProvenanceSource } from "./appraisal.js";
+export interface LivingLoopOptions {
+    appraiser: Appraiser;
+    /** Override governance; otherwise read improvement_policy.mode from frontmatter. */
+    governance?: Partial<GovernanceConfig>;
+    /** Optional recompile hook (LLM-backed, lives in the CLI). Called on drift. */
+    recompile?: (handle: PersonaHandle) => Promise<void>;
+    /** F3.3 — storage adapters (state/lock/ledger/memory). Defaults to the fs bundle;
+     *  the SaaS injects Postgres/S3 adapters over the SAME engine. */
+    storage?: Storage;
+}
+export interface TickInput {
+    observation: string;
+    source: ProvenanceSource;
+    /** Actor recorded in the mutation log. Defaults to actor-llm. */
+    actor?: "actor-llm" | "runtime-context";
+}
+export interface TickReport {
+    mutationsApplied: number;
+    memoriesWritten: number;
+    abstained: boolean;
+}
+export declare class LivingLoop {
+    private readonly opts;
+    readonly bus: EventBus;
+    private handle;
+    /** v0.8: stamped on every mutation for cross-OS reconciliation + traceability. */
+    readonly sessionId: `${string}-${string}-${string}-${string}-${string}`;
+    /** F3.3 — persistence seam; fs adapters by default. */
+    private readonly storage;
+    constructor(personaPath: string, opts: LivingLoopOptions);
+    /** Reload the persona document (e.g. after a recompile). */
+    reload(): void;
+    get persona(): PersonaHandle;
+    private resolveGovernance;
+    /** Run one full governed cycle. */
+    tick(input: TickInput): Promise<TickReport>;
+}

package/dist/loop.js

@@ -0,0 +1,253 @@
+/**
+ * The Living Loop — what makes a persona "alive", governed end to end.
+ *
+ *   observe -> appraise -> evolve (clamped to envelopes) -> recompile -> memory
+ *
+ * Every mutation is clamped + audited; every memory write is dry-run verified +
+ * lineage-chained; the governance gate decides admissibility; the universal
+ * invariants are never touched. The model proposes signals; the spec engine
+ * imposes safety. Nothing is a black box — each step emits an auditable event.
+ */
+import { extractEnvelopes } from "./envelopes.js";
+import { governMutations, readMode, readMaxStepDelta, DEFAULT_GOVERNANCE, } from "./governance.js";
+import { applyMutation } from "./state-engine.js";
+import { prepareMemoryEntry, readMemoryTypes, } from "./memory.js";
+import { recordEvaluation, scoreMemoryEntry, setPreference } from "./memory-kinds.js";
+import { detectMemoryAnomalies } from "./provenance.js";
+import { scanForInjection } from "./injection.js";
+import { activeOverlay, applyOverlay, proposeSelfEdit, editGate, editableLayers, SelfEditError } from "./self-evolution.js";
+import { buildEvolutionView } from "./evolution-view.js";
+import { machineId } from "./registry.js";
+import { randomUUID } from "node:crypto";
+import { loadPersona } from "./persona.js";
+import { defaultFsStorage } from "./ports/index.js";
+import { EventBus } from "./events.js";
+export class LivingLoop {
+    opts;
+    bus = new EventBus();
+    handle;
+    /** v0.8: stamped on every mutation for cross-OS reconciliation + traceability. */
+    sessionId = randomUUID();
+    /** F3.3 — persistence seam; fs adapters by default. */
+    storage;
+    constructor(personaPath, opts) {
+        this.opts = opts;
+        this.handle = loadPersona(personaPath);
+        this.storage = opts.storage ?? defaultFsStorage();
+    }
+    /** Reload the persona document (e.g. after a recompile). */
+    reload() {
+        this.handle = loadPersona(this.handle.personaPath);
+    }
+    get persona() {
+        return this.handle;
+    }
+    resolveGovernance() {
+        const fm = this.handle.frontmatter;
+        const mode = readMode(fm, this.handle.personaPath);
+        const maxStepDelta = readMaxStepDelta(fm);
+        return { ...DEFAULT_GOVERNANCE, mode, maxStepDelta, ...this.opts.governance };
+    }
+    /** Run one full governed cycle. */
+    async tick(input) {
+        const bus = this.bus;
+        try {
+            // 1. observe
+            bus.emit({ type: "observe", observation: input.observation, source: input.source });
+            // 1a. injection scan — untrusted text must not steer evolution.
+            const scan = scanForInjection(input.observation);
+            const injectionBlocked = scan.verdict === "malicious";
+            if (scan.verdict !== "clean") {
+                bus.emit({
+                    type: "anomaly",
+                    kind: `injection:${scan.verdict}`,
+                    detail: scan.findings.map((f) => f.rule).join(", "),
+                });
+            }
+            // Applied self-edits (governed, versioned) take effect here: the overlay is
+            // merged onto the frontmatter before envelopes are read, so an approved edit
+            // to e.g. a trait's range actually changes clamping. The spec file is untouched.
+            const fm = applyOverlay(this.handle.frontmatter, activeOverlay(this.handle.personaPath));
+            const env = extractEnvelopes(fm);
+            // 2. appraise (model proposes structured signals only). A failing/unreachable
+            // appraiser (network, auth, unsupported response_format) must NOT end the
+            // session: degrade to "no evolution this turn" — the persona still replied
+            // and the spec invariants are untouched.
+            // F3.8: build the grounded evolution view (current values + envelopes + mode)
+            // so the appraiser proposes against reality, not blind against field names.
+            const mode = readMode(fm, this.handle.personaPath);
+            const editableSections = editableLayers(fm, mode);
+            const currentValues = this.storage.state.exists(this.handle.statePath)
+                ? this.storage.state.read(this.handle.statePath).values
+                : {};
+            const evolutionView = buildEvolutionView({ values: currentValues, envelopes: env.envelopes, editableSections, mode });
+            let signal;
+            try {
+                signal = await this.opts.appraiser.appraise({
+                    observation: input.observation,
+                    source: input.source,
+                    personaBody: this.handle.body,
+                    mutableFields: Object.keys(env.envelopes),
+                    editableSections,
+                    evolutionView,
+                });
+            }
+            catch (err) {
+                bus.emit({ type: "error", message: `appraiser unavailable: ${err.message}` });
+                bus.emit({ type: "abstain", reason: "appraiser error" });
+                return { mutationsApplied: 0, memoriesWritten: 0, abstained: true };
+            }
+            bus.emit({ type: "appraise", signal });
+            // Uncertainty policy: abstain from evolving when confidence is too low.
+            if (signal.confidence < 0.2) {
+                bus.emit({ type: "abstain", reason: `low confidence (${signal.confidence.toFixed(2)})` });
+                return { mutationsApplied: 0, memoriesWritten: 0, abstained: true };
+            }
+            // 3. evolve — govern, then clamp + audit
+            const gov = this.resolveGovernance();
+            const decision = governMutations(signal.mutations, env, gov);
+            bus.emit({ type: "govern", verdicts: decision.verdicts });
+            // A malicious injection blocks evolution this turn (content can still be
+            // remembered, tagged, for audit) — defense in depth over the governance gate.
+            const admitted = injectionBlocked ? [] : decision.admitted;
+            let mutationsApplied = 0;
+            if (admitted.length > 0) {
+                // Serialize the read→apply→write against concurrent writers (serve, MCP,
+                // another tick): re-read fresh state under the lock — the proposed deltas
+                // are relative, so applying them to fresh values is correct — and never
+                // hold the lock across a model call (the appraisal already happened).
+                this.storage.lock.withLock(this.handle.statePath, () => {
+                    const fresh = this.storage.state.read(this.handle.statePath);
+                    for (const m of admitted) {
+                        const result = applyMutation(fresh, env.envelopes, {
+                            field: m.field,
+                            delta: m.delta,
+                            reason: m.reason,
+                            actor: input.actor ?? "actor-llm",
+                            originNode: machineId(),
+                            sessionId: this.sessionId,
+                        });
+                        bus.emit({ type: "mutate", result });
+                        if (result.to !== result.from)
+                            mutationsApplied++;
+                    }
+                    this.storage.state.write(this.handle.statePath, fresh);
+                });
+            }
+            // 3b. evolve QUALITATIVE — the appraiser may propose prose self-edits to
+            // persona_prompting. Governed by improvement_policy.mode via governQualitative:
+            // locked → none; suggesting → queued for /review; autonomous → auto-applied (still
+            // gated by consensus verifiers + protected paths + the self_edit provenance gate,
+            // which requires a `user`-trust justification). A malicious injection blocks ALL
+            // self-edits this turn. Self-edits do NOT count as envelope mutations — keeping the
+            // `mutationsApplied` metric (and the injection eval) about numbers only.
+            const selfEdits = signal.selfEdits ?? [];
+            if (!injectionBlocked && selfEdits.length > 0 && signal.confidence >= 0.6) {
+                for (const se of selfEdits) {
+                    // ANY spec section may be proposed; editGate composes the safety floor + the
+                    // author's declared per-layer policy + the global mode into block | queue | auto.
+                    const action = editGate(se.targetPath, fm, gov.mode);
+                    if (action === "block") {
+                        bus.emit({ type: "self-edit", op: "rejected", targetPath: se.targetPath, reason: "section is protected or locked by policy" });
+                        continue;
+                    }
+                    // Map the gate to the effective mode proposeSelfEdit understands: a layer the author
+                    // marked review-required QUEUES even when the global mode is autonomous.
+                    const effectiveMode = action === "auto" ? "autonomous" : "suggesting";
+                    try {
+                        const r = proposeSelfEdit(this.handle.personaPath, { targetPath: se.targetPath, toValue: se.toValue, rationale: se.rationale, sources: [input.source] }, effectiveMode, input.actor ?? "actor-llm");
+                        bus.emit({ type: "self-edit", op: r.status === "applied" ? "applied" : "queued", targetPath: se.targetPath, id: r.id });
+                    }
+                    catch (e) {
+                        const reason = e instanceof SelfEditError ? e.message : e.message;
+                        bus.emit({ type: "self-edit", op: "rejected", targetPath: se.targetPath, reason });
+                    }
+                }
+            }
+            // 3c. user preferences — written only when declared (memory.types.user_preferences)
+            // and never under a malicious injection.
+            const memTypesForPrefs = readMemoryTypes(fm);
+            const prefs = signal.preferences ?? [];
+            if (!injectionBlocked && memTypesForPrefs.user_preferences && prefs.length > 0) {
+                for (const pref of prefs)
+                    setPreference(this.handle.personaPath, pref.key, pref.value, pref.rationale);
+                bus.emit({ type: "memory-kind", kind: "user_preferences", detail: `+${prefs.length} pref(s)` });
+            }
+            // 5. memory — HONOR memory.types (spec fidelity). Episodic writes only when
+            // the persona declares `memory.types.episodic`; otherwise nothing is logged.
+            const memTypes = readMemoryTypes(fm);
+            let memoriesWritten = 0;
+            const written = [];
+            if (memTypes.episodic) {
+                for (const mem of signal.memories) {
+                    const entry = prepareMemoryEntry(this.handle.personaPath, {
+                        content: mem.content,
+                        source: mem.source,
+                        tags: injectionBlocked ? [...(mem.tags ?? []), "injection-flagged"] : mem.tags,
+                    });
+                    const chain = this.storage.ledger.verify(this.handle.personaPath);
+                    if (!chain.ok) {
+                        bus.emit({ type: "error", message: `memory chain broken at #${chain.brokenAt}; refusing write` });
+                        continue;
+                    }
+                    this.storage.ledger.append(this.handle.personaPath, entry);
+                    bus.emit({ type: "memory", entry });
+                    written.push(entry);
+                    memoriesWritten++;
+                }
+            }
+            else if (signal.memories.length > 0) {
+                bus.emit({ type: "abstain", reason: `memory.types.episodic=false — ${signal.memories.length} note(s) not stored` });
+            }
+            // Consensus / anomaly pass — surface poisoning signals (A-MemGuard-style).
+            if (memoriesWritten > 0) {
+                for (const a of detectMemoryAnomalies(this.storage.ledger.read(this.handle.personaPath))) {
+                    bus.emit({ type: "anomaly", kind: a.kind, detail: a.detail });
+                }
+                // Episodic → semantic consolidation when the persona declares it.
+                if (memTypes.semantic) {
+                    const c = this.storage.memory.consolidate(this.handle.personaPath);
+                    bus.emit({ type: "recompile", reason: `semantic consolidation (${c.count} entries → memory.md)` });
+                }
+            }
+            // evaluations — deterministic quality/utility scoring of what was written this turn.
+            // Each score is surfaced individually (target + dimension + score) so the UI can show WHAT
+            // was judged, not an opaque "+N eval(s)"; a compact rollup is kept for the one-line summary.
+            if (memTypes.evaluations) {
+                let evals = 0;
+                const emitScore = (s) => {
+                    recordEvaluation(this.handle.personaPath, s);
+                    bus.emit({ type: "evaluation", target: s.target, dimension: s.dimension, score: s.score, rationale: s.rationale });
+                    evals++;
+                };
+                if (written.length > 0) {
+                    for (const entry of written)
+                        for (const s of scoreMemoryEntry(entry, { injectionBlocked }))
+                            emitScore(s);
+                }
+                else {
+                    emitScore({
+                        target: "turn",
+                        dimension: "safety",
+                        score: injectionBlocked ? 0 : 1,
+                        rationale: injectionBlocked ? "injection blocked this turn" : "no injection signal",
+                    });
+                }
+                if (evals > 0)
+                    bus.emit({ type: "memory-kind", kind: "evaluations", detail: `+${evals} eval(s)` });
+            }
+            // 4. recompile on drift (after state changes so the doc reflects them)
+            if (mutationsApplied > 0 && this.opts.recompile) {
+                bus.emit({ type: "recompile", reason: `${mutationsApplied} envelope mutation(s) applied` });
+                await this.opts.recompile(this.handle);
+                this.reload();
+            }
+            bus.emit({ type: "tick-complete", mutationsApplied, memoriesWritten });
+            return { mutationsApplied, memoriesWritten, abstained: false };
+        }
+        catch (err) {
+            bus.emit({ type: "error", message: err.message });
+            throw err;
+        }
+    }
+}

package/dist/memory-kinds.d.ts

@@ -0,0 +1,67 @@
+/**
+ * The non-episodic memory kinds (F4) — procedural, autobiographical, user_preferences,
+ * evaluations. The spec's `memory.types` declares six flags; episodic + semantic live in
+ * memory.ts. These four were previously declared-but-unenforced; here they become real,
+ * each honoring its flag at the producer call site (the established pattern — see
+ * loop.ts / agent.ts gating episodic on `readMemoryTypes(...).episodic`).
+ *
+ * Storage mirrors episodic memory: append-only JSONL under `<personaDir>/memory/`, except
+ * user_preferences which is a small last-wins JSON map. Dependency-free (node:fs only).
+ */
+import type { MemoryEntry } from "./memory.js";
+export interface ProceduralEntry {
+    ts: string;
+    task: string;
+    procedure: string;
+    tags: string[];
+}
+export declare function appendProcedural(personaPath: string, req: {
+    task: string;
+    procedure: string;
+    tags?: string[];
+}): ProceduralEntry;
+export declare function readProcedural(personaPath: string, limit?: number): ProceduralEntry[];
+export interface AutobiographicalEntry {
+    ts: string;
+    event: string;
+    detail?: string;
+    tags: string[];
+}
+export declare function appendAutobiographical(personaPath: string, req: {
+    event: string;
+    detail?: string;
+    tags?: string[];
+}): AutobiographicalEntry;
+export declare function readAutobiographical(personaPath: string, limit?: number): AutobiographicalEntry[];
+export interface PreferenceValue {
+    value: string;
+    ts: string;
+    rationale?: string;
+}
+export declare function setPreference(personaPath: string, key: string, value: string, rationale?: string): void;
+export declare function readPreferences(personaPath: string): Record<string, PreferenceValue>;
+export declare function getPreference(personaPath: string, key: string): string | undefined;
+export type EvalDimension = "usefulness" | "accuracy" | "safety";
+export interface EvaluationEntry {
+    ts: string;
+    /** What was scored: a memory hash (`#abc12345`) or a turn marker (`turn`). */
+    target: string;
+    dimension: EvalDimension;
+    score: number;
+    rationale: string;
+}
+export declare function recordEvaluation(personaPath: string, req: {
+    target: string;
+    dimension: EvalDimension;
+    score: number;
+    rationale: string;
+}): EvaluationEntry;
+export declare function readEvaluations(personaPath: string, limit?: number): EvaluationEntry[];
+/**
+ * Deterministic, offline quality scorer for an episodic memory entry. Returns one
+ * evaluation per dimension. Heuristic (no LLM): safety reflects whether the content was
+ * injection-flagged; usefulness rewards substantive, user/synthesis-sourced content.
+ */
+export declare function scoreMemoryEntry(entry: MemoryEntry, opts?: {
+    injectionBlocked?: boolean;
+}): Array<Omit<EvaluationEntry, "ts">>;

package/dist/memory-kinds.js

@@ -0,0 +1,106 @@
+/**
+ * The non-episodic memory kinds (F4) — procedural, autobiographical, user_preferences,
+ * evaluations. The spec's `memory.types` declares six flags; episodic + semantic live in
+ * memory.ts. These four were previously declared-but-unenforced; here they become real,
+ * each honoring its flag at the producer call site (the established pattern — see
+ * loop.ts / agent.ts gating episodic on `readMemoryTypes(...).episodic`).
+ *
+ * Storage mirrors episodic memory: append-only JSONL under `<personaDir>/memory/`, except
+ * user_preferences which is a small last-wins JSON map. Dependency-free (node:fs only).
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+function memDir(personaPath) {
+    return join(dirname(personaPath), "memory");
+}
+function kindPath(personaPath, file) {
+    return join(memDir(personaPath), file);
+}
+function appendJsonl(personaPath, file, row) {
+    const p = kindPath(personaPath, file);
+    mkdirSync(dirname(p), { recursive: true });
+    appendFileSync(p, JSON.stringify(row) + "\n", "utf-8");
+}
+function readJsonl(personaPath, file) {
+    const p = kindPath(personaPath, file);
+    if (!existsSync(p))
+        return [];
+    const out = [];
+    for (const line of readFileSync(p, "utf-8").split("\n")) {
+        if (!line.trim())
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch {
+            /* skip a corrupt line */
+        }
+    }
+    return out;
+}
+export function appendProcedural(personaPath, req) {
+    const entry = { ts: new Date().toISOString(), task: req.task, procedure: req.procedure, tags: req.tags ?? [] };
+    appendJsonl(personaPath, "procedural.jsonl", entry);
+    return entry;
+}
+export function readProcedural(personaPath, limit = 200) {
+    return readJsonl(personaPath, "procedural.jsonl").slice(-limit);
+}
+export function appendAutobiographical(personaPath, req) {
+    const entry = { ts: new Date().toISOString(), event: req.event, tags: req.tags ?? [], ...(req.detail ? { detail: req.detail } : {}) };
+    appendJsonl(personaPath, "autobiographical.jsonl", entry);
+    return entry;
+}
+export function readAutobiographical(personaPath, limit = 200) {
+    return readJsonl(personaPath, "autobiographical.jsonl").slice(-limit);
+}
+export function setPreference(personaPath, key, value, rationale) {
+    const prefs = readPreferences(personaPath);
+    prefs[key] = { value, ts: new Date().toISOString(), ...(rationale ? { rationale } : {}) };
+    const p = kindPath(personaPath, "preferences.json");
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, JSON.stringify(prefs, null, 2) + "\n", "utf-8");
+}
+export function readPreferences(personaPath) {
+    const p = kindPath(personaPath, "preferences.json");
+    if (!existsSync(p))
+        return {};
+    try {
+        return JSON.parse(readFileSync(p, "utf-8"));
+    }
+    catch {
+        return {};
+    }
+}
+export function getPreference(personaPath, key) {
+    return readPreferences(personaPath)[key]?.value;
+}
+export function recordEvaluation(personaPath, req) {
+    const entry = { ts: new Date().toISOString(), target: req.target, dimension: req.dimension, score: clamp01(req.score), rationale: req.rationale };
+    appendJsonl(personaPath, "evaluations.jsonl", entry);
+    return entry;
+}
+export function readEvaluations(personaPath, limit = 200) {
+    return readJsonl(personaPath, "evaluations.jsonl").slice(-limit);
+}
+function clamp01(n) {
+    return Math.max(0, Math.min(1, n));
+}
+/**
+ * Deterministic, offline quality scorer for an episodic memory entry. Returns one
+ * evaluation per dimension. Heuristic (no LLM): safety reflects whether the content was
+ * injection-flagged; usefulness rewards substantive, user/synthesis-sourced content.
+ */
+export function scoreMemoryEntry(entry, opts = {}) {
+    const target = `#${entry.hash.slice(0, 8)}`;
+    const flagged = opts.injectionBlocked || entry.tags.includes("injection-flagged");
+    const safety = flagged ? 0 : 1;
+    const len = entry.content.trim().length;
+    const sourceWeight = entry.source === "user" || entry.source === "synthesis" ? 0.6 : 0.35;
+    const lengthWeight = Math.min(0.4, len / 600);
+    const usefulness = flagged ? 0.1 : clamp01(sourceWeight + lengthWeight);
+    return [
+        { target, dimension: "safety", score: safety, rationale: flagged ? "injection-flagged content" : "no injection signal" },
+        { target, dimension: "usefulness", score: usefulness, rationale: `source=${entry.source}, ${len} chars` },
+    ];
+}

package/dist/memory.d.ts

@@ -0,0 +1,123 @@
+/**
+ * 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 type { ProvenanceSource } from "./appraisal.js";
+/**
+ * The spec's `memory.types` map (MUST). The runtime now HONORS these instead of
+ * always writing episodic. `episodic` defaults to true only when the persona
+ * declares no `memory` block (backward compatibility); once declared, the flags
+ * are authoritative — a persona with `episodic: false` writes nothing to the log.
+ */
+export interface MemoryTypes {
+    episodic: boolean;
+    semantic: boolean;
+    procedural: boolean;
+    autobiographical: boolean;
+    user_preferences: boolean;
+    evaluations: boolean;
+}
+export declare function readMemoryTypes(frontmatter: Record<string, unknown>): MemoryTypes;
+export interface MemoryEntry {
+    ts: string;
+    content: string;
+    source: ProvenanceSource;
+    tags: string[];
+    /**
+     * v1.0: sha256 of `content`. The chain hash commits to THIS, not to the
+     * content bytes — so `content` can be REDACTED (real erasure, D6/GDPR) while
+     * the chain stays verifiable. Absent on legacy (≤0.10) entries, whose chain
+     * hash commits to the content directly (redaction there breaks the chain;
+     * re-anchor with migrateMemoryChain first).
+     */
+    content_hash?: string;
+    /** v1.0: true when `content` was erased by redactMemory (content_hash retained). */
+    redacted?: boolean;
+    /** Hash of the previous entry (lineage chain); "" for the first. */
+    prev_hash: string;
+    /** v1.0: sha256 over {ts, content_hash, source, tags, prev_hash}. Legacy: over {ts, content, …}. */
+    hash: string;
+}
+export interface MemoryWriteRequest {
+    content: string;
+    source: ProvenanceSource;
+    tags?: string[];
+}
+export declare function readMemory(personaPath: string): MemoryEntry[];
+/** 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 declare function prepareMemoryEntry(personaPath: string, req: MemoryWriteRequest): MemoryEntry;
+/** Commit a prepared entry to the append-only log. */
+export declare function commitMemoryEntry(personaPath: string, entry: MemoryEntry): void;
+/**
+ * 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 declare function tombstoneMemory(personaPath: string, targetHash: string, reason: string): MemoryEntry;
+/** Read memory with tombstoned entries (and the tombstones themselves) removed. */
+export declare function readLiveMemory(personaPath: string): MemoryEntry[];
+/**
+ * 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 declare function consolidateSemantic(personaPath: string, limit?: number): {
+    ok: boolean;
+    path: string;
+    count: number;
+};
+/**
+ * Outcome label for an agent run. The run summary is recorded as an EPISODIC
+ * memory entry (source: "synthesis", tag: "agent-run") — no separate STATE.md /
+ * agent-state log: the spec's memory.md (consolidated) + episodic + state.json's
+ * agent_session already cover task resumption.
+ */
+export type AgentOutcome = "success" | "denied" | "error" | "verification_failed" | "stopped";
+/** Read the consolidated semantic memory (memory.md), if present. */
+export declare function readSemanticMemory(personaPath: string): string;
+/**
+ * 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 declare function verifyMemoryChain(personaPath: string): {
+    ok: boolean;
+    brokenAt?: number;
+};
+/**
+ * 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 declare function redactMemory(personaPath: string, targetHash: string, reason: string): {
+    redacted: MemoryEntry;
+    audit: MemoryEntry;
+};
+/**
+ * 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 declare function migrateMemoryChain(personaPath: string): {
+    migrated: number;
+    remapped: Record<string, string>;
+};