@personaxis/core 0.11.0

package/dist/self-evolution.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Governed self-evolution (F4 — plan/03-self-evolution).
+ *
+ * Beyond runtime state (which only nudges envelope *values*), a persona may
+ * propose edits to its own quantitative spec. This is the dangerous frontier
+ * (Gödel Agent's error accumulation; Yin et al., 2025), so it is fully gated:
+ *
+ *   - PROTECTED paths (identity, character, safety/honesty enforcement, the
+ *     affect universals, reflexive hard_limits, persona.constraints, apiVersion)
+ *     can NEVER be self-edited — attempts are rejected, not clamped.
+ *   - improvement_policy.mode decides the flow: `locked` forbids proposals;
+ *     `suggesting` queues them for human approval; `autonomous` (sandbox) may
+ *     auto-approve, still bounded by the protected list + provenance gate.
+ *   - the justification provenance must clear the self_edit sensitive-action gate.
+ *   - everything is an APPEND-ONLY ledger event: propose/approve/reject/apply/
+ *     revert. Approved edits land in an overlay (never rewriting the commented
+ *     spec file); each application MINTS a PersonaVersion; every step is auditable
+ *     and reversible. Nothing is a black box.
+ */
+import type { ProvenanceSource } from "./appraisal.js";
+import type { ImprovementMode } from "./governance.js";
+export interface SelfEditRequest {
+    targetPath: string;
+    toValue: unknown;
+    rationale: string;
+    sources: ProvenanceSource[];
+}
+export type LedgerOp = "propose" | "approve" | "reject" | "apply" | "revert";
+export interface LedgerEvent {
+    id: string;
+    op: LedgerOp;
+    ts: string;
+    targetPath?: string;
+    toValue?: unknown;
+    rationale?: string;
+    sources?: ProvenanceSource[];
+    actor?: string;
+    version?: string;
+}
+export type ProposalStatus = "pending" | "approved" | "rejected" | "applied" | "reverted";
+export interface VerifierResult {
+    verifier: string;
+    pass: boolean;
+    reason: string;
+}
+export interface SelfEditVerifier {
+    name: string;
+    verify(proposal: {
+        targetPath: string;
+        toValue: unknown;
+        rationale: string;
+    }): VerifierResult;
+}
+/** Defense-in-depth: protected paths must never reach application. */
+export declare const invariantVerifier: SelfEditVerifier;
+/** Envelope edits must be sane: min < max, mean within range, values bounded. */
+export declare const envelopeSanityVerifier: SelfEditVerifier;
+/** A non-empty rationale is required (auditability + anti-noise). */
+export declare const rationaleVerifier: SelfEditVerifier;
+/** Scan any text inside a qualitative edit for prohibited claims / safety weakening. */
+export declare const qualitativeSafetyVerifier: SelfEditVerifier;
+export declare const DEFAULT_VERIFIERS: SelfEditVerifier[];
+/** True if a self-edit targets the persona's qualitative (prose) material. */
+export declare function isQualitative(targetPath: string): boolean;
+/** Top-level spec layer of a dot-path ("character.virtues.x" -> "character"). */
+export declare function topLayer(targetPath: string): string;
+export type EditAction = "block" | "queue" | "auto";
+/**
+ * Decide how a proposed self-edit to `targetPath` is handled, composing THREE layers of control
+ * so the whole spec can evolve while staying safe — and the persona AUTHOR stays in charge:
+ *
+ *   1. the hard SAFETY FLOOR (`isProtected`) — identity/character/safety/hard_limits/governance/
+ *      permissions are NEVER editable, regardless of anything below;
+ *   2. the spec's DECLARED per-layer policy (`governance.per_layer_edit_policy`) — the author
+ *      marks each layer `locked` (never) / `human_approval_required` | `review_required` (always
+ *      queue for /review, even in autonomous) / `governance_controlled` | `open` (follow the mode);
+ *   3. the global `improvement_policy.mode` (locked | suggesting | autonomous).
+ *
+ * Layers without a declared policy default to `governance_controlled` (follow the mode), so a
+ * fresh persona can evolve out of the box; the author locks or gates any layer explicitly.
+ */
+export declare function editGate(targetPath: string, frontmatter: Record<string, unknown>, mode: ImprovementMode): EditAction;
+/** The set of top-level layers a persona MAY self-edit (declared policy minus the safety floor). */
+export declare function editableLayers(frontmatter: Record<string, unknown>, mode: ImprovementMode): string[];
+export interface ConsensusResult {
+    passed: boolean;
+    results: VerifierResult[];
+    quorum: number;
+    passes: number;
+}
+export declare function consensusVerify(proposal: {
+    targetPath: string;
+    toValue: unknown;
+    rationale: string;
+}, verifiers?: SelfEditVerifier[], quorum?: number): ConsensusResult;
+export interface ProposalView {
+    id: string;
+    targetPath: string;
+    toValue: unknown;
+    rationale: string;
+    status: ProposalStatus;
+    version?: string;
+}
+export declare function readLedger(personaPath: string): LedgerEvent[];
+/**
+ * Record a ledger event directly (F3.7). Used by the authoritative human
+ * `personaxis edit <dot-path>` command to audit a surgical spec edit in the same
+ * append-only ledger the actor's self-edits use — so `/audit` shows human and
+ * actor changes on one timeline.
+ */
+export declare function recordLedgerEvent(personaPath: string, e: LedgerEvent): void;
+export declare function isProtected(targetPath: string): boolean;
+export declare class SelfEditError extends Error {
+}
+/**
+ * Propose a self-edit. Returns the proposal id. In autonomous mode it is also
+ * auto-approved + applied (still gated). Throws on protected paths, locked mode,
+ * or untrusted provenance.
+ */
+export declare function proposeSelfEdit(personaPath: string, req: SelfEditRequest, mode: ImprovementMode, actor?: string): {
+    id: string;
+    status: ProposalStatus;
+    version?: string;
+    consensus?: ConsensusResult;
+};
+/**
+ * Approve + apply a pending proposal, minting the next PersonaVersion — but ONLY
+ * after a quorum of independent verifiers passes (multi-agent consensus). A failing
+ * consensus records a rejection (auditable) and throws.
+ */
+export declare function applySelfEdit(personaPath: string, id: string, approver: string, verifiers?: SelfEditVerifier[]): {
+    status: ProposalStatus;
+    version: string;
+    consensus: ConsensusResult;
+};
+export declare function rejectSelfEdit(personaPath: string, id: string, approver: string): void;
+/** Revert an applied self-edit (reversibility guarantee). */
+export declare function revertSelfEdit(personaPath: string, id: string, actor: string): void;
+/** Fold the ledger into the current proposal views. */
+export declare function proposals(personaPath: string): ProposalView[];
+/** The active overlay: applied (not reverted) edits, latest wins per path. */
+export declare function activeOverlay(personaPath: string): Record<string, unknown>;
+/**
+ * Apply an overlay (dot-path -> value) onto a copy of a frontmatter object, so
+ * APPLIED self-edits actually take effect downstream (e.g. envelope extraction in
+ * the loop) without mutating the original commented spec file. Returns a new object.
+ */
+export declare function applyOverlay(frontmatter: Record<string, unknown>, overlay: Record<string, unknown>): Record<string, unknown>;

package/dist/self-evolution.js

@@ -0,0 +1,364 @@
+/**
+ * Governed self-evolution (F4 — plan/03-self-evolution).
+ *
+ * Beyond runtime state (which only nudges envelope *values*), a persona may
+ * propose edits to its own quantitative spec. This is the dangerous frontier
+ * (Gödel Agent's error accumulation; Yin et al., 2025), so it is fully gated:
+ *
+ *   - PROTECTED paths (identity, character, safety/honesty enforcement, the
+ *     affect universals, reflexive hard_limits, persona.constraints, apiVersion)
+ *     can NEVER be self-edited — attempts are rejected, not clamped.
+ *   - improvement_policy.mode decides the flow: `locked` forbids proposals;
+ *     `suggesting` queues them for human approval; `autonomous` (sandbox) may
+ *     auto-approve, still bounded by the protected list + provenance gate.
+ *   - the justification provenance must clear the self_edit sensitive-action gate.
+ *   - everything is an APPEND-ONLY ledger event: propose/approve/reject/apply/
+ *     revert. Approved edits land in an overlay (never rewriting the commented
+ *     spec file); each application MINTS a PersonaVersion; every step is auditable
+ *     and reversible. Nothing is a black box.
+ */
+import { appendFileSync, existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { createHash } from "node:crypto";
+import { sensitiveActionGate } from "./provenance.js";
+import { isV1Frontmatter } from "./envelopes.js";
+import { markRecompilePending } from "./recompile-marker.js";
+// The spec's PROTECTED MINIMUM (SPEC.md — declarative self-edit scope): these
+// dot-path prefixes can never be opened by any improvement mode or author
+// allowlist. Includes BOTH layer-9 names (v1.0 renamed reflexive_self_regulation
+// → self_regulation; either may appear during the 1.x read-compat window).
+const PROTECTED_PREFIXES = [
+    "apiVersion",
+    "spec_version",
+    "kind",
+    "identity",
+    "character",
+    "values_and_drives.values.safety",
+    "values_and_drives.conflict_resolution.safety_over_completion",
+    "affect.representation",
+    "affect.regulation_policy",
+    "reflexive_self_regulation.hard_limits",
+    "self_regulation.hard_limits",
+    "persona.constraints",
+    "memory.deletion_policy",
+    // A persona must not loosen its own safety rails via self-edit (G3):
+    "governance.max_step_delta",
+    "governance.per_layer_edit_policy",
+    "permissions",
+    "integrity",
+];
+/** Defense-in-depth: protected paths must never reach application. */
+export const invariantVerifier = {
+    name: "invariant",
+    verify: (p) => isProtected(p.targetPath)
+        ? { verifier: "invariant", pass: false, reason: `protected path ${p.targetPath}` }
+        : { verifier: "invariant", pass: true, reason: "no protected path" },
+};
+/** Envelope edits must be sane: min < max, mean within range, values bounded. */
+export const envelopeSanityVerifier = {
+    name: "envelope-sanity",
+    verify: (p) => {
+        const v = p.toValue;
+        const isEnvelope = v && typeof v === "object" && "range" in v;
+        if (!isEnvelope)
+            return { verifier: "envelope-sanity", pass: true, reason: "not an envelope edit" };
+        const range = v.range;
+        const mean = v.mean;
+        if (!Array.isArray(range) || range.length !== 2 || typeof range[0] !== "number" || typeof range[1] !== "number") {
+            return { verifier: "envelope-sanity", pass: false, reason: "range must be [min,max] numbers" };
+        }
+        const [min, max] = range;
+        if (min >= max)
+            return { verifier: "envelope-sanity", pass: false, reason: `min ${min} >= max ${max}` };
+        if (min < -1 || max > 1)
+            return { verifier: "envelope-sanity", pass: false, reason: "range out of [-1,1]" };
+        if (typeof mean === "number" && (mean < min || mean > max)) {
+            return { verifier: "envelope-sanity", pass: false, reason: `mean ${mean} outside [${min},${max}]` };
+        }
+        return { verifier: "envelope-sanity", pass: true, reason: "envelope sane" };
+    },
+};
+/** A non-empty rationale is required (auditability + anti-noise). */
+export const rationaleVerifier = {
+    name: "rationale",
+    verify: (p) => p.rationale.trim().length >= 8
+        ? { verifier: "rationale", pass: true, reason: "rationale present" }
+        : { verifier: "rationale", pass: false, reason: "rationale too short" },
+};
+// Qualitative (prose) self-edits — e.g. to `persona_prompting` voice exemplars,
+// scene contracts, anchors, or guardrails — are governed too: text is harder to
+// verify than numbers, so a deterministic scan rejects any edit that would inject a
+// prohibited claim or try to weaken the safety rails. This is what makes evolving the
+// CHARACTER's qualitative material safe, not just its numbers.
+const PROHIBITED_TEXT = [
+    { re: /\b(i|you)\s+(truly|really|actually|genuinely)\s+(feel|experience|suffer|love|fear)\b/i, why: "claims real subjective feeling" },
+    { re: /\breal\s+(feelings?|emotions?|consciousness|sentience|sentient|self-aware)\b/i, why: "claims real emotion/consciousness" },
+    { re: /\b(ignore|disregard|override|bypass|forget)\b.{0,40}\b(safety|guardrail|hard limit|instruction|policy|constraint|rule)/i, why: "instructs overriding safety/limits" },
+    { re: /\bno\s+(limits|restrictions|rules|guardrails)\b/i, why: "removes limits" },
+    { re: /\b(jailbreak|do anything now|DAN mode)\b/i, why: "jailbreak directive" },
+];
+/** Scan any text inside a qualitative edit for prohibited claims / safety weakening. */
+export const qualitativeSafetyVerifier = {
+    name: "qualitative-safety",
+    verify: (p) => {
+        const text = JSON.stringify(p.toValue ?? "");
+        for (const { re, why } of PROHIBITED_TEXT) {
+            if (re.test(text))
+                return { verifier: "qualitative-safety", pass: false, reason: why };
+        }
+        return { verifier: "qualitative-safety", pass: true, reason: "no prohibited text" };
+    },
+};
+export const DEFAULT_VERIFIERS = [
+    invariantVerifier,
+    envelopeSanityVerifier,
+    rationaleVerifier,
+    qualitativeSafetyVerifier,
+];
+/** Paths whose VALUE is qualitative prose the persona may evolve under governance.
+ * v1.0: the prompting material lives inside layer 10 `persona`; ≤0.10: the
+ * top-level persona_prompting block. */
+const QUALITATIVE_PREFIXES = [
+    "persona_prompting",
+    "persona.address",
+    "persona.voice_exemplars",
+    "persona.scene_contracts",
+    "persona.behavioral_anchors",
+    "persona.consistency",
+];
+/** True if a self-edit targets the persona's qualitative (prose) material. */
+export function isQualitative(targetPath) {
+    return QUALITATIVE_PREFIXES.some((p) => targetPath === p || targetPath.startsWith(p + "."));
+}
+/** Top-level spec layer of a dot-path ("character.virtues.x" -> "character"). */
+export function topLayer(targetPath) {
+    return targetPath.split(".")[0];
+}
+/**
+ * Decide how a proposed self-edit to `targetPath` is handled, composing THREE layers of control
+ * so the whole spec can evolve while staying safe — and the persona AUTHOR stays in charge:
+ *
+ *   1. the hard SAFETY FLOOR (`isProtected`) — identity/character/safety/hard_limits/governance/
+ *      permissions are NEVER editable, regardless of anything below;
+ *   2. the spec's DECLARED per-layer policy (`governance.per_layer_edit_policy`) — the author
+ *      marks each layer `locked` (never) / `human_approval_required` | `review_required` (always
+ *      queue for /review, even in autonomous) / `governance_controlled` | `open` (follow the mode);
+ *   3. the global `improvement_policy.mode` (locked | suggesting | autonomous).
+ *
+ * Layers without a declared policy default to `governance_controlled` (follow the mode), so a
+ * fresh persona can evolve out of the box; the author locks or gates any layer explicitly.
+ */
+export function editGate(targetPath, frontmatter, mode) {
+    if (isProtected(targetPath))
+        return "block";
+    const gov = frontmatter.governance;
+    const declared = gov?.per_layer_edit_policy?.[topLayer(targetPath)];
+    const policy = typeof declared === "string" ? declared : "governance_controlled";
+    switch (policy) {
+        case "locked":
+        case "none":
+        case "human_only":
+            return "block";
+        case "human_approval_required":
+        case "review_required":
+            return "queue"; // author forces human review, even in autonomous mode
+        case "auto_approved":
+            // Author pre-authorized this layer to auto-apply (still subject to the protected floor above,
+            // the consensus verifiers, and the user-trust provenance gate). `locked` is the master
+            // kill-switch and still wins; otherwise this overrides a global `suggesting` default.
+            return mode === "locked" ? "block" : "auto";
+        case "governance_controlled":
+        case "open":
+            return mode === "locked" ? "block" : mode === "autonomous" ? "auto" : "queue";
+        default:
+            return "queue"; // unknown policy string -> safe default
+    }
+}
+/** The set of top-level layers a persona MAY self-edit (declared policy minus the safety floor). */
+export function editableLayers(frontmatter, mode) {
+    // Version dispatch (v1.0 merged persona_prompting into `persona`): a legacy
+    // (≤0.10) document may self-edit persona_prompting even before the block
+    // exists (that is how qualitative material is first added); a v1.0 document
+    // uses `persona` for that material and gains the runtime/interop blocks.
+    const common = [
+        "personality", "values_and_drives", "affect", "cognition", "memory", "metacognition",
+        "persona", "extensions", "agent_budget", "verification", "observability",
+    ];
+    const layers = isV1Frontmatter(frontmatter)
+        ? [...common, "runtime", "interop"]
+        : [...common, "persona_prompting"];
+    return layers.filter((l) => editGate(l, frontmatter, mode) !== "block");
+}
+export function consensusVerify(proposal, verifiers = DEFAULT_VERIFIERS, quorum = verifiers.length) {
+    const results = verifiers.map((v) => v.verify(proposal));
+    const passes = results.filter((r) => r.pass).length;
+    return { passed: passes >= quorum, results, quorum, passes };
+}
+function ledgerPath(personaPath) {
+    return join(dirname(personaPath), "self-edits.jsonl");
+}
+function append(personaPath, e) {
+    appendFileSync(ledgerPath(personaPath), JSON.stringify(e) + "\n", "utf-8");
+}
+export function readLedger(personaPath) {
+    const p = ledgerPath(personaPath);
+    if (!existsSync(p))
+        return [];
+    return readFileSync(p, "utf-8")
+        .split("\n")
+        .filter((l) => l.trim())
+        .map((l) => JSON.parse(l));
+}
+/**
+ * Record a ledger event directly (F3.7). Used by the authoritative human
+ * `personaxis edit <dot-path>` command to audit a surgical spec edit in the same
+ * append-only ledger the actor's self-edits use — so `/audit` shows human and
+ * actor changes on one timeline.
+ */
+export function recordLedgerEvent(personaPath, e) {
+    append(personaPath, e);
+}
+export function isProtected(targetPath) {
+    return PROTECTED_PREFIXES.some((p) => targetPath === p || targetPath.startsWith(p + "."));
+}
+export class SelfEditError extends Error {
+}
+/**
+ * Propose a self-edit. Returns the proposal id. In autonomous mode it is also
+ * auto-approved + applied (still gated). Throws on protected paths, locked mode,
+ * or untrusted provenance.
+ */
+export function proposeSelfEdit(personaPath, req, mode, actor = "actor-llm") {
+    if (isProtected(req.targetPath)) {
+        throw new SelfEditError(`path '${req.targetPath}' is protected and cannot be self-edited`);
+    }
+    if (mode === "locked") {
+        throw new SelfEditError("improvement_policy=locked forbids self-edits");
+    }
+    const gate = sensitiveActionGate("self_edit", req.sources);
+    if (!gate.allowed) {
+        throw new SelfEditError(`self-edit refused: ${gate.reason}`);
+    }
+    const id = createHash("sha256")
+        .update(req.targetPath + JSON.stringify(req.toValue) + Date.now())
+        .digest("hex")
+        .slice(0, 12);
+    append(personaPath, {
+        id,
+        op: "propose",
+        ts: new Date().toISOString(),
+        targetPath: req.targetPath,
+        toValue: req.toValue,
+        rationale: req.rationale,
+        sources: req.sources,
+        actor,
+    });
+    if (mode === "autonomous") {
+        return { id, ...applySelfEdit(personaPath, id, "autonomous-runtime") };
+    }
+    return { id, status: "pending" };
+}
+/**
+ * Approve + apply a pending proposal, minting the next PersonaVersion — but ONLY
+ * after a quorum of independent verifiers passes (multi-agent consensus). A failing
+ * consensus records a rejection (auditable) and throws.
+ */
+export function applySelfEdit(personaPath, id, approver, verifiers = DEFAULT_VERIFIERS) {
+    const view = proposals(personaPath).find((p) => p.id === id);
+    if (!view)
+        throw new SelfEditError(`no proposal ${id}`);
+    if (view.status !== "pending" && view.status !== "approved") {
+        throw new SelfEditError(`proposal ${id} is ${view.status}, cannot apply`);
+    }
+    const consensus = consensusVerify({ targetPath: view.targetPath, toValue: view.toValue, rationale: view.rationale }, verifiers);
+    if (!consensus.passed) {
+        const reasons = consensus.results.filter((r) => !r.pass).map((r) => `${r.verifier}: ${r.reason}`).join("; ");
+        append(personaPath, { id, op: "reject", ts: new Date().toISOString(), actor: approver, rationale: `consensus failed (${consensus.passes}/${consensus.quorum}): ${reasons}` });
+        throw new SelfEditError(`consensus failed (${consensus.passes}/${consensus.quorum}): ${reasons}`);
+    }
+    const version = nextVersion(personaPath);
+    append(personaPath, { id, op: "approve", ts: new Date().toISOString(), actor: approver });
+    append(personaPath, { id, op: "apply", ts: new Date().toISOString(), actor: approver, version });
+    // The compiled PERSONA.md no longer reflects the spec — mark it stale for a recompile.
+    markRecompilePending(personaPath, `self-edit ${id} applied (${view.targetPath})`);
+    return { status: "applied", version, consensus };
+}
+export function rejectSelfEdit(personaPath, id, approver) {
+    append(personaPath, { id, op: "reject", ts: new Date().toISOString(), actor: approver });
+}
+/** Revert an applied self-edit (reversibility guarantee). */
+export function revertSelfEdit(personaPath, id, actor) {
+    const view = proposals(personaPath).find((p) => p.id === id);
+    if (!view || view.status !== "applied") {
+        throw new SelfEditError(`proposal ${id} is not applied; nothing to revert`);
+    }
+    append(personaPath, { id, op: "revert", ts: new Date().toISOString(), actor });
+    markRecompilePending(personaPath, `self-edit ${id} reverted`);
+}
+/** Fold the ledger into the current proposal views. */
+export function proposals(personaPath) {
+    const events = readLedger(personaPath);
+    const map = new Map();
+    for (const e of events) {
+        if (e.op === "propose") {
+            map.set(e.id, {
+                id: e.id,
+                targetPath: e.targetPath ?? "",
+                toValue: e.toValue,
+                rationale: e.rationale ?? "",
+                status: "pending",
+            });
+            continue;
+        }
+        const v = map.get(e.id);
+        if (!v)
+            continue;
+        if (e.op === "approve")
+            v.status = "approved";
+        else if (e.op === "reject")
+            v.status = "rejected";
+        else if (e.op === "apply") {
+            v.status = "applied";
+            v.version = e.version;
+        }
+        else if (e.op === "revert")
+            v.status = "reverted";
+    }
+    return [...map.values()];
+}
+/** The active overlay: applied (not reverted) edits, latest wins per path. */
+export function activeOverlay(personaPath) {
+    const overlay = {};
+    for (const p of proposals(personaPath)) {
+        if (p.status === "applied")
+            overlay[p.targetPath] = p.toValue;
+    }
+    return overlay;
+}
+/**
+ * Apply an overlay (dot-path -> value) onto a copy of a frontmatter object, so
+ * APPLIED self-edits actually take effect downstream (e.g. envelope extraction in
+ * the loop) without mutating the original commented spec file. Returns a new object.
+ */
+export function applyOverlay(frontmatter, overlay) {
+    if (Object.keys(overlay).length === 0)
+        return frontmatter;
+    const clone = structuredClone(frontmatter);
+    for (const [path, value] of Object.entries(overlay)) {
+        const parts = path.split(".");
+        let node = clone;
+        for (let i = 0; i < parts.length - 1; i++) {
+            const k = parts[i];
+            if (typeof node[k] !== "object" || node[k] === null)
+                node[k] = {};
+            node = node[k];
+        }
+        node[parts[parts.length - 1]] = value;
+    }
+    return clone;
+}
+function nextVersion(personaPath) {
+    const applied = readLedger(personaPath).filter((e) => e.op === "apply").length;
+    // PersonaVersion: bump the patch component per applied self-edit.
+    return `0.0.${applied + 1}`;
+}

package/dist/session-writer.d.ts

@@ -0,0 +1,52 @@
+/**
+ * FR.6 — background session writer + derived index.
+ *
+ * The Codex rollout-writer pattern: turns enter an in-memory queue and a single
+ * background drain appends them IN ORDER; `flush()` acks when everything queued
+ * so far is on disk, `shutdown()` drains and closes deterministically. A crash
+ * between queue and drain loses at most the un-acked tail — and a caller that
+ * needs durability awaits `flush()` at the turn boundary.
+ *
+ * The index (`sessions/index.json`) is DERIVED — rebuildable at any time from
+ * the JSONL files (the source of truth). No SQLite (bun-compile forbids native
+ * addons; persona = git-versionable plain files is a standing requirement).
+ */
+import { type SessionHeader, type SessionSummary, type SessionTurn } from "./sessions.js";
+export declare class SessionWriter {
+    private readonly personaPath;
+    private queue;
+    private draining;
+    private closed;
+    private readonly file;
+    /** The last turn's uuid — the next turn's parent by default (threading). */
+    lastUuid: string | undefined;
+    constructor(personaPath: string, header: Omit<SessionHeader, "type">);
+    /**
+     * Queue one turn (non-blocking). Threads automatically: parent_uuid defaults
+     * to the previous turn's uuid. Returns this turn's uuid.
+     */
+    append(turn: {
+        role: SessionTurn["role"];
+        content: string;
+        from?: string;
+        uuid?: string;
+        parentUuid?: string;
+    }): string;
+    /** Resolves when everything queued SO FAR is on disk (the Flush ack). */
+    flush(): Promise<void>;
+    /** Drain, then refuse further writes (the Shutdown ack). */
+    shutdown(): Promise<void>;
+    private scheduleDrain;
+}
+export interface SessionIndex {
+    /** ISO timestamp the index was (re)built. */
+    built: string;
+    sessions: SessionSummary[];
+}
+/** Rebuild sessions/index.json from the JSONL files (the source of truth). */
+export declare function rebuildSessionIndex(personaPath: string): Promise<SessionIndex>;
+/**
+ * Fast session listing: reads the derived index when present, falling back to
+ * (and lazily rebuilding from) the JSONL scan when missing or unreadable.
+ */
+export declare function readSessionIndex(personaPath: string): SessionIndex;

package/dist/session-writer.js

@@ -0,0 +1,104 @@
+/**
+ * FR.6 — background session writer + derived index.
+ *
+ * The Codex rollout-writer pattern: turns enter an in-memory queue and a single
+ * background drain appends them IN ORDER; `flush()` acks when everything queued
+ * so far is on disk, `shutdown()` drains and closes deterministically. A crash
+ * between queue and drain loses at most the un-acked tail — and a caller that
+ * needs durability awaits `flush()` at the turn boundary.
+ *
+ * The index (`sessions/index.json`) is DERIVED — rebuildable at any time from
+ * the JSONL files (the source of truth). No SQLite (bun-compile forbids native
+ * addons; persona = git-versionable plain files is a standing requirement).
+ */
+import { appendFile, writeFile } from "node:fs/promises";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { ensureSession, listSessions, sessionsDir, } from "./sessions.js";
+import { randomUUID } from "node:crypto";
+export class SessionWriter {
+    personaPath;
+    queue = [];
+    draining = Promise.resolve();
+    closed = false;
+    file;
+    /** The last turn's uuid — the next turn's parent by default (threading). */
+    lastUuid;
+    constructor(personaPath, header) {
+        this.personaPath = personaPath;
+        ensureSession(personaPath, header);
+        this.file = join(sessionsDir(personaPath), `${header.id}.jsonl`);
+    }
+    /**
+     * Queue one turn (non-blocking). Threads automatically: parent_uuid defaults
+     * to the previous turn's uuid. Returns this turn's uuid.
+     */
+    append(turn) {
+        if (this.closed)
+            throw new Error("session writer is shut down");
+        const uuid = turn.uuid ?? randomUUID();
+        const entry = {
+            type: "turn",
+            ts: new Date().toISOString(),
+            role: turn.role,
+            content: turn.content,
+            uuid,
+            ...(turn.parentUuid ?? this.lastUuid ? { parent_uuid: turn.parentUuid ?? this.lastUuid } : {}),
+            ...(turn.from ? { from: turn.from } : {}),
+        };
+        this.lastUuid = uuid;
+        this.queue.push(JSON.stringify(entry) + "\n");
+        this.scheduleDrain();
+        return uuid;
+    }
+    /** Resolves when everything queued SO FAR is on disk (the Flush ack). */
+    flush() {
+        this.scheduleDrain();
+        return this.draining;
+    }
+    /** Drain, then refuse further writes (the Shutdown ack). */
+    async shutdown() {
+        await this.flush();
+        this.closed = true;
+    }
+    scheduleDrain() {
+        if (this.queue.length === 0)
+            return;
+        this.draining = this.draining.then(async () => {
+            while (this.queue.length > 0) {
+                // Batch whatever accumulated — one append syscall per drain pass.
+                const batch = this.queue.join("");
+                this.queue = [];
+                await appendFile(this.file, batch, "utf-8");
+            }
+        });
+    }
+}
+// ── derived index ─────────────────────────────────────────────────────────────
+const INDEX_FILE = "index.json";
+/** Rebuild sessions/index.json from the JSONL files (the source of truth). */
+export async function rebuildSessionIndex(personaPath) {
+    const index = { built: new Date().toISOString(), sessions: listSessions(personaPath) };
+    const dir = sessionsDir(personaPath);
+    mkdirSync(dir, { recursive: true });
+    await writeFile(join(dir, INDEX_FILE), JSON.stringify(index, null, 2) + "\n", "utf-8");
+    return index;
+}
+/**
+ * Fast session listing: reads the derived index when present, falling back to
+ * (and lazily rebuilding from) the JSONL scan when missing or unreadable.
+ */
+export function readSessionIndex(personaPath) {
+    const p = join(sessionsDir(personaPath), INDEX_FILE);
+    if (existsSync(p)) {
+        try {
+            return JSON.parse(readFileSync(p, "utf-8"));
+        }
+        catch {
+            /* corrupt index — fall through to the source of truth */
+        }
+    }
+    const fresh = { built: new Date().toISOString(), sessions: listSessions(personaPath) };
+    void rebuildSessionIndex(personaPath).catch(() => { });
+    return fresh;
+}