hippo-memory 1.43.3 → 1.45.0

package/dist/src/api.js

@@ -1,2109 +0,0 @@
-/**
- * Domain API layer for Hippo.
- *
- * Pure functions taking a Context (hippoRoot + tenantId + actor) plus
- * operation options. Both the CLI (direct mode) and the HTTP server
- * (`hippo serve`, A1) call into this module so the business logic lives
- * in exactly one place.
- */
-import { createHash } from 'node:crypto';
-import { openHippoDb, closeHippoDb } from './db.js';
-import { writeEntry, writeEntryDbOnly, 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, } from './store.js';
-import { RejectedValueError } from './rejection.js';
-import { rejectValue, unrejectValue, listRejectionsForTenant } from './reject-flow.js';
-import { formatHandoffEvidenceLine } from './handoff.js';
-import { createMemory, applyOutcome, calculateStrength, Layer, } from './memory.js';
-import { appendAuditEvent, queryAuditEvents, auditMemories, isContentWorthStoring, } from './audit.js';
-import { promoteToGlobal, getGlobalRoot, autoShare, searchBothHybrid } from './shared.js';
-import { writeRecallTrace, writeRecallTraceAtRoot, recordTraceOutcome } from './recall-trace.js';
-import { evalNow, isRecallBoostAblated } from './ablation.js';
-import { archiveRawMemory } from './raw-archive.js';
-import { createApiKey, listApiKeys, revokeApiKey, } from './auth.js';
-import { applyGoalStackBoost } from './goals.js';
-import { markRetrieved, estimateTokens, hybridSearch, physicsSearch } from './search.js';
-import { compareEntryIdentity, compareScoredResults } from './compare.js';
-import { scopeMatch } from './scope.js';
-import { consolidate } from './consolidate.js';
-import { loadConfig } from './config.js';
-import { resolveProjectIdentity, classifyOriginProject } from './project-identity.js';
-import { detectSecret } from './secret-detect.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 { detectAvailabilityBias } from './availability.js';
-/**
- * Helper for building process-local (admin-by-default) Actor values. v1.12.0
- * factory used by CLI / MCP / connector Context constructors so the role
- * boilerplate isn't repeated at every site. Bearer-authed callers (HTTP
- * /v1/*) construct Actor directly from the api_keys row's role column via
- * buildContextWithAuth in src/server.ts.
- */
-export function adminActor(subject) {
-    return { subject, role: 'admin' };
-}
-/**
- * Thrown by `api.recall` when a caller's options violate a recall contract
- * that has been opted into via env. Carries a stable `code` field for HTTP /
- * MCP / CLI render paths to discriminate without parsing the message.
- *
- * Codes:
- *   - 'fresh_tail_requires_session_id' — `freshTailCount > 0` AND no
- *     `freshTailSessionId` AND `HIPPO_REQUIRE_SESSION_SCOPED_FRESH_TAIL=1`.
- *     Default behaviour (env unset) returns tenant-wide rows; the env gate
- *     is opt-in so multi-session tenants can fail loud instead of silently
- *     surfacing cross-session rows tagged `isFreshTail=true`.
- *   - 'invalid_scorer_window' — `opts.scorerWindow` is set to a non-positive,
- *     non-integer, or non-finite value. Pre-v1.7.0 the value 0 routed
- *     through FTS/LIKE `LIMIT 0` and then fell through to an uncapped
- *     full-store fallback (codex v1.7.0 diff-pass P1). Validated upfront
- *     so the contract holds.
- */
-export class RecallContractError extends Error {
-    code;
-    constructor(code, message) {
-        super(message);
-        this.name = 'RecallContractError';
-        this.code = code;
-    }
-}
-// 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
-// without an api.ts import cycle — same pattern as classifyOriginProject
-// below. Imported here for this module's own call sites and re-exported for
-// back-compat (`api.isPrivateScope`, test imports). NOTE: the import statement
-// is required — a bare `export { x } from` re-export does not bind the local
-// names this module's ~9 call sites use.
-import { isPrivateScope, passesScopeFilterForRecall } from './recall-scope.js';
-export { isPrivateScope, passesScopeFilterForRecall };
-export { passesCliRecallScopeFilter } from './recall-scope.js';
-// v39: classifyOriginProject lives in project-identity.ts (leaf) so
-// shared.ts can use it without an api.ts import cycle. Re-exported here for
-// callers that already import the api surface.
-export { classifyOriginProject } from './project-identity.js';
-/**
- * v39: the single ambient-injection admission policy, shared by getContext
- * and the CLI-side ambient-state summary so the two cannot drift.
- *
- * - S4 secret veto is UNCONDITIONAL: neither crossProject nor
- *   contextProjectIsolation:false re-includes secrets. A flagged row only
- *   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.
- * - S3 origin partition: other-project rows are excluded unless
- *   `includeCrossProject`.
- */
-function ambientAdmitEntry(e, currentProjectName, includeCrossProject) {
-    if (!ambientSecretAdmit(e, currentProjectName))
-        return false;
-    if (!passesScopeFilterForRecall(e.scope ?? null, undefined))
-        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;
- * flagged rows with no project origin never ambient-inject.
- */
-export function ambientSecretAdmit(e, currentProjectName) {
-    if (!detectSecret(e).flagged)
-        return true;
-    const origin = e.origin_project;
-    if (origin === undefined || origin === null || origin === '')
-        return false;
-    return origin === currentProjectName;
-}
-// The pinned-only branch needs pins and recent-N candidates, not the corpus.
-function loadAmbientEntries(hippoRoot, tenantId, pinnedOnly, includeRecent, admit) {
-    if (!pinnedOnly)
-        return loadAllEntries(hippoRoot, tenantId).filter(admit);
-    // DF3's quality floor runs on the recent-N slice AFTER this load, so the load
-    // counts by it too, or it stops short of a store whose newest rows are junk.
-    const admitAmbient = (e) => admit(e) && (e.pinned || isContentWorthStoring(e.content));
-    return loadAmbientCandidates(hippoRoot, tenantId, includeRecent, admitAmbient);
-}
-export function remember(ctx, opts) {
-    const entry = createMemory(opts.content, {
-        kind: opts.kind ?? 'distilled',
-        scope: opts.scope ?? null,
-        owner: opts.owner ?? null,
-        artifact_ref: opts.artifactRef ?? null,
-        tags: opts.tags,
-        tenantId: ctx.tenantId,
-    });
-    // writeEntry threads ctx.actor.subject into its internal audit hook, so exactly
-    // one 'remember' event lands in the log with the supplied actor.
-    writeEntry(ctx.hippoRoot, entry, { actor: ctx.actor.subject, afterWrite: opts.afterWrite });
-    return { id: entry.id, kind: entry.kind, tenantId: ctx.tenantId };
-}
-/**
- * Shared construction helper for `RecallSuppressionSummary`. Used by
- * `api.recall`, `cmdRecall`, and the MCP `hippo_recall` handler so all three
- * pipelines produce the same shape without duplicating field-construction
- * logic. Pass-through identity today; kept as a helper so future field
- * additions (B4 interference counter wiring, etc.) land at one site.
- */
-export function buildSuppressionSummary(counts) {
-    return {
-        totalCandidates: counts.totalCandidates,
-        droppedPreRank: counts.droppedPreRank,
-        droppedByBudget: counts.droppedByBudget,
-        summarySubstitutionsAdded: counts.summarySubstitutionsAdded,
-        freshTailAdded: counts.freshTailAdded,
-        suppressedByInterference: counts.suppressedByInterference,
-    };
-}
-/**
- * Domain-level recall. Loads BM25-ranked candidates from SQLite scoped to
- * `ctx.tenantId`. The `mode` flag is accepted for forward compatibility (the
- * CLI exposes hybrid/physics paths) but Task 2 wires only the BM25 candidate
- * loader; later tasks can extend this to call the physics/hybrid scorer.
- *
- * **api.recall does NOT mutate `index.last_retrieval_ids`** (v1.11.5 contract
- * lock). The CLI `cmdRecall` (cli.ts) writes `last_retrieval_ids` because the
- * CLI is interactive (user is about to run `hippo outcome --good`). SDK callers
- * are programmatic: they either pass explicit ids to `api.outcome` or call
- * `api.getContext` first for the context-then-outcome workflow (getContext
- * DOES write `last_retrieval_ids`). Adding the side-effect here would change
- * `api.recall` from a pure read into a read+write, breaking SDK callers who
- * batch recall calls in a row. Locked by
- * `tests/api-recall-no-side-effects.test.ts`.
- */
-export function recall(ctx, opts) {
-    const limit = opts.limit ?? 10;
-    // F5 (v1.6.5) preflight — codex P1: original guard fired AFTER
-    // loadSearchEntries (which runs initStore, migrating legacy state on first
-    // call). For a true contract preflight we want the throw before any
-    // store-touching work. Single check here; the consumer site at
-    // `if (freshTailCount > 0)` does NOT re-validate (would be a no-op).
-    const freshTailCountPreflight = opts.freshTailCount ?? 0;
-    if (freshTailCountPreflight > 0 &&
-        !opts.freshTailSessionId &&
-        process.env.HIPPO_REQUIRE_SESSION_SCOPED_FRESH_TAIL === '1') {
-        throw new RecallContractError('fresh_tail_requires_session_id', 'fresh-tail requires a session id when HIPPO_REQUIRE_SESSION_SCOPED_FRESH_TAIL=1; ' +
-            'pass opts.freshTailSessionId or unset the env to allow tenant-wide fresh-tail.');
-    }
-    // F3 (v1.7.0): scorerWindow opt-in. When undefined (default),
-    // loadSearchEntries uses its own store-internal default — this
-    // preserves every pre-v1.7.0 caller's behaviour bit-for-bit (codex
-    // mk2-pass P0-1: defaulting to `limit` would have shrunk the
-    // candidate pool and killed overflow summaries).
-    // DEFAULT_SEARCH_CANDIDATE_LIMIT is imported from store.ts so the two
-    // values cannot drift (codex diff-pass P1 #3).
-    // Validate the input — codex diff-pass P1 #1 caught that scorerWindow=0
-    // would route through FTS/LIKE LIMIT 0 and then fall through to an
-    // uncapped full-store fallback. Reject non-positive / non-finite values.
-    if (opts.scorerWindow !== undefined) {
-        if (!Number.isFinite(opts.scorerWindow) ||
-            !Number.isInteger(opts.scorerWindow) ||
-            opts.scorerWindow < 1) {
-            throw new RecallContractError('invalid_scorer_window', `scorerWindow must be a positive integer; got ${opts.scorerWindow}`);
-        }
-    }
-    const windowSize = opts.scorerWindow ?? DEFAULT_SEARCH_CANDIDATE_LIMIT;
-    // v1.7.1 — root-cause fix for the `unknown:legacy` leak. Scope predicate
-    // is now pushed into `loadSearchRows` SQL via `loadRecallSearchEntries`.
-    // - opts.scope undefined / '': SQL excludes `unknown:legacy`.
-    // - opts.scope non-empty: SQL exact-matches m.scope = opts.scope.
-    // Tenant predicate still runs first, so a tenant-mismatched scope cannot
-    // surface another tenant's row even when both share the same scope string.
-    //
-    // **CALLER CONTRACT:** any future recall-mode loader MUST go through
-    // `loadRecallSearchEntries` (or invoke the SQL scope predicate equivalently).
-    // Calling `loadSearchEntries` from this code path re-introduces the v1.6.5
-    // codex-flagged leak. See `passesScopeFilterForRecall` in this file for
-    // the canonical recall-side scope rule (kept in sync with the SQL clause
-    // in loadSearchRows).
-    //
-    // Also fixes a latent code smell: pre-v1.7.1 passed `opts.scorerWindow`
-    // (raw, possibly undefined) where `windowSize` was intended.
-    // v1.12.13 / C5 — WYSIATI counters. Declared BEFORE the load step so the
-    // assignments at the existing filter sites (load / scope-filter / limit-
-    // slice / substitution / fresh-tail) are after declaration. The return at
-    // end-of-function reads them via buildSuppressionSummary.
-    let totalCandidatesCount = 0;
-    let droppedPreRankCount = 0;
-    let droppedByBudgetCount = 0;
-    let summarySubstitutionsCount = 0;
-    let freshTailAddedCount = 0;
-    const all = loadRecallSearchEntries(ctx.hippoRoot, opts.query, windowSize, ctx.tenantId, opts.scope);
-    // v1.12.13 / C5 — WYSIATI totalCandidates counter (post tenant + SQL scope
-    // predicate, pre JS scope filter).
-    totalCandidatesCount = all.length;
-    let entries;
-    if (opts.scope !== undefined && opts.scope !== '') {
-        // SQL already exact-matched in loadRecallSearchEntries; keep the JS
-        // filter as defense-in-depth so a future SQL-clause regression cannot
-        // silently surface cross-scope rows.
-        entries = all.filter((e) => e.scope === opts.scope);
-    }
-    else {
-        // SQL already excluded `unknown:legacy` AND (v1.25.0) pre-filtered
-        // ':private:' scopes with a conservative LIKE before the candidate
-        // window, so private rows can no longer starve admitted rows out of the
-        // LIMIT (codex review-stage P2). This JS filter stays as the exact
-        // anchored `<source>:private:*` rule (v1.2.1 generalization) and
-        // defense-in-depth: connector authors cannot silently surface private
-        // rows to no-scope callers even if the SQL clause regresses.
-        entries = all.filter((e) => !isPrivateScope(e.scope ?? null));
-    }
-    // v1.12.13 / C5 — WYSIATI dropped_pre_rank counter (JS scope filter drops
-    // for api.recall; cmdRecall pipeline rolls --outcome/--layer/--as-of/etc.
-    // into the same field per the plan's Task 3 mapping table).
-    droppedPreRankCount = all.length - entries.length;
-    // BM25 ordering already comes from loadRecallSearchEntries; cap to `limit`.
-    // Score is a placeholder — the physics/hybrid scorers in src/search.ts
-    // produce richer breakdowns and will replace this when wired up.
-    let baseSlice = entries.slice(0, limit);
-    // v1.12.13 / C5 — WYSIATI dropped_by_budget counter (candidates loaded but
-    // excluded by the final limit slice).
-    droppedByBudgetCount = entries.length - baseSlice.length;
-    // v1.7.4 -- single db handle for the goal-stack boost AND the audit-event
-    // emit below (codex P1: do not open a second short-lived handle for the
-    // appendAuditEvent call). The handle is closed in the matching `finally`
-    // immediately above the continuity block.
-    const db = openHippoDb(ctx.hippoRoot);
-    // v1.7.4 -- declared outside the try so the return statement (which lives
-    // outside, after the continuity block) can read the final values.
-    let rankedOut = [];
-    let tokensOut = 0;
-    let totalOut = 0;
-    // v1.7.4 -- dlPFC goal-stack boost on the PRIMARY band only. Appendix paths
-    // (fresh-tail, summary substitutions) are appended AFTER and keep their
-    // semantically-special placement.
-    let baseScored = baseSlice.map((entry, idx) => ({
-        entry,
-        score: Math.max(0, 1 - idx / Math.max(1, limit)),
-    }));
-    // A7 recall-trace: separate side-channel accumulator, allocated ONLY under
-    // explain. applyGoalStackBoost writes goal-boost steps here keyed by entry
-    // id; the baseRanked map reads it. When !explain it stays undefined and is
-    // never passed → the helper's default-path math is byte-identical.
-    const explainTrace = opts.explain ? new Map() : undefined;
-    try {
-        if (opts.sessionId && !opts.goalTag) {
-            baseScored = applyGoalStackBoost(db, baseScored, {
-                sessionId: opts.sessionId,
-                tenantId: ctx.tenantId,
-                limit,
-                // trace is optional on applyGoalStackBoost; explicitly passing
-                // undefined when !explain is identical to omitting the key.
-                trace: explainTrace,
-            });
-            baseSlice = baseScored.map((r) => r.entry);
-        }
-        // v1.5.0 DAG-aware substitution (Phase 1, Task 2). When entries overflow the
-        // limit and ≥2 of them share a level-2 parent summary, append the parent
-        // summary so the user sees a compact pointer to the dropped detail. Capped
-        // at ceil(limit * 0.3) substitutions so a runaway DAG can't expand results.
-        // Each substituted summary is tenant-scoped via loadEntriesByIds and
-        // re-checked against the active scope filter (default-deny on private).
-        // Drill-down (Task 3) reverses substitution: caller passes substitutedFor[]
-        // ids back through `drillDown` to recover the children.
-        const summarizeOverflow = opts.summarizeOverflow ?? true;
-        let substituted = [];
-        if (summarizeOverflow && entries.length > limit) {
-            const overflow = entries.slice(limit);
-            const baseIds = new Set(baseSlice.map((e) => e.id));
-            const overflowByParent = new Map();
-            for (const e of overflow) {
-                const parentId = e.dag_parent_id;
-                if (!parentId)
-                    continue;
-                if ((e.dag_level ?? 0) > 1)
-                    continue;
-                const list = overflowByParent.get(parentId) ?? [];
-                list.push(e);
-                overflowByParent.set(parentId, list);
-            }
-            const eligibleParentIds = Array.from(overflowByParent.keys()).filter((pid) => (overflowByParent.get(pid)?.length ?? 0) >= 2 && !baseIds.has(pid));
-            if (eligibleParentIds.length > 0) {
-                const parents = loadEntriesByIds(ctx.hippoRoot, eligibleParentIds, ctx.tenantId);
-                const eligibleParents = parents.filter((p) => (p.dag_level ?? 0) === 2 && passesScopeFilterForRecall(p.scope ?? null, opts.scope));
-                const maxSub = Math.max(1, Math.ceil(limit * 0.3));
-                // Order parents by overflow count descending so the most
-                // information-dense substitutions come first. Overflow count is the
-                // true primary key (unchanged); compareEntryIdentity is only a TAIL
-                // for the case two parents overflow the same number of children —
-                // without it that tie fell to SQLite scan order / loadEntriesByIds
-                // batch order (T2, deterministic tie keys).
-                eligibleParents.sort((a, b) => {
-                    const ac = overflowByParent.get(a.id)?.length ?? 0;
-                    const bc = overflowByParent.get(b.id)?.length ?? 0;
-                    return bc !== ac ? bc - ac : compareEntryIdentity(a, b);
-                });
-                substituted = eligibleParents.slice(0, maxSub).map((p) => ({
-                    entry: p,
-                    childIds: (overflowByParent.get(p.id) ?? []).map((e) => e.id),
-                }));
-            }
-        }
-        // v1.12.13 / C5 — WYSIATI summary_substitutions_added counter.
-        summarySubstitutionsCount = substituted.length;
-        // v1.7.4 -- baseScored carries the (possibly boosted) per-row scores. When
-        // the goal-stack boost did not run, scores are identical to the original
-        // positional placeholder; when it did run, scores reflect the boost AND the
-        // rows are in the boosted order (helper sort()).
-        const baseRanked = baseScored.map((r) => {
-            const item = {
-                id: r.entry.id,
-                content: r.entry.content,
-                score: r.score,
-                layer: r.entry.layer,
-                strength: r.entry.strength,
-            };
-            // A7 recall-trace: under explain, every api band carries rerankPipeline:'api';
-            // only baseRanked passes through the goal-boost helper, so only it can carry
-            // a step (and only for rows that actually matched an active goal).
-            if (opts.explain) {
-                item.rerankPipeline = 'api';
-                const step = explainTrace?.get(r.entry.id);
-                if (step)
-                    item.rerankTrace = [step];
-            }
-            return item;
-        });
-        // Substituted summaries land at the end with score = 0.5 (mid-rank), so
-        // they don't outrank top-N strong matches but stay above lowest-rank
-        // leaves on the consumer side. Caller sorts/filters as it sees fit.
-        const summaryRanked = substituted.map((s) => {
-            const item = {
-                id: s.entry.id,
-                content: s.entry.content,
-                score: 0.5,
-                layer: s.entry.layer,
-                strength: s.entry.strength,
-                isSummary: true,
-                substitutedFor: s.childIds,
-                descendantCount: s.entry.descendant_count ?? s.childIds.length,
-            };
-            // A7 recall-trace: summary band runs no re-ranking, but under explain it
-            // still carries the pipeline marker (no steps). Absent when !explain.
-            if (opts.explain)
-                item.rerankPipeline = 'api';
-            return item;
-        });
-        // v1.5.2 fresh-tail. Surface the last N kind='raw' rows so an agent's
-        // "what did I just see" recall path always covers the recent window even
-        // when the query terms don't match. Tenant + scope filtered.
-        //
-        // Dual-membership semantics: `loadSearchEntries` returns all tenant-scoped
-        // rows scored by BM25 (even rows with no token overlap can surface at
-        // score≈0), so a row in the recent window often ALSO appears as a BM25
-        // hit. We don't duplicate. Instead:
-        //   1. Mark any baseRanked entry that's in the recent set with isFreshTail.
-        //   2. Prepend genuinely-new recent rows (not in BM25 hits or summaries).
-        // Net: every recent row carries `isFreshTail=true`, exactly once.
-        const freshTailCount = opts.freshTailCount ?? 0;
-        const freshRanked = [];
-        if (freshTailCount > 0) {
-            // F5 contract guard fires at recall() preflight (top of function).
-            // No re-check needed here — by the time we reach this block the
-            // env/session policy has already been validated.
-            const recent = loadFreshRawMemories(ctx.hippoRoot, freshTailCount, ctx.tenantId, opts.freshTailSessionId);
-            const recentScoped = recent.filter((m) => passesScopeFilterForRecall(m.scope ?? null, opts.scope));
-            const recentIdSet = new Set(recentScoped.map((m) => m.id));
-            for (const r of baseRanked) {
-                if (recentIdSet.has(r.id))
-                    r.isFreshTail = true;
-            }
-            const seenIds = new Set([
-                ...baseRanked.map((r) => r.id),
-                ...summaryRanked.map((r) => r.id),
-            ]);
-            for (const m of recentScoped) {
-                if (seenIds.has(m.id))
-                    continue;
-                const item = {
-                    id: m.id,
-                    content: m.content,
-                    score: 1.0,
-                    layer: m.layer,
-                    strength: m.strength,
-                    isFreshTail: true,
-                };
-                // A7 recall-trace: fresh-tail band runs no re-ranking; under explain
-                // it carries the pipeline marker (no steps). Absent when !explain.
-                if (opts.explain)
-                    item.rerankPipeline = 'api';
-                freshRanked.push(item);
-                seenIds.add(m.id);
-            }
-        }
-        // v1.12.13 / C5 — WYSIATI fresh_tail_added counter. Captures the new rows
-        // prepended (NOT rows already in baseRanked that got tagged isFreshTail).
-        freshTailAddedCount = freshRanked.length;
-        rankedOut = [...freshRanked, ...baseRanked, ...summaryRanked];
-        tokensOut = rankedOut.reduce((acc, r) => acc + Math.ceil(r.content.length / 4), 0);
-        totalOut = entries.length;
-        // TODO(a1-task-4): emit via the shared audit hook in store.ts so we don't
-        // double-emit. Recall does not currently write through writeEntry, so no
-        // duplicate exists today, but we keep the same shape for symmetry.
-        // v1.7.4: reuse the `db` handle opened above for the goal-stack boost --
-        // single open/close spans both side effects.
-        // GDPR Path A: store a sha256 hash (16 hex chars) of the query text
-        // instead of the truncated query itself. If a caller queries with content
-        // that matches an archived (RTBF) memory, the original text must not
-        // persist in audit_log. query_length is preserved for debugging
-        // long-prompt patterns and compliance metrics.
-        appendAuditEvent(db, {
-            tenantId: ctx.tenantId,
-            actor: ctx.actor.subject,
-            op: 'recall',
-            metadata: {
-                query_hash: createHash('sha256').update(opts.query).digest('hex').slice(0, 16),
-                query_length: opts.query.length,
-                results: rankedOut.length,
-            },
-        });
-        // LC1 (docs/plans/2026-08-02-lc1-recall-trace-persistence.md): trace the
-        // returned ids+ranks+scores next to the audit emit, on the SAME open
-        // 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.
-        if (!opts.suppressRecallTrace) {
-            writeRecallTrace(db, {
-                tenantId: ctx.tenantId,
-                sessionId: opts.sessionId ?? null,
-                pipeline: 'api',
-                query: opts.query,
-                explainMode: opts.explain === true,
-                results: rankedOut.map((r) => ({
-                    memoryId: r.id,
-                    score: r.score,
-                    rerankSteps: r.rerankTrace,
-                })),
-            });
-        }
-    }
-    finally {
-        closeHippoDb(db);
-    }
-    let continuity;
-    let continuityTokens;
-    if (opts.includeContinuity) {
-        const snapshot = loadActiveTaskSnapshot(ctx.hippoRoot, ctx.tenantId);
-        // No active snapshot = no anchor = no handoff/events. Avoids resurrecting
-        // a stale handoff from a deleted/completed session.
-        const sessionId = snapshot?.session_id ?? undefined;
-        const sessionHandoff = sessionId
-            ? loadLatestHandoff(ctx.hippoRoot, ctx.tenantId, sessionId)
-            : null;
-        const recentSessionEvents = sessionId
-            ? listSessionEvents(ctx.hippoRoot, ctx.tenantId, { session_id: sessionId, limit: 5 })
-            : [];
-        // Scope filtering on continuity. Mirrors the memory-recall path:
-        //   - opts.scope set: EXACT match required (no cross-scope leakage)
-        //   - opts.scope unset: default-deny on ANY `<source>:private:*` AND on
-        //     legacy 'unknown:legacy' rows quarantined by the v23 migration.
-        //     Public and null scopes pass through.
-        // v1.1.0 wrongly wrote this as `opts.scope || isPublic`, which allowed
-        // ANY explicit scope to see ALL continuity rows. v1.2 closed the latent
-        // leak. v1.2.1 generalizes the private check from slack-only to any
-        // source so v1.3 GitHub (and future Jira/Linear/etc.) cannot leak.
-        const rowScope = (r) => r?.scope ?? null;
-        // v1.2: TaskSnapshot / SessionHandoff / SessionEvent now carry scope; the
-        // wrapper just normalizes null vs undefined. W1: was its own copy of
-        // passesScopeFilterForRecall (cloned 3x); calls the shared helper now.
-        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));
-        continuity = {
-            activeSnapshot: filteredSnapshot,
-            sessionHandoff: filteredHandoff,
-            recentSessionEvents: filteredEvents,
-        };
-        const tokenize = (s) => s ? Math.ceil(s.length / 4) : 0;
-        continuityTokens =
-            tokenize(filteredSnapshot?.task) +
-                tokenize(filteredSnapshot?.summary) +
-                tokenize(filteredSnapshot?.next_step) +
-                tokenize(filteredHandoff?.summary) +
-                tokenize(filteredHandoff?.nextAction) +
-                (filteredHandoff?.artifacts ?? []).reduce((acc, a) => acc + tokenize(a), 0) +
-                (filteredHandoff?.constraints ?? []).reduce((acc, c) => acc + tokenize(c), 0) +
-                tokenize(filteredHandoff?.evidence ? formatHandoffEvidenceLine(filteredHandoff.evidence) : null) +
-                tokenize(filteredHandoff?.outcome) +
-                tokenize(filteredHandoff?.targetRuntime) +
-                tokenize(filteredHandoff?.cardId) +
-                filteredEvents.reduce((acc, e) => acc + tokenize(e.content), 0);
-    }
-    // v0.32 / J3.2 — auto-injection of reference-class baserate when the
-    // query carries a forward-prediction phrase AND the closest matching
-    // class has closed historical data. Pipeline-invariant (queryText-
-    // derived), so MCP and CLI both read this as the single source of
-    // truth instead of recomputing (unlike suppressionSummary which IS
-    // per-pipeline). opts.actor threads through to the inner
-    // computePredictionBaserate call so MCP/HTTP-originated hints attribute
-    // correctly instead of defaulting to 'cli'. Disabled by HIPPO_AUTODEBIAS=off.
-    // v1.13.4: switched from computePlanningFallacyHint to
-    // computePlanningFallacyOutput so the no-class-match / tiebreak
-    // watching variant can also reach the caller surface. The two
-    // outputs are mutually exclusive; we splat both as optional fields.
-    const planningFallacyOutput = computePlanningFallacyOutput(ctx.hippoRoot, ctx.tenantId, opts.query, { actor: ctx.actor.subject });
-    const planningFallacyHint = planningFallacyOutput.hint ?? null;
-    const planningFallacyWatching = planningFallacyOutput.watching ?? null;
-    // v0.33 / J1 (v1.13.2) — recall-recurrence anchoring detection.
-    // Uses opts.recallHistory (caller-supplied snapshot) + this pipeline's
-    // own top-1 from rankedOut[0]. PURE read — does NOT mutate the snapshot
-    // or any caller-side Map. Disabled by HIPPO_ANCHORING=off (which gates
-    // even the detectAnchoring call so disabled tenants pay zero work on
-    // this surface). On CLI-routed call paths opts.recallHistory is
-    // undefined because cmdRecall computes its own hint separately; the
-    // 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) {
-        const queryHash = hashQueryText(opts.query);
-        const topMemoryId = rankedOut[0]?.id ?? null;
-        anchoringHint = detectAnchoring(opts.recallHistory, queryHash, topMemoryId);
-        if (anchoringHint?.reason === 'memory_dominance') {
-            suppressedByInterferenceCount = 1;
-            // Emit audit op for the memory-dominance detection.
-            const db = openHippoDb(ctx.hippoRoot);
-            try {
-                appendAuditEvent(db, {
-                    tenantId: ctx.tenantId,
-                    actor: ctx.actor.subject,
-                    op: 'recall_anchor_detected_memory_dominance',
-                    targetId: anchoringHint.memoryId,
-                    metadata: {
-                        memory_id: anchoringHint.memoryId,
-                        query_count: anchoringHint.queryCount ?? null,
-                    },
-                });
-            }
-            finally {
-                closeHippoDb(db);
-            }
-        }
-        else if (anchoringHint?.reason === 'query_repeat') {
-            const db = openHippoDb(ctx.hippoRoot);
-            try {
-                appendAuditEvent(db, {
-                    tenantId: ctx.tenantId,
-                    actor: ctx.actor.subject,
-                    op: 'recall_anchor_detected_query_repeat',
-                    targetId: anchoringHint.memoryId,
-                    metadata: { memory_id: anchoringHint.memoryId },
-                });
-            }
-            finally {
-                closeHippoDb(db);
-            }
-        }
-    }
-    // v1.13.x / J2 — availability/recency-bias detection. PURE read: compares
-    // the age distribution of the returned top-K (baseSlice, the post-goal-boost
-    // slice) against the matched candidate pool it was drawn from (entries, the
-    // scope/private-FILTERED candidate set baseSlice is sliced from — NOT `all`,
-    // which still holds private/cross-scope rows the caller is not eligible to see
-    // and that could never enter the top-K; counting them would leak hidden pool
-    // shape and inflate the signal). Soft warning only — does NOT filter, reorder,
-    // or suppress. Disabled by HIPPO_AVAILABILITY=off (gates even the detect call
-    // so disabled tenants pay zero work). Suppressed via opts.suppressAvailabilityHint
-    // when the caller computes its own per-pipeline hint (MCP), mirroring the J1
-    // 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) {
-        availabilityHint = detectAvailabilityBias({
-            topK: baseSlice.map((e) => ({ id: e.id, created: e.created })),
-            pool: entries.map((e) => ({ id: e.id, created: e.created })),
-        });
-        if (availabilityHint) {
-            const db = openHippoDb(ctx.hippoRoot);
-            try {
-                appendAuditEvent(db, {
-                    tenantId: ctx.tenantId,
-                    actor: ctx.actor.subject,
-                    op: 'recall_availability_detected',
-                    metadata: {
-                        recent_fraction: availabilityHint.recentFraction,
-                        older_passed_over: availabilityHint.olderCandidatesPassedOver,
-                        returned_count: availabilityHint.returnedCount,
-                    },
-                });
-            }
-            finally {
-                closeHippoDb(db);
-            }
-        }
-    }
-    const result = {
-        results: rankedOut,
-        total: totalOut,
-        tokens: tokensOut,
-        continuity,
-        continuityTokens,
-        windowSize,
-        suppressionSummary: buildSuppressionSummary({
-            totalCandidates: totalCandidatesCount,
-            droppedPreRank: droppedPreRankCount,
-            droppedByBudget: droppedByBudgetCount,
-            summarySubstitutionsAdded: summarySubstitutionsCount,
-            freshTailAdded: freshTailAddedCount,
-            suppressedByInterference: suppressedByInterferenceCount,
-        }),
-    };
-    if (planningFallacyHint)
-        result.planningFallacyHint = planningFallacyHint;
-    if (planningFallacyWatching)
-        result.planningFallacyWatching = planningFallacyWatching;
-    if (anchoringHint)
-        result.anchoringHint = anchoringHint;
-    if (availabilityHint)
-        result.availabilityHint = availabilityHint;
-    return result;
-}
-/**
- * Build a chronologically-ordered context window for a session. Adapts the
- * lossless-claw context-engine pattern to Hippo's score-ranked memory store.
- *
- * Algorithm:
- *   1. Load all kind='raw' rows for the session, tenant + scope filtered.
- *   2. Split: newest `freshTailCount` are protected (fresh tail).
- *   3. For older rows, when ≥2 share a level-2 parent, substitute the
- *      summary; everything else passes through as raw.
- *   4. Hippo-additive eviction: when over-budget, drop the lowest-strength
- *      non-fresh-tail item first. Fresh-tail rows are never evicted.
- *
- * Strength-weighted eviction is the differentiator from lossless-claw,
- * which evicts oldest-first. A high-strength older row (high retrieval
- * count, slow decay) survives; a low-strength recent row (newer but
- * unimportant) goes first.
- *
- * Returns `items: []` cleanly when:
- *   - sessionId is empty
- *   - no raws exist for the session
- *   - all rows fail the scope/tenant filter
- */
-export function assemble(ctx, sessionId, opts = {}) {
-    const budget = opts.budget ?? 4000;
-    const freshTailCount = opts.freshTailCount ?? 10;
-    const summarizeOlder = opts.summarizeOlder ?? true;
-    const rowCap = opts.rowCap ?? 5000;
-    if (!sessionId) {
-        return { sessionId, items: [], tokens: 0, totalRaw: 0, summarized: 0, evicted: 0, truncated: false };
-    }
-    const rows = loadSessionRawMemories(ctx.hippoRoot, sessionId, ctx.tenantId, rowCap);
-    const truncated = rows.length === rowCap;
-    // v1.6.3 senior-review P0-1: report the FULL post-filter row count even
-    // when the cap windows the loaded set. Pre-v1.6.3 used `scoped.length`
-    // which under-reported on long sessions and made consumers render
-    // wrong "session has N msgs" UX.
-    const scoped = rows.filter((r) => passesScopeFilterForRecall(r.scope ?? null, opts.scope));
-    let totalRaw;
-    if (truncated) {
-        // v1.6.3 codex P1 / senior P0: scope-aware unbounded COUNT. The helper
-        // SQL-encodes the same default-deny rule passesScopeFilterForRecall
-        // applies in TS, so a no-scope caller cannot infer private rows by
-        // comparing totalRaw to items.length on a truncated session.
-        totalRaw = countSessionRawMemories(ctx.hippoRoot, sessionId, ctx.tenantId, opts.scope);
-    }
-    else {
-        totalRaw = scoped.length;
-    }
-    if (scoped.length === 0) {
-        return { sessionId, items: [], tokens: 0, totalRaw, summarized: 0, evicted: 0, truncated };
-    }
-    // Split newest N into fresh tail; rest is older.
-    const tailStartIdx = Math.max(0, scoped.length - freshTailCount);
-    const olderRows = scoped.slice(0, tailStartIdx);
-    const tailRows = scoped.slice(tailStartIdx);
-    // Substitute parent summaries for older rows that share one.
-    const olderItems = [];
-    let summarized = 0;
-    if (summarizeOlder && olderRows.length > 0) {
-        const olderByParent = new Map();
-        for (const r of olderRows) {
-            if (!r.dag_parent_id)
-                continue;
-            const list = olderByParent.get(r.dag_parent_id) ?? [];
-            list.push(r);
-            olderByParent.set(r.dag_parent_id, list);
-        }
-        const eligibleParentIds = Array.from(olderByParent.keys()).filter((pid) => (olderByParent.get(pid)?.length ?? 0) >= 2);
-        const parents = eligibleParentIds.length > 0
-            ? loadEntriesByIds(ctx.hippoRoot, eligibleParentIds, ctx.tenantId)
-                .filter((p) => (p.dag_level ?? 0) === 2)
-                .filter((p) => passesScopeFilterForRecall(p.scope ?? null, opts.scope))
-            : [];
-        const claimedRawIds = new Set();
-        for (const parent of parents) {
-            const claimed = (olderByParent.get(parent.id) ?? []).map((r) => r.id);
-            claimed.forEach((id) => claimedRawIds.add(id));
-            olderItems.push({
-                id: parent.id,
-                content: parent.content,
-                createdAt: parent.earliest_at ?? parent.created,
-                isSummary: true,
-                substitutedFor: claimed,
-                strength: parent.strength,
-            });
-            summarized += claimed.length;
-        }
-        for (const r of olderRows) {
-            if (claimedRawIds.has(r.id))
-                continue;
-            olderItems.push({
-                id: r.id,
-                content: r.content,
-                createdAt: r.created,
-                strength: r.strength,
-            });
-        }
-    }
-    else {
-        for (const r of olderRows) {
-            olderItems.push({
-                id: r.id,
-                content: r.content,
-                createdAt: r.created,
-                strength: r.strength,
-            });
-        }
-    }
-    const tailItems = tailRows.map((r) => ({
-        id: r.id,
-        content: r.content,
-        createdAt: r.created,
-        isFreshTail: true,
-        strength: r.strength,
-    }));
-    // F4 (v1.6.5): byte compare canonical UTC ISO timestamps. ~50× faster than
-    // localeCompare and chronological by virtue of the timestamp invariant
-    // documented in src/memory.ts above MemoryEntry.
-    const cmpIso = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
-    olderItems.sort((a, b) => cmpIso(a.createdAt, b.createdAt));
-    tailItems.sort((a, b) => cmpIso(a.createdAt, b.createdAt));
-    let items = [...olderItems, ...tailItems];
-    let tokens = items.reduce((acc, it) => acc + Math.ceil(it.content.length / 4), 0);
-    let evicted = 0;
-    while (tokens > budget && items.length > 0) {
-        let worstIdx = -1;
-        let worstStrength = Infinity;
-        for (let i = 0; i < items.length; i++) {
-            if (items[i].isFreshTail)
-                continue;
-            if (items[i].strength < worstStrength) {
-                worstStrength = items[i].strength;
-                worstIdx = i;
-            }
-        }
-        if (worstIdx === -1)
-            break;
-        const cost = Math.ceil(items[worstIdx].content.length / 4);
-        items = items.filter((_, i) => i !== worstIdx);
-        tokens -= cost;
-        evicted++;
-    }
-    return { sessionId, items, tokens, totalRaw, summarized, evicted, truncated };
-}
-/**
- * Walk one step down the DAG from a level-2 (or higher) summary to its direct
- * children. Companion to `recall(... summarizeOverflow: true)` — when recall
- * surfaces a summary with `substitutedFor: [...]`, the caller drills into the
- * summary id to recover the original detail.
- *
- * Tenant scope: only summaries owned by `ctx.tenantId` are reachable. The same
- * scope filter that recall applies is enforced on the children — a level-2
- * summary in `slack:public:CGEN` cannot leak `slack:private:*` children even
- * if the underlying DAG accidentally linked across scopes.
- *
- * Returns a discriminated `DrillDownOutcome`: `DrillDownResult` on success,
- * or `{failure: '...'}` for `not_found` (covers genuinely-missing AND wrong-
- * tenant, intentionally indistinguishable), `not_drillable` (id is a leaf
- * row), or `scope_blocked` (caller has no scope grant for the row's scope).
- *
- * Pre-v1.6.4 returned null for all four cases. JS callers migrate via
- * `'failure' in result` checks; HTTP route maps `not_drillable` to 422.
- */
-export function drillDown(ctx, summaryId, opts = {}) {
-    const limit = opts.limit ?? 50;
-    // v0.30 / E5: depth defaults 1 (backward compat); hard cap 10 levels
-    // prevents pathological deep trees. CLI/HTTP/MCP reject invalid values.
-    const depth = Math.max(1, Math.min(Math.trunc(opts.depth ?? 1), 10));
-    const summary = readEntry(ctx.hippoRoot, summaryId, ctx.tenantId);
-    // No unscoped cross-tenant probe here — readEntry's null return covers
-    // both "doesn't exist" and "exists in another tenant" by design.
-    // Distinguishing them via an unscoped lookup would leak existence to
-    // unauthorised tenants. The two cases collapse into not_found.
-    if (!summary)
-        return { failure: 'not_found' };
-    if ((summary.dag_level ?? 0) < 2)
-        return { failure: 'not_drillable' };
-    if (!passesScopeFilterForRecall(summary.scope ?? null, undefined)) {
-        // codex round 3 P1: collapse to not_found. A distinguishable
-        // "scope_blocked" tells a no-scope caller "this row exists, just
-        // not for you" — same existence-leak the HTTP 404 collapse was
-        // already preventing. Match the HTTP behaviour at the API level.
-        return { failure: 'not_found' };
-    }
-    // v0.30 / E5: BFS walk levels 1..depth with visited-Set dedup. Defensive
-    // against shared-child data anomalies (dag_parent_id has no uniqueness
-    // constraint, so a misconfigured tree could double-emit at depth > 1).
-    // Each level uses loadChildrenOf which is tenant-scoped via ctx.tenantId.
-    const collected = [];
-    const visited = new Set([summaryId]);
-    let frontier = [summaryId];
-    // independent-review MED #4 fold: track level-0 direct-children count
-    // separately so the descendantCount fallback (for legacy summaries with
-    // null descendant_count) reflects DIRECT children, not BFS-collected total.
-    let level0DirectCount = 0;
-    for (let level = 0; level < depth; level++) {
-        const nextFrontier = [];
-        for (const parentId of frontier) {
-            const kids = loadChildrenOf(ctx.hippoRoot, parentId, ctx.tenantId);
-            const eligibleKids = kids.filter((c) => passesScopeFilterForRecall(c.scope ?? null, undefined));
-            for (const k of eligibleKids) {
-                if (visited.has(k.id))
-                    continue;
-                visited.add(k.id);
-                collected.push(k);
-                nextFrontier.push(k.id);
-                if (level === 0)
-                    level0DirectCount++;
-            }
-        }
-        if (nextFrontier.length === 0)
-            break;
-        frontier = nextFrontier;
-    }
-    // Apply global cumulative token budget + limit cap on collected.
-    let children = collected;
-    let truncated = false;
-    if (opts.budget !== undefined) {
-        const out = [];
-        let used = 0;
-        for (const c of collected) {
-            const t = Math.ceil(c.content.length / 4);
-            if (out.length > 0 && used + t > opts.budget) {
-                truncated = true;
-                break;
-            }
-            out.push(c);
-            used += t;
-        }
-        children = out;
-    }
-    if (children.length > limit) {
-        children = children.slice(0, limit);
-        truncated = true;
-    }
-    return {
-        summary: {
-            id: summary.id,
-            content: summary.content,
-            // v0.30 / E5: descendant_count stays the summary's STORED value
-            // (direct children at creation time). totalChildren below reflects
-            // the full BFS collection at the requested depth.
-            // independent-review MED #4 fold: legacy fallback uses level-0 direct
-            // count (NOT collected.length which is BFS-depth-N total).
-            descendantCount: summary.descendant_count ?? level0DirectCount,
-            earliestAt: summary.earliest_at ?? null,
-            latestAt: summary.latest_at ?? null,
-        },
-        children: children.map((c) => ({
-            id: c.id,
-            content: c.content,
-            layer: c.layer,
-            dagLevel: c.dag_level ?? 0,
-            created: c.created,
-        })),
-        // v0.30 / E5: totalChildren = BFS-collected count (depth-aware). For
-        // depth=1 this equals the eligible direct-children count (backward
-        // compat). For depth>1 it is the cumulative count across levels.
-        totalChildren: collected.length,
-        truncated,
-    };
-}
-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;
-            const updated = applyOutcome(entry, good);
-            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 forget(ctx, id) {
-    const db = openHippoDb(ctx.hippoRoot);
-    try {
-        // SAFETY: row's shape matches the single `tenant_id` column named in
-        // the SELECT above.
-        const row = db
-            .prepare(`SELECT tenant_id FROM memories WHERE id = ?`)
-            .get(id);
-        if (!row || row.tenant_id !== ctx.tenantId) {
-            throw new Error(`memory not found: ${id}`);
-        }
-    }
-    finally {
-        closeHippoDb(db);
-    }
-    const removed = deleteEntry(ctx.hippoRoot, id, { actor: ctx.actor.subject });
-    if (!removed) {
-        throw new Error(`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
-    // it. api.remember cannot take the same move; see the server route.
-    updateStats(ctx.hippoRoot, { forgotten: 1 });
-    return { ok: true, id };
-}
-/**
- * Reject a value: tombstone its normalized digest so a matching write is
- * refused everywhere (remember/capture/import/sync) until `unreject`. Two
- * forms — pass exactly one:
- *  - `memoryId`: reject the CURRENT content of an existing memory. Removes
- *    that row and every other live row in the tenant whose normalized
- *    digest matches (not just the id passed).
- *  - `value`: pre-emptive form — tombstone content that may not currently
- *    be stored (or is already gone). Zero removals.
- *
- * `reason` is required (the tombstone stores no content; reason is its
- * only human-readable identity). Throws if the memory id is not found in
- * `ctx.tenantId`, or if both/neither of `memoryId`/`value` are given.
- */
-export function reject(ctx, opts) {
-    if (opts.memoryId !== undefined) {
-        // Tenant scope, same not-found-shaped denial as forget/promote above:
-        // rejectValue itself also tenant-checks the id, but pre-checking here
-        // keeps the error message consistent with the rest of this module.
-        const db = openHippoDb(ctx.hippoRoot);
-        try {
-            // SAFETY: row's shape matches the single `tenant_id` column named in
-            // the SELECT above.
-            const row = db
-                .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}`);
-            }
-        }
-        finally {
-            closeHippoDb(db);
-        }
-    }
-    const result = rejectValue({
-        hippoRoot: ctx.hippoRoot,
-        tenantId: ctx.tenantId,
-        actor: ctx.actor.subject,
-        reason: opts.reason,
-        memoryId: opts.memoryId,
-        value: opts.value,
-    });
-    return { digest: result.digest, removedIds: result.removedIds };
-}
-/**
- * Delete a tombstone by exact digest or unambiguous prefix, restoring the
- * value's writability — the only v1 escape hatch (no per-write force flag).
- * Throws if `digestOrPrefix` matches no tombstone, is blank, or matches
- * more than one (use a longer prefix).
- */
-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}`);
-    }
-    if (outcome.status === 'ambiguous') {
-        throw new Error(`"${digestOrPrefix}" matches ${outcome.candidates.length} tombstones; use a longer prefix`);
-    }
-    return { ok: true, digest: outcome.digest };
-}
-/** List every rejected-value tombstone for `ctx.tenantId`, newest first. */
-export function listRejections(ctx) {
-    return listRejectionsForTenant(ctx.hippoRoot, ctx.tenantId);
-}
-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 {
-        // SAFETY: row's shape matches the single `tenant_id` column named in
-        // the SELECT above.
-        const row = ownerDb
-            .prepare(`SELECT tenant_id FROM memories WHERE id = ?`)
-            .get(id);
-        if (!row || row.tenant_id !== ctx.tenantId) {
-            throw new Error(`memory not found: ${id}`);
-        }
-    }
-    finally {
-        closeHippoDb(ownerDb);
-    }
-    // promoteToGlobal threads ctx.actor.subject into the writeEntry call on the global
-    // db, which emits a 'remember' audit row. We then add the user-facing
-    // 'promote' event on the global db so the audit trail keeps the intent
-    // distinct from the underlying upsert.
-    const globalEntry = promoteToGlobal(ctx.hippoRoot, id, { actor: ctx.actor.subject, tenantId: ctx.tenantId });
-    const db = openHippoDb(getGlobalRoot());
-    try {
-        appendAuditEvent(db, {
-            tenantId: ctx.tenantId,
-            actor: ctx.actor.subject,
-            op: 'promote',
-            targetId: globalEntry.id,
-            metadata: { sourceId: id },
-        });
-    }
-    finally {
-        closeHippoDb(db);
-    }
-    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 Error(`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.`);
-    }
-    const newEntry = createMemory(newContent, {
-        layer: old.layer ?? Layer.Episodic,
-        tags: [...old.tags],
-        pinned: old.pinned,
-        source: old.source,
-        confidence: 'verified',
-        tenantId: ctx.tenantId,
-    });
-    // 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 Error(`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 (self-heals on next backfill
-        // via writeIndexMirror reading the DB) but DOES NOT desync the DB or
-        // roll back the supersede. Logged + swallowed, non-fatal.
-        try {
-            writeEntryMirrors(ctx.hippoRoot, db, newEntry);
-        }
-        catch (mirrorErr) {
-            console.error('supersede: mirror write failed (non-fatal, will self-heal):', 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.
-        // SAFETY: row's shape matches the single `tenant_id` column named in
-        // the SELECT above.
-        const row = db
-            .prepare(`SELECT tenant_id FROM memories WHERE id = ?`)
-            .get(id);
-        if (!row || row.tenant_id !== ctx.tenantId) {
-            throw new Error(`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) {
-            console.error(`archiveRaw: mirror cleanup failed for ${id} (will retry via reaper on next openHippoDb):`, 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.
-            db.prepare(`UPDATE raw_archive SET mirror_cleaned_at = ? WHERE memory_id = ?`).run(new Date().toISOString(), id);
-        }
-    }
-    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.
-    updateStats(ctx.hippoRoot, { forgotten: 1 });
-    // 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() };
-}
-/**
- * Mint a new API key. The new key is ALWAYS bound to `ctx.tenantId`. Callers
- * cannot override the tenant via the opts bag — a previous `tenantId` field
- * was removed because the HTTP layer would happily forward `body.tenantId`,
- * letting tenant A mint a key for tenant B. The HTTP route handler at
- * `src/server.ts` POST /v1/auth/keys mirrors this: it ignores any body
- * `tenantId` and uses the resolved Bearer's tenant exclusively.
- *
- * Per A5 v2 follow-ups (TODOS.md), `auth_create` is currently unaudited —
- * we intentionally match that behavior here for consistency. When A5 v2
- * lands and adds the audit op, this function should mirror the cli handler.
- */
-export function authCreate(ctx, opts) {
-    const db = openHippoDb(ctx.hippoRoot);
-    try {
-        const role = opts.role ?? 'admin';
-        const result = createApiKey(db, { tenantId: ctx.tenantId, label: opts.label, role });
-        // v1.12.4: audit emit (closes the gap v1.12.3 CHANGELOG flagged as deferred).
-        // Mirrors the auth_revoke pattern at authRevoke — same try/catch so audit
-        // failure can't crash a successful mint. The plaintext is NEVER logged;
-        // metadata carries label + role + the keyId (which is non-secret).
-        try {
-            appendAuditEvent(db, {
-                tenantId: ctx.tenantId,
-                actor: ctx.actor.subject,
-                op: 'auth_create',
-                targetId: result.keyId,
-                metadata: {
-                    label: opts.label ?? null,
-                    role,
-                },
-            });
-        }
-        catch {
-            // Audit must not crash a successful mint.
-        }
-        return { keyId: result.keyId, plaintext: result.plaintext, tenantId: ctx.tenantId, role };
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-/**
- * List API keys visible to the calling tenant.
- *
- * Divergence from `cmdAuthList` in src/cli.ts: the CLI today returns ALL keys
- * regardless of tenant (single-tenant deployments). The API surface is tenant-
- * scoped because future multi-tenant deployments will share a hippoRoot, and
- * tenant A must not see tenant B's keys. Read-only — no audit emit (matches A5).
- */
-export function authList(ctx, opts) {
-    const db = openHippoDb(ctx.hippoRoot);
-    try {
-        const all = listApiKeys(db, opts);
-        return all.filter((k) => k.tenantId === ctx.tenantId);
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-export function authRevoke(ctx, keyId) {
-    const db = openHippoDb(ctx.hippoRoot);
-    try {
-        // SAFETY: row's shape matches the three columns named in the SELECT
-        // above.
-        const row = db
-            .prepare(`SELECT key_id, tenant_id, revoked_at FROM api_keys WHERE key_id = ?`)
-            .get(keyId);
-        if (!row) {
-            throw new Error(`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}`);
-        }
-        let revokedAt;
-        let alreadyRevoked = false;
-        if (row.revoked_at) {
-            alreadyRevoked = true;
-            revokedAt = row.revoked_at;
-        }
-        else {
-            revokeApiKey(db, keyId);
-            // SAFETY: updated's shape matches the single `revoked_at` column named
-            // in the SELECT above.
-            const updated = db
-                .prepare(`SELECT revoked_at FROM api_keys WHERE key_id = ?`)
-                .get(keyId);
-            revokedAt = updated?.revoked_at ?? new Date().toISOString();
-        }
-        if (!alreadyRevoked) {
-            try {
-                appendAuditEvent(db, {
-                    tenantId: row.tenant_id, // M1: KEY's tenant, not ctx.tenantId.
-                    actor: ctx.actor.subject,
-                    op: 'auth_revoke',
-                    targetId: keyId,
-                });
-            }
-            catch {
-                // Audit must not crash a successful revoke.
-            }
-        }
-        return { ok: true, revokedAt };
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-/**
- * Read audit events scoped to `ctx.tenantId`. Read-only — no audit emit (matches
- * A5: cmdAuditList does not record a 'recall'-style read event).
- */
-export function auditList(ctx, opts) {
-    const db = openHippoDb(ctx.hippoRoot);
-    try {
-        return queryAuditEvents(db, {
-            tenantId: ctx.tenantId,
-            op: opts.op,
-            since: opts.since,
-            limit: opts.limit,
-        });
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-/**
- * Assemble a context bundle: recalled memories (pinned-only / strength-sorted
- * fallback / hybrid search) + active task snapshot + session handoff + recent
- * session events. Budget-bounded, tenant-scoped. Mutates `last_retrieval_ids`
- * + emits a 'recall' audit row for non-pinned, non-'*' queries.
- *
- * Behaves like the pre-extraction `cmdContext` data-loading + selection
- * pipeline. CLI presentation (markdown / json / additional-context rendering)
- * stays in `cli.ts`.
- *
- * Tenant scope: all `loadAllEntries` / snapshot / handoff / events reads use
- * `ctx.tenantId`. Cross-tenant rows are filtered out.
- *
- * Returns an empty result (`entries: []`, snapshot/handoff/events undefined)
- * when there's nothing to surface (no memories AND no snapshot AND no handoff
- * AND no recent events).
- */
-export async function getContext(ctx, opts = {}) {
-    const pinnedOnly = opts.pinnedOnly === true;
-    const budget = opts.budget ?? 1500;
-    const limit = opts.limit ?? Number.POSITIVE_INFINITY;
-    const includeRecent = opts.includeRecent ?? 0;
-    const activeScope = opts.scope ?? '';
-    if (budget <= 0) {
-        return { entries: [], tokens: 0 };
-    }
-    // Pinned-only path is allowed against an un-initialised local store (the
-    // UserPromptSubmit hook can run in directories without a .hippo). Non-pinned
-    // path requires an initialised local store; callers should check first.
-    const hasLocal = isInitialized(ctx.hippoRoot);
-    const query = (opts.q ?? '').trim() || '*';
-    const globalRoot = getGlobalRoot();
-    const hasGlobal = isInitialized(globalRoot);
-    // 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).
-    // 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);
-    const isolationEnabled = config.contextProjectIsolation !== false;
-    const currentProjectName = opts.currentProject ?? resolveProjectIdentity(process.cwd()).name;
-    const includeCrossProject = opts.crossProject === true || !isolationEnabled;
-    const ambientAdmit = (e) => ambientAdmitEntry(e, currentProjectName, includeCrossProject);
-    // Superseded rows never inject, and ambientAdmitEntry regex-scans content for
-    // secrets, so WHICH rows reach this predicate is what loadAmbientEntries cares
-    // about below.
-    const admit = (e) => !e.superseded_by && ambientAdmit(e);
-    // Tenant-scoped loads (v1.11.1 lesson: NEVER resolveTenantId({}) here).
-    let localEntries = hasLocal
-        ? loadAmbientEntries(ctx.hippoRoot, ctx.tenantId, pinnedOnly, includeRecent, admit)
-        : [];
-    let globalEntries = hasGlobal
-        ? loadAmbientEntries(globalRoot, ctx.tenantId, pinnedOnly, includeRecent, admit)
-        : [];
-    // Computed below, after markRetrieved runs, so avgStrength reflects the
-    // post-retrieval strengths rather than a stale pre-mutation snapshot.
-    let ambientState;
-    // DF1 T2: bounded read — an orphaned snapshot (no later pre-compact
-    // superseded it, no session-end closed it) must age out of this ambient
-    // surface instead of injecting into every future prompt forever. Owner
-    // reads (opts.currentSessionId matches the snapshot's session_id) stay
-    // unbounded; see loadFreshActiveTaskSnapshot's own doc comment for the
-    // exact null/empty-id matching rules.
-    const rowScope = (r) => r?.scope ?? null;
-    const rawActiveSnapshot = hasLocal
-        ? loadFreshActiveTaskSnapshot(ctx.hippoRoot, ctx.tenantId, {
-            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)
-        ? rawActiveSnapshot
-        : null;
-    // Key on the RAW snapshot: a scope-hidden active session must not fall through to another session's ambient handoff.
-    const rawSessionHandoff = !hasLocal
-        ? null
-        : rawActiveSnapshot?.session_id
-            ? loadLatestHandoff(ctx.hippoRoot, ctx.tenantId, rawActiveSnapshot.session_id)
-            : loadLatestHandoff(ctx.hippoRoot, ctx.tenantId, undefined, {
-                unfinishedOnly: true,
-                maxAgeMs: SNAPSHOT_AMBIENT_MAX_AGE_MS,
-                // 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)
-        ? rawSessionHandoff
-        : null;
-    // Raw session id here too: each event is admitted on its own scope, same as recall and the CLI.
-    const recentSessionEvents = hasLocal && rawActiveSnapshot?.session_id
-        ? listSessionEvents(ctx.hippoRoot, ctx.tenantId, {
-            session_id: rawActiveSnapshot.session_id,
-            limit: 5,
-        }).filter((e) => passesScopeFilterForRecall(rowScope(e), undefined))
-        : [];
-    if (localEntries.length === 0 &&
-        globalEntries.length === 0 &&
-        !activeSnapshot &&
-        !sessionHandoff &&
-        recentSessionEvents.length === 0) {
-        return { entries: [], tokens: 0 };
-    }
-    let selectedItems = [];
-    let totalTokens = 0;
-    if (pinnedOnly) {
-        // loadConfig is safe even when local isn't initialised — returns defaults.
-        const pinnedCfg = loadConfig(ctx.hippoRoot);
-        if (!pinnedCfg.pinnedInject.enabled) {
-            return { entries: [], tokens: 0 };
-        }
-        // Effective budget: explicit opts.budget wins over config.
-        const effBudget = opts.budget !== undefined ? budget : pinnedCfg.pinnedInject.budget;
-        const nowP = evalNow(); // honors HIPPO_FAKE_NOW (eval-only; see ablation.ts)
-        const selectedIds = new Set();
-        let usedP = 0;
-        // Pinned entries are explicit user intent, the recent-N list an automatic
-        // backfill. Both loops share ONE budget and the recent loop runs first, so
-        // pins are ranked here and reserve their share before it can spend.
-        const pinnedLocal = localEntries.filter((e) => e.pinned);
-        const pinnedGlobal = globalEntries.filter((e) => e.pinned);
-        const rankedPinned = [
-            ...pinnedLocal.map((e) => ({ entry: e, isGlobal: false })),
-            ...pinnedGlobal.map((e) => ({ entry: e, isGlobal: true })),
-        ]
-            .map(({ entry, isGlobal }) => {
-            const scopeSig = scopeMatch(entry.tags, activeScope);
-            const sBst = scopeSig === 1 ? 1.5 : scopeSig === -1 ? 0.5 : 1.0;
-            return {
-                entry,
-                score: calculateStrength(entry, nowP) * (isGlobal ? 1 / 1.2 : 1) * sBst,
-                tokens: estimateTokens(entry.content),
-                isGlobal,
-            };
-        })
-            .sort(compareScoredResults);
-        // Mirror the pinned admission loop's own `continue`-not-`break`
-        // semantics (further down) so the reserve equals what that loop will
-        // actually admit -- a big pin near the front should not block smaller
-        // pins behind it from reserving their share too.
-        // Dedupe by id: `syncGlobalToLocal` copies global rows into the local
-        // store preserving `entry.id`, so a synced pin appears in BOTH
-        // `pinnedLocal` and `pinnedGlobal` and would otherwise reserve its cost
-        // twice. The admission loop already dedupes via `selectedIds`; the
-        // reserve has to mirror that or it silently starves recents of budget a
-        // single returned pin never needed.
-        let pinnedReserve = 0;
-        const reservedIds = new Set();
-        for (const r of rankedPinned) {
-            if (reservedIds.has(r.entry.id))
-                continue;
-            if (pinnedReserve + r.tokens <= effBudget) {
-                pinnedReserve += r.tokens;
-                reservedIds.add(r.entry.id);
-            }
-        }
-        // Known, accepted tradeoff: a pin that also lands in the recent-N slice
-        // is counted once in `pinnedReserve` (here) AND admitted again by the
-        // recent loop below, so a little budget goes unused (`recentBudget` is
-        // more conservative than it needs to be in that case). That only
-        // under-fills recents slightly -- it never displaces a pin -- so it is
-        // the safe direction and is not worth extra bookkeeping to recover.
-        const recentBudget = Math.max(0, effBudget - pinnedReserve);
-        if (includeRecent > 0) {
-            const recent = [
-                ...localEntries.map((entry) => ({ entry, isGlobal: false })),
-                ...globalEntries.map((entry) => ({ entry, isGlobal: true })),
-            ]
-                // T2 (src/compare.ts) note: this already carries an explicit
-                // per-instance tiebreak (created desc -> id localeCompare) and is
-                // deliberately left as-is rather than routed through
-                // compareEntryIdentity. `created` reflects ingest order, so it is
-                // cross-ingest stable at ms granularity; the residual is honest,
-                // not silently ignored — rows created in the same millisecond fall
-                // to `id.localeCompare`, which is per-instance random (id is
-                // crypto.randomUUID()), so this listing is per-instance-
-                // deterministic but NOT cross-ingest-stable under same-ms
-                // collisions.
-                .sort((a, b) => {
-                const byCreated = Date.parse(b.entry.created) - Date.parse(a.entry.created);
-                return byCreated !== 0 ? byCreated : b.entry.id.localeCompare(a.entry.id);
-            })
-                // DF3 (docs/plans/2026-08-23-df3-include-recent-quality-floor.md):
-                // filter before slice, not after — the caller asked for N recent
-                // *useful* entries, so a junk row must be skipped and backfilled
-                // past, not counted against the N. Skip-only: no mutation, no audit
-                // row, nothing becomes unrecoverable.
-                //
-                // `entry.pinned ||` bypass IS needed here (codex review finding,
-                // corrects the earlier claim in this comment that it wasn't): under
-                // budget pressure, a pinned entry that fails the heuristic gets
-                // dropped from this recent slice, and an unpinned entry backfills
-                // into its slot and consumes `usedP` in the loop below. By the time
-                // the pinned block runs (further down), the budget it needed is
-                // already spent, so it hits `continue` and the pinned entry is
-                // omitted entirely — the pinned block is NOT a safety net once the
-                // recent loop has already spent the shared budget.
-                .filter(({ entry }) => entry.pinned || isContentWorthStoring(entry.content))
-                .slice(0, includeRecent)
-                .map(({ entry, isGlobal }) => ({
-                entry,
-                score: calculateStrength(entry, nowP) * (isGlobal ? 1 / 1.2 : 1),
-                tokens: estimateTokens(entry.content),
-                isGlobal,
-            }));
-            for (const r of recent) {
-                if (selectedIds.has(r.entry.id))
-                    continue;
-                if (usedP + r.tokens > recentBudget)
-                    continue;
-                selectedItems.push(r);
-                selectedIds.add(r.entry.id);
-                usedP += r.tokens;
-            }
-        }
-        if (pinnedLocal.length === 0 &&
-            pinnedGlobal.length === 0 &&
-            selectedItems.length === 0) {
-            return { entries: [], tokens: 0 };
-        }
-        for (const r of rankedPinned) {
-            if (selectedIds.has(r.entry.id))
-                continue;
-            if (usedP + r.tokens > effBudget)
-                continue;
-            selectedItems.push(r);
-            selectedIds.add(r.entry.id);
-            usedP += r.tokens;
-        }
-        totalTokens = usedP;
-    }
-    else if (query === '*') {
-        // No query: return strongest memories by strength, up to budget.
-        const now = evalNow(); // honors HIPPO_FAKE_NOW (eval-only; see ablation.ts)
-        const localRanked = localEntries
-            .map((e) => ({
-            entry: e,
-            score: calculateStrength(e, now),
-            tokens: estimateTokens(e.content),
-            isGlobal: false,
-        }))
-            .sort(compareScoredResults);
-        const globalRanked = globalEntries
-            .map((e) => ({
-            entry: e,
-            score: calculateStrength(e, now) * (1 / 1.2),
-            tokens: estimateTokens(e.content),
-            isGlobal: true,
-        }))
-            .sort(compareScoredResults);
-        const combined = [...localRanked, ...globalRanked].sort(compareScoredResults);
-        let used = 0;
-        for (const r of combined) {
-            if (used + r.tokens > budget)
-                continue;
-            selectedItems.push(r);
-            used += r.tokens;
-        }
-        totalTokens = used;
-    }
-    else {
-        // Real query: hybrid search (global + local) or physics+hybrid (local only).
-        let results;
-        if (hasGlobal) {
-            // searchBothHybrid loads from the store roots itself, so the ambient
-            // filter above never saw its candidates. Admission runs INSIDE the
-            // search via the opt-in entryFilter, BEFORE ranking, cross-store
-            // content-dedupe, and budgeting - a post-filter instead would let an
-            // excluded row saturate the budget (codex rounds 1+3) or shadow its
-            // admitted duplicate in the dedupe pass (codex round 4). Recall paths
-            // never set entryFilter, so their behavior is unchanged.
-            const merged = await searchBothHybrid(query, ctx.hippoRoot, globalRoot, {
-                budget,
-                scope: activeScope,
-                tenantId: ctx.tenantId,
-                entryFilter: ambientAdmit,
-            });
-            const localIndex = loadIndex(ctx.hippoRoot);
-            results = merged.map((r) => ({
-                entry: r.entry,
-                score: r.score,
-                tokens: r.tokens,
-                isGlobal: !localIndex.entries[r.entry.id],
-            }));
-        }
-        else {
-            const ctxConfig = loadConfig(ctx.hippoRoot);
-            const usePhysicsCtx = ctxConfig.physics?.enabled !== false;
-            const ctxResults = usePhysicsCtx
-                ? await physicsSearch(query, localEntries, {
-                    budget,
-                    hippoRoot: ctx.hippoRoot,
-                    physicsConfig: ctxConfig.physics,
-                    scope: activeScope,
-                })
-                : await hybridSearch(query, localEntries, {
-                    budget,
-                    hippoRoot: ctx.hippoRoot,
-                    scope: activeScope,
-                });
-            results = ctxResults.map((r) => ({
-                entry: r.entry,
-                score: r.score,
-                tokens: r.tokens,
-                isGlobal: false,
-            }));
-        }
-        selectedItems = results;
-        totalTokens = results.reduce((sum, r) => sum + r.tokens, 0);
-        // A5 H4: emit recall audit row for context-mode searches (matches the
-        // 'recall' op emitted by api.recall for parity). pinnedOnly + '*' fallback
-        // never hit the search engines, so they don't emit (matches cmdContext).
-        const ctxRecallMetadata = {
-            query: query.slice(0, 200),
-            results: selectedItems.length,
-            mode: 'context',
-        };
-        if (hasLocal) {
-            const localDb = openHippoDb(ctx.hippoRoot);
-            try {
-                appendAuditEvent(localDb, {
-                    tenantId: ctx.tenantId,
-                    actor: ctx.actor.subject,
-                    op: 'recall',
-                    metadata: ctxRecallMetadata,
-                });
-            }
-            finally {
-                closeHippoDb(localDb);
-            }
-        }
-        if (hasGlobal) {
-            const globalDb = openHippoDb(globalRoot);
-            try {
-                appendAuditEvent(globalDb, {
-                    tenantId: ctx.tenantId,
-                    actor: ctx.actor.subject,
-                    op: 'recall',
-                    metadata: ctxRecallMetadata,
-                });
-            }
-            finally {
-                closeHippoDb(globalDb);
-            }
-        }
-    }
-    if (limit < selectedItems.length) {
-        selectedItems = selectedItems.slice(0, limit);
-        totalTokens = selectedItems.reduce((sum, r) => sum + r.tokens, 0);
-    }
-    // v39: annotate every returned entry with its origin and how it relates to
-    // the active project, so renderers can demarcate cross-project inclusions.
-    selectedItems = selectedItems.map((r) => ({
-        ...r,
-        origin: r.entry.origin_project ?? null,
-        category: classifyOriginProject(r.entry.origin_project, currentProjectName),
-    }));
-    if (selectedItems.length === 0 &&
-        !activeSnapshot &&
-        !sessionHandoff &&
-        recentSessionEvents.length === 0) {
-        // LC1 F5 fix: this bare early-return used to skip tracing entirely — a
-        // query that found nothing is exactly the coverage-gap signal Track LC
-        // needs. Write an empty trace (result_count 0, no result rows) so it
-        // lands in the training corpus. Never touches localIndex/
-        // last_retrieval_ids/last_trace_id — by construction it can't desync
-        // (mirrors the CLI zero-result path). Skipped under pinnedOnly (hot
-        // path stays read-only, same reason it skips markRetrieved). Fail-soft
-        // internally; never throws.
-        if (!pinnedOnly) {
-            // No snapshot in this branch, so the caller's own id is the only session to stamp.
-            writeRecallTraceAtRoot(ctx.hippoRoot, {
-                tenantId: ctx.tenantId,
-                sessionId: opts.currentSessionId || null,
-                pipeline: 'context',
-                query,
-                explainMode: false,
-                results: [],
-            });
-        }
-        return { entries: [], tokens: 0 };
-    }
-    // pinnedOnly is the UserPromptSubmit hot path — read-only so pinned
-    // memories don't inflate retrieval_count or extend half_life by 2 days per
-    // turn over a long session.
-    if (!pinnedOnly) {
-        const toUpdate = selectedItems.map((s) => s.entry);
-        const updatedEntries = markRetrieved(toUpdate);
-        const localIndex = loadIndex(ctx.hippoRoot);
-        // EVAL-ONLY ablation (see ablation.ts): under the recall flag,
-        // markRetrieved returns unmutated entries (ids preserved for outcome
-        // attribution) and persistence is skipped (identical-row writes still
-        // refresh updated_at / mirrors / DAG dirty flags).
-        if (!isRecallBoostAblated()) {
-            for (const u of updatedEntries) {
-                const targetRoot = localIndex.entries[u.id]
-                    ? ctx.hippoRoot
-                    : hasGlobal
-                        ? globalRoot
-                        : ctx.hippoRoot;
-                writeEntry(targetRoot, u);
-            }
-        }
-        localIndex.last_retrieval_ids = updatedEntries.map((u) => u.id);
-        // LC1 F1 structural fix (docs/plans/2026-08-02-lc1-recall-trace-persistence.md):
-        // write the trace FIRST — post-limit, post-annotation `selectedItems`
-        // actually returned, on a fresh short-lived connection (the audit
-        // handles above ~2410 are already closed by this point, matching this
-        // block's own per-call-handle convention: writeEntry, saveIndex) — then
-        // fold the resulting id into `localIndex` so the SAME `saveIndex` call
-        // below persists last_retrieval_ids + last_trace_id atomically.
-        // LOCKSTEP INVARIANT: last_trace_id must only ever advance together
-        // with last_retrieval_ids; a two-connection stamp-then-clear design
-        // could desync them on a crash between writes. A failed trace write
-        // (traceId null) sets last_trace_id to null rather than leaving the
-        // OLD id pointing at ids that are about to be overwritten. Fail-soft
-        // internally; never throws.
-        const traceId = writeRecallTraceAtRoot(ctx.hippoRoot, {
-            tenantId: ctx.tenantId,
-            sessionId: opts.currentSessionId || activeSnapshot?.session_id || null,
-            pipeline: 'context',
-            query,
-            explainMode: false,
-            results: selectedItems.map((s) => ({
-                memoryId: s.entry.id,
-                score: s.score,
-            })),
-        });
-        localIndex.last_trace_id = traceId !== null ? String(traceId) : null;
-        saveIndex(ctx.hippoRoot, localIndex);
-        updateStats(ctx.hippoRoot, { recalled: selectedItems.length });
-        // Replace selectedItems entries with markRetrieved-updated copies so
-        // the returned ContextResult reflects post-recall state.
-        selectedItems = selectedItems.map((s) => ({
-            ...s,
-            entry: updatedEntries.find((u) => u.id === s.entry.id) ?? s.entry,
-        }));
-        // Overlay by id (no re-read) so avgStrength reflects post-retrieval strength.
-        if (config.ambient.enabled) {
-            const updatedById = new Map(updatedEntries.map((u) => [u.id, u]));
-            const overlaid = [...localEntries, ...globalEntries].map((e) => updatedById.get(e.id) ?? e);
-            if (overlaid.length > 0) {
-                ambientState = computeAmbientState(overlaid);
-            }
-        }
-    }
-    return {
-        entries: selectedItems,
-        tokens: totalTokens,
-        activeSnapshot: activeSnapshot ?? undefined,
-        sessionHandoff: sessionHandoff ?? undefined,
-        recentEvents: recentSessionEvents.length > 0 ? recentSessionEvents : undefined,
-        ambientState,
-    };
-}
-const DEFAULT_SLEEP_PHASES = {
-    consolidate,
-    deduplicateStore,
-    auditMemories,
-    autoShare,
-    loadAllEntries,
-    deleteEntry,
-    computeAmbientState,
-    loadConfig,
-    loadPendingExtractionTenants,
-    extractGraph,
-};
-export async function sleep(ctx, opts = {}) {
-    const dryRun = Boolean(opts.dryRun);
-    // v1.12.2: resolve phase dependencies, allowing test-only `__phases`
-    // override to inject deterministic throws for mid-phase failure coverage.
-    const phases = { ...DEFAULT_SLEEP_PHASES, ...(opts.__phases ?? {}) };
-    // v1.11.5: 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.
-    let consolidationCount = 0;
-    let dedupCount = 0;
-    let auditDeletedCount = 0;
-    let ambientTotal = 0;
-    let phaseError = null;
-    let graphSnapshotError = null;
-    let result = null;
-    try {
-        // Snapshot dirty tenants BEFORE any memory-deleting phase (consolidate /
-        // dedup / audit). The graph_extraction_queue rows are FK'd to mirror
-        // memories with ON DELETE CASCADE, so a phase that deletes a queued mirror
-        // (e.g. dedup removing a near-duplicate superseding decision) would drop the
-        // tenant from a drain-time load and leave its graph stale (codex P1). The
-        // MAX(id) watermark captured here stays valid: arrivals during sleep get a
-        // higher id and remain pending.
-        //
-        // Fail-soft (codex P2): a queue-read failure here must NOT abort core sleep
-        // (consolidation / dedup / audit run regardless). On failure, skip graph
-        // refresh this sleep (recovered next sleep) and surface a detail once
-        // `result` exists (Phase 6).
-        let dirtyTenants = [];
-        if (!dryRun) {
-            try {
-                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.
-                graphSnapshotError = snapErr.message;
-            }
-        }
-        // Phase 1: Consolidation.
-        const consolidateResult = await phases.consolidate(ctx.hippoRoot, { dryRun });
-        consolidationCount = consolidateResult.semanticCreated + consolidateResult.merged;
-        result = {
-            active: consolidateResult.decayed,
-            removed: consolidateResult.removed,
-            mergedEpisodic: consolidateResult.merged,
-            newSemantic: consolidateResult.semanticCreated,
-            dryRun,
-            details: consolidateResult.details,
-        };
-        if (dryRun)
-            return result;
-        // Phase 2: Dedup (post-consolidate near-duplicate cleanup).
-        const dedupResult = phases.deduplicateStore(ctx.hippoRoot);
-        dedupCount = dedupResult.removed;
-        if (dedupResult.removed > 0) {
-            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;
-            result.deduped = {
-                removed: dedupResult.removed,
-                semDups,
-                epiDups,
-                crossDups,
-            };
-        }
-        // Phase 3: Quality audit (remove junk, report warnings).
-        const allEntries = phases.loadAllEntries(ctx.hippoRoot);
-        const auditOut = phases.auditMemories(allEntries);
-        if (auditOut.issues.length > 0) {
-            const errors = auditOut.issues.filter((i) => i.severity === 'error');
-            const warnings = auditOut.issues.filter((i) => i.severity === 'warning');
-            if (errors.length > 0) {
-                for (const issue of errors) {
-                    phases.deleteEntry(ctx.hippoRoot, issue.memoryId);
-                }
-            }
-            auditDeletedCount = errors.length;
-            if (errors.length > 0 || warnings.length > 0) {
-                result.audit = {
-                    errorsRemoved: errors.length,
-                    warningCount: warnings.length,
-                };
-            }
-        }
-        // Phase 4: Auto-share high-transfer-score memories to global.
-        if (!opts.noShare) {
-            const sleepConfig = phases.loadConfig(ctx.hippoRoot);
-            if (sleepConfig.autoShareOnSleep) {
-                // v1.25.0: surface the secret-veto skip count (v39 follow-up #2) so
-                // the veto is observable instead of silent.
-                // AT1: rejectedSkipped is autoShare's sibling counter for candidates
-                // the global store's rejection tombstone refused (threaded the same
-                // way as secretSkipped just below).
-                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;
-                }
-            }
-        }
-        // Phase 5: Post-sleep ambient state summary.
-        const postSleepConfig = phases.loadConfig(ctx.hippoRoot);
-        if (postSleepConfig.ambient.enabled) {
-            const postSleepEntries = phases.loadAllEntries(ctx.hippoRoot).filter((e) => !e.superseded_by);
-            if (postSleepEntries.length > 0) {
-                result.ambient = phases.computeAmbientState(postSleepEntries);
-                ambientTotal = result.ambient.totalMemories;
-            }
-        }
-        // Phase 6: Graph extraction drain (E3 sleep enqueue-hook). Rebuild the
-        // entity/relation graph for every tenant marked dirty (by markGraphDirty)
-        // since the last sleep, so `recall --hops` + cross-object `references` edges
-        // run on fresh data without a manual `hippo graph extract`. Fully
-        // fault-isolated: the consolidation work above has already committed, so a
-        // failure here must never abort sleep; a per-tenant extract failure leaves
-        // that tenant's queue items pending for the next sleep. (Skipped under
-        // dryRun via the early return above.)
-        try {
-            if (graphSnapshotError) {
-                // The dirty-tenant snapshot failed (codex P2 fail-soft). Core sleep
-                // already succeeded; surface the skipped graph refresh as a detail.
-                result.details = [
-                    ...(result.details ?? []),
-                    `graph: dirty-tenant snapshot failed (skipped graph refresh): ${graphSnapshotError}`,
-                ];
-            }
-            let gTenants = 0;
-            let gEntities = 0;
-            let gRelations = 0;
-            // dirtyTenants was snapshotted before the memory-deleting phases above.
-            for (const { tenantId, maxPendingId } of dirtyTenants) {
-                try {
-                    const ext = 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;
-                    // Watermark drain: mark processed only items enqueued before this
-                    // rebuild started (id <= maxPendingId). Arrivals during the rebuild
-                    // keep pending status and are caught next sleep; rows whose mirror was
-                    // cascade-deleted earlier this sleep are already gone (no-op).
-                    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}`,
-            ];
-        }
-        return result;
-    }
-    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 {
-        // v1.11.5: emit one 'consolidate' audit_log row per api.sleep invocation,
-        // with phase counters in metadata. Closes the CLI/MCP parity gap that T6
-        // fixed for cmdOutcome (Episode A follow-up). In finally so partial-failure
-        // paths still emit; `partial: true` + errorMessage flag the failure.
-        // Dedicated handle for this emit only (phase helpers above each open their
-        // own handle via hippoRoot — SQLite single-writer makes parallel handles
-        // safe for the read-heavy phases).
-        //
-        // TODO(v1.12.0 + A5 v2): the audit row is tagged with ctx.tenantId but
-        // api.sleep is host-wide (cross-tenant dedup is intentional). When
-        // /v1/sleep moves off loopback-only, either tag with a synthetic "host"
-        // tenant or scope api.sleep per-tenant. Independent-review-critic flag,
-        // v1.11.5 ship.
-        //
-        // Error preservation: if openHippoDb or appendAuditEvent throws here, we
-        // do NOT let it replace the original phaseError (independent-review HIGH:
-        // would mask the underlying consolidation failure). Audit emit failure
-        // is logged to stderr but the original throw wins.
-        try {
-            const db = openHippoDb(ctx.hippoRoot);
-            try {
-                const sleepAuditMetadata = {
-                    consolidationCount,
-                    dedupCount,
-                    auditDeletedCount,
-                    ambientTotal,
-                    dryRun,
-                    noShare: opts.noShare ?? false,
-                    partial: phaseError !== null,
-                    triggeredByTenant: ctx.tenantId, // preserve for audit forensics
-                };
-                if (phaseError)
-                    sleepAuditMetadata.errorMessage = phaseError.message;
-                appendAuditEvent(db, {
-                    tenantId: '__host__',
-                    actor: ctx.actor.subject,
-                    op: 'consolidate',
-                    metadata: { ...sleepAuditMetadata },
-                });
-            }
-            finally {
-                closeHippoDb(db);
-            }
-        }
-        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}`);
-        }
-    }
-}
-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=api.js.map