hippo-memory 1.63.2 → 1.64.1

package/dist/api/recall.js

@@ -18,12 +18,13 @@ import { physicsSearch } from '../search/physics-search.js';
 import { churnStaleFactor } from '../search/boosts.js';
 import { compareEntryIdentity } from '../compare.js';
 import { dropHeldCopies, duplicateKey, storedTextKeys } from '../same-text.js';
-import { loadConfig } from '../config.js';
+import { isSharedStore, loadConfig } from '../config.js';
+import { classifyOriginProject, projectNames } from '../project-identity.js';
 import { computePlanningFallacyOutput } from '../predictions/planning-fallacy.js';
 import { detectAnchoring, hashQueryText, biasHintEnabled } from '../recall-history.js';
 import { detectAvailabilityBias } from '../availability.js';
-import { passesScopeFilterForRecall, assertScopeRequestAllowed, isRestrictedScope } from '../recall-scope.js';
-import { RecallContractError } from './types.js';
+import { passesScopeFilterForRecall, assertScopeRequestAllowed, personalScopeOf } from '../recall-scope.js';
+import { ownerOrSubject, RecallContractError } from './types.js';
 /**
  * Shared construction helper for `RecallSuppressionSummary`. Used by
  * `api.recall`, `cmdRecall`, and the MCP `hippo_recall` handler so all three
@@ -60,44 +61,54 @@ export function recall(ctx, opts) {
     // A member key may not unlock a private or quarantined scope by naming it.
     assertScopeRequestAllowed(ctx.actor, opts.scope);
     const windowSize = recallWindowSize(opts);
-    return recallFrom(ctx, opts, windowSize, loadRecallSearchEntries(ctx.hippoRoot, opts.query, windowSize, ctx.tenantId, opts.scope, 'exact', false));
+    const own = personalScopeOf(ctx.actor) ?? undefined;
+    return recallFrom(ctx, opts, windowSize, loadRecallSearchEntries(ctx.hippoRoot, opts.query, windowSize, ctx.tenantId, opts.scope, 'exact', false, recallOrigin(opts), own), own);
+}
+function recallOrigin(opts) {
+    return opts.project ? projectNames(opts.project) : undefined;
+}
+function inCallerProject(entry, opts) {
+    return !opts.project || classifyOriginProject(entry.origin_project, opts.project) !== 'cross-project';
 }
 /** Mode-aware recall that strengthens each returned row; never writes last_retrieval_ids (contract lock). */
 export async function retrieve(ctx, opts) {
     assertScopeRequestAllowed(ctx.actor, opts.scope);
     const windowSize = recallWindowSize(opts);
+    // From the authenticated actor, never from RecallOpts, which a caller fills in.
+    const own = personalScopeOf(ctx.actor) ?? undefined;
     if (opts.showRanked)
-        return retrieveFromStore(ctx, opts, windowSize, opts.showRanked);
-    let candidates = loadRecallSearchEntries(ctx.hippoRoot, opts.query, windowSize, ctx.tenantId, opts.scope, 'exact', false);
+        return retrieveFromStore(ctx, opts, windowSize, opts.showRanked, own);
+    let candidates = loadRecallSearchEntries(ctx.hippoRoot, opts.query, windowSize, ctx.tenantId, opts.scope, 'exact', false, recallOrigin(opts), own);
     if (opts.mode === 'hybrid' || opts.mode === 'physics') {
-        const searchOpts = { budget: Infinity, hippoRoot: ctx.hippoRoot, scope: opts.scope ?? null, vectorCandidates: recallVectorSpec(ctx, opts) };
+        const searchOpts = { budget: Infinity, hippoRoot: ctx.hippoRoot, scope: opts.scope ?? null, vectorCandidates: recallVectorSpec(ctx, opts, own) };
         const ranked = opts.mode === 'physics'
             ? await physicsSearch(opts.query, candidates, { ...searchOpts, physicsConfig: loadConfig(ctx.hippoRoot).physics })
             : await hybridSearch(opts.query, candidates, searchOpts);
         const rankedIds = new Set(ranked.map((r) => r.entry.id));
         candidates = [...ranked.map((r) => r.entry), ...candidates.filter((e) => !rankedIds.has(e.id))];
     }
-    const result = recallFrom(ctx, opts, windowSize, candidates);
+    const result = recallFrom(ctx, opts, windowSize, candidates, own);
     strengthenRetrieved(ctx.hippoRoot, result.results.map((r) => r.id), { tenantId: ctx.tenantId, recallBoostAblated: isRecallBoostAblated() });
     return result;
 }
 /** api.retrieve's vector arm: the recall load's exact-scope rule, current rows only. */
-function recallVectorSpec(ctx, opts) {
+function recallVectorSpec(ctx, opts, own) {
     return {
         tenantId: ctx.tenantId,
-        scope: recallScopeFilter(opts.scope, 'exact'),
+        scope: recallScopeFilter(opts.scope, 'exact', own),
         includeSuperseded: false,
-        admit: (e) => passesScopeFilterForRecall(e.scope ?? null, opts.scope),
+        origin: recallOrigin(opts),
+        admit: (e) => passesScopeFilterForRecall(e.scope ?? null, opts.scope, own),
     };
 }
 // Tag, pin and recency boosts can lift a row from deep in the BM25 order, so MCP ranks a wide lexical window.
 const SHOW_RANKED_LEXICAL_WINDOW = 1000;
 /** `retrieve` under `showRanked`: physics when `mode` says so, hybrid otherwise, over a wide lexical window plus the nearest vectors. */
-async function retrieveFromStore(ctx, opts, windowSize, show) {
-    const loaded = loadRecallSearchEntries(ctx.hippoRoot, opts.query, Math.max(windowSize, SHOW_RANKED_LEXICAL_WINDOW), ctx.tenantId, opts.scope, 'exact', false);
-    const pool = loaded.filter((e) => passesScopeFilterForRecall(e.scope ?? null, opts.scope));
+async function retrieveFromStore(ctx, opts, windowSize, show, own) {
+    const loaded = loadRecallSearchEntries(ctx.hippoRoot, opts.query, Math.max(windowSize, SHOW_RANKED_LEXICAL_WINDOW), ctx.tenantId, opts.scope, 'exact', false, recallOrigin(opts), own);
+    const pool = loaded.filter((e) => passesScopeFilterForRecall(e.scope ?? null, opts.scope, own));
     // 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, vectorCandidates: recallVectorSpec(ctx, opts) };
+    const searchOpts = { budget: Infinity, hippoRoot: ctx.hippoRoot, vectorCandidates: recallVectorSpec(ctx, opts, own) };
     let ranked = opts.mode === 'physics'
         ? await physicsSearch(opts.query, pool, { ...searchOpts, physicsConfig: loadConfig(ctx.hippoRoot).physics })
         : await hybridSearch(opts.query, pool, searchOpts);
@@ -111,7 +122,7 @@ async function retrieveFromStore(ctx, opts, windowSize, show) {
         }
     }
     const window = ranked.slice(0, windowSize).map((r) => r.entry);
-    const result = recallFrom(ctx, { ...opts, suppressRecallTrace: true }, windowSize, window);
+    const result = recallFrom(ctx, { ...opts, suppressRecallTrace: true }, windowSize, window, own);
     // Rows the vector arm added count as candidates too.
     const inPool = new Set(pool.map((e) => e.id));
     const candidates = [...pool, ...ranked.map((r) => r.entry).filter((e) => !inPool.has(e.id))];
@@ -151,14 +162,14 @@ function recallWindowSize(opts) {
     }
     return opts.scorerWindow ?? DEFAULT_SEARCH_CANDIDATE_LIMIT;
 }
-function recallFrom(ctx, opts, windowSize, all) {
+function recallFrom(ctx, opts, windowSize, all, own) {
     const limit = opts.limit ?? 10;
-    const window = admitCandidates(opts, all, limit);
+    const window = admitCandidates(opts, all, limit, own);
     // One db handle spans the goal-stack boost and the audit and trace rows; it closes before the continuity block.
     const db = openHippoDb(ctx.hippoRoot);
     let bands;
     try {
-        bands = rankBands(db, ctx, opts, window, limit);
+        bands = rankBands(db, ctx, opts, window, limit, own);
         auditAndTraceRecall(db, ctx, opts, bands.rankedOut);
     }
     finally {
@@ -166,7 +177,7 @@ function recallFrom(ctx, opts, windowSize, all) {
     }
     const rankedOut = bands.rankedOut;
     const { continuity, continuityTokens } = opts.includeContinuity
-        ? loadContinuity(ctx, opts)
+        ? loadContinuity(ctx, opts, own)
         : { continuity: undefined, continuityTokens: undefined };
     // Query-derived, so MCP and CLI read this one hint instead of recomputing; HIPPO_AUTODEBIAS=off disables it.
     // The hint and the no-class-match / tiebreak watching variant are mutually exclusive; both go out as optional fields.
@@ -202,7 +213,7 @@ function recallFrom(ctx, opts, windowSize, all) {
     return result;
 }
 // The SQL load already applied tenant and scope; any recall-mode loader must go through loadRecallSearchEntries.
-function admitCandidates(opts, all, limit) {
+function admitCandidates(opts, all, limit, own) {
     const current = all.filter((e) => !e.superseded_by);
     let entries;
     if (opts.scope !== undefined && opts.scope !== '') {
@@ -211,7 +222,7 @@ function admitCandidates(opts, all, limit) {
     }
     else {
         // SQL pre-filtered ':private:' loosely before the window; this is the exact anchored `<source>:private:*` rule.
-        entries = current.filter((e) => !isRestrictedScope(e.scope ?? null));
+        entries = current.filter((e) => passesScopeFilterForRecall(e.scope ?? null, undefined, own));
     }
     const droppedPreRank = all.length - entries.length;
     entries = entries
@@ -223,7 +234,7 @@ function admitCandidates(opts, all, limit) {
     return { entries, baseSlice, droppedPreRank, droppedByBudget: entries.length - baseSlice.length };
 }
 // The goal-stack boost touches the primary band only; the fresh-tail and summary bands keep their fixed placement.
-function rankBands(db, ctx, opts, window, limit) {
+function rankBands(db, ctx, opts, window, limit, own) {
     let baseScored = window.baseSlice.map((entry, idx) => ({
         entry,
         score: Math.max(0, 1 - idx / Math.max(1, limit)),
@@ -239,7 +250,7 @@ function rankBands(db, ctx, opts, window, limit) {
         });
     }
     let substituted = (opts.summarizeOverflow ?? true) && window.entries.length > limit
-        ? substituteOverflow(ctx, opts, window.entries, baseScored.map((r) => r.entry), limit)
+        ? substituteOverflow(ctx, opts, window.entries, baseScored.map((r) => r.entry), limit, own)
         : [];
     let heldDropped = 0;
     if (!opts.keepHeldCopies) {
@@ -252,7 +263,7 @@ function rankBands(db, ctx, opts, window, limit) {
     const baseRanked = baseScored.map((r) => baseItem(r, opts, explainTrace));
     const summaryRanked = substituted.map((s) => summaryItem(s, opts));
     const freshRanked = (opts.freshTailCount ?? 0) > 0
-        ? freshTailBand(ctx, opts, baseRanked, summaryRanked, opts.keepHeldCopies ? [] : [...baseSlice, ...substituted.map((s) => s.entry)])
+        ? freshTailBand(ctx, opts, baseRanked, summaryRanked, opts.keepHeldCopies ? [] : [...baseSlice, ...substituted.map((s) => s.entry)], own)
         : [];
     return {
         rankedOut: [...freshRanked, ...baseRanked, ...summaryRanked],
@@ -264,7 +275,7 @@ function rankBands(db, ctx, opts, window, limit) {
 }
 // When the overflow holds 2+ children of one level-2 summary, that summary stands in for them, capped at 30% of
 // `limit`. Each one is tenant-scoped and re-checked against the scope filter; drillDown recovers the children.
-function substituteOverflow(ctx, opts, entries, baseSlice, limit) {
+function substituteOverflow(ctx, opts, entries, baseSlice, limit, own) {
     const overflow = entries.slice(limit);
     const baseIds = new Set(baseSlice.map((e) => e.id));
     const overflowByParent = new Map();
@@ -282,7 +293,7 @@ function substituteOverflow(ctx, opts, entries, baseSlice, limit) {
     if (eligibleParentIds.length === 0)
         return [];
     const parents = loadEntriesByIds(ctx.hippoRoot, eligibleParentIds, ctx.tenantId);
-    const eligibleParents = parents.filter((p) => (p.dag_level ?? 0) === 2 && !p.superseded_by && passesScopeFilterForRecall(p.scope ?? null, opts.scope));
+    const eligibleParents = parents.filter((p) => (p.dag_level ?? 0) === 2 && !p.superseded_by && passesScopeFilterForRecall(p.scope ?? null, opts.scope, own) && inCallerProject(p, opts));
     const maxSub = Math.max(1, Math.ceil(limit * 0.3));
     // Most overflowed children first; compareEntryIdentity only breaks a tie, which used to fall to scan order.
     eligibleParents.sort((a, b) => {
@@ -330,10 +341,10 @@ function summaryItem(s, opts) {
 }
 // The last N raw rows, so "what did I just see" always covers the recent window. A recent row already in the BM25
 // band is only tagged isFreshTail; new ones are prepended, so every recent row appears exactly once.
-function freshTailBand(ctx, opts, baseRanked, summaryRanked, shownEntries) {
+function freshTailBand(ctx, opts, baseRanked, summaryRanked, shownEntries, own) {
     // The session-id contract was already checked by recallWindowSize's preflight.
-    const recent = loadFreshRawMemories(ctx.hippoRoot, opts.freshTailCount ?? 0, ctx.tenantId, opts.freshTailSessionId);
-    const recentScoped = recent.filter((m) => passesScopeFilterForRecall(m.scope ?? null, opts.scope));
+    const recent = loadFreshRawMemories(ctx.hippoRoot, opts.freshTailCount ?? 0, ctx.tenantId, opts.freshTailSessionId, recallOrigin(opts));
+    const recentScoped = recent.filter((m) => passesScopeFilterForRecall(m.scope ?? null, opts.scope, own));
     const recentIdSet = new Set(recentScoped.map((m) => m.id));
     for (const r of baseRanked) {
         if (recentIdSet.has(r.id))
@@ -389,20 +400,24 @@ function auditAndTraceRecall(db, ctx, opts, rankedOut) {
     }
 }
 // No active snapshot means no anchor, so no handoff or events: a stale handoff from a closed session never resurfaces.
-function loadContinuity(ctx, opts) {
-    const snapshot = loadActiveTaskSnapshot(ctx.hippoRoot, ctx.tenantId);
+function loadContinuity(ctx, opts, own) {
+    // On a shared store the tenant's newest row is another developer's; no project keys to nothing, so the block is empty.
+    const key = isSharedStore(ctx.hippoRoot)
+        ? { owner: ownerOrSubject(ctx.actor), project: opts.project ? projectNames(opts.project) : [] }
+        : undefined;
+    const snapshot = loadActiveTaskSnapshot(ctx.hippoRoot, ctx.tenantId, key);
     const sessionId = snapshot?.session_id ?? undefined;
     const sessionHandoff = sessionId
-        ? loadLatestHandoff(ctx.hippoRoot, ctx.tenantId, sessionId)
+        ? loadLatestHandoff(ctx.hippoRoot, ctx.tenantId, sessionId, {}, key)
         : null;
     const recentSessionEvents = sessionId
         ? listSessionEvents(ctx.hippoRoot, ctx.tenantId, { session_id: sessionId, limit: 5 })
         : [];
     // The memory-recall scope rule: an explicit scope must match exactly; without one, private and legacy rows are denied.
     const rowScope = (r) => r?.scope ?? null;
-    const filteredSnapshot = snapshot && passesScopeFilterForRecall(rowScope(snapshot), opts.scope) ? snapshot : null;
-    const filteredHandoff = sessionHandoff && passesScopeFilterForRecall(rowScope(sessionHandoff), opts.scope) ? sessionHandoff : null;
-    const filteredEvents = recentSessionEvents.filter((e) => passesScopeFilterForRecall(rowScope(e), opts.scope));
+    const filteredSnapshot = snapshot && passesScopeFilterForRecall(rowScope(snapshot), opts.scope, own) ? snapshot : null;
+    const filteredHandoff = sessionHandoff && passesScopeFilterForRecall(rowScope(sessionHandoff), opts.scope, own) ? sessionHandoff : null;
+    const filteredEvents = recentSessionEvents.filter((e) => passesScopeFilterForRecall(rowScope(e), opts.scope, own));
     const continuity = {
         activeSnapshot: filteredSnapshot,
         sessionHandoff: filteredHandoff,

package/dist/api/remember.d.ts

@@ -19,6 +19,13 @@ export interface RememberOpts {
     afterWrite?: (db: DatabaseSyncLike, memoryId: string) => void;
     /** Connector-ingested content an agent doesn't control; gates detectInstruction. CLI/HTTP/MCP never set this. */
     untrusted?: boolean;
+    /** The caller's project: its name becomes the row's origin. Without it the store's fallback applies (NULL on a shared store). */
+    project?: {
+        readonly name: string;
+        readonly aliases?: readonly string[];
+    };
+    /** Store it in the caller's own personal scope, readable by its owner alone in every project; needs an owner on the actor and no `scope`. */
+    personal?: boolean;
 }
 export interface RememberResult {
     id: string;

package/dist/api/remember.js

@@ -5,10 +5,31 @@ import { quarantineScopeFor, recordQuarantine } from '../quarantine.js';
 import { createMemory } from '../memory.js';
 import { loadConfig } from '../config.js';
 import { vetSecrets } from '../secret-detect.js';
+import { assertCallerProject } from '../project-identity.js';
+import { BadRequestError } from '../api-errors.js';
+import { assertClientScope, personalScopeOf } from '../recall-scope.js';
+/** The scope a write lands in: the caller's own personal scope when asked for, else the client's, which may not be a personal one. */
+function rememberScope(ctx, opts) {
+    if (!opts.personal) {
+        assertClientScope(opts.scope);
+        return opts.scope ?? null;
+    }
+    if (opts.untrusted)
+        throw new Error('personal memories come from their owner, never from a connector');
+    if (opts.scope !== undefined)
+        throw new BadRequestError('send personal or scope, not both');
+    const own = personalScopeOf(ctx.actor);
+    if (own === null) {
+        throw new BadRequestError('personal memories need a key its owner minted, or a sign-in; owner ids over 239 characters or with control characters cannot hold them');
+    }
+    return own;
+}
 export function remember(ctx, opts) {
+    if (opts.project)
+        assertCallerProject(opts.project);
+    const requestedScope = rememberScope(ctx, opts);
     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(vetted.content, {
         kind: opts.kind ?? 'distilled',
         scope: detection.flagged ? quarantineScopeFor(requestedScope) : requestedScope,
@@ -32,7 +53,10 @@ export function remember(ctx, opts) {
             opts.afterWrite?.(db, memoryId);
         }
         : opts.afterWrite;
-    writeEntry(ctx.hippoRoot, entry, { actor: ctx.actor.subject, afterWrite });
+    // Aliases only widen what a reader matches; a row has one origin. A personal row's '' follows its owner into every project.
+    const origin = opts.personal ? '' : opts.project?.name;
+    const stamped = origin !== undefined ? { ...entry, origin_project: origin } : entry;
+    writeEntry(ctx.hippoRoot, stamped, { actor: ctx.actor.subject, afterWrite });
     const result = { id: entry.id, kind: entry.kind, tenantId: ctx.tenantId };
     if (detection.flagged)
         result.quarantined = { reason: detection.reason ?? 'unknown' };

package/dist/api/sleep-run.d.ts

@@ -0,0 +1,28 @@
+import { loadAllEntries } from '../store/entry-reads.js';
+import { deleteEntry } from '../store/delete-and-batch.js';
+import { auditMemories } from '../audit.js';
+import { autoShare } from '../shared.js';
+import { consolidate } from '../consolidate/sleep.js';
+import { loadConfig } from '../config.js';
+import { deduplicateStore } from '../dedupe.js';
+import { computeAmbientState } from '../ambient.js';
+import { loadPendingExtractionTenants } from '../graph/read.js';
+import { type ExtractResult } from '../graph-extract.js';
+import type { Context } from './types.js';
+import type { SleepOpts, SleepResult } from './sleep.js';
+/** Test-only seam: `runSleep` overrides force a phase to throw into emitSleepAudit's `partial: true` row; production never sets them. */
+export interface SleepPhases {
+    consolidate: typeof consolidate;
+    deduplicateStore: typeof deduplicateStore;
+    auditMemories: typeof auditMemories;
+    autoShare: typeof autoShare;
+    loadAllEntries: typeof loadAllEntries;
+    deleteEntry: typeof deleteEntry;
+    computeAmbientState: typeof computeAmbientState;
+    loadConfig: typeof loadConfig;
+    loadPendingExtractionTenants: typeof loadPendingExtractionTenants;
+    extractGraph: (hippoRoot: string, tenantId: string) => ExtractResult | Promise<ExtractResult>;
+}
+/** `sleep` with its phase dependencies overridable; tests pass stubs here, so the seam never touches the public `SleepOpts`. */
+export declare function runSleep(ctx: Context, opts: SleepOpts, overrides?: Partial<SleepPhases>): Promise<SleepResult>;
+//# sourceMappingURL=sleep-run.d.ts.map

package/dist/api/sleep-run.js

@@ -0,0 +1,267 @@
+// The sleep pipeline behind `sleep`, with its phase dependencies injectable; kept out of the package root.
+import { openHippoDb, closeHippoDb } from '../db.js';
+import { loadAllEntries } from '../store/entry-reads.js';
+import { deleteEntry, memoriesBackingObjects } from '../store/delete-and-batch.js';
+import { appendAuditEvent, reportAuditWriteFailure, auditMemories } from '../audit.js';
+import { autoShare } from '../shared.js';
+import { consolidate } from '../consolidate/sleep.js';
+import { failedUnitOf } from '../store/delete-and-batch.js';
+import { loadConfig } from '../config.js';
+import { deduplicateStore } from '../dedupe.js';
+import { computeAmbientState } from '../ambient.js';
+import { loadPendingExtractionTenants } from '../graph/read.js';
+import { markPendingProcessedUpTo } from '../graph/write.js';
+import { extractGraphChunked } from '../graph-extract.js';
+const DEFAULT_SLEEP_PHASES = {
+    consolidate,
+    deduplicateStore,
+    auditMemories,
+    autoShare,
+    loadAllEntries,
+    deleteEntry,
+    computeAmbientState,
+    loadConfig,
+    loadPendingExtractionTenants,
+    extractGraph: extractGraphChunked,
+};
+/** `sleep` with its phase dependencies overridable; tests pass stubs here, so the seam never touches the public `SleepOpts`. */
+export async function runSleep(ctx, opts, overrides = {}) {
+    const dryRun = Boolean(opts.dryRun);
+    const phases = { ...DEFAULT_SLEEP_PHASES, ...overrides };
+    // Phase counters for the consolidate audit emit (in finally).
+    // Accumulated as each phase completes so partial-failure paths still report
+    // accurate "what got done before the failure" data.
+    const counts = { consolidation: 0, dedup: 0, auditDeleted: 0, ambient: 0 };
+    let phaseError = null;
+    try {
+        return await runSleepPhases(ctx, opts, phases, counts);
+    }
+    catch (err) {
+        // SAFETY: phaseError is read via phaseError.message / (phaseError !==
+        // null) below, both safe even if a non-Error was thrown; this mirrors
+        // the existing lenient (err as Error) pattern used throughout this catch chain.
+        phaseError = err;
+        throw err;
+    }
+    finally {
+        emitSleepAudit(ctx, opts, dryRun, counts, phaseError);
+    }
+}
+async function runSleepPhases(ctx, opts, phases, counts) {
+    const dryRun = Boolean(opts.dryRun);
+    const snapshot = snapshotDirtyTenants(ctx, phases, dryRun);
+    // Phase 1: Consolidation.
+    const consolidateResult = await phases.consolidate(ctx.hippoRoot, { dryRun });
+    counts.consolidation = consolidateResult.semanticCreated + consolidateResult.merged;
+    const result = sleepResultFrom(consolidateResult, dryRun);
+    // Phase 2: Dedup (post-consolidate near-duplicate cleanup).
+    const dedupResult = phases.deduplicateStore(ctx.hippoRoot, { dryRun, actor: ctx.actor.subject });
+    counts.dedup = dedupResult.removed;
+    if (dedupResult.removed > 0)
+        result.deduped = dedupSummary(dedupResult);
+    // Phase 3: Quality audit (remove junk, report warnings; a dry run skips rows earlier phases would remove).
+    counts.auditDeleted = runQualityAudit(ctx, phases, dryRun, consolidateResult, dedupResult, result);
+    if (dryRun)
+        return result;
+    // Phase 4: Auto-share high-transfer-score memories to global.
+    if (!opts.noShare)
+        shareOnSleep(ctx, phases, result);
+    // Phase 5: Post-sleep ambient state summary.
+    counts.ambient = summarizeAmbient(ctx, phases, result);
+    await drainGraphQueue(ctx, phases, snapshot, result);
+    return result;
+}
+// Taken before any memory-deleting phase: queue rows cascade-delete with their mirror, so a later read would miss
+// tenants dedup touched. Fail-soft: a failed read skips the graph refresh this sleep and never aborts core sleep.
+function snapshotDirtyTenants(ctx, phases, dryRun) {
+    const snapshot = { dirtyTenants: [], error: null };
+    if (!dryRun) {
+        try {
+            snapshot.dirtyTenants = phases.loadPendingExtractionTenants(ctx.hippoRoot);
+        }
+        catch (snapErr) {
+            // 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.
+            snapshot.error = snapErr.message;
+        }
+    }
+    return snapshot;
+}
+function sleepResultFrom(consolidateResult, dryRun) {
+    const result = {
+        active: consolidateResult.decayed,
+        removed: consolidateResult.removed,
+        mergedEpisodic: consolidateResult.merged,
+        newSemantic: consolidateResult.semanticCreated,
+        dryRun,
+        details: consolidateResult.details,
+    };
+    // Set only when non-zero, so a store without dormant memories gets a
+    // byte-identical result (HTTP /v1/sleep, the CLI render snapshot).
+    if (consolidateResult.dormant > 0) {
+        result.dormant = consolidateResult.dormant;
+    }
+    if (consolidateResult.dormantExpired > 0) {
+        result.dormantExpired = consolidateResult.dormantExpired;
+    }
+    return result;
+}
+function dedupSummary(dedupResult) {
+    const semDups = dedupResult.pairs.filter((p) => p.keptLayer === 'semantic' && p.removedLayer === 'semantic').length;
+    const epiDups = dedupResult.pairs.filter((p) => p.keptLayer === 'episodic' && p.removedLayer === 'episodic').length;
+    const crossDups = dedupResult.pairs.filter((p) => p.keptLayer !== p.removedLayer).length;
+    return {
+        removed: dedupResult.removed,
+        semDups,
+        epiDups,
+        crossDups,
+    };
+}
+/** Returns how many audit errors were deleted, or would be under dryRun. */
+function runQualityAudit(ctx, phases, dryRun, consolidateResult, dedupResult, result) {
+    const planned = new Set(dryRun ? [...(consolidateResult.removedIds ?? []), ...dedupResult.pairs.map((p) => p.removed)] : []);
+    const allEntries = phases.loadAllEntries(ctx.hippoRoot).filter((e) => !planned.has(e.id));
+    const auditOut = phases.auditMemories(allEntries, memoriesBackingObjects(ctx.hippoRoot));
+    if (auditOut.issues.length === 0)
+        return 0;
+    const errors = auditOut.issues.filter((i) => i.severity === 'error');
+    const warnings = auditOut.issues.filter((i) => i.severity === 'warning');
+    let removed = 0;
+    for (const issue of errors) {
+        const reason = `sleep-audit: ${issue.reason}`;
+        if (dryRun || phases.deleteEntry(ctx.hippoRoot, issue.memoryId, { actor: ctx.actor.subject, reason, automatic: true }))
+            removed++;
+    }
+    if (removed > 0 || warnings.length > 0) {
+        result.audit = {
+            errorsRemoved: removed,
+            warningCount: warnings.length,
+        };
+    }
+    return removed;
+}
+function shareOnSleep(ctx, phases, result) {
+    const sleepConfig = phases.loadConfig(ctx.hippoRoot);
+    if (!sleepConfig.autoShareOnSleep)
+        return;
+    // Both skip counters are surfaced so the secret veto and the rejection tombstone are observable, not silent.
+    const autoShareStats = { secretSkipped: 0, rejectedSkipped: 0 };
+    const shared = phases.autoShare(ctx.hippoRoot, { minScore: 0.6, stats: autoShareStats });
+    if (shared.length > 0) {
+        result.shared = shared.length;
+    }
+    if (autoShareStats.secretSkipped > 0) {
+        result.secretSkipped = autoShareStats.secretSkipped;
+    }
+    if (autoShareStats.rejectedSkipped > 0) {
+        result.rejectedSkipped = autoShareStats.rejectedSkipped;
+    }
+}
+/** Returns the ambient total the audit row reports: 0 when ambient is off or no current row is left. */
+function summarizeAmbient(ctx, phases, result) {
+    const postSleepConfig = phases.loadConfig(ctx.hippoRoot);
+    if (!postSleepConfig.ambient.enabled)
+        return 0;
+    const postSleepEntries = phases.loadAllEntries(ctx.hippoRoot).filter((e) => !e.superseded_by);
+    if (postSleepEntries.length === 0)
+        return 0;
+    result.ambient = phases.computeAmbientState(postSleepEntries);
+    return result.ambient.totalMemories;
+}
+// Phase 6: rebuild the graph of every tenant marked dirty since the last sleep, so graph recall runs on fresh data.
+// Fault-isolated: consolidation has already committed, so no failure here aborts sleep; a failed tenant stays pending.
+async function drainGraphQueue(ctx, phases, snapshot, result) {
+    try {
+        if (snapshot.error) {
+            // Core sleep already succeeded; surface the skipped graph refresh as a detail.
+            result.details = [
+                ...(result.details ?? []),
+                `graph: dirty-tenant snapshot failed (skipped graph refresh): ${snapshot.error}`,
+            ];
+        }
+        let gTenants = 0;
+        let gEntities = 0;
+        let gRelations = 0;
+        // dirtyTenants was snapshotted before the memory-deleting phases above.
+        for (const { tenantId, maxPendingId } of snapshot.dirtyTenants) {
+            try {
+                const ext = await phases.extractGraph(ctx.hippoRoot, tenantId);
+                // Count the rebuild as soon as it succeeds — it happened regardless of
+                // the drain-mark below.
+                gTenants += 1;
+                gEntities += ext.entities;
+                gRelations += ext.relations;
+                if (ext.skipped) {
+                    result.details = [
+                        ...(result.details ?? []),
+                        `graph: ${ext.skipped} stale op(s) skipped for a tenant; the next sleep redoes them`,
+                    ];
+                }
+                // Watermark drain: only items enqueued before this rebuild started are marked; later arrivals stay pending.
+                // Marked only after the last chunk, so a run stopped between chunks leaves the tenant for the next one.
+                markPendingProcessedUpTo(ctx.hippoRoot, tenantId, maxPendingId);
+            }
+            catch (tenantErr) {
+                // 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.
+                result.details = [
+                    ...(result.details ?? []),
+                    `graph: extract failed for a dirty tenant (left pending): ${tenantErr.message}`,
+                ];
+            }
+        }
+        if (gTenants > 0) {
+            result.graph = { tenants: gTenants, entities: gEntities, relations: gRelations };
+        }
+    }
+    catch (graphErr) {
+        // 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.
+        result.details = [
+            ...(result.details ?? []),
+            `graph: drain phase failed (skipped): ${graphErr.message}`,
+        ];
+    }
+}
+// One 'consolidate' row per sleep, emitted from finally so a partial failure still reports what got done.
+// Its own handle; an audit failure is logged and never replaces the original phase error.
+function emitSleepAudit(ctx, opts, dryRun, counts, phaseError) {
+    try {
+        const db = openHippoDb(ctx.hippoRoot);
+        try {
+            const sleepAuditMetadata = {
+                consolidationCount: counts.consolidation,
+                dedupCount: counts.dedup,
+                auditDeletedCount: counts.auditDeleted,
+                ambientTotal: counts.ambient,
+                dryRun,
+                noShare: opts.noShare ?? false,
+                partial: phaseError !== null,
+                triggeredByTenant: ctx.tenantId, // preserve for audit forensics
+            };
+            if (phaseError)
+                sleepAuditMetadata.errorMessage = phaseError.message;
+            // A flush stopped between chunks names the unit it would have committed next, so a unit that fails every night can be found.
+            const nextUnitIds = failedUnitOf(phaseError);
+            if (nextUnitIds)
+                sleepAuditMetadata.nextUnitIds = nextUnitIds;
+            appendAuditEvent(db, {
+                tenantId: '__host__',
+                actor: ctx.actor.subject,
+                op: 'consolidate',
+                metadata: { ...sleepAuditMetadata },
+            });
+        }
+        finally {
+            closeHippoDb(db);
+        }
+    }
+    catch (auditErr) {
+        // Logged, never thrown: a second failure must not mask the original phaseError.
+        reportAuditWriteFailure('consolidate', String(auditErr));
+    }
+}
+//# sourceMappingURL=sleep-run.js.map

package/dist/api/sleep.d.ts

@@ -1,38 +1,11 @@
-import { loadAllEntries } from '../store/entry-reads.js';
-import { deleteEntry } from '../store/delete-and-batch.js';
-import { auditMemories } from '../audit.js';
-import { autoShare } from '../shared.js';
-import { consolidate } from '../consolidate/sleep.js';
-import { loadConfig } from '../config.js';
-import { deduplicateStore } from '../dedupe.js';
-import { computeAmbientState, type AmbientState } from '../ambient.js';
-import { loadPendingExtractionTenants } from '../graph/read.js';
-import { extractGraph } from '../graph-extract.js';
+import type { AmbientState } from '../ambient.js';
 import type { Context } from './types.js';
-/**
- * Options for `sleep` — run the pure-storage consolidation pipeline
- * (consolidate + dedup + audit + share + ambient) and return structured counts.
- *
- * Extracted from `cmdSleepCore` Phase 2-6 in Episode A. NOT covered by api.sleep:
- * the cli-only auto-learn phase (Phase 1: learnFromRepo + the agent memory import),
- * which is intrinsically host-bound (uses `process.cwd()` / `os.homedir()`).
- * Auto-learn stays in cli.ts cmdSleepCore as a pre-api block.
- *
- * The CLI `cmdSleep` wrapper continues to own the log-file tee + console
- * rendering + `process.exit`; `api.sleep` is pure (no console.log, no IO
- * beyond the store).
- */
+/** Options for `sleep`, one consolidation cycle on a SQLite store that returns counts; unlike `hippo sleep` it skips the auto-learn step. */
 export interface SleepOpts {
+    /** Report what a sleep would change without applying it; sharing, the ambient summary and the graph refresh are skipped. */
     dryRun?: boolean;
+    /** Skip copying high-scoring memories to the global store under `HIPPO_HOME`. Default false, so every tenant's memories are eligible; multi-tenant callers pass `true`. */
     noShare?: boolean;
-    /**
-     * @internal Test-only DI seam — see `tests/api-sleep-phase-faults.test.ts`.
-     * Override one or more phase dependencies (typically a throwing stub) to
-     * force mid-phase failure paths deterministically. Production callers
-     * MUST NOT use this field. The runtime defaults at `DEFAULT_SLEEP_PHASES`
-     * preserve all current behaviour when `__phases` is undefined.
-     */
-    __phases?: Partial<SleepPhases>;
 }
 export interface SleepResult {
     active: number;
@@ -90,19 +63,6 @@ export interface SleepResult {
     };
     details?: string[];
 }
-/** Test-only seam: `SleepOpts.__phases` forces a phase to throw into emitSleepAudit's `partial: true` row; production never sets it. */
-export interface SleepPhases {
-    consolidate: typeof consolidate;
-    deduplicateStore: typeof deduplicateStore;
-    auditMemories: typeof auditMemories;
-    autoShare: typeof autoShare;
-    loadAllEntries: typeof loadAllEntries;
-    deleteEntry: typeof deleteEntry;
-    computeAmbientState: typeof computeAmbientState;
-    loadConfig: typeof loadConfig;
-    loadPendingExtractionTenants: typeof loadPendingExtractionTenants;
-    extractGraph: typeof extractGraph;
-}
-/** Sleeps the WHOLE hippoRoot, every tenant, so /v1/sleep stays loopback-only; never auto-deletes pinned, raw, kept or object-backing rows. */
+/** Sleeps the WHOLE hippoRoot, every tenant, so /v1/sleep stays loopback-only; SQLite only; never auto-deletes pinned, raw, kept or object-backing rows. */
 export declare function sleep(ctx: Context, opts?: SleepOpts): Promise<SleepResult>;
 //# sourceMappingURL=sleep.d.ts.map