hippo-memory 1.59.0 → 1.61.0

package/dist/api/learn.js

@@ -0,0 +1,88 @@
+// Git auto-learn: fix/revert/bug commit subjects become memories. `hippo learn`, init, sleep and MCP hippo_learn share it.
+import { ForbiddenError } from '../api-errors.js';
+import { fetchGitLog, extractLessons, partitionLessons, isGitRepo } from '../autolearn.js';
+import { loadConfig } from '../config.js';
+import { embedMemory } from '../embeddings.js';
+import { extractInvalidationTarget, invalidateMatching } from '../invalidation.js';
+import { computeSchemaFit, createMemory, Layer } from '../memory.js';
+import { extractPathTags } from '../path-context.js';
+import { RejectedValueError } from '../rejection.js';
+import { duplicateKey, longestWord, storedTextKeys } from '../same-text.js';
+import { loadTextsHoldingWords } from '../store/candidates.js';
+import { loadAllEntries } from '../store/entry-reads.js';
+import { writeEntry } from '../store/entry-writes.js';
+import { updateStats } from '../store/index-and-stats.js';
+// SHORTCUT: two profiles keep each surface's rows as they were; fold MCP onto the CLI profile once it may invalidate.
+export const CLI_LEARN = Object.freeze({ tags: Object.freeze(['error', 'git-learned']), source: 'git-learn', full: true });
+export const MCP_LEARN = Object.freeze({ tags: Object.freeze(['git-learned']), source: 'git', full: false });
+/** Learn from `repoPath`'s last `days` of commits into the caller's tenant. Host admin only. */
+export function learn(ctx, opts) {
+    // It reads the host's own git history, which belongs to the host, not to the caller's tenant.
+    if (!ctx.actor.hostAdmin)
+        throw new ForbiddenError('hippo_learn requires a host admin');
+    const none = { added: 0, skipped: 0, rejected: 0, lowInfo: 0, invalidations: [] };
+    if (!isGitRepo(opts.repoPath))
+        return { status: 'not-a-repo', ...none };
+    const gitLog = fetchGitLog(opts.repoPath, opts.days);
+    if (!gitLog.trim())
+        return { status: 'no-commits', ...none };
+    const config = loadConfig(ctx.hippoRoot);
+    const parsed = extractLessons(gitLog, config.gitLearnPatterns);
+    if (parsed.length === 0)
+        return { status: 'no-lessons', ...none };
+    // The gate filters the loop input, so a dropped lesson neither stores nor invalidates; docs/decisions git-learn-gate-placement says why.
+    const { kept, dropped } = partitionLessons(parsed);
+    return { status: 'scanned', lowInfo: dropped.length, ...writeLessons(ctx, kept, opts, config) };
+}
+function writeLessons(ctx, lessons, opts, config) {
+    const { hippoRoot, tenantId } = ctx;
+    const { profile } = opts;
+    // Schema fit needs every row; without it, only rows holding a lesson's longest word can be its copy.
+    const existing = profile.full ? loadAllEntries(hippoRoot, tenantId) : undefined;
+    const keys = storedTextKeys(existing ?? loadTextsHoldingWords(hippoRoot, tenantId, lessons.map(longestWord)));
+    const pathTags = profile.full ? extractPathTags(opts.repoPath) : [];
+    const counts = { added: 0, skipped: 0, rejected: 0, invalidations: [] };
+    for (const lesson of lessons) {
+        if (keys.has(duplicateKey(lesson))) {
+            counts.skipped++;
+            continue;
+        }
+        const target = profile.full ? extractInvalidationTarget(lesson) : null;
+        if (target) {
+            const { invalidated } = invalidateMatching(hippoRoot, target, tenantId);
+            if (invalidated > 0)
+                counts.invalidations.push({ from: target.from, count: invalidated });
+        }
+        const entry = createMemory(lesson, {
+            layer: Layer.Episodic,
+            tags: [...profile.tags],
+            source: profile.source,
+            confidence: 'observed',
+            schema_fit: existing && computeSchemaFit(lesson, [...profile.tags], existing),
+            tenantId,
+            baseHalfLifeDays: config.defaultHalfLifeDays,
+        });
+        for (const tag of pathTags)
+            if (!entry.tags.includes(tag))
+                entry.tags.push(tag);
+        // A refused lesson must not abort the rest of the git-log scan.
+        try {
+            writeEntry(hippoRoot, entry, { actor: ctx.actor.subject });
+        }
+        catch (err) {
+            if (err instanceof RejectedValueError) {
+                counts.rejected++;
+                continue;
+            }
+            throw err;
+        }
+        if (profile.full)
+            updateStats(hippoRoot, { remembered: 1 });
+        keys.add(duplicateKey(lesson));
+        if (profile.full)
+            void embedMemory(hippoRoot, entry);
+        counts.added++;
+    }
+    return counts;
+}
+//# sourceMappingURL=learn.js.map

package/dist/api/outcome.d.ts

@@ -0,0 +1,61 @@
+import type { Context } from './types.js';
+/**
+ * Apply a positive/negative outcome to a list of recently-recalled memory ids.
+ * Used by the MCP `hippo_outcome` tool and the HTTP `POST /v1/outcome` route.
+ * Tenant-scoped: ids that don't belong to ctx.tenantId are silently skipped
+ * (matches the prior MCP semantics — a stale id from another tenant doesn't
+ * crash the call). Each successful outcome emits one audit_log row with
+ * op='outcome' tagged with ctx.actor.subject.
+ *
+ * Returns `{applied, appliedIds}`. `appliedIds` is the tenant-filtered subset
+ * of input ids that actually had `applyOutcome` run on them (i.e. ids whose
+ * `readEntry(..., ctx.tenantId)` resolved). Callers that surface the id list
+ * over a multi-tenant boundary (HTTP /v1/outcome last-recall path, Python SDK)
+ * MUST return `appliedIds` instead of the raw input list — otherwise the
+ * non-applied (cross-tenant) ids leak to the caller. Added in v1.11.4 to
+ * close that disclosure path on POST /v1/outcome.
+ *
+ * `opts.traceId` (LC1, docs/plans/2026-08-02-lc1-recall-trace-persistence.md):
+ * OPTIONAL additive opt so a programmatic caller can link this outcome to
+ * the recall_traces row it judges. NOT applied unconditionally — an SDK
+ * caller passing explicit ids with no preceding CLI/context recall would
+ * otherwise get linked to a stale, unrelated trace. `outcomeForLastRecall`
+ * supplies this automatically from `last_trace_id`; every other caller
+ * (server.ts explicit-ids path, MCP hippo_outcome) omits it and gets no
+ * linkage, which is correct.
+ */
+export interface OutcomeResult {
+    applied: number;
+    appliedIds: string[];
+}
+export declare function outcome(ctx: Context, ids: ReadonlyArray<string>, good: boolean, opts?: {
+    traceId?: number;
+}): OutcomeResult;
+/**
+ * Apply an outcome to the ids most recently returned by `recall()`.
+ *
+ * Reads `loadIndex(ctx.hippoRoot).last_retrieval_ids` (per-hippoRoot local
+ * state; not tenant-scoped at the index layer) and forwards to `outcome()`,
+ * which DOES tenant-filter via `readEntry(..., ctx.tenantId)`. Cross-tenant
+ * ids in `last_retrieval_ids` are silently skipped, matching the MCP
+ * `hippo_outcome` semantics.
+ *
+ * **Tenant-safe response shape (v1.11.4 security fix):** the returned `ids`
+ * field contains ONLY the tenant-filtered subset that actually had outcomes
+ * applied (i.e. `appliedIds` from the inner `outcome()` call). Earlier
+ * versions returned the raw `last_retrieval_ids` regardless of tenant, which
+ * leaked cross-tenant memory IDs to the caller via POST /v1/outcome's
+ * no-body last-recall response. The fix is at this helper so all callers
+ * (CLI cmdOutcome, HTTP /v1/outcome, MCP `hippo_outcome` if added later)
+ * inherit the tenant-safe contract.
+ *
+ * Do NOT tighten `loadIndex` with `tenantId` inside this helper — doing so
+ * would break the (correct) cross-tenant-silent-skip behavior covered by
+ * the test in `tests/api-outcome-for-last-recall.test.ts`.
+ */
+export interface OutcomeForLastRecallResult {
+    applied: number;
+    ids: string[];
+}
+export declare function outcomeForLastRecall(ctx: Context, good: boolean): OutcomeForLastRecallResult;
+//# sourceMappingURL=outcome.d.ts.map

package/dist/api/outcome.js

@@ -0,0 +1,66 @@
+// Outcome feedback on recalled memories.
+import { openHippoDb, closeHippoDb } from '../db.js';
+import { writeEntry } from '../store/entry-writes.js';
+import { readEntry } from '../store/entry-reads.js';
+import { loadIndex } from '../store/index-and-stats.js';
+import { applyOutcome, CHURN_STALE_TAG } from '../memory.js';
+import { appendAuditEvent } from '../audit.js';
+import { recordTraceOutcome } from '../recall-trace.js';
+export function outcome(ctx, ids, good, opts) {
+    const appliedIds = [];
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        for (const id of ids) {
+            const entry = readEntry(ctx.hippoRoot, id, ctx.tenantId);
+            if (!entry)
+                continue;
+            let updated = applyOutcome(entry, good);
+            if (good && updated.tags.includes(CHURN_STALE_TAG)) { // FE2: a good outcome reconfirms the entry
+                updated = { ...updated, tags: updated.tags.filter((t) => t !== CHURN_STALE_TAG) };
+            }
+            writeEntry(ctx.hippoRoot, updated, { actor: ctx.actor.subject });
+            appendAuditEvent(db, {
+                tenantId: ctx.tenantId,
+                actor: ctx.actor.subject,
+                op: 'outcome',
+                targetId: id,
+                metadata: { good },
+            });
+            appliedIds.push(id);
+        }
+        // LC1: link the outcome to its trace, recording only the ids actually
+        // credited (post tenant-filtering, matches appliedIds). Lives in its own
+        // append-only table so audit_log pruning can never erase training data.
+        if (opts?.traceId !== undefined && appliedIds.length > 0) {
+            recordTraceOutcome(db, {
+                traceId: opts.traceId,
+                tenantId: ctx.tenantId,
+                outcome: good ? 'positive' : 'negative',
+                memoryIds: appliedIds,
+            });
+        }
+    }
+    finally {
+        closeHippoDb(db);
+    }
+    return { applied: appliedIds.length, appliedIds };
+}
+export function outcomeForLastRecall(ctx, good) {
+    const idx = loadIndex(ctx.hippoRoot);
+    const ids = idx.last_retrieval_ids;
+    if (ids.length === 0)
+        return { applied: 0, ids: [] };
+    // LC1 F1(d) structural fix (docs/plans/2026-08-02-lc1-recall-trace-persistence.md):
+    // read the trace id from the SAME `loadIndex` snapshot already in hand
+    // (idx.last_trace_id) — a single-snapshot read, not a second DB round
+    // trip via a now-deleted readLastTraceId helper. The value is already
+    // strict-parsed by buildIndexFromDb's parseLastTraceId (store.ts): every
+    // consumer gets a clean positive-integer string or null, never a garbage
+    // value that could reach outcome() and INSERT trace_id=0/NaN. null on a
+    // fresh store / pre-v40 flow / api.recall-only usage — outcome() skips
+    // linkage silently when traceId is undefined.
+    const traceId = idx.last_trace_id !== null ? Number(idx.last_trace_id) : null;
+    const { applied, appliedIds } = outcome(ctx, ids, good, traceId !== null ? { traceId } : undefined);
+    return { applied, ids: appliedIds };
+}
+//# sourceMappingURL=outcome.js.map

package/dist/api/promote.d.ts

@@ -0,0 +1,54 @@
+import { type DatabaseSyncLike } from '../db.js';
+import type { Context } from './types.js';
+/**
+ * Copy a local memory into the global store. Mirrors `cmdPromote` in cli.ts:
+ * the `writeEntry` inside `promoteToGlobal` emits a 'remember' on the global
+ * db; we add a 'promote' audit event on the global db so the user-facing
+ * intent stays distinct from the underlying upsert.
+ *
+ * Note: `promoteToGlobal` does not currently take a tenantId override — it
+ * reads the entry from the local root via `readEntry` (no tenant filter) and
+ * preserves the entry's existing tenantId on the global side. Task 4 may
+ * tighten this once writeEntry/readEntry thread tenant context.
+ */
+export interface PromoteResult {
+    ok: true;
+    sourceId: string;
+    globalId: string;
+}
+export declare function promote(ctx: Context, id: string): PromoteResult;
+/**
+ * Replace an old memory with new content, chaining old.superseded_by = new.id.
+ * Mirrors `cmdSupersede` in cli.ts (without flag-driven layer/tag/pin overrides
+ * — A1 keeps the API minimal; the CLI handler will continue to handle those
+ * flags and pass the resolved values once Task 4 lands).
+ */
+export interface SupersedeResult {
+    ok: true;
+    oldId: string;
+    newId: string;
+}
+export declare function supersede(ctx: Context, oldId: string, newContent: string): SupersedeResult;
+/**
+ * Archive a kind='raw' memory: snapshot into raw_archive, mark archived, delete.
+ *
+ * `archiveRawMemory` audits the operation internally (op='archive_raw') using the
+ * row's own tenant_id. We DO NOT emit a second audit event here to avoid double-
+ * emitting the archive_raw op (unlike Task 1 remember/forget where the underlying
+ * helpers hardcode actor='cli'). Instead we pass `ctx.actor.subject` through as `who`,
+ * and raw-archive.ts uses that for the audit row.
+ */
+export interface ArchiveRawOpts {
+    /**
+     * Connector idempotency hook (v0.39 commit 3). Runs inside the same
+     * SAVEPOINT as the archive — throwing rolls the archive back. Used by the
+     * Slack deletion connector to mark the deletion event seen atomically.
+     */
+    afterArchive?: (db: DatabaseSyncLike, archivedMemoryId: string) => void;
+}
+export interface ArchiveRawResult {
+    ok: true;
+    archivedAt: string;
+}
+export declare function archiveRaw(ctx: Context, id: string, reason: string, opts?: ArchiveRawOpts): ArchiveRawResult;
+//# sourceMappingURL=promote.d.ts.map

package/dist/api/promote.js

@@ -0,0 +1,203 @@
+// Promote to the global store, supersede with a successor, and archive raw memories.
+import { openHippoDb, closeHippoDb, isSqliteBusy } from '../db.js';
+import { ConflictError, NotFoundError } from '../api-errors.js';
+import { auditRejectionRefusal } from '../store/audit-event.js';
+import { stampOriginProject } from '../store/entry-row.js';
+import { removeEntryMirrors } from '../store/mirrors.js';
+import { writeEntryDbOnly, writeEntryMirrors } from '../store/entry-writes.js';
+import { readEntry } from '../store/entry-reads.js';
+import { updateStatsUnlessBusy } from '../store/index-and-stats.js';
+import { markSummaryDirtyInTx } from '../summary-dirty.js';
+import { RejectedValueError } from '../rejection.js';
+import { log } from '../log.js';
+import { createSuccessor } from '../memory.js';
+import { appendAuditEvent } from '../audit.js';
+import { promoteToGlobal } from '../shared.js';
+import { archiveRawMemory } from '../raw-archive.js';
+import { loadConfig } from '../config.js';
+import { selectMemoryTenant } from '../store/tenant-lookup.js';
+export function promote(ctx, id) {
+    // Tenant scope: promoteToGlobal reads the entry from the local root via
+    // readEntry without a tenant filter, so a Bearer for tenant A could
+    // promote tenant B's row by guessing or leaking the id. Pre-check the
+    // row's tenant_id and deny cross-tenant access with the same not-found
+    // wording archiveRaw uses (no info leak about whether the id exists in
+    // another tenant).
+    const ownerDb = openHippoDb(ctx.hippoRoot);
+    try {
+        if (selectMemoryTenant(ownerDb, id) !== ctx.tenantId) {
+            throw new NotFoundError(`memory not found: ${id}`);
+        }
+    }
+    finally {
+        closeHippoDb(ownerDb);
+    }
+    // The 'promote' row commits with the global copy, so no write follows the commit and a busy store fails the whole promote.
+    const globalEntry = promoteToGlobal(ctx.hippoRoot, id, {
+        actor: ctx.actor.subject,
+        tenantId: ctx.tenantId,
+        afterWrite: (db, globalId) => appendAuditEvent(db, {
+            tenantId: ctx.tenantId,
+            actor: ctx.actor.subject,
+            op: 'promote',
+            targetId: globalId,
+            metadata: { sourceId: id },
+        }),
+    });
+    return { ok: true, sourceId: id, globalId: globalEntry.id };
+}
+export function supersede(ctx, oldId, newContent) {
+    // Read old (tenant-scoped). readEntry filters by tenantId, so a Bearer for
+    // tenant A on tenant B's id throws "Memory not found" here without any
+    // info leak.
+    const old = readEntry(ctx.hippoRoot, oldId, ctx.tenantId);
+    if (!old) {
+        throw new NotFoundError(`Memory not found: ${oldId}`);
+    }
+    // Guard: not already superseded. The CAS UPDATE below race-safely closes
+    // the window between this read and the write; this check just produces a
+    // clearer error in the common single-writer case.
+    if (old.superseded_by) {
+        throw new ConflictError(`Memory ${oldId} is already superseded by ${old.superseded_by}. Supersede that one instead.`);
+    }
+    const newEntry = createSuccessor(old, newContent, {
+        tenantId: ctx.tenantId,
+        baseHalfLifeDays: loadConfig(ctx.hippoRoot).defaultHalfLifeDays,
+    });
+    // Race-safe transition: open a fresh db handle, BEGIN IMMEDIATE, run all
+    // three steps (CAS on old + writeEntryDbOnly(new) + supersede audit row)
+    // inside the same transaction. Two concurrent supersedes: exactly one CAS
+    // wins (changes=1), the other gets changes=0 and throws CONFLICT. No
+    // dangling-pointer window: the new memory's row commits atomically with
+    // the old.superseded_by pointer.
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        db.exec('BEGIN IMMEDIATE');
+        try {
+            // 1. CAS update: only succeed if old.superseded_by IS NULL AND the
+            //    row still belongs to ctx.tenantId. Tenant filter is belt-and-
+            //    braces with the readEntry above — it costs nothing and closes
+            //    a hypothetical window where ownership changes between read and
+            //    update.
+            const result = db.prepare(`
+        UPDATE memories
+        SET superseded_by = ?
+        WHERE id = ? AND tenant_id = ? AND superseded_by IS NULL
+      `).run(newEntry.id, oldId, ctx.tenantId);
+            if ((result.changes ?? 0) === 0) {
+                db.exec('ROLLBACK');
+                throw new ConflictError(`Memory ${oldId} already superseded by another writer`);
+            }
+            // v0.30 / E2 — DAG live-coupling: OLD entry just transitioned to
+            // superseded. Its parent (if any) needs rebuild. Lands strictly
+            // between the rollback guard above and the writeEntryDbOnly(NEW)
+            // below so a failed CAS hits throw before this hook. The NEW
+            // entry's parent (typically same parent) is auto-marked by the
+            // writeEntryDbOnly hook (same parent → idempotent, audits once).
+            if (old.dag_parent_id) {
+                markSummaryDirtyInTx(db, old.dag_parent_id, ctx.tenantId, ctx.actor.subject);
+            }
+            // 2. Write new memory inside same tx via writeEntryDbOnly (DB-only
+            //    path). This emits its OWN 'remember' audit row for the new
+            //    memory inside the SAVEPOINT — atomic with the row INSERT.
+            writeEntryDbOnly(db, stampOriginProject(ctx.hippoRoot, newEntry), { actor: ctx.actor.subject });
+            // 3. User-facing 'supersede' audit row inside the same tx so the
+            //    chain pointer + audit trail commit atomically.
+            appendAuditEvent(db, {
+                tenantId: ctx.tenantId,
+                actor: ctx.actor.subject,
+                op: 'supersede',
+                targetId: oldId,
+                metadata: { newId: newEntry.id },
+            });
+            db.exec('COMMIT');
+        }
+        catch (err) {
+            try {
+                db.exec('ROLLBACK');
+            }
+            catch { /* already rolled back */ }
+            // AT1 (plan §3): refusal audit lands post-ROLLBACK, in a fresh
+            // implicit transaction the aborted outer one cannot claw back — then
+            // rethrow so the caller sees the refusal.
+            if (err instanceof RejectedValueError) {
+                auditRejectionRefusal(db, err, ctx.actor.subject);
+            }
+            throw err;
+        }
+        // Mirrors after COMMIT, while the db handle is still open. Same
+        // invariant as the original writeEntry: a mirror failure leaves disk
+        // MISSING the markdown for the new memory (rebuildIndex rewrites every
+        // markdown mirror from the DB) but DOES NOT desync the DB or
+        // roll back the supersede. Logged + swallowed, non-fatal.
+        try {
+            writeEntryMirrors(ctx.hippoRoot, newEntry);
+        }
+        catch (mirrorErr) {
+            log.error(`supersede: mirror write failed (non-fatal, will self-heal): ${mirrorErr instanceof Error ? mirrorErr.message : String(mirrorErr)}`);
+        }
+    }
+    finally {
+        closeHippoDb(db);
+    }
+    return { ok: true, oldId, newId: newEntry.id };
+}
+export function archiveRaw(ctx, id, reason, opts = {}) {
+    const db = openHippoDb(ctx.hippoRoot);
+    let mirrorOk = false;
+    try {
+        // Tenant scope: archiveRawMemory looks up the row by id alone, so a
+        // Bearer for tenant A could archive tenant B's raw row without this
+        // pre-check. Deny cross-tenant access with the same not-found message
+        // archiveRawMemory itself would throw on a missing row, so we don't
+        // leak whether the id exists in another tenant.
+        if (selectMemoryTenant(db, id) !== ctx.tenantId) {
+            throw new NotFoundError(`memory not found: ${id}`);
+        }
+        archiveRawMemory(db, id, {
+            reason,
+            who: ctx.actor.subject,
+            afterArchive: opts.afterArchive,
+        });
+        // archiveRawMemory deletes the memories row but leaves any legacy markdown
+        // mirror in <root>/{buffer,episodic,semantic}/<id>.md untouched. If we left
+        // the mirror in place, a subsequent initStore() on an empty memories table
+        // would silently re-import the row via bootstrapLegacyStore — defeating the
+        // archive (and the GDPR right-to-be-forgotten promise on raw rows). Mirror
+        // forget() at src/store.ts:1046, which uses the same removeEntryMirrors call.
+        // The DB transaction has already committed; if filesystem unlink fails here
+        // we log and continue. The mirror reaper in openHippoDb will catch it on
+        // next DB open: raw_archive.mirror_cleaned_at stays NULL until every layer
+        // mirror for this id is gone, so the reaper genuinely retries.
+        try {
+            removeEntryMirrors(ctx.hippoRoot, id);
+            mirrorOk = true;
+        }
+        catch (mirrorErr) {
+            log.error(`archiveRaw: mirror cleanup failed for ${id} (will retry via reaper on next openHippoDb): ${mirrorErr instanceof Error ? mirrorErr.message : String(mirrorErr)}`);
+        }
+        if (mirrorOk) {
+            // Stamp mirror_cleaned_at now so the next openHippoDb reaper SELECT
+            // returns empty for this row. NULL stays untouched on failure -> retry.
+            try {
+                db.prepare(`UPDATE raw_archive SET mirror_cleaned_at = ? WHERE memory_id = ?`).run(new Date().toISOString(), id);
+            }
+            catch (err) {
+                if (!isSqliteBusy(err))
+                    throw err;
+                log.warnThenDebug('archive-mirror-stamp-busy', `archived ${id}; the store was busy, so the mirror reaper will re-check it on the next open`);
+            }
+        }
+    }
+    finally {
+        closeHippoDb(db);
+    }
+    // Counted here rather than in the CLI: the HTTP archive route calls this too,
+    // so a routed archive would otherwise never reach the forgotten counter.
+    updateStatsUnlessBusy(ctx.hippoRoot, { forgotten: 1 }, `removed ${id}`);
+    // archiveRawMemory does not return the archive_at timestamp it wrote. We
+    // emit a fresh ISO timestamp here for the API response. Within a millisecond
+    // of the actual write, fine for a server response shape.
+    return { ok: true, archivedAt: new Date().toISOString() };
+}
+//# sourceMappingURL=promote.js.map

package/dist/api/quarantine.d.ts

@@ -0,0 +1,24 @@
+import { type QuarantineStatus } from '../quarantine.js';
+import type { KeysetPosition } from '../keyset.js';
+import type { Context } from './types.js';
+export interface QuarantineListItem {
+    id: string;
+    originalScope: string | null;
+    reason: string;
+    status: QuarantineStatus;
+    quarantinedAt: string;
+    decidedAt: string | null;
+    decidedBy: string | null;
+    contentPreview: string;
+}
+/** A tenant's quarantined memories, newest first. Default `status` is 'pending' (the review queue). */
+export declare function quarantineList(ctx: Context, opts?: {
+    status?: QuarantineStatus | 'all';
+    limit?: number;
+    after?: KeysetPosition;
+}): QuarantineListItem[];
+/** Release a quarantined memory to its original scope. Admin only; the scope guard refuses a row moved since (mirrors restoreDormant). */
+export declare function quarantineApprove(ctx: Context, id: string): void;
+/** Keep a quarantined memory hidden for good. Admin only; the raw row is untouched (append-only). */
+export declare function quarantineReject(ctx: Context, id: string): void;
+//# sourceMappingURL=quarantine.d.ts.map

package/dist/api/quarantine.js

@@ -0,0 +1,121 @@
+// Quarantine review: list, approve and reject held memories.
+import { openHippoDb, closeHippoDb } from '../db.js';
+import { ConflictError, ForbiddenError, NotFoundError } from '../api-errors.js';
+import { writeEntryMirrors } from '../store/entry-writes.js';
+import { readEntry } from '../store/entry-reads.js';
+import { quarantineScopeFor, getQuarantineRow, listQuarantineRows, approveQuarantineRow, rejectQuarantineRow, } from '../quarantine.js';
+import { log } from '../log.js';
+import { appendAuditEvent } from '../audit.js';
+const QUARANTINE_PREVIEW_CHARS = 200;
+/** A tenant's quarantined memories, newest first. Default `status` is 'pending' (the review queue). */
+export function quarantineList(ctx, opts = {}) {
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        const rows = listQuarantineRows(db, ctx.tenantId, opts.status ?? 'pending', opts.limit, opts.after);
+        return rows.map((row) => {
+            const entry = readEntry(ctx.hippoRoot, row.memoryId, ctx.tenantId);
+            return {
+                id: row.memoryId,
+                originalScope: row.originalScope,
+                reason: row.reason,
+                status: row.status,
+                quarantinedAt: row.quarantinedAt,
+                decidedAt: row.decidedAt,
+                decidedBy: row.decidedBy,
+                contentPreview: entry ? entry.content.slice(0, QUARANTINE_PREVIEW_CHARS) : '',
+            };
+        });
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+function loadPendingQuarantineRow(db, tenantId, id) {
+    const row = getQuarantineRow(db, tenantId, id);
+    if (!row)
+        throw new NotFoundError(`not quarantined: ${id}`);
+    if (row.status !== 'pending')
+        throw new ConflictError(`${id} is already ${row.status}`);
+    return row;
+}
+/** Release a quarantined memory to its original scope. Admin only; the scope guard refuses a row moved since (mirrors restoreDormant). */
+export function quarantineApprove(ctx, id) {
+    if (ctx.actor.role !== 'admin') {
+        throw new ForbiddenError('Only an admin key can approve a quarantined memory');
+    }
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        db.exec('BEGIN IMMEDIATE');
+        try {
+            const row = loadPendingQuarantineRow(db, ctx.tenantId, id);
+            const quarantineScope = quarantineScopeFor(row.originalScope);
+            const updated = db
+                .prepare(`UPDATE memories SET scope = ? WHERE id = ? AND tenant_id = ? AND scope = ?`)
+                .run(row.originalScope, id, ctx.tenantId, quarantineScope);
+            if (Number(updated.changes ?? 0) !== 1) {
+                throw new ConflictError(`memory ${id} scope changed since quarantine; refusing to approve`);
+            }
+            approveQuarantineRow(db, ctx.tenantId, id, ctx.actor.subject);
+            appendAuditEvent(db, {
+                tenantId: ctx.tenantId,
+                actor: ctx.actor.subject,
+                op: 'quarantine_approve',
+                targetId: id,
+                metadata: { originalScope: row.originalScope },
+            });
+            db.exec('COMMIT');
+        }
+        catch (err) {
+            try {
+                db.exec('ROLLBACK');
+            }
+            catch { /* already rolled back */ }
+            throw err;
+        }
+    }
+    finally {
+        closeHippoDb(db);
+    }
+    // Post-commit, best-effort: a failed rewrite leaves the mirror showing the quarantine scope (fail-closed).
+    try {
+        const restored = readEntry(ctx.hippoRoot, id, ctx.tenantId);
+        if (restored)
+            writeEntryMirrors(ctx.hippoRoot, restored);
+    }
+    catch (err) {
+        log.error(`quarantine: mirror rewrite failed for ${id}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/** Keep a quarantined memory hidden for good. Admin only; the raw row is untouched (append-only). */
+export function quarantineReject(ctx, id) {
+    if (ctx.actor.role !== 'admin') {
+        throw new ForbiddenError('Only an admin key can reject a quarantined memory');
+    }
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        db.exec('BEGIN IMMEDIATE');
+        try {
+            loadPendingQuarantineRow(db, ctx.tenantId, id);
+            rejectQuarantineRow(db, ctx.tenantId, id, ctx.actor.subject);
+            appendAuditEvent(db, {
+                tenantId: ctx.tenantId,
+                actor: ctx.actor.subject,
+                op: 'quarantine_reject',
+                targetId: id,
+                metadata: {},
+            });
+            db.exec('COMMIT');
+        }
+        catch (err) {
+            try {
+                db.exec('ROLLBACK');
+            }
+            catch { /* already rolled back */ }
+            throw err;
+        }
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+//# sourceMappingURL=quarantine.js.map