hippo-memory 1.56.0 → 1.58.0

package/dist/api.js

@@ -7,6 +7,8 @@
  * in exactly one place.
  */
 import { openHippoDb, closeHippoDb } from './db.js';
+import { BadRequestError, ConflictError, ForbiddenError, NotFoundError } from './api-errors.js';
+export { ApiError, BadRequestError, ConflictError, ForbiddenError, NotFoundError } from './api-errors.js';
 import { writeEntry, writeEntryDbOnly, strengthenRetrieved, stampOriginProject, writeEntryMirrors, readEntry, deleteEntry, loadRecallSearchEntries, loadEntriesByIds, loadChildrenOf, loadFreshRawMemories, loadSessionRawMemories, countSessionRawMemories, DEFAULT_SEARCH_CANDIDATE_LIMIT, removeEntryMirrors, loadActiveTaskSnapshot, loadFreshActiveTaskSnapshot, loadLatestHandoff, listSessionEvents, SNAPSHOT_AMBIENT_MAX_AGE_MS, loadIndex, saveIndex, loadAllEntries, loadAmbientCandidates, updateStats, isInitialized, markSummaryDirtyInTx, auditRejectionRefusal, memoriesBackingObjects, } from './store.js';
 import { RejectedValueError } from './rejection.js';
 import { rejectValue, unrejectValue, listRejectionsForTenant } from './reject-flow.js';
@@ -16,15 +18,15 @@ import { detectInstruction } from './instruction-detect.js';
 import { quarantineScopeFor, recordQuarantine, getQuarantineRow, listQuarantineRows, approveQuarantineRow, rejectQuarantineRow, } from './quarantine.js';
 import { summarizeFailures } from './failure-log.js';
 import { formatHandoffEvidenceLine } from './handoff.js';
-import { createMemory, createSuccessor, applyOutcome, calculateStrength, CHURN_STALE_TAG, COMPACTION_MEMORY_TAG, } from './memory.js';
-import { appendAuditEvent, auditQueryFields, queryAuditEvents, auditMemories, isContentWorthStoring, } from './audit.js';
+import { createMemory, createSuccessor, applyOutcome, calculateStrength, markRetrieved, CHURN_STALE_TAG, COMPACTION_MEMORY_TAG, } from './memory.js';
+import { appendAuditEvent, reportAuditWriteFailure, auditQueryFields, queryAuditEvents, auditMemories, isContentWorthStoring, } from './audit.js';
 import { promoteToGlobal, getGlobalRoot, autoShare, searchBothHybrid } from './shared.js';
 import { writeRecallTrace, writeRecallTraceAtRoot, recordTraceOutcome } from './recall-trace.js';
 import { evalNow } from './ablation.js';
 import { archiveRawMemory } from './raw-archive.js';
 import { createApiKey, listApiKeys, revokeApiKey, grantScope, ungrantScope, } from './auth.js';
 import { applyGoalStackBoost } from './goals.js';
-import { markRetrieved, estimateTokens, hybridSearch, physicsSearch, churnStaleFactor } from './search.js';
+import { estimateTokens, hybridSearch, physicsSearch, churnStaleFactor } from './search.js';
 import { compareEntryIdentity, compareScoredResults } from './compare.js';
 import { dropHeldCopies, duplicateKey, storedTextKeys } from './same-text.js';
 import { scopeMatch } from './scope.js';
@@ -32,14 +34,14 @@ import { consolidate } from './consolidate.js';
 import { loadConfig } from './config.js';
 import { resolveProjectIdentity, classifyOriginProject, isGlobalStoreRoot } from './project-identity.js';
 import { promptTokens, contentTokens, gatePromptRecall, } from './prompt-recall.js';
-import { detectSecret } from './secret-detect.js';
+import { detectSecret, vetSecrets } from './secret-detect.js';
 import { isSessionDigestRow } from './session-digest.js';
 import { deduplicateStore } from './dedupe.js';
 import { computeAmbientState } from './ambient.js';
 import { loadPendingExtractionTenants, markPendingProcessedUpTo } from './graph.js';
 import { extractGraph } from './graph-extract.js';
 import { computePlanningFallacyOutput, } from './predictions.js';
-import { detectAnchoring, hashQueryText, } from './recall-history.js';
+import { detectAnchoring, hashQueryText, biasHintEnabled, } from './recall-history.js';
 import { detectAvailabilityBias } from './availability.js';
 /**
  * Helper for building process-local (admin-by-default) Actor values. v1.12.0
@@ -68,7 +70,7 @@ export function adminActor(subject) {
  *     full-store fallback (codex v1.7.0 diff-pass P1). Validated upfront
  *     so the contract holds.
  */
-export class RecallContractError extends Error {
+export class RecallContractError extends BadRequestError {
     code;
     constructor(code, message) {
         super(message);
@@ -76,13 +78,6 @@ export class RecallContractError extends Error {
         this.code = code;
     }
 }
-/** The actor's role or identity does not allow the operation. HTTP maps it to 403. */
-export class ForbiddenError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = 'ForbiddenError';
-    }
-}
 // v1.25.0: the recall-side scope predicates (PRIVATE_SCOPE_RE, isPrivateScope,
 // passesScopeFilterForRecall) live in recall-scope.ts (leaf) so shared.ts can
 // apply the same default-deny rule to searchBothHybrid's internal loads
@@ -107,23 +102,22 @@ export { classifyOriginProject } from './project-identity.js';
  *   injects inside its owning project; flagged rows with no project origin
  *   (''/null) never ambient-inject at all. Explicit recall is unaffected -
  *   recalling a secret is a deliberate act.
- * - S2 envelope parity: private scopes + quarantine buckets never inject.
+ * - S2 envelope parity: private/quarantine scopes never inject unless `exactScope` names one.
  * - S3 origin partition: other-project rows are excluded unless
  *   `includeCrossProject`.
  */
-function ambientAdmitEntry(e, currentProjectName, includeCrossProject) {
+function ambientAdmitEntry(e, currentProjectName, includeCrossProject, exactScope) {
     if (!ambientSecretAdmit(e, currentProjectName))
         return false;
-    if (!passesScopeFilterForRecall(e.scope ?? null, undefined))
+    if (!passesScopeFilterForRecall(e.scope ?? null, exactScope))
         return false;
     if (includeCrossProject)
         return true;
     return classifyOriginProject(e.origin_project, currentProjectName) !== 'cross-project';
 }
 /**
- * v39 S4: the secret half of the ambient policy on its own, for surfaces
- * with their own scope semantics (MCP hippo_context's explicit-scope
- * exact-match). A flagged row is only admitted inside its owning project;
+ * v39 S4: the secret half of the ambient policy on its own, for callers
+ * that apply their own scope rule. A flagged row is only admitted inside its owning project;
  * flagged rows with no project origin never ambient-inject.
  */
 export function ambientSecretAdmit(e, currentProjectName) {
@@ -171,9 +165,10 @@ export function oneCopyPerMemory(local, global, now) {
     return [local.filter((e) => kept.has(e)), global.filter((e) => kept.has(e))];
 }
 export function remember(ctx, opts) {
-    const detection = opts.untrusted ? detectInstruction(opts.content) : { flagged: false, reason: null };
+    const vetted = vetSecrets(opts.content, opts.tags ?? [], opts.untrusted === true);
+    const detection = opts.untrusted ? detectInstruction(vetted.content) : { flagged: false, reason: null };
     const requestedScope = opts.scope ?? null;
-    const entry = createMemory(opts.content, {
+    const entry = createMemory(vetted.content, {
         kind: opts.kind ?? 'distilled',
         scope: detection.flagged ? quarantineScopeFor(requestedScope) : requestedScope,
         owner: opts.owner ?? null,
@@ -200,6 +195,8 @@ export function remember(ctx, opts) {
     const result = { id: entry.id, kind: entry.kind, tenantId: ctx.tenantId };
     if (detection.flagged)
         result.quarantined = { reason: detection.reason ?? 'unknown' };
+    if (vetted.warnings.length > 0)
+        result.warnings = vetted.warnings;
     return result;
 }
 /**
@@ -244,6 +241,8 @@ export function recall(ctx, opts) {
 export async function retrieve(ctx, opts) {
     assertScopeRequestAllowed(ctx.actor, opts.scope);
     const windowSize = recallWindowSize(opts);
+    if (opts.showRanked)
+        return retrieveFromStore(ctx, opts, windowSize, opts.showRanked);
     let candidates = loadRecallSearchEntries(ctx.hippoRoot, opts.query, windowSize, ctx.tenantId, opts.scope, 'exact', false);
     if (opts.mode === 'hybrid' || opts.mode === 'physics') {
         const searchOpts = { budget: Infinity, hippoRoot: ctx.hippoRoot, scope: opts.scope ?? null };
@@ -257,6 +256,40 @@ export async function retrieve(ctx, opts) {
     strengthenRetrieved(ctx.hippoRoot, result.results.map((r) => r.id), ctx.tenantId);
     return result;
 }
+/** `retrieve` under `showRanked`: physics when `mode` says so, hybrid otherwise, over every admitted row. */
+async function retrieveFromStore(ctx, opts, windowSize, show) {
+    const store = loadAllEntries(ctx.hippoRoot, ctx.tenantId);
+    const pool = store.filter((e) => passesScopeFilterForRecall(e.scope ?? null, opts.scope));
+    // No scope option: the scope boost follows HIPPO_SCOPE and the skill env, as MCP recall always ranked.
+    const searchOpts = { budget: Infinity, hippoRoot: ctx.hippoRoot };
+    let ranked = opts.mode === 'physics'
+        ? await physicsSearch(opts.query, pool, { ...searchOpts, physicsConfig: loadConfig(ctx.hippoRoot).physics })
+        : await hybridSearch(opts.query, pool, searchOpts);
+    if (opts.sessionId && !opts.goalTag) {
+        const db = openHippoDb(ctx.hippoRoot);
+        try {
+            ranked = applyGoalStackBoost(db, ranked, { sessionId: opts.sessionId, tenantId: ctx.tenantId, limit: ranked.length });
+        }
+        finally {
+            closeHippoDb(db);
+        }
+    }
+    const window = ranked.slice(0, windowSize).map((r) => r.entry);
+    const result = recallFrom(ctx, { ...opts, suppressRecallTrace: true }, windowSize, window);
+    const shown = show({ ranked, pool, droppedByScope: store.length - pool.length }, result);
+    strengthenRetrieved(ctx.hippoRoot, shown, ctx.tenantId);
+    if (!opts.suppressRecallTrace) {
+        const scores = new Map(ranked.map((r) => [r.entry.id, r.score]));
+        writeRecallTraceAtRoot(ctx.hippoRoot, {
+            tenantId: ctx.tenantId,
+            sessionId: opts.sessionId ?? null,
+            pipeline: 'mcp',
+            query: opts.query,
+            results: shown.map((id) => ({ memoryId: id, score: scores.get(id) ?? 0 })),
+        });
+    }
+    return result;
+}
 /** Contract preflight: throws before any store-touching work. */
 function recallWindowSize(opts) {
     // F5 (v1.6.5) preflight — codex P1: original guard fired AFTER
@@ -564,9 +597,9 @@ function recallFrom(ctx, opts, windowSize, all) {
         // handle. v1.11.5 contract lock holds — api.recall does NOT write
         // last_trace_id (tests/api-recall-no-side-effects.test.ts); a trace INSERT
         // is the same observability class as the audit row it sits beside, not
-        // retrieval state. F2 fix: suppressed when the caller (currently only the
-        // MCP handler) traces its own, different result set — see
-        // opts.suppressRecallTrace JSDoc. Fail-soft internally; never throws.
+        // retrieval state. F2 fix: suppressed when the caller traces its own,
+        // different result set (retrieve under showRanked traces the shown list as
+        // 'mcp'). Fail-soft internally; never throws.
         if (!opts.suppressRecallTrace) {
             writeRecallTrace(db, {
                 tenantId: ctx.tenantId,
@@ -656,7 +689,7 @@ function recallFrom(ctx, opts, windowSize, all) {
     // detect call returns null and api.recall's anchoringHint stays absent.
     let anchoringHint = null;
     let suppressedByInterferenceCount = 0;
-    if (process.env.HIPPO_ANCHORING !== 'off' && opts.recallHistory) {
+    if (biasHintEnabled('anchoring') && opts.recallHistory) {
         const queryHash = hashQueryText(opts.query);
         const topMemoryId = rankedOut[0]?.id ?? null;
         anchoringHint = detectAnchoring(opts.recallHistory, queryHash, topMemoryId);
@@ -709,7 +742,7 @@ function recallFrom(ctx, opts, windowSize, all) {
     // opts.recallHistory gate above so we never double-emit the audit op. Audit
     // emission is pipeline-local, mirroring the J1 block above.
     let availabilityHint = null;
-    if (process.env.HIPPO_AVAILABILITY !== 'off' && !opts.suppressAvailabilityHint) {
+    if (biasHintEnabled('availability') && !opts.suppressAvailabilityHint) {
         availabilityHint = detectAvailabilityBias({
             topK: baseSlice.map((e) => ({ id: e.id, created: e.created })),
             pool: entries.map((e) => ({ id: e.id, created: e.created })),
@@ -1072,7 +1105,7 @@ export function forget(ctx, id) {
             .prepare(`SELECT tenant_id FROM memories WHERE id = ?`)
             .get(id);
         if (!row || row.tenant_id !== ctx.tenantId) {
-            throw new Error(`memory not found: ${id}`);
+            throw new NotFoundError(`memory not found: ${id}`);
         }
     }
     finally {
@@ -1080,7 +1113,7 @@ export function forget(ctx, id) {
     }
     const removed = deleteEntry(ctx.hippoRoot, id, { actor: ctx.actor.subject });
     if (!removed) {
-        throw new Error(`memory not found: ${id}`);
+        throw new NotFoundError(`memory not found: ${id}`);
     }
     // Counted here, not in the CLI: both callers of this function (cmdForget and
     // the HTTP route) are the two paths of one user command, so neither can miss
@@ -1115,7 +1148,7 @@ export function reject(ctx, opts) {
                 .prepare(`SELECT tenant_id FROM memories WHERE id = ?`)
                 .get(opts.memoryId);
             if (!row || row.tenant_id !== ctx.tenantId) {
-                throw new Error(`memory not found: ${opts.memoryId}`);
+                throw new NotFoundError(`memory not found: ${opts.memoryId}`);
             }
         }
         finally {
@@ -1141,10 +1174,10 @@ export function reject(ctx, opts) {
 export function unreject(ctx, digestOrPrefix) {
     const outcome = unrejectValue(ctx.hippoRoot, ctx.tenantId, digestOrPrefix, ctx.actor.subject);
     if (outcome.status === 'not_found') {
-        throw new Error(`no rejected value matches: ${digestOrPrefix}`);
+        throw new NotFoundError(`no rejected value matches: ${digestOrPrefix}`);
     }
     if (outcome.status === 'ambiguous') {
-        throw new Error(`"${digestOrPrefix}" matches ${outcome.candidates.length} tombstones; use a longer prefix`);
+        throw new BadRequestError(`"${digestOrPrefix}" matches ${outcome.candidates.length} tombstones; use a longer prefix`);
     }
     return { ok: true, digest: outcome.digest };
 }
@@ -1167,7 +1200,7 @@ export function promote(ctx, id) {
             .prepare(`SELECT tenant_id FROM memories WHERE id = ?`)
             .get(id);
         if (!row || row.tenant_id !== ctx.tenantId) {
-            throw new Error(`memory not found: ${id}`);
+            throw new NotFoundError(`memory not found: ${id}`);
         }
     }
     finally {
@@ -1199,13 +1232,13 @@ export function supersede(ctx, oldId, newContent) {
     // info leak.
     const old = readEntry(ctx.hippoRoot, oldId, ctx.tenantId);
     if (!old) {
-        throw new Error(`Memory not found: ${oldId}`);
+        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 Error(`Memory ${oldId} is already superseded by ${old.superseded_by}. Supersede that one instead.`);
+        throw new ConflictError(`Memory ${oldId} is already superseded by ${old.superseded_by}. Supersede that one instead.`);
     }
     const newEntry = createSuccessor(old, newContent, {
         tenantId: ctx.tenantId,
@@ -1233,7 +1266,7 @@ export function supersede(ctx, oldId, newContent) {
       `).run(newEntry.id, oldId, ctx.tenantId);
             if ((result.changes ?? 0) === 0) {
                 db.exec('ROLLBACK');
-                throw new Error(`Memory ${oldId} already superseded by another writer`);
+                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
@@ -1304,7 +1337,7 @@ export function archiveRaw(ctx, id, reason, opts = {}) {
             .prepare(`SELECT tenant_id FROM memories WHERE id = ?`)
             .get(id);
         if (!row || row.tenant_id !== ctx.tenantId) {
-            throw new Error(`memory not found: ${id}`);
+            throw new NotFoundError(`memory not found: ${id}`);
         }
         archiveRawMemory(db, id, {
             reason,
@@ -1383,8 +1416,9 @@ export function authCreate(ctx, opts) {
                 },
             });
         }
-        catch {
+        catch (error) {
             // Audit must not crash a successful mint.
+            reportAuditWriteFailure('auth_create', String(error), result.keyId);
         }
         return { keyId: result.keyId, plaintext: result.plaintext, tenantId: ctx.tenantId, role };
     }
@@ -1422,11 +1456,11 @@ export function authRevoke(ctx, keyId) {
             .prepare(`SELECT key_id, tenant_id, revoked_at, role FROM api_keys WHERE key_id = ?`)
             .get(keyId);
         if (!row) {
-            throw new Error(`Unknown key_id: ${keyId}`);
+            throw new NotFoundError(`Unknown key_id: ${keyId}`);
         }
         // Cross-tenant access denied: same message as missing key, no info leak.
         if (row.tenant_id !== ctx.tenantId) {
-            throw new Error(`Unknown key_id: ${keyId}`);
+            throw new NotFoundError(`Unknown key_id: ${keyId}`);
         }
         if (ctx.actor.viaAuthResolver && row.role === 'admin') {
             throw new ForbiddenError('An auth resolver admin cannot revoke an admin key, which outranks it');
@@ -1455,8 +1489,9 @@ export function authRevoke(ctx, keyId) {
                     targetId: keyId,
                 });
             }
-            catch {
+            catch (error) {
                 // Audit must not crash a successful revoke.
+                reportAuditWriteFailure('auth_revoke', String(error), keyId);
             }
         }
         return { ok: true, revokedAt };
@@ -1484,13 +1519,13 @@ function changeScopeGrant(ctx, keyId, scope, op) {
             .prepare(`SELECT tenant_id, revoked_at FROM api_keys WHERE key_id = ?`)
             .get(keyId);
         if (!row || row.tenant_id !== ctx.tenantId) {
-            throw new Error(`Unknown key_id: ${keyId}`);
+            throw new NotFoundError(`Unknown key_id: ${keyId}`);
         }
         if (op === 'auth_grant' && row.revoked_at) {
-            throw new Error(`${keyId} is revoked; a grant on it would never apply`);
+            throw new ConflictError(`${keyId} is revoked; a grant on it would never apply`);
         }
         if (!isRestrictedScope(scope)) {
-            throw new Error(`${scope} is not a restricted scope; it is already readable by default`);
+            throw new BadRequestError(`${scope} is not a restricted scope; it is already readable by default`);
         }
         if (op === 'auth_grant')
             grantScope(db, keyId, scope);
@@ -1501,7 +1536,7 @@ function changeScopeGrant(ctx, keyId, scope, op) {
         }
         catch (err) {
             // Audit must not undo a grant change that already committed; surface it instead.
-            console.error(`auth: audit write failed for ${op} ${keyId}: ${err instanceof Error ? err.message : String(err)}`);
+            reportAuditWriteFailure(op, String(err), keyId);
         }
         return { ok: true };
     }
@@ -1551,6 +1586,8 @@ export async function getContext(ctx, opts = {}) {
     const limit = opts.limit ?? Number.POSITIVE_INFINITY;
     const includeRecent = opts.includeRecent ?? 0;
     const activeScope = opts.scope ?? '';
+    assertScopeRequestAllowed(ctx.actor, opts.exactScope);
+    const exactScope = opts.exactScope || undefined;
     if (budget <= 0) {
         return { entries: [], tokens: 0 };
     }
@@ -1562,10 +1599,7 @@ export async function getContext(ctx, opts = {}) {
     const primaryIsGlobal = isGlobalStoreRoot(ctx.hippoRoot);
     const hasLocalTaskState = hasLocal && !primaryIsGlobal;
     // v39 memory scope isolation (docs/plans/2026-07-01-memory-scope-isolation.md).
-    // S2: envelope-filter parity with api.recall for AMBIENT context - private
-    // scopes and quarantine buckets never inject. `requested` is deliberately
-    // undefined: opts.scope is the scope-TAG boost input here, not an
-    // envelope-scope request (api.recall's exact-match semantics don't apply).
+    // S2: envelope-filter parity with api.recall; opts.scope is only the tag boost, opts.exactScope the envelope request.
     // S3: origin partition - other-project memories are excluded unless the
     // caller explicitly asks for them (crossProject) or isolation is disabled.
     const config = loadConfig(ctx.hippoRoot);
@@ -1612,9 +1646,8 @@ export async function getContext(ctx, opts = {}) {
             sessionId: opts.currentSessionId,
         })
         : null;
-    // W1: pre-existing leak; same `requested: undefined` ambientAdmitEntry
-    // already uses when it scope-filters memory rows above.
-    const activeSnapshot = rawActiveSnapshot && passesScopeFilterForRecall(rowScope(rawActiveSnapshot), undefined)
+    // W1: the same envelope rule ambientAdmitEntry applies to memory rows.
+    const activeSnapshot = rawActiveSnapshot && passesScopeFilterForRecall(rowScope(rawActiveSnapshot), exactScope)
         ? rawActiveSnapshot
         : null;
     // Key on the RAW snapshot: a scope-hidden active session must not fall through to another session's ambient handoff.
@@ -1628,7 +1661,7 @@ export async function getContext(ctx, opts = {}) {
                 // codex P2: admit scope in SQL so a newer denied row can't hide an older eligible one before LIMIT 1.
                 scopeFilter: 'default-deny',
             });
-    const sessionHandoff = rawSessionHandoff && passesScopeFilterForRecall(rowScope(rawSessionHandoff), undefined)
+    const sessionHandoff = rawSessionHandoff && passesScopeFilterForRecall(rowScope(rawSessionHandoff), exactScope)
         ? rawSessionHandoff
         : null;
     // Raw session id here too: each event is admitted on its own scope, same as recall and the CLI.
@@ -1636,7 +1669,7 @@ export async function getContext(ctx, opts = {}) {
         ? listSessionEvents(ctx.hippoRoot, ctx.tenantId, {
             session_id: rawActiveSnapshot.session_id,
             limit: 5,
-        }).filter((e) => passesScopeFilterForRecall(rowScope(e), undefined))
+        }).filter((e) => passesScopeFilterForRecall(rowScope(e), exactScope))
         : [];
     const shownSnapshot = activeSnapshot && (!cost || pays(cost.snapshot(activeSnapshot))) ? activeSnapshot : null;
     const shownHandoff = sessionHandoff && (!cost || pays(cost.handoff(sessionHandoff))) ? sessionHandoff : null;
@@ -1650,7 +1683,7 @@ export async function getContext(ctx, opts = {}) {
             digestHiddenForHandoff = true;
             return false;
         }
-        return ambientAdmitEntry(e, currentProjectName, includeCrossProject);
+        return ambientAdmitEntry(e, currentProjectName, includeCrossProject, exactScope);
     };
     const ownSessionId = opts.currentSessionId || '';
     // Inside admit, not after the load, so the loader's window widens past a session's own items.
@@ -2198,10 +2231,10 @@ export function restoreDormant(ctx, id) {
         try {
             const dormant = readDormantSnapshot(db, ctx.tenantId, id);
             if (!dormant) {
-                throw new Error(`dormant memory not found: ${id}`);
+                throw new NotFoundError(`dormant memory not found: ${id}`);
             }
             if (db.prepare(`SELECT 1 FROM memories WHERE id = ?`).get(id) !== undefined) {
-                throw new Error(`memory ${id} is already active; forget it before restoring its dormant copy`);
+                throw new ConflictError(`memory ${id} is already active; forget it before restoring its dormant copy`);
             }
             const now = new Date();
             // Dormant rows are long-lived, so a snapshot can predate a field added
@@ -2260,7 +2293,7 @@ export function forgetDormant(ctx, id) {
     const db = openHippoDb(ctx.hippoRoot);
     try {
         if (!deleteDormantRow(db, ctx.tenantId, id)) {
-            throw new Error(`dormant memory not found: ${id}`);
+            throw new NotFoundError(`dormant memory not found: ${id}`);
         }
         try {
             appendAuditEvent(db, {
@@ -2271,8 +2304,9 @@ export function forgetDormant(ctx, id) {
                 metadata: { dormant: true },
             });
         }
-        catch {
+        catch (error) {
             // Best-effort, like every other forget audit row: the delete stands.
+            reportAuditWriteFailure('forget', String(error), id);
         }
     }
     finally {
@@ -2318,9 +2352,9 @@ export function quarantineList(ctx, opts = {}) {
 function loadPendingQuarantineRow(db, tenantId, id) {
     const row = getQuarantineRow(db, tenantId, id);
     if (!row)
-        throw new Error(`not quarantined: ${id}`);
+        throw new NotFoundError(`not quarantined: ${id}`);
     if (row.status !== 'pending')
-        throw new Error(`${id} is already ${row.status}`);
+        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). */
@@ -2338,7 +2372,7 @@ export function quarantineApprove(ctx, id) {
                 .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 Error(`memory ${id} scope changed since quarantine; refusing to approve`);
+                throw new ConflictError(`memory ${id} scope changed since quarantine; refusing to approve`);
             }
             approveQuarantineRow(db, ctx.tenantId, id, ctx.actor.subject);
             appendAuditEvent(db, {
@@ -2655,16 +2689,8 @@ export async function sleep(ctx, opts = {}) {
             }
         }
         catch (auditErr) {
-            // Audit emit failure must NOT mask the original phaseError. Log to
-            // stderr so the secondary failure is observable but does not throw.
-            // This guards the case where consolidation AND audit-emit fail in the
-            // same invocation against the same DB (correlated: same disk, same
-            // schema state) — losing the original error makes diagnosis much harder.
-            // SAFETY: this is a best-effort log message only; property access on
-            // any JS value is safe (undefined if absent), preserving the existing
-            // lenient formatting even when something non-Error was thrown.
-            // eslint-disable-next-line no-console
-            console.error(`[hippo] api.sleep audit emit failed: ${auditErr.message}`);
+            // Logged, never thrown: a second failure must not mask the original phaseError.
+            reportAuditWriteFailure('consolidate', String(auditErr));
         }
     }
 }

package/dist/audit.d.ts

@@ -33,6 +33,10 @@ export type AuditQueryFields = {
 };
 export declare function auditQueryFields(query: string): AuditQueryFields;
 export declare function appendAuditEvent(db: DatabaseSyncLike, opts: AppendAuditOpts): void;
+/** For callers that keep a mutation when its audit row fails: the failure is logged and counted, never silent. */
+export declare function reportAuditWriteFailure(op: AuditOp, reason: string, targetId?: string | null): void;
+/** Audit rows this process failed to write; the loopback `/health` body reports it. */
+export declare function auditWriteFailureCount(): number;
 export interface QueryAuditOpts {
     tenantId: string;
     op?: AuditOp;

package/dist/audit.js

@@ -1,5 +1,6 @@
 import { createHash } from 'node:crypto';
 import { canAutoDelete } from './memory.js';
+import { log } from './log.js';
 export const STOP_WORDS = new Set([
     'the', 'a', 'an', 'is', 'was', 'are', 'were', 'be', 'been', 'being',
     'to', 'of', 'in', 'for', 'on', 'with', 'at', 'by', 'from', 'it',
@@ -250,6 +251,16 @@ export function auditQueryFields(query) {
 export function appendAuditEvent(db, opts) {
     db.prepare(`INSERT INTO audit_log (ts, tenant_id, actor, op, target_id, metadata_json) VALUES (?, ?, ?, ?, ?, ?)`).run(new Date().toISOString(), opts.tenantId, opts.actor, opts.op, opts.targetId ?? null, JSON.stringify(opts.metadata ?? {}, bigintSafeReplacer));
 }
+let auditWriteFailures = 0;
+/** For callers that keep a mutation when its audit row fails: the failure is logged and counted, never silent. */
+export function reportAuditWriteFailure(op, reason, targetId) {
+    auditWriteFailures++;
+    log.error(`audit write failed: ${reason}`, { op, target: targetId ?? undefined });
+}
+/** Audit rows this process failed to write; the loopback `/health` body reports it. */
+export function auditWriteFailureCount() {
+    return auditWriteFailures;
+}
 export function queryAuditEvents(db, opts) {
     const where = ['tenant_id = ?'];
     const params = [opts.tenantId];

package/dist/autolearn.d.ts

@@ -20,7 +20,7 @@ export declare function extractLessons(gitLog: string, customPatterns?: string[]
  * steps: this function is the write-path gate, called by each caller that
  * actually stores a lesson, not by the parser itself.
  *
- * Order is preserved in both output arrays.
+ * Order is preserved in both output arrays; both hold lessons with secret shapes redacted.
  */
 export declare function partitionLessons(lessons: string[]): {
     kept: string[];

package/dist/autolearn.js

@@ -7,14 +7,16 @@ import { createMemory, Layer, DEFAULT_HALF_LIFE_DAYS } from './memory.js';
 import { loadAllEntries } from './store.js';
 import { textOverlap } from './search.js';
 import { isContentWorthStoring } from './audit.js';
+import { redactSecretsStrict } from './secret-detect.js';
 /** A memory of a failed command, "Command '<cmd>' failed: <truncated stderr>"; no store is in reach, so `hippo watch` re-derives its half-life from the store's config. */
 export function captureError(exitCode, stderr, command, tenantId) {
     // Truncate to first 500 chars to avoid storing megabytes of build logs
-    const wasTruncated = stderr.length > 500;
-    const truncated = stderr.slice(0, 500).trim();
+    const clean = redactSecretsStrict(stderr);
+    const wasTruncated = clean.length > 500;
+    const truncated = clean.slice(0, 500).trim();
     const suffix = wasTruncated ? ' [truncated]' : '';
     // Strip leading env var assignments (KEY=val or key=val) before the actual command name
-    const safeCmd = command.replace(/^([A-Za-z_][A-Za-z0-9_]*=\S+\s+)+/, '').trim() || '(redacted)';
+    const safeCmd = redactSecretsStrict(command.replace(/^([A-Za-z_][A-Za-z0-9_]*=\S+\s+)+/, '').trim()) || '(redacted)';
     const content = `Command '${safeCmd}' failed (exit ${exitCode}): ${truncated}${suffix}`;
     // Derive a sanitized tag from the command name (first word, strip path)
     const cmdBase = safeCmd.split(/\s+/)[0].replace(/[^a-zA-Z0-9-]/g, '');
@@ -78,12 +80,12 @@ export function extractLessons(gitLog, customPatterns) {
  * steps: this function is the write-path gate, called by each caller that
  * actually stores a lesson, not by the parser itself.
  *
- * Order is preserved in both output arrays.
+ * Order is preserved in both output arrays; both hold lessons with secret shapes redacted.
  */
 export function partitionLessons(lessons) {
     const kept = [];
     const dropped = [];
-    for (const lesson of lessons) {
+    for (const lesson of lessons.map((l) => redactSecretsStrict(l))) {
         if (isContentWorthStoring(lesson)) {
             kept.push(lesson);
         }

package/dist/capture-contract.d.ts

@@ -0,0 +1,47 @@
+/** A host lifecycle moment hippo can capture from. */
+export type CaptureEvent = 'prompt' | 'tool-failure' | 'pre-compact' | 'post-compact' | 'session-start' | 'session-end' | 'reset';
+/** What hippo read from one host payload, before anything is written. */
+export interface CaptureInput {
+    readonly runtime: string;
+    readonly event: CaptureEvent;
+    /** True when no host payload arrived: a person ran the verb by hand. */
+    readonly manual: boolean;
+    readonly sessionId: string | null;
+    readonly cwd: string | null;
+    readonly transcriptPath: string | null;
+    /** The host's own reason for the event, such as `auto` or `manual` compaction. */
+    readonly trigger: string | null;
+}
+/** The outcome of reading a payload: usable input, a payload hippo refuses, or no payload at all. */
+export type CaptureReceipt = {
+    readonly status: 'received';
+    readonly input: CaptureInput;
+} | {
+    readonly status: 'skipped' | 'unavailable';
+    readonly reason: string;
+};
+/** Working state saved before the host drops context, so the session can resume; it is not a lesson. */
+export interface Checkpoint {
+    readonly runtime: string;
+    readonly sessionId: string | null;
+    readonly task: string;
+    readonly summary: string;
+    readonly nextStep: string;
+    readonly savedAt: string;
+}
+/** How far capture has read one session's source, so a retry resumes instead of re-reading or skipping. */
+export interface ProgressCursor {
+    readonly runtime: string;
+    readonly sessionId: string;
+    readonly source: string;
+    /** Opaque position in the source, such as a byte offset or the last turn id read. */
+    readonly position: string;
+    readonly updatedAt: string;
+}
+/** A string guard that avoids `typeof`; it matches it for every value `JSON.parse` can produce. */
+export declare function isStringValue<T>(value: T): value is T & string;
+/** An object guard that avoids `typeof`; arrays count as objects, as they do for `typeof`. */
+export declare function isObjectLike<T>(value: T): value is T & object;
+/** Reads a Claude Code PreCompact payload; only an empty stdin counts as a manual run. */
+export declare function readClaudeCodePreCompact(stdinText: string | undefined, timedOut: boolean): CaptureReceipt;
+//# sourceMappingURL=capture-contract.d.ts.map

package/dist/capture-contract.js

@@ -0,0 +1,49 @@
+// The shared shape every agent adapter turns a host payload into, so capture code is written once for all runtimes.
+// Field meanings, statuses and how to add a runtime: docs/integrations/agent-inventory.md.
+/** A string guard that avoids `typeof`; it matches it for every value `JSON.parse` can produce. */
+export function isStringValue(value) {
+    return String(value) === value;
+}
+/** An object guard that avoids `typeof`; arrays count as objects, as they do for `typeof`. */
+export function isObjectLike(value) {
+    return value !== null && value instanceof Object;
+}
+/** Reads a Claude Code PreCompact payload; only an empty stdin counts as a manual run. */
+export function readClaudeCodePreCompact(stdinText, timedOut) {
+    const empty = !stdinText || stdinText.trim() === '';
+    if (timedOut && empty) {
+        return { status: 'unavailable', reason: 'no PreCompact payload arrived before the stdin wait window closed' };
+    }
+    const base = { runtime: 'claude-code', event: 'pre-compact' };
+    if (empty) {
+        return { status: 'received', input: { ...base, manual: true, sessionId: null, cwd: null, transcriptPath: null, trigger: null } };
+    }
+    let payload;
+    try {
+        payload = JSON.parse(stdinText.trim());
+    }
+    catch {
+        // Non-JSON stdin leaves payload undefined, which the shape check rejects like an explicit null.
+    }
+    // A bad payload is skipped, never treated as manual: discovery could pick up another session's transcript.
+    if (!isObjectLike(payload) || !('transcript_path' in payload) || !isStringValue(payload.transcript_path)) {
+        return { status: 'skipped', reason: 'malformed or incomplete PreCompact payload (missing string transcript_path)' };
+    }
+    const transcriptPath = payload.transcript_path;
+    // Path shape only: CLAUDE_CONFIG_DIR can move the transcript root, and a same-user process can already read every transcript.
+    if (!/\.jsonl$/i.test(transcriptPath)) {
+        return { status: 'skipped', reason: `payload transcript_path is not a .jsonl file: ${transcriptPath}` };
+    }
+    return {
+        status: 'received',
+        input: {
+            ...base,
+            manual: false,
+            sessionId: 'session_id' in payload && isStringValue(payload.session_id) ? payload.session_id : null,
+            cwd: 'cwd' in payload && isStringValue(payload.cwd) ? payload.cwd : null,
+            transcriptPath,
+            trigger: 'trigger' in payload && isStringValue(payload.trigger) ? payload.trigger : null,
+        },
+    };
+}
+//# sourceMappingURL=capture-contract.js.map