hippo-memory 1.60.0 → 1.61.0

package/dist/store/handoffs.js

@@ -0,0 +1,184 @@
+import { closeHippoDb, openHippoDb } from '../db.js';
+import { rowToSessionHandoff, isHandoffOutcome, } from '../handoff.js';
+import { RECALL_DEFAULT_DENY_SCOPES } from '../recall-scope.js';
+import { assertTenantId } from '../tenant.js';
+import { openStore } from './open.js';
+import { loadActiveTaskSnapshot } from './sessions.js';
+// W1: the nine-column SELECT was cloned four times (plan rule 8); one
+// definition so a sixth caller can't drift from the other five.
+/** Column list shared by every session_handoffs SELECT; store-cards.ts reuses it for the card handoff lookup. */
+export const HANDOFF_COLUMNS = 'id, session_id, repo_root, task_id, summary, next_action, artifacts_json, scope, created_at, constraints_json, evidence_json, outcome, target_runtime, card_id';
+/**
+ * Save a session handoff record. Returns the persisted handoff.
+ */
+export function saveSessionHandoff(hippoRoot, tenantId, handoff) {
+    assertTenantId('saveSessionHandoff', tenantId);
+    const db = openStore(hippoRoot);
+    const now = new Date().toISOString();
+    // v1.2: scope is wired through. Read-side default-deny in api.recall +
+    // cmdRecall continuity excludes slack:private:* and 'unknown:legacy'.
+    try {
+        const result = db.prepare(`
+      INSERT INTO session_handoffs(session_id, repo_root, task_id, summary, next_action, artifacts_json, scope, tenant_id, created_at, constraints_json, evidence_json, outcome, target_runtime, card_id)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(handoff.sessionId, handoff.repoRoot ?? null, handoff.taskId ?? null, handoff.summary, handoff.nextAction ?? null, JSON.stringify(handoff.artifacts ?? []), handoff.scope ?? null, tenantId, now, JSON.stringify(handoff.constraints ?? []), handoff.evidence ? JSON.stringify(handoff.evidence) : null, handoff.outcome ?? null, handoff.targetRuntime ?? null, handoff.cardId ?? null);
+        const id = Number(result.lastInsertRowid ?? 0);
+        // SAFETY: row's shape matches HANDOFF_COLUMNS.
+        const row = db.prepare(`
+      SELECT ${HANDOFF_COLUMNS}
+      FROM session_handoffs
+      WHERE id = ?
+    `).get(id);
+        if (!row) {
+            throw new Error('Failed to reload saved session handoff');
+        }
+        return rowToSessionHandoff(row);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/** Load the most recent handoff, optionally filtered by session ID. */
+export function loadLatestHandoff(hippoRoot, tenantId, sessionId, opts = {}) {
+    assertTenantId('loadLatestHandoff', tenantId);
+    const db = openStore(hippoRoot);
+    try {
+        const conditions = ['tenant_id = ?'];
+        const params = [tenantId];
+        if (sessionId) {
+            conditions.push('session_id = ?');
+            params.push(sessionId);
+        }
+        if (opts.excludeSessionId) {
+            conditions.push('session_id != ?');
+            params.push(opts.excludeSessionId);
+        }
+        if (opts.unfinishedOnly) {
+            // codex P2: restrict to each session's newest revision first — stampHandoffOutcome
+            // only stamps the newest row, so an older null-outcome revision must not resurrect.
+            conditions.push(`id IN (SELECT MAX(id) FROM session_handoffs WHERE tenant_id = ? GROUP BY session_id)`);
+            params.push(tenantId);
+            conditions.push(`(outcome IS NULL OR outcome IN ('partial','failure'))`);
+        }
+        if (opts.maxAgeMs != null) {
+            conditions.push('created_at >= ?');
+            params.push(new Date(Date.now() - opts.maxAgeMs).toISOString());
+        }
+        if (opts.scopeFilter === 'default-deny') {
+            // codex P2: admit scope before LIMIT 1, else a newer denied row hides an older eligible one.
+            const placeholders = RECALL_DEFAULT_DENY_SCOPES.map(() => '?').join(', ');
+            conditions.push(`(scope IS NULL OR (scope NOT IN (${placeholders}) AND scope NOT LIKE '%:private:%'))`);
+            params.push(...RECALL_DEFAULT_DENY_SCOPES);
+        }
+        // SAFETY: row's shape matches HANDOFF_COLUMNS.
+        const row = db.prepare(`
+      SELECT ${HANDOFF_COLUMNS}
+      FROM session_handoffs
+      WHERE ${conditions.join(' AND ')}
+      ORDER BY created_at DESC, id DESC
+      LIMIT 1
+    `).get(...params);
+        return row ? rowToSessionHandoff(row) : null;
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/**
+ * Load a specific handoff by its row ID.
+ */
+export function loadHandoffById(hippoRoot, tenantId, id) {
+    assertTenantId('loadHandoffById', tenantId);
+    const db = openStore(hippoRoot);
+    try {
+        // SAFETY: row's shape matches HANDOFF_COLUMNS.
+        const row = db.prepare(`
+      SELECT ${HANDOFF_COLUMNS}
+      FROM session_handoffs
+      WHERE id = ? AND tenant_id = ?
+    `).get(id, tenantId);
+        return row ? rowToSessionHandoff(row) : null;
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/** Stamp the outcome on a session's newest handoff, only if it has none yet. Returns rows changed. */
+export function stampHandoffOutcome(hippoRoot, tenantId, sessionId, outcome) {
+    assertTenantId('stampHandoffOutcome', tenantId);
+    const db = openStore(hippoRoot);
+    try {
+        const result = db.prepare(`
+      UPDATE session_handoffs SET outcome = ?
+      WHERE tenant_id = ? AND session_id = ? AND outcome IS NULL
+        AND id = (
+          SELECT id FROM session_handoffs
+          WHERE tenant_id = ? AND session_id = ?
+          ORDER BY created_at DESC, id DESC LIMIT 1
+        )
+    `).run(outcome, tenantId, sessionId, tenantId, sessionId);
+        return Number(result.changes ?? 0);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/** Auto-write a handoff at session-end (DF1 T3) from the session's active snapshot, else from `derived`, its transcript state.
+ * @param evidence best-effort git state; outcome comes from the newest session_complete event.
+ * @returns null when neither source is the session's, a newer handoff covers the snapshot, or the session's latest handoff was not read off its transcript. */
+export function writeSessionEndHandoff(hippoRoot, tenantId, sessionId, evidence, derived = null) {
+    assertTenantId('writeSessionEndHandoff', tenantId);
+    const active = loadActiveTaskSnapshot(hippoRoot, tenantId);
+    const existing = loadLatestHandoff(hippoRoot, tenantId, sessionId);
+    let snapshot;
+    let handoffEvidence = evidence;
+    if (active && active.session_id === sessionId) {
+        // Strict '>': a same-millisecond tie must not swallow the session's only write (test 6e).
+        if (existing && existing.updatedAt > active.updated_at)
+            return null;
+        snapshot = active;
+    }
+    else {
+        // Only an earlier transcript read gives way; `hippo handoff create` and unmarked older handoffs keep winning.
+        if (!derived || (existing && existing.evidence?.derivedFrom !== 'transcript'))
+            return null;
+        snapshot = { ...derived, scope: null };
+        handoffEvidence = { ...evidence, derivedFrom: 'transcript' };
+    }
+    const db = openHippoDb(hippoRoot);
+    let outcome = null;
+    try {
+        // SAFETY: row's shape matches the single `content` column below.
+        const completeEvent = db.prepare(`
+      SELECT content FROM session_events
+      WHERE tenant_id = ? AND session_id = ? AND event_type = 'session_complete'
+      ORDER BY created_at DESC, id DESC LIMIT 1
+    `).get(tenantId, sessionId);
+        if (isHandoffOutcome(completeEvent?.content))
+            outcome = completeEvent.content;
+    }
+    finally {
+        closeHippoDb(db);
+    }
+    // codex P2: same-task refresh carries forward envelope fields nobody cleared,
+    // rather than dropping them when the snapshot rewrite has no opinion on them.
+    // codex P1: a scope mismatch must not leak private metadata into an unscoped envelope.
+    const carryForward = existing != null && existing.taskId === snapshot.task
+        && (existing.scope ?? null) === (snapshot.scope ?? null);
+    return saveSessionHandoff(hippoRoot, tenantId, {
+        version: 1,
+        sessionId,
+        repoRoot: carryForward ? existing.repoRoot : undefined,
+        taskId: snapshot.task,
+        summary: snapshot.summary,
+        nextAction: snapshot.next_step,
+        artifacts: carryForward ? existing.artifacts : [],
+        scope: snapshot.scope,
+        evidence: handoffEvidence,
+        outcome,
+        constraints: carryForward ? existing.constraints : undefined,
+        targetRuntime: carryForward ? existing.targetRuntime : undefined,
+        cardId: carryForward ? existing.cardId : undefined,
+    });
+}
+//# sourceMappingURL=handoffs.js.map

package/dist/store/index-and-stats.d.ts

@@ -0,0 +1,52 @@
+import type { HippoIndex, LegacyStats } from './rows.js';
+/** Load the derived index from SQLite. Read-only: index.json is only ever written by `rebuildIndex`. */
+export declare function loadIndex(hippoRoot: string): HippoIndex;
+/**
+ * Persist mutable index metadata. Entry rows themselves are derived from SQLite.
+ *
+ * LC1 F1(c) structural fix: `last_retrieval_ids` and `last_trace_id` must
+ * land atomically — callers (getContext, cmdRecall) fold a freshly-written
+ * trace id into `index.last_trace_id` before calling this, relying on BOTH
+ * meta keys committing together. Wrapped in BEGIN/COMMIT so a crash or a
+ * mid-write failure can never advance one key without the other. index.json
+ * is left untouched; only `rebuildIndex` writes it.
+ */
+export declare function saveIndex(hippoRoot: string, index: HippoIndex): void;
+/**
+ * Rebuild mirrors from SQLite, importing any legacy markdown files not already present.
+ */
+export declare function rebuildIndex(hippoRoot: string): HippoIndex;
+export declare function updateStats(hippoRoot: string, delta: {
+    remembered?: number;
+    recalled?: number;
+    forgotten?: number;
+}): void;
+export declare function updateStatsUnlessBusy(hippoRoot: string, delta: Parameters<typeof updateStats>[1], committed: string): void;
+export declare function loadStats(hippoRoot: string): LegacyStats;
+export declare function appendConsolidationRun(hippoRoot: string, run: {
+    timestamp: string;
+    decayed: number;
+    merged: number;
+    removed: number;
+}): void;
+/** Rows a tenant created since the last sleep (runs are host-wide), looking back at most 24 hours. */
+export declare function countCreatedSinceLastSleep(hippoRoot: string, tenantId: string, now?: Date): number;
+/**
+ * Session decay context: provides the data needed for session-based and adaptive decay.
+ */
+export interface SessionDecayContext {
+    /** Total number of sleep (consolidation) cycles completed. */
+    sleepCount: number;
+    /** Average interval between recent sleep cycles, in days. 0 if < 2 cycles. */
+    avgSessionIntervalDays: number;
+}
+/**
+ * Load the session decay context from the store.
+ * Uses consolidation_runs timestamps to compute session intervals.
+ */
+export declare function loadSessionDecayContext(hippoRoot: string): SessionDecayContext;
+/**
+ * Increment the sleep counter. Called after each consolidation run.
+ */
+export declare function incrementSleepCount(hippoRoot: string): void;
+//# sourceMappingURL=index-and-stats.d.ts.map

package/dist/store/index-and-stats.js

@@ -0,0 +1,214 @@
+import { closeHippoDb, setMeta, isSqliteBusy, pruneConsolidationRuns, getMeta } from '../db.js';
+import { RejectedValueError } from '../rejection.js';
+import { log } from '../log.js';
+import { audit } from './audit-event.js';
+import { stampOriginProjectForImport, upsertEntryRow } from './entry-row.js';
+import { buildIndexFromDb, syncMirrorFiles, writeIndexMirror, writeStatsMirror, buildStatsFromDb } from './mirrors.js';
+import { openStore, loadLegacyEntriesFromMarkdown } from './open.js';
+/** Load the derived index from SQLite. Read-only: index.json is only ever written by `rebuildIndex`. */
+export function loadIndex(hippoRoot) {
+    const db = openStore(hippoRoot);
+    try {
+        return buildIndexFromDb(db);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/**
+ * Persist mutable index metadata. Entry rows themselves are derived from SQLite.
+ *
+ * LC1 F1(c) structural fix: `last_retrieval_ids` and `last_trace_id` must
+ * land atomically — callers (getContext, cmdRecall) fold a freshly-written
+ * trace id into `index.last_trace_id` before calling this, relying on BOTH
+ * meta keys committing together. Wrapped in BEGIN/COMMIT so a crash or a
+ * mid-write failure can never advance one key without the other. index.json
+ * is left untouched; only `rebuildIndex` writes it.
+ */
+export function saveIndex(hippoRoot, index) {
+    const db = openStore(hippoRoot);
+    try {
+        db.exec('BEGIN');
+        try {
+            setMeta(db, 'last_retrieval_ids', JSON.stringify(index.last_retrieval_ids ?? []));
+            setMeta(db, 'last_trace_id', index.last_trace_id ?? '');
+            db.exec('COMMIT');
+        }
+        catch (error) {
+            try {
+                db.exec('ROLLBACK');
+            }
+            catch { /* already rolled back; keep the original error */ }
+            throw error;
+        }
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/**
+ * Rebuild mirrors from SQLite, importing any legacy markdown files not already present.
+ */
+export function rebuildIndex(hippoRoot) {
+    const db = openStore(hippoRoot);
+    try {
+        // SAFETY: rows' shape matches the single `id` column selected above.
+        const existingIds = new Set(db.prepare(`SELECT id FROM memories`).all().map((row) => row.id));
+        const legacyEntries = loadLegacyEntriesFromMarkdown(hippoRoot).filter((entry) => !existingIds.has(entry.id));
+        if (legacyEntries.length > 0) {
+            db.exec('BEGIN');
+            try {
+                // AT1 (plan §3, round-3 redesign): same guard-with-per-row-skip as
+                // bootstrapLegacyStore — rebuildIndex is the other channel through
+                // which a stale markdown mirror could resurrect a rejected value.
+                // Refusal audit written INLINE (nothing rolls back on a skip).
+                let rejectedCount = 0;
+                for (const entry of legacyEntries) {
+                    // v39: same store-derived origin stamp as bootstrapLegacyStore.
+                    const stamped = stampOriginProjectForImport(hippoRoot, entry);
+                    try {
+                        upsertEntryRow(db, stamped);
+                    }
+                    catch (err) {
+                        if (err instanceof RejectedValueError) {
+                            rejectedCount++;
+                            audit(db, 'reject_refusal', err.entryId, { digest: err.digest, reason: err.reason }, 'cli', err.tenantId);
+                            continue;
+                        }
+                        throw err;
+                    }
+                }
+                if (rejectedCount > 0) {
+                    log.warn(`rebuildIndex: skipped ${rejectedCount} rejected value(s) found in legacy mirrors`);
+                }
+                db.exec('COMMIT');
+            }
+            catch (err) {
+                try {
+                    db.exec('ROLLBACK');
+                }
+                catch { /* ignore if no active txn */ }
+                throw err;
+            }
+        }
+        syncMirrorFiles(hippoRoot, db);
+        const index = buildIndexFromDb(db);
+        writeIndexMirror(hippoRoot, index);
+        return index;
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+export function updateStats(hippoRoot, delta) {
+    const db = openStore(hippoRoot);
+    try {
+        // One atomic statement per counter, and only for counters the caller
+        // named: the read-modify-write this replaces both lost increments to a
+        // concurrent writer and stamped stale values over the untouched two.
+        const increments = [
+            ['total_remembered', delta.remembered ?? 0],
+            ['total_recalled', delta.recalled ?? 0],
+            ['total_forgotten', delta.forgotten ?? 0],
+        ];
+        for (const [key, amount] of increments) {
+            if (amount === 0)
+                continue;
+            // Both binds are the same string: node:sqlite binds a JS number as REAL,
+            // which would store "1.0" into this TEXT column instead of "1".
+            db.prepare(`
+        INSERT INTO meta(key, value) VALUES(?, ?)
+        ON CONFLICT(key) DO UPDATE SET value = CAST(meta.value AS INTEGER) + CAST(? AS INTEGER)
+      `).run(key, String(amount), String(amount));
+        }
+        writeStatsMirror(hippoRoot, buildStatsFromDb(db));
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+export function updateStatsUnlessBusy(hippoRoot, delta, committed) {
+    try {
+        updateStats(hippoRoot, delta);
+    }
+    catch (err) {
+        if (!isSqliteBusy(err))
+            throw err;
+        log.warnThenDebug('stats-busy', `${committed}, but the store was busy, so the stats counters were not updated`);
+    }
+}
+export function loadStats(hippoRoot) {
+    const db = openStore(hippoRoot);
+    try {
+        return buildStatsFromDb(db);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+export function appendConsolidationRun(hippoRoot, run) {
+    const db = openStore(hippoRoot);
+    try {
+        db.prepare(`INSERT INTO consolidation_runs(timestamp, decayed, merged, removed) VALUES (?, ?, ?, ?)`).run(run.timestamp, run.decayed, run.merged, run.removed);
+        pruneConsolidationRuns(db, 50);
+        writeStatsMirror(hippoRoot, buildStatsFromDb(db));
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/** Rows a tenant created since the last sleep (runs are host-wide), looking back at most 24 hours. */
+export function countCreatedSinceLastSleep(hippoRoot, tenantId, now = new Date()) {
+    const db = openStore(hippoRoot);
+    try {
+        const dayAgo = new Date(now.getTime() - 86_400_000).toISOString();
+        const row = db.prepare(`SELECT COUNT(*) AS n FROM memories WHERE tenant_id = ?
+         AND created > MAX(?, COALESCE((SELECT MAX(timestamp) FROM consolidation_runs), ''))`).get(tenantId, dayAgo);
+        return row.n;
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/**
+ * Load the session decay context from the store.
+ * Uses consolidation_runs timestamps to compute session intervals.
+ */
+export function loadSessionDecayContext(hippoRoot) {
+    const db = openStore(hippoRoot);
+    try {
+        // Get recent consolidation timestamps (last 20)
+        // SAFETY: rows' shape matches the single `timestamp` column above.
+        const rows = db.prepare(`SELECT timestamp FROM consolidation_runs ORDER BY timestamp DESC, id DESC LIMIT 20`).all();
+        const sleepCount = Number(getMeta(db, 'sleep_count', '0')) || rows.length;
+        if (rows.length < 2) {
+            return { sleepCount, avgSessionIntervalDays: 0 };
+        }
+        // Compute average interval between consecutive sessions
+        const timestamps = rows.map((r) => new Date(r.timestamp).getTime()).reverse();
+        let totalInterval = 0;
+        for (let i = 1; i < timestamps.length; i++) {
+            totalInterval += timestamps[i] - timestamps[i - 1];
+        }
+        const avgMs = totalInterval / (timestamps.length - 1);
+        const avgDays = avgMs / (1000 * 60 * 60 * 24);
+        return { sleepCount, avgSessionIntervalDays: Math.max(0, avgDays) };
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+/**
+ * Increment the sleep counter. Called after each consolidation run.
+ */
+export function incrementSleepCount(hippoRoot) {
+    const db = openStore(hippoRoot);
+    try {
+        const current = Number(getMeta(db, 'sleep_count', '0')) || 0;
+        setMeta(db, 'sleep_count', String(current + 1));
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+//# sourceMappingURL=index-and-stats.js.map

package/dist/store/markdown.d.ts

@@ -0,0 +1,10 @@
+import { type MemoryEntry } from '../memory.js';
+/**
+ * Serialize a MemoryEntry to markdown with YAML frontmatter.
+ */
+export declare function serializeEntry(entry: MemoryEntry): string;
+/**
+ * Deserialize a markdown file to a MemoryEntry.
+ */
+export declare function deserializeEntry(raw: string): MemoryEntry | null;
+//# sourceMappingURL=markdown.d.ts.map

package/dist/store/markdown.js

@@ -0,0 +1,108 @@
+import { dumpFrontmatter, parseFrontmatter } from '../yaml.js';
+/**
+ * Serialize a MemoryEntry to markdown with YAML frontmatter.
+ */
+export function serializeEntry(entry) {
+    const frontmatter = {
+        id: entry.id,
+        created: entry.created,
+        last_retrieved: entry.last_retrieved,
+        retrieval_count: entry.retrieval_count,
+        strength: Math.round(entry.strength * 10000) / 10000,
+        half_life_days: entry.half_life_days,
+        layer: entry.layer,
+        tags: entry.tags,
+        emotional_valence: entry.emotional_valence,
+        schema_fit: entry.schema_fit,
+        source: entry.source,
+        outcome_score: entry.outcome_score,
+        outcome_positive: entry.outcome_positive,
+        outcome_negative: entry.outcome_negative,
+        conflicts_with: entry.conflicts_with,
+        pinned: entry.pinned,
+        confidence: entry.confidence ?? 'observed',
+        parents: entry.parents ?? [],
+        starred: entry.starred ?? false,
+        trace_outcome: entry.trace_outcome ?? null,
+        source_session_id: entry.source_session_id ?? null,
+        kind: entry.kind ?? 'distilled',
+        scope: entry.scope ?? null,
+        owner: entry.owner ?? null,
+        artifact_ref: entry.artifact_ref ?? null,
+    };
+    // Emit tenant_id only when not 'default' to keep diffs clean for the dominant
+    // single-tenant case (mirrors the plan's task 7 guidance).
+    const tenantId = entry.tenantId ?? 'default';
+    if (tenantId !== 'default') {
+        frontmatter['tenant_id'] = tenantId;
+    }
+    // v39: '' (user-global) and null (unknown, hidden by default) must both round-trip;
+    // only undefined (unstamped) is omitted, so a rebuild stamps nothing it can read.
+    if (entry.origin_project !== undefined) {
+        frontmatter['origin_project'] = entry.origin_project;
+    }
+    // Spread into a fresh object literal: dumpFrontmatter's Record<string,
+    // YamlValue> parameter needs an index signature, which a named interface
+    // reference (EntryFrontmatterFields) doesn't structurally provide even
+    // though every property's value type already matches.
+    const fm = dumpFrontmatter({ ...frontmatter });
+    return `${fm}\n\n${entry.content}\n`;
+}
+/**
+ * Deserialize a markdown file to a MemoryEntry.
+ */
+export function deserializeEntry(raw) {
+    const { data, content } = parseFrontmatter(raw);
+    if (!data['id'] || !data['layer'])
+        return null;
+    // SAFETY: every `as X` below narrows a raw YAML frontmatter field to an
+    // enum/union member of MemoryEntry; frontmatter is only ever written by
+    // serializeEntry (whose own fields are typed), so out-of-range values here
+    // would indicate hand-edited files, which this parser is not required to
+    // reject — matches the pre-existing permissive-parse behavior.
+    return {
+        id: String(data['id']),
+        created: String(data['created'] ?? new Date().toISOString()),
+        last_retrieved: String(data['last_retrieved'] ?? new Date().toISOString()),
+        retrieval_count: Number(data['retrieval_count'] ?? 0),
+        strength: Number(data['strength'] ?? 1.0),
+        half_life_days: Number(data['half_life_days'] ?? 7),
+        layer: data['layer'],
+        tags: normalizeStringArray(data['tags']),
+        emotional_valence: data['emotional_valence'] ?? 'neutral',
+        schema_fit: Number(data['schema_fit'] ?? 0.5),
+        source: String(data['source'] ?? 'cli'),
+        outcome_score: data['outcome_score'] === null || data['outcome_score'] === undefined ? null : Number(data['outcome_score']),
+        outcome_positive: Number(data['outcome_positive'] ?? 0),
+        outcome_negative: Number(data['outcome_negative'] ?? 0),
+        conflicts_with: normalizeStringArray(data['conflicts_with']),
+        pinned: Boolean(data['pinned'] ?? false),
+        confidence: data['confidence'] ?? 'observed',
+        content: content.trim(),
+        parents: normalizeStringArray(data['parents']),
+        starred: Boolean(data['starred'] ?? false),
+        trace_outcome: data['trace_outcome'] ?? null,
+        source_session_id: data['source_session_id'] === null || data['source_session_id'] === undefined
+            ? null
+            : String(data['source_session_id']),
+        valid_from: data['valid_from'] ? String(data['valid_from']) : String(data['created'] ?? new Date().toISOString()),
+        superseded_by: data['superseded_by'] === null || data['superseded_by'] === undefined
+            ? null
+            : String(data['superseded_by']),
+        extracted_from: data['extracted_from'] ?? null,
+        dag_level: Number(data['dag_level'] ?? 0),
+        dag_parent_id: data['dag_parent_id'] ?? null,
+        kind: (data['kind'] ?? 'distilled'),
+        scope: data['scope'] === null || data['scope'] === undefined ? null : String(data['scope']),
+        owner: data['owner'] === null || data['owner'] === undefined ? null : String(data['owner']),
+        artifact_ref: data['artifact_ref'] === null || data['artifact_ref'] === undefined ? null : String(data['artifact_ref']),
+        tenantId: data['tenant_id'] === null || data['tenant_id'] === undefined ? 'default' : String(data['tenant_id']),
+        origin_project: !('origin_project' in data) ? undefined : data['origin_project'] === null ? null : String(data['origin_project']),
+    };
+}
+function normalizeStringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.map((item) => String(item));
+}
+//# sourceMappingURL=markdown.js.map

package/dist/store/mirrors.d.ts

@@ -0,0 +1,49 @@
+import { Layer, type MemoryEntry } from '../memory.js';
+import { openHippoDb } from '../db.js';
+import { type TaskSnapshot, type SessionEvent, type HippoIndex, type LegacyStats } from './rows.js';
+export declare function layerDir(root: string, layer: Layer): string;
+export declare function ensureMirrorDirectories(hippoRoot: string): void;
+export declare function writeActiveTaskMirror(hippoRoot: string, tenantId: string, snapshot: TaskSnapshot): void;
+export declare function removeActiveTaskMirror(hippoRoot: string, tenantId: string): void;
+export declare function writeRecentSessionMirror(hippoRoot: string, tenantId: string, events: SessionEvent[]): void;
+export declare function writeMarkdownMirror(hippoRoot: string, entry: MemoryEntry): void;
+export declare function removeEntryMirrors(hippoRoot: string, id: string): void;
+/**
+ * AT1 mirror-purge honesty fix (docs/plans/2026-08-15-at1-rejected-value-tombstone.md):
+ * the candidate markdown mirror paths still on disk for `id`, computed the
+ * same way `removeEntryMirrors` walks them (one per layer: buffer/episodic/
+ * semantic), filtered to the ones that still `fs.existsSync`. Used to report
+ * an EXPLICIT path when a best-effort purge fails and no reaper exists to
+ * retry it — plain `removeEntryMirrors` returns void, giving no way to name
+ * which file is stuck.
+ */
+export declare function getExistingEntryMirrorPaths(hippoRoot: string, id: string): string[];
+/**
+ * AT1 fix: best-effort markdown-mirror purge shared by `reject-flow.ts`'s
+ * `rejectValue` and `resolveConflict`'s post-commit purge. Both used to log
+ * "will retry via reaper on next open" for EVERY failure, but the reaper
+ * (`cleanupArchivedMirrors`, raw-archive-mirror-cleanup.ts) only scans
+ * `raw_archive` — that message was false for a non-raw id, which has no
+ * reaper at all.
+ *
+ * Retries the unlink once synchronously (the common real-world failure is a
+ * transient lock/AV-scanner false positive, not a permanent one). On a
+ * second failure: raw ids still get the honest reaper message (true); non-raw
+ * ids get the EXPLICIT leftover file path(s) and a manual-delete instruction,
+ * since nothing will ever retry them automatically.
+ *
+ * Returns true if the mirror ended up purged (first or second attempt).
+ */
+export declare function purgeMirrorBestEffort(hippoRoot: string, id: string, isRaw: boolean, logPrefix: string): boolean;
+/** Derive the current `HippoIndex` from SQLite. Exported for `rebuildIndex`
+ *  (the only index.json writer) and the longmemeval benchmark. */
+export declare function buildIndexFromDb(db: ReturnType<typeof openHippoDb>): HippoIndex;
+export declare function buildStatsFromDb(db: ReturnType<typeof openHippoDb>): LegacyStats;
+/** Write the `index.json` mirror file for an already-derived index. Exported for
+ *  `rebuildIndex` (the only index.json writer) and the longmemeval benchmark. */
+export declare function writeIndexMirror(hippoRoot: string, index: HippoIndex): void;
+export declare function writeStatsMirror(hippoRoot: string, stats: LegacyStats): void;
+/** Mirrors are derived from SQLite and written after COMMIT, so a failed write warns instead of failing a committed change. */
+export declare function mirrorBestEffort(what: string, write: () => void): void;
+export declare function syncMirrorFiles(hippoRoot: string, db: ReturnType<typeof openHippoDb>): void;
+//# sourceMappingURL=mirrors.d.ts.map