hippo-memory 1.60.0 → 1.62.0

package/dist/api/promote.js

@@ -0,0 +1,192 @@
+// 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) {
+    const old = readSupersedable(ctx, oldId);
+    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 {
+        commitSupersede(db, ctx, oldId, old, newEntry);
+        // 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 };
+}
+/** The tenant-scoped row to supersede; readEntry's tenant filter makes another tenant's id read as not found. */
+function readSupersedable(ctx, oldId) {
+    const old = readEntry(ctx.hippoRoot, oldId, ctx.tenantId);
+    if (!old) {
+        throw new NotFoundError(`Memory not found: ${oldId}`);
+    }
+    // The CAS UPDATE closes the race; this check only gives 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.`);
+    }
+    return old;
+}
+/** CAS on the old row, the successor's insert and the 'supersede' audit row, in one BEGIN IMMEDIATE transaction. */
+function commitSupersede(db, ctx, oldId, old, newEntry) {
+    db.exec('BEGIN IMMEDIATE');
+    try {
+        // The tenant filter repeats readEntry's check at no cost, closing an ownership change 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`);
+        }
+        // After the CAS guard, so a lost race throws before the old parent is marked for rebuild.
+        if (old.dag_parent_id) {
+            markSummaryDirtyInTx(db, old.dag_parent_id, ctx.tenantId, ctx.actor.subject);
+        }
+        // Emits its own 'remember' audit row inside the same transaction.
+        writeEntryDbOnly(db, stampOriginProject(ctx.hippoRoot, newEntry), { actor: ctx.actor.subject });
+        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 */ }
+        // The refusal audit lands after ROLLBACK, in a fresh implicit transaction the aborted one cannot undo.
+        if (err instanceof RejectedValueError) {
+            auditRejectionRefusal(db, err, ctx.actor.subject);
+        }
+        throw err;
+    }
+}
+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