hippo-memory 1.60.0 → 1.61.0

package/dist/api.js

@@ -1,2731 +1,29 @@
-/**
- * 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 { openHippoDb, closeHippoDb } from './db.js';
-import { BadRequestError, ConflictError, ForbiddenError, NotFoundError } from './api-errors.js';
+// Domain API layer: Context-taking functions that the CLI, the HTTP server and MCP all call, so the
+// business logic lives in one place. The code lives in src/api/, one module per domain; this barrel
+// keeps every import path that callers already use.
 export { ApiError, BadRequestError, ConflictError, ForbiddenError, NotFoundError } from './api-errors.js';
-import { writeEntry, writeEntryDbOnly, strengthenRetrieved, stampOriginProject, writeEntryMirrors, readEntry, deleteEntry, loadRecallSearchEntries, loadEntriesByIds, loadChildrenOf, loadFreshRawMemories, loadSessionRawMemories, countSessionRawMemories, DEFAULT_SEARCH_CANDIDATE_LIMIT, removeEntryMirrors, loadActiveTaskSnapshot, loadFreshActiveTaskSnapshot, loadLatestHandoff, listSessionEvents, SNAPSHOT_AMBIENT_MAX_AGE_MS, loadIndex, saveIndex, loadAllEntries, loadAmbientCandidates, loadContextCandidates, updateStats, isInitialized, markSummaryDirtyInTx, auditRejectionRefusal, memoriesBackingObjects, } from './store.js';
-import { RejectedValueError } from './rejection.js';
-import { rejectValue, unrejectValue, listRejectionsForTenant } from './reject-flow.js';
-import { listDormantRows, readDormantSnapshot, deleteDormantRow, hasDormantRow, } from './dormant.js';
-import { recordTokenUse, summarizeTokenUse } from './token-ledger.js';
-import { detectInstruction } from './instruction-detect.js';
-import { quarantineScopeFor, recordQuarantine, getQuarantineRow, listQuarantineRows, approveQuarantineRow, rejectQuarantineRow, } from './quarantine.js';
-import { summarizeFailures } from './failure-log.js';
-import { log } from './log.js';
-import { formatHandoffEvidenceLine } from './handoff.js';
-import { createMemory, createSuccessor, applyOutcome, calculateStrength, markRetrieved, CHURN_STALE_TAG, COMPACTION_MEMORY_TAG, } from './memory.js';
-import { appendAuditEvent, reportAuditWriteFailure, auditQueryFields, queryAuditEvents, auditMemories, isContentWorthStoring, } from './audit.js';
-import { promoteToGlobal, getGlobalRoot, autoShare, searchBothHybrid } from './shared.js';
-import { writeRecallTrace, writeRecallTraceAtRoot, recordTraceOutcome } from './recall-trace.js';
-import { evalNow } from './ablation.js';
-import { archiveRawMemory } from './raw-archive.js';
-import { createApiKey, listApiKeys, revokeApiKey, grantScope, ungrantScope, } from './auth.js';
-import { applyGoalStackBoost } from './goals.js';
-import { estimateTokens, hybridSearch, physicsSearch, churnStaleFactor } from './search.js';
-import { compareEntryIdentity, compareScoredResults } from './compare.js';
-import { dropHeldCopies, duplicateKey, storedTextKeys } from './same-text.js';
-import { scopeMatch } from './scope.js';
-import { consolidate } from './consolidate.js';
-import { loadConfig } from './config.js';
-import { resolveProjectIdentity, classifyOriginProject, isGlobalStoreRoot } from './project-identity.js';
-import { promptTokens, contentTokens, gatePromptRecall, } from './prompt-recall.js';
-import { detectSecret, vetSecrets } from './secret-detect.js';
-import { isSessionDigestRow } from './session-digest.js';
-import { deduplicateStore } from './dedupe.js';
-import { computeAmbientState } from './ambient.js';
-import { loadPendingExtractionTenants, markPendingProcessedUpTo } from './graph.js';
-import { extractGraph } from './graph-extract.js';
-import { computePlanningFallacyOutput, } from './predictions.js';
-import { detectAnchoring, hashQueryText, biasHintEnabled, } 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 BadRequestError {
-    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, assertScopeRequestAllowed, isRestrictedScope } from './recall-scope.js';
-export { isPrivateScope, passesScopeFilterForRecall };
+// The recall-side scope predicates live in recall-scope.ts (leaf) so shared.ts can use them without an import cycle.
+export { isPrivateScope, passesScopeFilterForRecall } from './recall-scope.js';
 export { passesCliRecallScopeFilter, ScopeForbiddenError } 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.
+// classifyOriginProject lives in project-identity.ts (leaf) for the same reason.
 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/quarantine scopes never inject unless `exactScope` names one.
- * - S3 origin partition: other-project rows are excluded unless
- *   `includeCrossProject`.
- */
-function ambientAdmitEntry(e, currentProjectName, includeCrossProject, exactScope) {
-    if (!ambientSecretAdmit(e, currentProjectName))
-        return false;
-    if (!passesScopeFilterForRecall(e.scope ?? null, exactScope))
-        return false;
-    if (includeCrossProject)
-        return true;
-    return classifyOriginProject(e.origin_project, currentProjectName) !== 'cross-project';
-}
-/**
- * v39 S4: the secret half of the ambient policy on its own, for callers
- * that apply their own scope rule. A flagged row is only admitted inside its owning project;
- * flagged rows with no project origin never ambient-inject.
- */
-export function ambientSecretAdmit(e, currentProjectName) {
-    if (!detectSecret(e).flagged)
-        return true;
-    const origin = e.origin_project;
-    if (origin === undefined || origin === null || origin === '')
-        return false;
-    return origin === currentProjectName;
-}
-/** Most rows per store a no-query context reads; past it, ranking and ambientState see the strongest by decay. */
-export const CONTEXT_CANDIDATE_CAP = 2000;
-// The pinned-only branch needs pins and recent-N candidates, not the corpus; `recall` applies there only.
-// Without `window` the whole store loads: a local-only query searches every local row.
-function loadAmbientEntries(hippoRoot, tenantId, pinnedOnly, includeRecent, admit, recall, onQualityDrop, window) {
-    if (!pinnedOnly) {
-        const rows = window ? loadContextCandidates(hippoRoot, tenantId, window) : loadAllEntries(hippoRoot, tenantId);
-        return { entries: rows.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) => {
-        if (!admit(e))
-            return false;
-        if (e.pinned || isContentWorthStoring(e.content))
-            return true;
-        onQualityDrop?.(e);
-        return false;
-    };
-    return loadAmbientCandidates(hippoRoot, tenantId, includeRecent, admitAmbient, recall);
-}
-// Share and promote copy a memory to the global store under a new id, so equal content is the only link.
-// A pinned copy wins, then the stronger one after the ranking's own global discount; a tie keeps the local copy.
-export function oneCopyPerMemory(local, global, now) {
-    const score = (e, isGlobal) => calculateStrength(e, now) * (isGlobal ? 1 / 1.2 : 1);
-    const best = new Map();
-    const offer = (entry, isGlobal) => {
-        const held = best.get(entry.content);
-        const wins = !held || (held.entry.pinned !== entry.pinned
-            ? entry.pinned
-            : score(entry, isGlobal) > score(held.entry, held.isGlobal));
-        if (wins)
-            best.set(entry.content, { entry, isGlobal });
-    };
-    for (const e of local)
-        offer(e, false);
-    for (const e of global)
-        offer(e, true);
-    const kept = new Set([...best.values()].map((b) => b.entry));
-    return [local.filter((e) => kept.has(e)), global.filter((e) => kept.has(e))];
-}
-export function remember(ctx, opts) {
-    const vetted = vetSecrets(opts.content, opts.tags ?? [], opts.untrusted === true);
-    const detection = opts.untrusted ? detectInstruction(vetted.content) : { flagged: false, reason: null };
-    const requestedScope = opts.scope ?? null;
-    const entry = createMemory(vetted.content, {
-        kind: opts.kind ?? 'distilled',
-        scope: detection.flagged ? quarantineScopeFor(requestedScope) : requestedScope,
-        owner: opts.owner ?? null,
-        artifact_ref: opts.artifactRef ?? null,
-        tags: opts.tags,
-        tenantId: ctx.tenantId,
-        baseHalfLifeDays: loadConfig(ctx.hippoRoot).defaultHalfLifeDays,
-    });
-    // writeEntry threads ctx.actor.subject into its internal audit hook, so exactly
-    // one 'remember' event lands in the log with the supplied actor.
-    const afterWrite = detection.flagged
-        ? (db, memoryId) => {
-            recordQuarantine(db, {
-                tenantId: ctx.tenantId,
-                memoryId,
-                originalScope: requestedScope,
-                reason: detection.reason ?? 'unknown',
-                actor: ctx.actor.subject,
-            });
-            opts.afterWrite?.(db, memoryId);
-        }
-        : opts.afterWrite;
-    writeEntry(ctx.hippoRoot, entry, { actor: ctx.actor.subject, afterWrite });
-    const result = { id: entry.id, kind: entry.kind, tenantId: ctx.tenantId };
-    if (detection.flagged)
-        result.quarantined = { reason: detection.reason ?? 'unknown' };
-    if (vetted.warnings.length > 0)
-        result.warnings = vetted.warnings;
-    return result;
-}
-/**
- * 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` and keeps that order whatever `mode` says; `retrieve` is the
- * mode-aware, strengthening variant the HTTP route uses.
- *
- * **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) {
-    // A member key may not unlock a private or quarantined scope by naming it.
-    assertScopeRequestAllowed(ctx.actor, opts.scope);
-    const windowSize = recallWindowSize(opts);
-    return recallFrom(ctx, opts, windowSize, loadRecallSearchEntries(ctx.hippoRoot, opts.query, windowSize, ctx.tenantId, opts.scope, 'exact', false));
-}
-/** Mode-aware recall that strengthens each returned row; never writes last_retrieval_ids (v1.11.5 lock). */
-export async function retrieve(ctx, opts) {
-    assertScopeRequestAllowed(ctx.actor, opts.scope);
-    const windowSize = recallWindowSize(opts);
-    if (opts.showRanked)
-        return retrieveFromStore(ctx, opts, windowSize, opts.showRanked);
-    let candidates = loadRecallSearchEntries(ctx.hippoRoot, opts.query, windowSize, ctx.tenantId, opts.scope, 'exact', false);
-    if (opts.mode === 'hybrid' || opts.mode === 'physics') {
-        const searchOpts = { budget: Infinity, hippoRoot: ctx.hippoRoot, scope: opts.scope ?? null };
-        const ranked = opts.mode === 'physics'
-            ? await physicsSearch(opts.query, candidates, { ...searchOpts, physicsConfig: loadConfig(ctx.hippoRoot).physics })
-            : await hybridSearch(opts.query, candidates, searchOpts);
-        const rankedIds = new Set(ranked.map((r) => r.entry.id));
-        candidates = [...ranked.map((r) => r.entry), ...candidates.filter((e) => !rankedIds.has(e.id))];
-    }
-    const result = recallFrom(ctx, opts, windowSize, candidates);
-    strengthenRetrieved(ctx.hippoRoot, result.results.map((r) => r.id), ctx.tenantId);
-    return result;
-}
-/** `retrieve` under `showRanked`: physics when `mode` says so, hybrid otherwise, over every admitted row. */
-async function retrieveFromStore(ctx, opts, windowSize, show) {
-    const store = loadAllEntries(ctx.hippoRoot, ctx.tenantId);
-    const pool = store.filter((e) => passesScopeFilterForRecall(e.scope ?? null, opts.scope));
-    // No scope option: the scope boost follows HIPPO_SCOPE and the skill env, as MCP recall always ranked.
-    const searchOpts = { budget: Infinity, hippoRoot: ctx.hippoRoot };
-    let ranked = opts.mode === 'physics'
-        ? await physicsSearch(opts.query, pool, { ...searchOpts, physicsConfig: loadConfig(ctx.hippoRoot).physics })
-        : await hybridSearch(opts.query, pool, searchOpts);
-    if (opts.sessionId && !opts.goalTag) {
-        const db = openHippoDb(ctx.hippoRoot);
-        try {
-            ranked = applyGoalStackBoost(db, ranked, { sessionId: opts.sessionId, tenantId: ctx.tenantId, limit: ranked.length });
-        }
-        finally {
-            closeHippoDb(db);
-        }
-    }
-    const window = ranked.slice(0, windowSize).map((r) => r.entry);
-    const result = recallFrom(ctx, { ...opts, suppressRecallTrace: true }, windowSize, window);
-    const shown = show({ ranked, pool, droppedByScope: store.length - pool.length }, result);
-    strengthenRetrieved(ctx.hippoRoot, shown, ctx.tenantId);
-    if (!opts.suppressRecallTrace) {
-        const scores = new Map(ranked.map((r) => [r.entry.id, r.score]));
-        writeRecallTraceAtRoot(ctx.hippoRoot, {
-            tenantId: ctx.tenantId,
-            sessionId: opts.sessionId ?? null,
-            pipeline: 'mcp',
-            query: opts.query,
-            results: shown.map((id) => ({ memoryId: id, score: scores.get(id) ?? 0 })),
-        });
-    }
-    return result;
-}
-/** Contract preflight: throws before any store-touching work. */
-function recallWindowSize(opts) {
-    // F5 (v1.6.5) preflight — codex P1: original guard fired AFTER
-    // 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}`);
-        }
-    }
-    return opts.scorerWindow ?? DEFAULT_SEARCH_CANDIDATE_LIMIT;
-}
-function recallFrom(ctx, opts, windowSize, all) {
-    const limit = opts.limit ?? 10;
-    // 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;
-    // v1.12.13 / C5 — WYSIATI totalCandidates counter (post tenant + SQL scope
-    // predicate, pre JS scope filter).
-    totalCandidatesCount = all.length;
-    const current = all.filter((e) => !e.superseded_by);
-    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 = current.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 = current.filter((e) => !isRestrictedScope(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;
-    entries = entries
-        .map((e, i) => ({ e, s: (1 - i / entries.length) * churnStaleFactor(e) }))
-        .sort((a, b) => b.s - a.s)
-        .map((r) => r.e);
-    // 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 && !p.superseded_by && 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),
-                }));
-            }
-        }
-        if (!opts.keepHeldCopies) {
-            const shownIds = new Set(dropHeldCopies([...baseScored.map((r) => r.entry), ...substituted.map((s) => s.entry)], (e) => e).map((e) => e.id));
-            droppedPreRankCount += baseScored.filter((r) => !shownIds.has(r.entry.id)).length;
-            baseScored = baseScored.filter((r) => shownIds.has(r.entry.id));
-            baseSlice = baseScored.map((r) => r.entry);
-            substituted = substituted.filter((s) => shownIds.has(s.entry.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),
-            ]);
-            const shownKeys = storedTextKeys(opts.keepHeldCopies ? [] : [...baseSlice, ...substituted.map((s) => s.entry)]);
-            for (const m of recentScoped) {
-                if (seenIds.has(m.id) || shownKeys.has(duplicateKey(m.content)))
-                    continue;
-                shownKeys.add(duplicateKey(m.content));
-                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 + estimateTokens(r.content), 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: {
-                ...auditQueryFields(opts.query),
-                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 traces its own,
-        // different result set (retrieve under showRanked traces the shown list as
-        // 'mcp'). Fail-soft internally; never throws.
-        if (!opts.suppressRecallTrace) {
-            writeRecallTrace(db, {
-                tenantId: ctx.tenantId,
-                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 ? estimateTokens(s) : 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.
-    // The hint and the no-class-match / tiebreak watching variant are mutually exclusive; both go out 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 (biasHintEnabled('anchoring') && 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 (biasHintEnabled('availability') && !opts.suppressAvailabilityHint) {
-        availabilityHint = detectAvailabilityBias({
-            topK: baseSlice.map((e) => ({ id: e.id, created: e.created })),
-            pool: entries.map((e) => ({ id: e.id, created: e.created })),
-        });
-        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 = {}) {
-    assertScopeRequestAllowed(ctx.actor, opts.scope);
-    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 && !p.superseded_by)
-                .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];
-    const itemCost = opts.cost?.item ?? ((it) => estimateTokens(it.content));
-    const room = budget - (opts.cost?.fixed(Math.max(budget, totalRaw)) ?? 0);
-    let tokens = items.reduce((acc, it) => acc + itemCost(it), 0);
-    let evicted = 0;
-    while (tokens > room && 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 = itemCost(items[worstIdx]);
-        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;
-    }
-    const summaryOut = {
-        id: summary.id,
-        content: summary.content,
-        // v0.30 / E5: the STORED direct-child count; the legacy fallback counts
-        // level-0 children, never the BFS-depth-N total (independent-review MED #4).
-        descendantCount: summary.descendant_count ?? level0DirectCount,
-        earliestAt: summary.earliest_at ?? null,
-        latestAt: summary.latest_at ?? null,
-    };
-    const all = collected.map((c) => ({
-        id: c.id,
-        content: c.content,
-        layer: c.layer,
-        dagLevel: c.dag_level ?? 0,
-        created: c.created,
-    }));
-    // Apply global cumulative token budget + limit cap on collected.
-    let children = all;
-    let truncated = false;
-    if (opts.budget !== undefined) {
-        const out = [];
-        let used = 0;
-        const room = opts.budget - (opts.cost?.fixed(summaryOut, all.length) ?? 0);
-        for (const c of all) {
-            const t = opts.cost ? opts.cost.child(c) : estimateTokens(c.content);
-            if (out.length > 0 && used + t > room) {
-                truncated = true;
-                break;
-            }
-            out.push(c);
-            used += t;
-        }
-        children = out;
-    }
-    if (children.length > limit) {
-        children = children.slice(0, limit);
-        truncated = true;
-    }
-    return {
-        summary: summaryOut,
-        children,
-        // 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;
-            let updated = applyOutcome(entry, good);
-            if (good && updated.tags.includes(CHURN_STALE_TAG)) { // FE2: a good outcome reconfirms the entry
-                updated = { ...updated, tags: updated.tags.filter((t) => t !== CHURN_STALE_TAG) };
-            }
-            writeEntry(ctx.hippoRoot, updated, { actor: ctx.actor.subject });
-            appendAuditEvent(db, {
-                tenantId: ctx.tenantId,
-                actor: ctx.actor.subject,
-                op: 'outcome',
-                targetId: id,
-                metadata: { good },
-            });
-            appliedIds.push(id);
-        }
-        // LC1: link the outcome to its trace, recording only the ids actually
-        // credited (post tenant-filtering, matches appliedIds). Lives in its own
-        // append-only table so audit_log pruning can never erase training data.
-        if (opts?.traceId !== undefined && appliedIds.length > 0) {
-            recordTraceOutcome(db, {
-                traceId: opts.traceId,
-                tenantId: ctx.tenantId,
-                outcome: good ? 'positive' : 'negative',
-                memoryIds: appliedIds,
-            });
-        }
-    }
-    finally {
-        closeHippoDb(db);
-    }
-    return { applied: appliedIds.length, appliedIds };
-}
-export function 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 NotFoundError(`memory not found: ${id}`);
-        }
-    }
-    finally {
-        closeHippoDb(db);
-    }
-    const removed = deleteEntry(ctx.hippoRoot, id, { actor: ctx.actor.subject });
-    if (!removed) {
-        throw new NotFoundError(`memory not found: ${id}`);
-    }
-    // Counted here, not in the CLI: both callers of this function (cmdForget and
-    // the HTTP route) are the two paths of one user command, so neither can miss
-    // 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 NotFoundError(`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 NotFoundError(`no rejected value matches: ${digestOrPrefix}`);
-    }
-    if (outcome.status === 'ambiguous') {
-        throw new BadRequestError(`"${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 NotFoundError(`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 NotFoundError(`Memory not found: ${oldId}`);
-    }
-    // Guard: not already superseded. The CAS UPDATE below race-safely closes
-    // the window between this read and the write; this check just produces a
-    // clearer error in the common single-writer case.
-    if (old.superseded_by) {
-        throw new ConflictError(`Memory ${oldId} is already superseded by ${old.superseded_by}. Supersede that one instead.`);
-    }
-    const newEntry = createSuccessor(old, newContent, {
-        tenantId: ctx.tenantId,
-        baseHalfLifeDays: loadConfig(ctx.hippoRoot).defaultHalfLifeDays,
-    });
-    // Race-safe transition: open a fresh db handle, BEGIN IMMEDIATE, run all
-    // three steps (CAS on old + writeEntryDbOnly(new) + supersede audit row)
-    // inside the same transaction. Two concurrent supersedes: exactly one CAS
-    // wins (changes=1), the other gets changes=0 and throws CONFLICT. No
-    // dangling-pointer window: the new memory's row commits atomically with
-    // the old.superseded_by pointer.
-    const db = openHippoDb(ctx.hippoRoot);
-    try {
-        db.exec('BEGIN IMMEDIATE');
-        try {
-            // 1. CAS update: only succeed if old.superseded_by IS NULL AND the
-            //    row still belongs to ctx.tenantId. Tenant filter is belt-and-
-            //    braces with the readEntry above — it costs nothing and closes
-            //    a hypothetical window where ownership changes between read and
-            //    update.
-            const result = db.prepare(`
-        UPDATE memories
-        SET superseded_by = ?
-        WHERE id = ? AND tenant_id = ? AND superseded_by IS NULL
-      `).run(newEntry.id, oldId, ctx.tenantId);
-            if ((result.changes ?? 0) === 0) {
-                db.exec('ROLLBACK');
-                throw new ConflictError(`Memory ${oldId} already superseded by another writer`);
-            }
-            // v0.30 / E2 — DAG live-coupling: OLD entry just transitioned to
-            // superseded. Its parent (if any) needs rebuild. Lands strictly
-            // between the rollback guard above and the writeEntryDbOnly(NEW)
-            // below so a failed CAS hits throw before this hook. The NEW
-            // entry's parent (typically same parent) is auto-marked by the
-            // writeEntryDbOnly hook (same parent → idempotent, audits once).
-            if (old.dag_parent_id) {
-                markSummaryDirtyInTx(db, old.dag_parent_id, ctx.tenantId, ctx.actor.subject);
-            }
-            // 2. Write new memory inside same tx via writeEntryDbOnly (DB-only
-            //    path). This emits its OWN 'remember' audit row for the new
-            //    memory inside the SAVEPOINT — atomic with the row INSERT.
-            writeEntryDbOnly(db, stampOriginProject(ctx.hippoRoot, newEntry), { actor: ctx.actor.subject });
-            // 3. User-facing 'supersede' audit row inside the same tx so the
-            //    chain pointer + audit trail commit atomically.
-            appendAuditEvent(db, {
-                tenantId: ctx.tenantId,
-                actor: ctx.actor.subject,
-                op: 'supersede',
-                targetId: oldId,
-                metadata: { newId: newEntry.id },
-            });
-            db.exec('COMMIT');
-        }
-        catch (err) {
-            try {
-                db.exec('ROLLBACK');
-            }
-            catch { /* already rolled back */ }
-            // AT1 (plan §3): refusal audit lands post-ROLLBACK, in a fresh
-            // implicit transaction the aborted outer one cannot claw back — then
-            // rethrow so the caller sees the refusal.
-            if (err instanceof RejectedValueError) {
-                auditRejectionRefusal(db, err, ctx.actor.subject);
-            }
-            throw err;
-        }
-        // Mirrors after COMMIT, while the db handle is still open. Same
-        // invariant as the original writeEntry: a mirror failure leaves disk
-        // MISSING the markdown for the new memory (rebuildIndex rewrites every
-        // markdown mirror from the DB) but DOES NOT desync the DB or
-        // roll back the supersede. Logged + swallowed, non-fatal.
-        try {
-            writeEntryMirrors(ctx.hippoRoot, newEntry);
-        }
-        catch (mirrorErr) {
-            log.error(`supersede: mirror write failed (non-fatal, will self-heal): ${mirrorErr instanceof Error ? mirrorErr.message : String(mirrorErr)}`);
-        }
-    }
-    finally {
-        closeHippoDb(db);
-    }
-    return { ok: true, oldId, newId: newEntry.id };
-}
-export function archiveRaw(ctx, id, reason, opts = {}) {
-    const db = openHippoDb(ctx.hippoRoot);
-    let mirrorOk = false;
-    try {
-        // Tenant scope: archiveRawMemory looks up the row by id alone, so a
-        // Bearer for tenant A could archive tenant B's raw row without this
-        // pre-check. Deny cross-tenant access with the same not-found message
-        // archiveRawMemory itself would throw on a missing row, so we don't
-        // leak whether the id exists in another tenant.
-        // 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 NotFoundError(`memory not found: ${id}`);
-        }
-        archiveRawMemory(db, id, {
-            reason,
-            who: ctx.actor.subject,
-            afterArchive: opts.afterArchive,
-        });
-        // archiveRawMemory deletes the memories row but leaves any legacy markdown
-        // mirror in <root>/{buffer,episodic,semantic}/<id>.md untouched. If we left
-        // the mirror in place, a subsequent initStore() on an empty memories table
-        // would silently re-import the row via bootstrapLegacyStore — defeating the
-        // archive (and the GDPR right-to-be-forgotten promise on raw rows). Mirror
-        // forget() at src/store.ts:1046, which uses the same removeEntryMirrors call.
-        // The DB transaction has already committed; if filesystem unlink fails here
-        // we log and continue. The mirror reaper in openHippoDb will catch it on
-        // next DB open: raw_archive.mirror_cleaned_at stays NULL until every layer
-        // mirror for this id is gone, so the reaper genuinely retries.
-        try {
-            removeEntryMirrors(ctx.hippoRoot, id);
-            mirrorOk = true;
-        }
-        catch (mirrorErr) {
-            log.error(`archiveRaw: mirror cleanup failed for ${id} (will retry via reaper on next openHippoDb): ${mirrorErr instanceof Error ? mirrorErr.message : String(mirrorErr)}`);
-        }
-        if (mirrorOk) {
-            // Stamp mirror_cleaned_at now so the next openHippoDb reaper SELECT
-            // returns empty for this row. NULL stays untouched on failure -> retry.
-            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.
- *
- * Only an admin actor can mint (ForbiddenError otherwise), and a key never
- * outranks its minter: a resolver admin is tenant-only, so it mints members.
- */
-export function authCreate(ctx, opts) {
-    if (ctx.actor.role !== 'admin') {
-        throw new ForbiddenError('Only an admin key can create API keys');
-    }
-    if (ctx.actor.viaAuthResolver && opts.role === 'admin') {
-        throw new ForbiddenError('A key minted through the auth resolver can only be a member key');
-    }
-    const db = openHippoDb(ctx.hippoRoot);
-    try {
-        const role = opts.role ?? (ctx.actor.viaAuthResolver ? 'member' : '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 (error) {
-            // Audit must not crash a successful mint.
-            reportAuditWriteFailure('auth_create', String(error), result.keyId);
-        }
-        return { keyId: result.keyId, plaintext: result.plaintext, tenantId: ctx.tenantId, role };
-    }
-    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) {
-    if (ctx.actor.role !== 'admin' && ctx.actor.subject !== `api_key:${keyId}`) {
-        throw new ForbiddenError('A member key can revoke only itself');
-    }
-    const db = openHippoDb(ctx.hippoRoot);
-    try {
-        // SAFETY: row's shape matches the four columns named in the SELECT
-        // above.
-        const row = db
-            .prepare(`SELECT key_id, tenant_id, revoked_at, role FROM api_keys WHERE key_id = ?`)
-            .get(keyId);
-        if (!row) {
-            throw new NotFoundError(`Unknown key_id: ${keyId}`);
-        }
-        // Cross-tenant access denied: same message as missing key, no info leak.
-        if (row.tenant_id !== ctx.tenantId) {
-            throw new NotFoundError(`Unknown key_id: ${keyId}`);
-        }
-        if (ctx.actor.viaAuthResolver && row.role === 'admin') {
-            throw new ForbiddenError('An auth resolver admin cannot revoke an admin key, which outranks it');
-        }
-        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 (error) {
-                // Audit must not crash a successful revoke.
-                reportAuditWriteFailure('auth_revoke', String(error), keyId);
-            }
-        }
-        return { ok: true, revokedAt };
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-/** Grant `keyId` read access to one restricted `scope` (ROADMAP Part VIII EI2). Admin only. */
-export function authGrant(ctx, keyId, scope) {
-    return changeScopeGrant(ctx, keyId, scope, 'auth_grant');
-}
-/** Revoke `keyId`'s grant on `scope`. Same authorization and lookup rules as authGrant. */
-export function authUngrant(ctx, keyId, scope) {
-    return changeScopeGrant(ctx, keyId, scope, 'auth_ungrant');
-}
-function changeScopeGrant(ctx, keyId, scope, op) {
-    if (ctx.actor.role !== 'admin') {
-        throw new ForbiddenError('Only an admin key can change scope grants');
-    }
-    const db = openHippoDb(ctx.hippoRoot);
-    try {
-        // SAFETY: row's shape matches the single tenant_id column in the SELECT.
-        const row = db
-            .prepare(`SELECT tenant_id, revoked_at FROM api_keys WHERE key_id = ?`)
-            .get(keyId);
-        if (!row || row.tenant_id !== ctx.tenantId) {
-            throw new NotFoundError(`Unknown key_id: ${keyId}`);
-        }
-        if (op === 'auth_grant' && row.revoked_at) {
-            throw new ConflictError(`${keyId} is revoked; a grant on it would never apply`);
-        }
-        if (!isRestrictedScope(scope)) {
-            throw new BadRequestError(`${scope} is not a restricted scope; it is already readable by default`);
-        }
-        if (op === 'auth_grant')
-            grantScope(db, keyId, scope);
-        else
-            ungrantScope(db, keyId, scope);
-        try {
-            appendAuditEvent(db, { tenantId: ctx.tenantId, actor: ctx.actor.subject, op, targetId: keyId, metadata: { scope } });
-        }
-        catch (err) {
-            // Audit must not undo a grant change that already committed; surface it instead.
-            reportAuditWriteFailure(op, String(err), keyId);
-        }
-        return { ok: true };
-    }
-    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);
-    }
-}
-const finiteOr = (v, dflt, min) => Number.isFinite(v) && v >= min ? v : dflt;
-/**
- * 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 ?? '';
-    assertScopeRequestAllowed(ctx.actor, opts.exactScope);
-    const exactScope = opts.exactScope || undefined;
-    if (budget <= 0) {
-        return { entries: [], tokens: 0 };
-    }
-    // Global memories do not establish a project boundary for task state.
-    const hasLocal = isInitialized(ctx.hippoRoot);
-    const query = (opts.q ?? '').trim() || '*';
-    const globalRoot = getGlobalRoot();
-    const hasGlobal = isInitialized(globalRoot);
-    const primaryIsGlobal = isGlobalStoreRoot(ctx.hippoRoot);
-    const hasLocalTaskState = hasLocal && !primaryIsGlobal;
-    // v39 memory scope isolation (docs/plans/2026-07-01-memory-scope-isolation.md).
-    // S2: envelope-filter parity with api.recall; opts.scope is only the tag boost, opts.exactScope the envelope request.
-    // S3: origin partition - other-project memories are excluded unless the
-    // caller explicitly asks for them (crossProject) or isolation is disabled.
-    const config = loadConfig(ctx.hippoRoot);
-    const isolationEnabled = config.contextProjectIsolation !== false;
-    const currentProjectName = opts.currentProject ?? resolveProjectIdentity(process.cwd()).name;
-    const includeCrossProject = opts.crossProject === true || !isolationEnabled;
-    // Z1: decided before the ambient loads so the FTS candidate query below (pinned-only
-    // branch) can piggyback on that connection instead of opening its own.
-    const promptRecallPending = pinnedOnly && Boolean(opts.prompt?.trim()) && config.pinnedInject.promptRecall === true;
-    const promptRecallTerms = promptRecallPending && config.pinnedInject.enabled
-        ? Array.from(promptTokens(opts.prompt ?? ''))
-        : [];
-    const recallRequest = promptRecallTerms.length > 0
-        ? { terms: promptRecallTerms, limit: Math.floor(finiteOr(config.pinnedInject.promptRecallCandidates, 100, 1)) }
-        : undefined;
-    const cost = opts.cost;
-    const price = (entry, isGlobal, promptRecall) => cost
-        ? cost.entry({ entry, isGlobal, promptRecall, origin: entry.origin_project ?? null, category: classifyOriginProject(entry.origin_project, currentProjectName) })
-        : estimateTokens(entry.content);
-    const blockBudget = pinnedOnly && opts.budget === undefined ? config.pinnedInject.budget : budget;
-    const obs = opts.deliveryObserver;
-    obs?.facts({ projectName: currentProjectName, budgetTokens: blockBudget, promptRecall: promptRecallPending });
-    if (pinnedOnly && !config.pinnedInject.enabled)
-        obs?.disabled();
-    let left = cost
-        ? Math.max(0, blockBudget - cost.fixed(blockBudget, { cross: includeCrossProject, promptRecall: promptRecallPending, ambient: !pinnedOnly && config.ambient.enabled }))
-        : blockBudget;
-    // Sections print ahead of the memories, so they are paid first; one that does not fit is dropped, as an oversize entry is.
-    const pays = (tokens) => {
-        if (tokens > left)
-            return false;
-        left -= tokens;
-        return true;
-    };
-    // 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 = hasLocalTaskState
-        ? loadFreshActiveTaskSnapshot(ctx.hippoRoot, ctx.tenantId, {
-            sessionId: opts.currentSessionId,
-        })
-        : null;
-    // W1: the same envelope rule ambientAdmitEntry applies to memory rows.
-    const activeSnapshot = rawActiveSnapshot && passesScopeFilterForRecall(rowScope(rawActiveSnapshot), exactScope)
-        ? rawActiveSnapshot
-        : null;
-    // Key on the RAW snapshot: a scope-hidden active session must not fall through to another session's ambient handoff.
-    const rawSessionHandoff = !hasLocalTaskState
-        ? 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), exactScope)
-        ? rawSessionHandoff
-        : null;
-    // Raw session id here too: each event is admitted on its own scope, same as recall and the CLI.
-    const recentSessionEvents = hasLocalTaskState && rawActiveSnapshot?.session_id
-        ? listSessionEvents(ctx.hippoRoot, ctx.tenantId, {
-            session_id: rawActiveSnapshot.session_id,
-            limit: 5,
-        }).filter((e) => passesScopeFilterForRecall(rowScope(e), exactScope))
-        : [];
-    const shownSnapshot = activeSnapshot && (!cost || pays(cost.snapshot(activeSnapshot))) ? activeSnapshot : null;
-    const shownHandoff = sessionHandoff && (!cost || pays(cost.handoff(sessionHandoff))) ? sessionHandoff : null;
-    const shownEvents = recentSessionEvents.length > 0 && (!cost || pays(cost.trail(recentSessionEvents))) ? recentSessionEvents : [];
-    obs?.sections(Number(shownSnapshot !== null) + Number(shownHandoff !== null) + Number(shownEvents.length > 0), Number(activeSnapshot !== shownSnapshot) + Number(sessionHandoff !== shownHandoff) + Number(recentSessionEvents.length !== shownEvents.length));
-    const transcriptHandoffSession = shownHandoff?.evidence?.derivedFrom === 'transcript' ? shownHandoff.sessionId : null;
-    let digestHiddenForHandoff = false;
-    const ambientAdmit = (e) => {
-        // A printed handoff already carries the session's closing message, which its digest would print a second time.
-        if (transcriptHandoffSession !== null && e.source_session_id === transcriptHandoffSession && isSessionDigestRow(e)) {
-            digestHiddenForHandoff = true;
-            return false;
-        }
-        return ambientAdmitEntry(e, currentProjectName, includeCrossProject, exactScope);
-    };
-    const ownSessionId = opts.currentSessionId || '';
-    // Inside admit, not after the load, so the loader's window widens past a session's own items.
-    const isOwnCompactionItem = (e) => ownSessionId !== '' &&
-        e.source_session_id === ownSessionId &&
-        e.tags.includes(COMPACTION_MEMORY_TAG);
-    // Superseded rows never inject; which rows reach ambientAdmitEntry matters because it regex-scans content for secrets.
-    const admit = (e) => !e.superseded_by && !isOwnCompactionItem(e) && ambientAdmit(e);
-    const loadAdmit = obs ? obs.watchAdmit(admit) : admit;
-    const qualityDrop = (isGlobal) => obs && !promptRecallPending ? (e) => obs.qualityDropped(e, isGlobal) : undefined;
-    // The window's predicates are ones admit applies anyway, so below the cap the admitted rows are unchanged.
-    const searchesLocalRows = query !== '*' && !(hasGlobal && !primaryIsGlobal);
-    const window = pinnedOnly || searchesLocalRows
-        ? undefined
-        : {
-            exactScope,
-            project: includeCrossProject || currentProjectName === '' ? undefined : currentProjectName,
-            cap: CONTEXT_CANDIDATE_CAP,
-            now: evalNow(),
-        };
-    // Tenant-scoped loads (v1.11.1 lesson: NEVER resolveTenantId({}) here).
-    const localLoad = hasLocal
-        ? loadAmbientEntries(ctx.hippoRoot, ctx.tenantId, pinnedOnly, includeRecent, loadAdmit, recallRequest, qualityDrop(primaryIsGlobal), window)
-        : { entries: [] };
-    const globalLoad = hasGlobal && !primaryIsGlobal
-        ? loadAmbientEntries(globalRoot, ctx.tenantId, pinnedOnly, includeRecent, loadAdmit, recallRequest, qualityDrop(true), window)
-        : { entries: [] };
-    let localEntries = localLoad.entries;
-    let globalEntries = globalLoad.entries;
-    // Computed after markRetrieved runs, so avgStrength reflects post-retrieval strengths.
-    let ambientState;
-    if (!promptRecallPending &&
-        localEntries.length === 0 &&
-        globalEntries.length === 0 &&
-        !shownSnapshot &&
-        !shownHandoff &&
-        shownEvents.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, less what the sections took.
-        const effBudget = left;
-        const nowP = evalNow(); // honors HIPPO_FAKE_NOW (eval-only; see ablation.ts)
-        obs?.offer(localEntries, primaryIsGlobal);
-        obs?.offer(globalEntries, true);
-        const [localPool, globalPool] = oneCopyPerMemory(localEntries, globalEntries, nowP);
-        obs?.dropMissing([...localEntries, ...globalEntries], [...localPool, ...globalPool], 'load', 'duplicate');
-        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 = localPool.filter((e) => e.pinned);
-        const pinnedGlobal = globalPool.filter((e) => e.pinned);
-        const rankedPinned = [
-            ...pinnedLocal.map((e) => ({ entry: e, isGlobal: primaryIsGlobal })),
-            ...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: price(entry, isGlobal),
-                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);
-        // Z1: gate the backfill on the prompt instead of recency (docs/plans/2026-09-26-z1-prompt-recall.md).
-        const promptRecallOn = promptRecallPending;
-        if (promptRecallOn) {
-            const rawMetric = pinnedCfg.pinnedInject.promptRecallMetric;
-            const metric = rawMetric === 'cosine' ? 'cosine' : 'jaccard';
-            const gate = {
-                metric,
-                threshold: finiteOr(pinnedCfg.pinnedInject.promptRecallThreshold, 0.04, 0),
-                minShared: finiteOr(pinnedCfg.pinnedInject.promptRecallMinShared, 2, 0),
-                maxItems: finiteOr(pinnedCfg.pinnedInject.promptRecallMaxItems, 5, 1),
-            };
-            const p = promptTokens(opts.prompt ?? '');
-            if (p.size > 0) {
-                // Candidates came off the ambient load's own connection (recallRequest above), not a fresh open.
-                // A candidate carrying a pin's text would inject that memory a second time.
-                const pinnedText = new Set(rankedPinned.map((r) => r.entry.content));
-                const ineligibleReason = (e) => !admit(e) ? 'scope'
-                    : e.pinned ? 'pinned'
-                        : !isContentWorthStoring(e.content) ? 'quality'
-                            : pinnedText.has(e.content) ? 'duplicate'
-                                : null;
-                const eligible = (e) => {
-                    const why = ineligibleReason(e);
-                    if (why !== null && why !== 'pinned')
-                        obs?.reject(e, 'eligible', why);
-                    return why === null;
-                };
-                obs?.offer(localLoad.recall ?? [], primaryIsGlobal, 'prompt-recall');
-                obs?.offer(globalLoad.recall ?? [], true, 'prompt-recall');
-                const localEligible = (localLoad.recall ?? []).filter(eligible);
-                const globalEligible = (globalLoad.recall ?? []).filter(eligible);
-                const [localCandidates, globalCandidates] = oneCopyPerMemory(localEligible, globalEligible, nowP);
-                obs?.dropMissing([...localEligible, ...globalEligible], [...localCandidates, ...globalCandidates], 'eligible', 'duplicate');
-                const seenCandidateIds = new Set();
-                const candidateItems = [];
-                // Local wins the id collision (a global row synced into the local store).
-                for (const e of localCandidates) {
-                    if (seenCandidateIds.has(e.id))
-                        continue;
-                    seenCandidateIds.add(e.id);
-                    candidateItems.push({ id: e.id, tokens: contentTokens(e.content), entry: e, isGlobal: primaryIsGlobal });
-                }
-                for (const e of globalCandidates) {
-                    if (seenCandidateIds.has(e.id))
-                        continue;
-                    seenCandidateIds.add(e.id);
-                    candidateItems.push({ id: e.id, tokens: contentTokens(e.content), entry: e, isGlobal: true });
-                }
-                const gated = gatePromptRecall(p, candidateItems, gate);
-                obs?.gated(p, candidateItems, gate, gated);
-                for (const g of gated) {
-                    if (selectedIds.has(g.item.id))
-                        continue;
-                    const tokens = price(g.item.entry, g.item.isGlobal, true);
-                    if (usedP + tokens > recentBudget) {
-                        obs?.reject(g.item.entry, 'budget', 'budget', g.score, tokens);
-                        continue;
-                    }
-                    selectedItems.push({ entry: g.item.entry, score: g.score, tokens, isGlobal: g.item.isGlobal, promptRecall: true });
-                    selectedIds.add(g.item.id);
-                    usedP += tokens;
-                }
-            }
-        }
-        else if (includeRecent > 0) {
-            const recent = [
-                ...localPool.map((entry) => ({ entry, isGlobal: primaryIsGlobal })),
-                ...globalPool.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: price(entry, isGlobal),
-                isGlobal,
-            }));
-            for (const r of recent) {
-                if (selectedIds.has(r.entry.id))
-                    continue;
-                if (usedP + r.tokens > recentBudget) {
-                    obs?.reject(r.entry, 'budget', 'budget', r.score, r.tokens);
-                    continue;
-                }
-                selectedItems.push(r);
-                selectedIds.add(r.entry.id);
-                usedP += r.tokens;
-            }
-        }
-        if (pinnedLocal.length === 0 &&
-            pinnedGlobal.length === 0 &&
-            selectedItems.length === 0 &&
-            !digestHiddenForHandoff) {
-            return { entries: [], tokens: 0 };
-        }
-        for (const r of rankedPinned) {
-            if (selectedIds.has(r.entry.id))
-                continue;
-            if (usedP + r.tokens > effBudget) {
-                obs?.reject(r.entry, 'budget', 'budget', r.score, r.tokens);
-                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 [localPool, globalPool] = oneCopyPerMemory(localEntries, globalEntries, now);
-        const localRanked = localPool
-            .map((e) => ({
-            entry: e,
-            score: calculateStrength(e, now),
-            tokens: price(e, primaryIsGlobal),
-            isGlobal: primaryIsGlobal,
-        }))
-            .sort(compareScoredResults);
-        const globalRanked = globalPool
-            .map((e) => ({
-            entry: e,
-            score: calculateStrength(e, now) * (1 / 1.2),
-            tokens: price(e, true),
-            isGlobal: true,
-        }))
-            .sort(compareScoredResults);
-        const combined = [...localRanked, ...globalRanked].sort(compareScoredResults);
-        let used = 0;
-        for (const r of combined) {
-            if (used + r.tokens > left)
-                continue;
-            selectedItems.push(r);
-            used += r.tokens;
-        }
-        totalTokens = used;
-    }
-    else {
-        // Real query: hybrid search (global + local) or physics+hybrid (local only).
-        let results;
-        const minResults = cost ? 0 : undefined; // a priced block skips an oversize top hit too, so the budget bounds it
-        if (hasGlobal && !primaryIsGlobal) {
-            // 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 localIndex = loadIndex(ctx.hippoRoot);
-            const isGlobalHit = (e) => !localIndex.entries[e.id];
-            const merged = await searchBothHybrid(query, ctx.hippoRoot, globalRoot, {
-                budget: left,
-                minResults,
-                cost: cost && ((r) => price(r.entry, isGlobalHit(r.entry))),
-                scope: activeScope,
-                tenantId: ctx.tenantId,
-                entryFilter: ambientAdmit,
-            });
-            results = merged.map((r) => ({
-                entry: r.entry,
-                score: r.score,
-                tokens: price(r.entry, isGlobalHit(r.entry)),
-                isGlobal: isGlobalHit(r.entry),
-            }));
-        }
-        else {
-            const ctxConfig = loadConfig(ctx.hippoRoot);
-            const usePhysicsCtx = ctxConfig.physics?.enabled !== false;
-            const localCost = cost && ((r) => price(r.entry, primaryIsGlobal));
-            const ctxResults = usePhysicsCtx
-                ? await physicsSearch(query, localEntries, {
-                    budget: left,
-                    minResults,
-                    cost: localCost,
-                    hippoRoot: ctx.hippoRoot,
-                    physicsConfig: ctxConfig.physics,
-                    scope: activeScope,
-                })
-                : await hybridSearch(query, localEntries, {
-                    budget: left,
-                    minResults,
-                    cost: localCost,
-                    hippoRoot: ctx.hippoRoot,
-                    scope: activeScope,
-                });
-            results = ctxResults.map((r) => ({
-                entry: r.entry,
-                score: r.score,
-                tokens: price(r.entry, primaryIsGlobal),
-                isGlobal: primaryIsGlobal,
-            }));
-        }
-        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 = {
-            ...auditQueryFields(query),
-            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 && !primaryIsGlobal) {
-            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) {
-        const cut = selectedItems.slice(0, limit);
-        obs?.dropMissing(selectedItems.map((r) => r.entry), cut.map((r) => r.entry), 'limit', 'limit');
-        selectedItems = cut;
-    }
-    const heldDropped = dropHeldCopies(selectedItems, (r) => r.entry); // after the last cut, so a merged row that was cut hides nothing
-    obs?.dropMissing(selectedItems.map((r) => r.entry), heldDropped.map((r) => r.entry), 'limit', 'duplicate');
-    selectedItems = heldDropped;
-    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),
-    }));
-    obs?.selected(selectedItems);
-    if (selectedItems.length === 0 &&
-        !shownSnapshot &&
-        !shownHandoff &&
-        shownEvents.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);
-        const retrievedIds = updatedEntries.map((u) => u.id);
-        const strengthenedHere = strengthenRetrieved(ctx.hippoRoot, retrievedIds);
-        if (hasGlobal)
-            strengthenRetrieved(globalRoot, retrievedIds.filter((id) => !strengthenedHere.has(id)));
-        localIndex.last_retrieval_ids = retrievedIds;
-        // 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: shownSnapshot ?? undefined,
-        sessionHandoff: shownHandoff ?? undefined,
-        recentEvents: shownEvents.length > 0 ? shownEvents : undefined,
-        ambientState,
-    };
-}
-/**
- * Record memory text handed to an agent in the token ledger (ROADMAP TE0).
- * Best-effort: never throws, because a ledger failure must not fail the
- * recall or context call that produced the text.
- */
-export function recordTokens(ctx, surface, use) {
-    try {
-        const db = openHippoDb(ctx.hippoRoot);
-        try {
-            recordTokenUse(db, {
-                tenantId: ctx.tenantId,
-                sessionId: use.sessionId ?? null,
-                surface,
-                event: 'inject',
-                items: use.items,
-                tokens: use.tokens,
-            });
-        }
-        finally {
-            closeHippoDb(db);
-        }
-    }
-    catch {
-        // Ledger is best-effort.
-    }
-}
-/**
- * Token ledger totals for the tenant over the last `days` days (default 30):
- * tokens sent, skipped as unchanged and re-read by later model calls, per
- * surface, with session counts and mean tokens per session.
- */
-export function tokenSummary(ctx, opts = {}) {
-    const db = openHippoDb(ctx.hippoRoot);
-    try {
-        return summarizeTokenUse(db, ctx.tenantId, reportWindowStart(opts.days));
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-/** Failed tool calls by outcome, and repeats across sessions, over the last `days` days (default 30); ROADMAP CD13. */
-export function failureSummary(ctx, opts = {}) {
-    const db = openHippoDb(ctx.hippoRoot);
-    try {
-        return summarizeFailures(db, ctx.tenantId, reportWindowStart(opts.days));
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-function reportWindowStart(days) {
-    const span = days !== undefined && Number.isFinite(days) && days > 0 ? days : 30;
-    return new Date(Date.now() - span * 86_400_000).toISOString();
-}
-/**
- * A tenant's dormant memories (src/dormant.ts): what sleep moved out of
- * active memory instead of deleting, when `dormant.enabled` is on. Newest
- * first; `opts.query` keeps rows containing every term (case-insensitive).
- */
-export function listDormant(ctx, opts = {}) {
-    const db = openHippoDb(ctx.hippoRoot);
-    try {
-        return listDormantRows(db, ctx.tenantId, opts);
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-/**
- * Bring a dormant memory back into active memory. It returns as if just
- * recalled: `last_retrieved` is now, so it gets a full half-life before it
- * can fade again. Every other field is the snapshot taken when it went
- * dormant.
- *
- * Throws when the tenant has no dormant memory with that id (another
- * tenant's id reads the same way), when a live memory already holds the id,
- * and RejectedValueError when the value has been rejected since. On any
- * throw the dormant copy stays where it is.
- */
-export function restoreDormant(ctx, id) {
-    const db = openHippoDb(ctx.hippoRoot);
-    try {
-        let restored;
-        db.exec('BEGIN IMMEDIATE');
-        try {
-            const dormant = readDormantSnapshot(db, ctx.tenantId, id);
-            if (!dormant) {
-                throw new NotFoundError(`dormant memory not found: ${id}`);
-            }
-            if (db.prepare(`SELECT 1 FROM memories WHERE id = ?`).get(id) !== undefined) {
-                throw new ConflictError(`memory ${id} is already active; forget it before restoring its dormant copy`);
-            }
-            const now = new Date();
-            // Dormant rows are long-lived, so a snapshot can predate a field added
-            // later: createMemory supplies a default for anything it lacks, then
-            // the snapshot overrides every field it does carry, content included.
-            // (The placeholder only satisfies createMemory's minimum length, so a
-            // legacy row shorter than 3 chars can still be restored.)
-            const revived = {
-                ...createMemory('dormant snapshot defaults', { baseHalfLifeDays: loadConfig(ctx.hippoRoot).defaultHalfLifeDays }),
-                ...dormant.entry,
-                last_retrieved: now.toISOString(),
-            };
-            restored = stampOriginProject(ctx.hippoRoot, { ...revived, strength: calculateStrength(revived, now) });
-            writeEntryDbOnly(db, restored, { actor: ctx.actor.subject });
-            deleteDormantRow(db, ctx.tenantId, id);
-            // A restore is a labelled "forgot it, then needed it" event: the
-            // signal a learned lifecycle (ROADMAP LC3) trains on. Same transaction
-            // as the restore, so the label exists exactly when the restore does.
-            appendAuditEvent(db, {
-                tenantId: ctx.tenantId,
-                actor: ctx.actor.subject,
-                op: 'dormant_restore',
-                targetId: id,
-                metadata: {
-                    reason: dormant.reason,
-                    strengthAtDormancy: dormant.strength,
-                    dormantAt: dormant.dormantAt,
-                    daysDormant: Math.max(0, (now.getTime() - Date.parse(dormant.dormantAt)) / (24 * 60 * 60 * 1000)),
-                },
-            });
-            db.exec('COMMIT');
-        }
-        catch (err) {
-            try {
-                db.exec('ROLLBACK');
-            }
-            catch { /* already rolled back */ }
-            if (err instanceof RejectedValueError) {
-                auditRejectionRefusal(db, err, ctx.actor.subject);
-            }
-            throw err;
-        }
-        writeEntryMirrors(ctx.hippoRoot, restored);
-        return restored;
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-/**
- * Permanently delete a dormant memory: the explicit "forget it for good"
- * that dormant storage leaves to the user. Throws when the tenant has no
- * dormant memory with that id.
- */
-export function forgetDormant(ctx, id) {
-    const db = openHippoDb(ctx.hippoRoot);
-    try {
-        if (!deleteDormantRow(db, ctx.tenantId, id)) {
-            throw new NotFoundError(`dormant memory not found: ${id}`);
-        }
-        try {
-            appendAuditEvent(db, {
-                tenantId: ctx.tenantId,
-                actor: ctx.actor.subject,
-                op: 'forget',
-                targetId: id,
-                metadata: { dormant: true },
-            });
-        }
-        catch (error) {
-            // Best-effort, like every other forget audit row: the delete stands.
-            reportAuditWriteFailure('forget', String(error), id);
-        }
-    }
-    finally {
-        closeHippoDb(db);
-    }
-    // Counted like every other permanent removal (forget, archiveRaw).
-    updateStats(ctx.hippoRoot, { forgotten: 1 });
-}
-/** Whether the tenant holds a dormant memory with this id (for "not found" hints). */
-export function isDormant(ctx, id) {
-    const db = openHippoDb(ctx.hippoRoot);
-    try {
-        return hasDormantRow(db, ctx.tenantId, id);
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-const QUARANTINE_PREVIEW_CHARS = 200;
-/** A tenant's quarantined memories, newest first. Default `status` is 'pending' (the review queue). */
-export function quarantineList(ctx, opts = {}) {
-    const db = openHippoDb(ctx.hippoRoot);
-    try {
-        const rows = listQuarantineRows(db, ctx.tenantId, opts.status ?? 'pending', opts.limit);
-        return rows.map((row) => {
-            const entry = readEntry(ctx.hippoRoot, row.memoryId, ctx.tenantId);
-            return {
-                id: row.memoryId,
-                originalScope: row.originalScope,
-                reason: row.reason,
-                status: row.status,
-                quarantinedAt: row.quarantinedAt,
-                decidedAt: row.decidedAt,
-                decidedBy: row.decidedBy,
-                contentPreview: entry ? entry.content.slice(0, QUARANTINE_PREVIEW_CHARS) : '',
-            };
-        });
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-function loadPendingQuarantineRow(db, tenantId, id) {
-    const row = getQuarantineRow(db, tenantId, id);
-    if (!row)
-        throw new NotFoundError(`not quarantined: ${id}`);
-    if (row.status !== 'pending')
-        throw new ConflictError(`${id} is already ${row.status}`);
-    return row;
-}
-/** Release a quarantined memory to its original scope. Admin only; the scope guard refuses a row moved since (mirrors restoreDormant). */
-export function quarantineApprove(ctx, id) {
-    if (ctx.actor.role !== 'admin') {
-        throw new ForbiddenError('Only an admin key can approve a quarantined memory');
-    }
-    const db = openHippoDb(ctx.hippoRoot);
-    try {
-        db.exec('BEGIN IMMEDIATE');
-        try {
-            const row = loadPendingQuarantineRow(db, ctx.tenantId, id);
-            const quarantineScope = quarantineScopeFor(row.originalScope);
-            const updated = db
-                .prepare(`UPDATE memories SET scope = ? WHERE id = ? AND tenant_id = ? AND scope = ?`)
-                .run(row.originalScope, id, ctx.tenantId, quarantineScope);
-            if (Number(updated.changes ?? 0) !== 1) {
-                throw new ConflictError(`memory ${id} scope changed since quarantine; refusing to approve`);
-            }
-            approveQuarantineRow(db, ctx.tenantId, id, ctx.actor.subject);
-            appendAuditEvent(db, {
-                tenantId: ctx.tenantId,
-                actor: ctx.actor.subject,
-                op: 'quarantine_approve',
-                targetId: id,
-                metadata: { originalScope: row.originalScope },
-            });
-            db.exec('COMMIT');
-        }
-        catch (err) {
-            try {
-                db.exec('ROLLBACK');
-            }
-            catch { /* already rolled back */ }
-            throw err;
-        }
-    }
-    finally {
-        closeHippoDb(db);
-    }
-    // Post-commit, best-effort: a failed rewrite leaves the mirror showing the quarantine scope (fail-closed).
-    try {
-        const restored = readEntry(ctx.hippoRoot, id, ctx.tenantId);
-        if (restored)
-            writeEntryMirrors(ctx.hippoRoot, restored);
-    }
-    catch (err) {
-        log.error(`quarantine: mirror rewrite failed for ${id}: ${err instanceof Error ? err.message : String(err)}`);
-    }
-}
-/** Keep a quarantined memory hidden for good. Admin only; the raw row is untouched (append-only). */
-export function quarantineReject(ctx, id) {
-    if (ctx.actor.role !== 'admin') {
-        throw new ForbiddenError('Only an admin key can reject a quarantined memory');
-    }
-    const db = openHippoDb(ctx.hippoRoot);
-    try {
-        db.exec('BEGIN IMMEDIATE');
-        try {
-            loadPendingQuarantineRow(db, ctx.tenantId, id);
-            rejectQuarantineRow(db, ctx.tenantId, id, ctx.actor.subject);
-            appendAuditEvent(db, {
-                tenantId: ctx.tenantId,
-                actor: ctx.actor.subject,
-                op: 'quarantine_reject',
-                targetId: id,
-                metadata: {},
-            });
-            db.exec('COMMIT');
-        }
-        catch (err) {
-            try {
-                db.exec('ROLLBACK');
-            }
-            catch { /* already rolled back */ }
-            throw err;
-        }
-    }
-    finally {
-        closeHippoDb(db);
-    }
-}
-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,
-        };
-        // Set only when non-zero, so a store without dormant memories gets a
-        // byte-identical result (HTTP /v1/sleep, the CLI render snapshot).
-        if (consolidateResult.dormant > 0) {
-            result.dormant = consolidateResult.dormant;
-        }
-        if (consolidateResult.dormantExpired > 0) {
-            result.dormantExpired = consolidateResult.dormantExpired;
-        }
-        // Phase 2: Dedup (post-consolidate near-duplicate cleanup).
-        const dedupResult = phases.deduplicateStore(ctx.hippoRoot, { dryRun, actor: ctx.actor.subject });
-        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; a dry run skips rows earlier phases would remove).
-        const planned = new Set(dryRun ? [...(consolidateResult.removedIds ?? []), ...dedupResult.pairs.map((p) => p.removed)] : []);
-        const allEntries = phases.loadAllEntries(ctx.hippoRoot).filter((e) => !planned.has(e.id));
-        const auditOut = phases.auditMemories(allEntries, memoriesBackingObjects(ctx.hippoRoot));
-        if (auditOut.issues.length > 0) {
-            const errors = auditOut.issues.filter((i) => i.severity === 'error');
-            const warnings = auditOut.issues.filter((i) => i.severity === 'warning');
-            let removed = 0;
-            for (const issue of errors) {
-                const reason = `sleep-audit: ${issue.reason}`;
-                if (dryRun || phases.deleteEntry(ctx.hippoRoot, issue.memoryId, { actor: ctx.actor.subject, reason, automatic: true }))
-                    removed++;
-            }
-            auditDeletedCount = removed;
-            if (removed > 0 || warnings.length > 0) {
-                result.audit = {
-                    errorsRemoved: removed,
-                    warningCount: warnings.length,
-                };
-            }
-        }
-        if (dryRun)
-            return result;
-        // 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) {
-            // Logged, never thrown: a second failure must not mask the original phaseError.
-            reportAuditWriteFailure('consolidate', String(auditErr));
-        }
-    }
-}
-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 };
-}
+export * from './api/types.js';
+export * from './api/remember.js';
+export * from './api/recall-types.js';
+export * from './api/recall.js';
+export * from './api/assemble.js';
+export * from './api/drill-down.js';
+export * from './api/outcome.js';
+export * from './api/forget.js';
+export * from './api/promote.js';
+export * from './api/auth.js';
+export * from './api/audit.js';
+export * from './api/context-types.js';
+export * from './api/context.js';
+export * from './api/tokens.js';
+export * from './api/dormant.js';
+export * from './api/quarantine.js';
+export * from './api/sleep.js';
+export * from './api/goals.js';
+export * from './api/learn.js';
 //# sourceMappingURL=api.js.map