hippo-memory 1.59.0 → 1.61.0

package/dist/api.d.ts

@@ -1,1266 +1,26 @@
-/**
- * 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 { type DatabaseSyncLike } from './db.js';
-import { BadRequestError } from './api-errors.js';
 export { ApiError, BadRequestError, ConflictError, ForbiddenError, NotFoundError } from './api-errors.js';
-import { deleteEntry, loadAllEntries, type TaskSnapshot, type SessionEvent } from './store.js';
-import { type RejectedValueRow } from './rejection.js';
-import { type DormantMemory, type ListDormantOpts } from './dormant.js';
-import { type TokenSummary, type TokenSurface } from './token-ledger.js';
-import { type QuarantineStatus } from './quarantine.js';
-import { type FailureSummary } from './failure-log.js';
-import { type SessionHandoff } from './handoff.js';
-import { type MemoryKind, type MemoryEntry } from './memory.js';
-import { auditMemories, type AuditEvent, type AuditOp } from './audit.js';
-import { autoShare } from './shared.js';
-import type { DeliveryObserver } from './delivery-recorder.js';
-import { type ApiKeyListItem } from './auth.js';
-import { type RerankStep, type SearchResult } from './search.js';
-import { consolidate } from './consolidate.js';
-import { loadConfig } from './config.js';
-import { deduplicateStore } from './dedupe.js';
-import { computeAmbientState, type AmbientState } from './ambient.js';
-import { loadPendingExtractionTenants } from './graph.js';
-import { extractGraph } from './graph-extract.js';
-import { type PlanningFallacyHint, type PlanningFallacyWatching } from './predictions.js';
-import { type AnchoringHint, type RecallHistorySnapshot } from './recall-history.js';
-import { type AvailabilityHint } from './availability.js';
-/**
- * Actor identity + authorization role for a Context. v1.12.0 A5 v2 sub-1.
- *
- * Before v1.12.0, Context.actor was a bare string. v1.12.0 promotes it to an
- * object carrying both the audit-log subject (formerly the string itself) and
- * a role for /v1/sleep admin gating. Audit helpers continue accepting `string`
- * — callers pass `ctx.actor.subject`. Role checks happen at the request
- * boundary (e.g. /v1/sleep), except in authCreate and authRevoke (ForbiddenError).
- */
-export interface Actor {
-    /** 'cli' | 'localhost:cli' | 'api_key:<key_id>' | 'mcp' | 'connector:slack' | 'connector:github' */
-    subject: string;
-    role: 'admin' | 'member';
-    /** EI2: restricted scopes a member key may read (auth.ts grantScope). Unused for admin actors. */
-    scopes?: readonly string[];
-    /** An auth resolver vouched for this caller, so its admin role stops at its own tenant. */
-    viaAuthResolver?: true;
-}
-export interface Context {
-    hippoRoot: string;
-    tenantId: string;
-    actor: Actor;
-}
-/**
- * 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 declare function adminActor(subject: string): Actor;
-/**
- * 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 declare class RecallContractError extends BadRequestError {
-    readonly code: 'fresh_tail_requires_session_id' | 'invalid_scorer_window';
-    constructor(code: 'fresh_tail_requires_session_id' | 'invalid_scorer_window', message: string);
-}
-import { isPrivateScope, passesScopeFilterForRecall } from './recall-scope.js';
-export { isPrivateScope, passesScopeFilterForRecall };
+export { isPrivateScope, passesScopeFilterForRecall } from './recall-scope.js';
 export { passesCliRecallScopeFilter, ScopeForbiddenError } from './recall-scope.js';
 export type { TokenSummary, TokenSurface, TokenSurfaceSummary } from './token-ledger.js';
 export type { FailureSummary } from './failure-log.js';
 export { classifyOriginProject } from './project-identity.js';
-/**
- * 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 declare function ambientSecretAdmit(e: MemoryEntry, currentProjectName: string): boolean;
-export declare function oneCopyPerMemory(local: readonly MemoryEntry[], global: readonly MemoryEntry[], now: Date): [MemoryEntry[], MemoryEntry[]];
-export interface RememberOpts {
-    content: string;
-    kind?: MemoryKind;
-    scope?: string;
-    owner?: string;
-    artifactRef?: string;
-    tags?: string[];
-    /**
-     * Optional hook invoked inside the same transaction as the underlying
-     * memories INSERT. Used by ingestion connectors (E1.3+) to stamp
-     * idempotency / cursor rows atomically with the memory row, so a crash
-     * mid-write cannot produce a memory without its corresponding side-effect
-     * log row (or vice versa). If the callback throws, the INSERT is rolled
-     * back and the error is rethrown.
-     */
-    afterWrite?: (db: DatabaseSyncLike, memoryId: string) => void;
-    /** CD5: connector-ingested content an agent doesn't control; gates detectInstruction. CLI/HTTP/MCP never set this. */
-    untrusted?: boolean;
-}
-export interface RememberResult {
-    id: string;
-    kind: MemoryKind;
-    tenantId: string;
-    /** Set only when untrusted content was flagged and quarantined instead of stored under its requested scope. */
-    quarantined?: {
-        reason: string;
-    };
-    /** Set only when the content held secret material: untrusted text had it redacted, typed text was stored as sent. */
-    warnings?: string[];
-}
-export declare function remember(ctx: Context, opts: RememberOpts): RememberResult;
-export interface RecallOpts {
-    query: string;
-    limit?: number;
-    /**
-     * F3 (v1.7.0): scorer-window opt-in. When set, `loadSearchEntries`
-     * loads up to `scorerWindow` candidates. When undefined (default),
-     * the existing behaviour is preserved: store-internal 200-row default,
-     * which every release before v1.7.0 silently relied on.
-     *
-     * `scorerWindow` lets callers decouple "how many candidates do I want
-     * the scorer to evaluate" from `limit` ("how many do I want returned").
-     * Useful when `summarizeOverflow=true` and you want a wider candidate
-     * pool to detect more level-2 parent clusters.
-     *
-     * NOT a hard cap on returned results. Fresh-tail and substituted
-     * summaries can extend the result count above `limit`. The CLI's
-     * existing slice in `cmdRecall` (cli.ts) is the CLI hard cap; library
-     * callers slice themselves if they want one.
-     *
-     * Validated as a positive finite integer when set. `scorerWindow: 0`
-     * or non-finite values throw `RecallContractError` with code
-     * `invalid_scorer_window` to prevent the v1.6.x footgun where 0 fell
-     * through to an uncapped fallback (codex v1.7.0 diff-pass P1).
-     *
-     * **Input is library-only at v1.7.0.** HTTP `/v1/memories`, MCP
-     * `hippo_recall`, and `client.ts` thin-client do NOT serialize this
-     * INPUT field; remote callers cannot send `scorerWindow` and will see
-     * the store default applied. The OUTPUT `RecallResult.windowSize` is
-     * always serialized over the wire (HTTP `sendJson` ships the whole
-     * RecallResult, so remote callers receive `windowSize: 200` in the
-     * response). Transport exposure for the input planned for v1.7.1
-     * alongside the deferred-queue items that need a wider candidate pool
-     * (e.g. mean-of-children summary re-rank).
-     */
-    scorerWindow?: number;
-    /** Candidate order. `recall` always keeps the BM25 order; `retrieve` honours this. */
-    mode?: 'bm25' | 'hybrid' | 'physics';
-    /**
-     * Restrict results to memories whose `scope` equals this value exactly.
-     *
-     * When `scope` is undefined or empty, recall applies a DEFAULT-DENY rule:
-     * any memory whose scope starts with `'slack:private:'` is filtered out so
-     * a frontend caller passing `undefined` cannot accidentally surface
-     * private-channel content. Memories with scope=null (the common case for
-     * non-Slack content) are still returned.
-     */
-    scope?: string;
-    /**
-     * v1.5.0 DAG-aware recall. When true (default), entries that overflow the
-     * `limit` and share a level-2 parent summary cause that summary to be
-     * appended in their place, capped at ceil(limit * 0.3) extra rows. Set to
-     * false to disable and get the pre-v1.5 strict-limit behaviour.
-     */
-    summarizeOverflow?: boolean;
-    /**
-     * v1.5.2 fresh-tail. When > 0, prepend the last N kind='raw' rows
-     * (tenant + scope filtered, dedup against the BM25 hits) so an agent's
-     * "what did I just see" recall path always covers the recent window
-     * even when the query terms don't match. Capped at 200. Default 0 = off.
-     */
-    freshTailCount?: number;
-    /**
-     * v1.6.2 fresh-tail session scope. When set, restricts the fresh-tail
-     * window to a specific session. Without it, fresh-tail is tenant-wide,
-     * which surfaces newest rows across ALL sessions — useful for "anything
-     * new in this tenant", but wrong for "what did I just see in this one
-     * conversation". Set to ctx-supplied session id for the correct shape.
-     */
-    freshTailSessionId?: string;
-    /**
-     * When true, include a continuity block (active task snapshot, latest matching
-     * session handoff, recent session events) on the result. Default false to keep
-     * the hot path cheap; agent boot paths should set this to true.
-     *
-     * All three lookups are tenant-scoped to ctx.tenantId via the v0.40+ store
-     * helpers. No risk of cross-tenant leak.
-     *
-     * Note: when no active snapshot exists, sessionHandoff is null and
-     * recentSessionEvents is []. We deliberately do NOT fall back to the latest
-     * tenant handoff without a session anchor, to avoid resurrecting stale state
-     * after a session ends. The explicit handoff-without-snapshot path remains
-     * `hippo session resume`.
-     */
-    includeContinuity?: boolean;
-    /**
-     * v1.7.4 -- when set AND `(ctx.tenantId, sessionId)` has active goals AND
-     * `goalTag` is unset, `api.recall` applies the dlPFC goal-stack boost lifted
-     * from CLI cmdRecall. Pre-v1.7.4 the boost was CLI-only (env-driven via
-     * HIPPO_SESSION_ID). Undefined preserves v1.7.3 behaviour (no boost).
-     *
-     * Why on RecallOpts and not Context: Context is shared by remember/recall/
-     * assemble/outcome. Goal-stack boost is recall-scoped only.
-     */
-    sessionId?: string;
-    /**
-     * v1.7.4 -- explicit goal-tag override. When set, the goal-stack boost is
-     * SUPPRESSED (mirrors the CLI's `goalTag === ''` gate from v0.38). Use to
-     * pin recall ranking against one specific goal/tag without the multi-goal
-     * stack interfering.
-     */
-    goalTag?: string;
-    /**
-     * v0.33 / J1 anchoring detector. Caller-supplied snapshot of the per-
-     * (tenant, session) recall ring. When present, api.recall computes
-     * `RecallResult.anchoringHint` against this snapshot + the just-computed
-     * top-1. When undefined (default), no anchoring detection runs on the
-     * api.recall surface — but a calling pipeline (CLI cmdRecall, MCP
-     * hippo_recall) MAY compute its own hint via the shared
-     * `detectAnchoring()` helper against its own ring + top-1.
-     *
-     * Pure read: api.recall NEVER mutates the snapshot or any caller-side
-     * Map. Caller is responsible for appending to its own ring after the
-     * recall (passing the resulting hint's memoryId as `anchoredOn` to feed
-     * the cooldown logic on the NEXT recall).
-     */
-    recallHistory?: RecallHistorySnapshot;
-    /**
-     * v1.13.x / J2 — when true, api.recall does NOT compute or emit the
-     * availabilityHint. Callers that run their OWN per-pipeline availability
-     * detection over a different result set (the MCP handler computes it over
-     * physics/hybrid results, not api.recall's BM25 band) pass this to avoid a
-     * double audit emission and a hint describing a result set the caller never
-     * surfaces. Mirrors how J1 only computes anchoring when opts.recallHistory
-     * is supplied. HTTP / direct SDK callers leave this unset and receive the hint.
-     */
-    suppressAvailabilityHint?: boolean;
-    /**
-     * A7 recall-trace. When true, api.recall captures the lifecycle re-ranking
-     * trace (currently the goal-boost step on the primary band) and attaches it
-     * to each `RecallResultItem` as `rerankTrace`, plus `rerankPipeline:'api'`.
-     * When undefined/false (default), both fields are absent on EVERY band so
-     * the response shape is byte-identical to pre-A7. The api pipeline applies
-     * only goal-boost; the richer CLI stages (interference/value/utility/
-     * reranker/retrieval-count-downweight) are A7.2.
-     */
-    explain?: boolean;
-    /**
-     * LC1 (docs/plans/2026-08-02-lc1-recall-trace-persistence.md) / F2 fix.
-     * When true, api.recall does NOT write a recall_traces row for this call.
-     * Mirrors `suppressAvailabilityHint`'s pattern: callers that run their OWN
-     * tracing over a DIFFERENT result set must suppress api.recall's copy so
-     * the training corpus doesn't get a trace mislabeled as 'api' pipeline
-     * when the caller's actual user-visible results came from elsewhere. Under
-     * `showRanked` it also drops the 'mcp' trace of the shown list. HTTP /
-     * direct SDK callers leave this unset and get the trace.
-     */
-    suppressRecallTrace?: boolean;
-    /** Set only by the MCP recall tool, which ranks with its own scorer and drops copies from its own final list: this call
-     *  then keeps a memory that a merged row in the same result holds word for word. Other callers leave it unset. */
-    keepHeldCopies?: boolean;
-    /** MCP recall only: `retrieve` ranks the whole scoped store and strengthens and traces (pipeline 'mcp') just the ids this returns; `results` stays the window band. */
-    showRanked?: (ranking: StoreRanking, result: RecallResult) => readonly string[];
-}
-/** `ranked`: every scored row, best first, goal boost applied, entries as loaded; `pool`: the store after the scope filter. */
-export interface StoreRanking {
-    ranked: SearchResult[];
-    pool: MemoryEntry[];
-    droppedByScope: number;
-}
-export interface ContinuityBlock {
-    activeSnapshot: TaskSnapshot | null;
-    sessionHandoff: SessionHandoff | null;
-    recentSessionEvents: SessionEvent[];
-}
-export interface RecallResultItem {
-    id: string;
-    content: string;
-    score: number;
-    layer: string;
-    strength: number;
-    /**
-     * v1.5.0 DAG-aware recall (docs/plans/2026-05-05-dag-recall.md Task 2).
-     * True when this row is a level-2 topic summary substituted in for
-     * overflowed children that didn't fit the limit.
-     */
-    isSummary?: boolean;
-    /**
-     * IDs of the overflow leaves this summary covers. Caller can drill
-     * into these via `drillDown` (Task 3) to recover the original detail.
-     */
-    substitutedFor?: string[];
-    /** Cached descendant count from schema v25; non-zero for level-2+ rows. */
-    descendantCount?: number;
-    /**
-     * v1.5.2 fresh-tail (docs/plans/2026-05-05-dag-recall.md Task 4). True
-     * for rows surfaced via the most-recent-N kind='raw' window, NOT by the
-     * BM25 query match. Caller can render them in a separate "recent" band.
-     */
-    isFreshTail?: boolean;
-    /**
-     * A7 recall-trace. Ordered lifecycle re-ranking steps that mutated this
-     * row's `score` after candidate generation. On the api pipeline this carries
-     * the goal-boost step (the only re-ranking api.recall applies). Populated
-     * ONLY when `RecallOpts.explain` is set; absent on the default path
-     * (additive optional, back-compat per the `windowSize?` precedent;
-     * `client.ts` deserializes `as RecallResult` so the field rides through).
-     */
-    rerankTrace?: RerankStep[];
-    /**
-     * A7 recall-trace. Names which pipeline produced `rerankTrace`. `'api'` on
-     * every band returned by `api.recall` when `explain` is set; the CLI carries
-     * its trace on `SearchResult` instead and does not set this. Absent on the
-     * default path. Distinguishes the api pipeline (goal-boost only) from the
-     * richer CLI pipeline (A7.2 will unify them).
-     */
-    rerankPipeline?: 'cli' | 'api';
-}
-export interface RecallResult {
-    results: RecallResultItem[];
-    total: number;
-    tokens: number;
-    continuity?: ContinuityBlock;
-    /**
-     * Tokens consumed by the continuity block: snapshot (task + summary + next_step)
-     * + handoff (summary + nextAction + artifacts + constraints + evidence line)
-     * + every event's full content across the last 5 events. Each measured by Math.ceil(len/4), matching
-     * the existing `tokens` count and src/search.ts estimateTokens().
-     * Undefined when continuity not requested. Callers needing a tighter budget
-     * should truncate event.content themselves before display.
-     */
-    continuityTokens?: number;
-    /**
-     * F3 (v1.7.0): scorer window actually used for this recall. Equals
-     * `opts.scorerWindow` when set, otherwise the store-internal default
-     * (200) used by `loadSearchEntries(undefined, ...)`. Reported so
-     * callers can introspect "did the scorer see enough candidates?"
-     * without re-deriving the value.
-     *
-     * Optional in the type to keep `RecallResult` literal-construction
-     * back-compatible with pre-v1.7 test fakes / mocks (senior review P1-2).
-     * Always present on values returned by `api.recall` itself; consumers
-     * reading from `api.recall` can treat it as defined.
-     */
-    windowSize?: number;
-    /**
-     * v1.12.13 / C5 — WYSIATI cutoff transparency. When present, gives the
-     * calling agent a per-pipeline breakdown of what was excluded from
-     * `results[]` and why. Always populated by `api.recall`, `cmdRecall`, and
-     * the MCP `hippo_recall` handler. Optional in the type for back-compat
-     * with test fakes / mocks (same pattern as `windowSize?`).
-     *
-     * Counters reflect actual filter activity in the pipeline that produced
-     * THIS specific RecallResult. api.recall counts its own filter sites;
-     * cmdRecall counts its (richer) filter sites; MCP counts the physics/
-     * hybrid pipeline's filter sites. Shape is identical across surfaces;
-     * numbers are honest per-path reports, NOT normalised cross-pipeline
-     * counts.
-     */
-    suppressionSummary?: RecallSuppressionSummary;
-    /**
-     * v0.32 / J3.2 — auto-injected planning-fallacy hint. When the recall
-     * query carries a forward-prediction phrase ("will take ~3 days", "ship
-     * by Friday", "ETA in 2 weeks") AND the closest matching prediction
-     * class has closed historical data, this carries the base-rate stats so
-     * the calling agent sees its track record at the moment of forecasting
-     * (Lovallo-Kahneman 2003 inside-vs-outside view).
-     *
-     * Populated by `api.recall` itself via `computePlanningFallacyOutput`.
-     * Pipeline-invariant: the value depends only on (queryText, tenantId,
-     * predictions table state) — all three are identical regardless of
-     * which downstream search pipeline produces the memory list, so MCP
-     * and CLI both read this field as the single source of truth (unlike
-     * `suppressionSummary` which is per-pipeline).
-     *
-     * Optional in the type so existing test fakes / mocks of RecallResult
-     * remain valid (same pattern as `windowSize?` / `suppressionSummary?`).
-     * Disabled by setting `HIPPO_AUTODEBIAS=off`.
-     */
-    planningFallacyHint?: PlanningFallacyHint;
-    /**
-     * v1.13.4 / J3.2 follow-up — "watching" variant emitted when the
-     * forward-claim regex matched but no baserate could be produced
-     * (either because no prediction class scored ≥ 1 on token overlap,
-     * or because ≥2 classes tied at the best score). Mutually exclusive
-     * with `planningFallacyHint`: at most one of the two is set per
-     * recall. Dogfood diary (docs/dogfood/2026-05-27-track-j-warnings.md)
-     * Trial 2a confirmed the pre-v1.13.4 silent-no-class-match path was
-     * the dominant J3.2 failure mode, because natural-language queries
-     * rarely share non-stopword tokens with class tags. The watching
-     * variant gives the agent enough signal to either re-tag the
-     * prediction or pass the suggestion through to the user.
-     *
-     * Pipeline-invariant same as `planningFallacyHint`. Honoured by
-     * api.recall, cmdRecall, and MCP handler render paths.
-     * Disabled by setting `HIPPO_AUTODEBIAS=off`.
-     */
-    planningFallacyWatching?: PlanningFallacyWatching;
-    /**
-     * v0.33 / J1 (v1.13.2) — recall-recurrence anchoring hint. Populated
-     * when api.recall's `opts.recallHistory` snapshot + the just-computed
-     * top-1 satisfy R1 (query_repeat) or R2 (memory_dominance).
-     *
-     * Per-pipeline detection: each pipeline (api.recall, cmdRecall, MCP)
-     * computes its OWN hint against its OWN top-1. This field reflects
-     * api.recall's compute ONLY. On CLI-routed call paths cmdRecall does
-     * NOT thread its ring snapshot through `opts.recallHistory`, so this
-     * field is null on CLI-routed calls even when CLI's own hint fires
-     * (the user-visible hint there comes from cmdRecall's parallel
-     * compute, surfaced via the CLI render path + cmdSuppressionSummary).
-     * Non-null on direct SDK / HTTP-routed invocations where the caller
-     * threads its own ring snapshot.
-     *
-     * Disabled by setting `HIPPO_ANCHORING=off`.
-     */
-    anchoringHint?: AnchoringHint;
-    /**
-     * v1.13.x / J2 — availability/recency-bias hint. Per-pipeline (computed
-     * against this pipeline's own returned top-K + the matched candidate pool
-     * it was drawn from), soft-warning ONLY: never filters, reorders, or
-     * suppresses a result. Fires when the returned slice is recency-dominated
-     * while substantially older relevant matches in the same pool were passed
-     * over. Disabled by setting `HIPPO_AVAILABILITY=off`.
-     */
-    availabilityHint?: AvailabilityHint;
-}
-/**
- * v1.12.13 / C5 — WYSIATI cutoff transparency (Track C Pineal Gland, C5).
- *
- * Surfaces what the recall pipeline excluded from `results[]` so the calling
- * agent does not treat the cutoff as the full picture (Kahneman's "What You
- * See Is All There Is" failure mode, TFAS ch. 7). Each counter reflects
- * filter activity in the pipeline that produced this RecallResult; counts
- * are honest per-path reports, not normalised cross-pipeline numbers.
- *
- * See `buildSuppressionSummary` for the shared construction helper used by
- * all three pipelines (api.recall, cmdRecall, MCP).
- */
-export interface RecallSuppressionSummary {
-    /** Total candidates loaded from the store, before any post-load filter or
-     *  limit cut. Per-pipeline source:
-     *  - api.recall: `all.length` immediately after `loadRecallSearchEntries`
-     *  - cmdRecall: candidate count immediately after the initial load
-     *  - MCP physics/hybrid: count of entries passed to physicsSearch/hybridSearch
-     */
-    totalCandidates: number;
-    /** Candidates dropped by any non-budget filter site (pre-rank OR post-rank,
-     *  but NOT the final budget cut). Field name retains the `preRank` label
-     *  for the original framing; semantically: any filter drop that is not the
-     *  final limit slice. Per-pipeline source:
-     *  - api.recall: `all.length - entries.length` (private-scope JS filter + scope-mismatch defense; pre-rank)
-     *  - cmdRecall: SUM of drops from `--as-of`, default-drop of superseded (when `--include-superseded` not set), `--filter-conflicts` (`.filter` drop only), `--outcome` (post-rank), `--layer` (post-rank). `--salience-threshold` HARD drops would also land here; current implementation is soft-rebalance only (logged in `ScoreBreakdown`, not here).
-     *  - MCP physics/hybrid: scope-filter drops at the MCP handler before physicsSearch
-     */
-    droppedPreRank: number;
-    /** Candidates loaded but excluded by the final `limit` slice after scoring.
-     *  Per-pipeline source:
-     *  - api.recall: `entries.length - baseSlice.length`
-     *  - cmdRecall: pre-slice candidate count minus final slice count
-     *  - MCP physics/hybrid: pre-slice minus post-slice at the physics/hybrid limit
-     */
-    droppedByBudget: number;
-    /** Substituted DAG-L2 summaries added back to mitigate overflow.
-     *  Per-pipeline source:
-     *  - api.recall: `substituted.length` after the `summarizeOverflow` block
-     *  - cmdRecall: 0 (CLI does not run summarizeOverflow)
-     *  - MCP physics/hybrid: count of summary rows appended from apiResult.tailOrSummary
-     */
-    summarySubstitutionsAdded: number;
-    /** Fresh-tail `kind='raw'` rows prepended.
-     *  Per-pipeline source:
-     *  - api.recall: `freshRanked.length` when `freshTailCount > 0`; else 0
-     *  - cmdRecall: 0 (CLI does not currently expose fresh-tail)
-     *  - MCP physics/hybrid: count of fresh-tail rows appended from apiResult.tailOrSummary
-     */
-    freshTailAdded: number;
-    /** Counter of memories suppressed by detected interference patterns.
-     *  v0.33 / J1 (v1.13.2): incremented by 1 PER PIPELINE when that
-     *  pipeline's own R2 memory_dominance verdict fires (via the J1
-     *  anchoring detector — see `detectAnchoring()` in src/recall-history.ts).
-     *  Each pipeline (api.recall, cmdRecall, MCP physics/hybrid) bumps its
-     *  OWN suppressionSummary independently because each runs its own
-     *  detector against its own top-1 + its own per-(tenant, session) ring
-     *  buffer. The number reflects this-pipeline interference only; not a
-     *  cross-pipeline aggregate.
-     *
-     *  Future B4-depth work may add additional sources (e.g. vlPFC inhibition
-     *  scores). No `interference_suppression` table is built — the v1.12.13
-     *  doc that referenced one was speculative; J1 uses caller-side in-memory
-     *  rings instead.
-     */
-    suppressedByInterference: number;
-}
-/**
- * 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 declare function buildSuppressionSummary(counts: {
-    totalCandidates: number;
-    droppedPreRank: number;
-    droppedByBudget: number;
-    summarySubstitutionsAdded: number;
-    freshTailAdded: number;
-    suppressedByInterference: number;
-}): RecallSuppressionSummary;
-/**
- * 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 declare function recall(ctx: Context, opts: RecallOpts): RecallResult;
-/** Mode-aware recall that strengthens each returned row; never writes last_retrieval_ids (v1.11.5 lock). */
-export declare function retrieve(ctx: Context, opts: RecallOpts): Promise<RecallResult>;
-export interface AssembleOpts {
-    /** Token budget. Default 4000. */
-    budget?: number;
-    /** Recent raw rows always kept verbatim. Default 10. */
-    freshTailCount?: number;
-    /** Substitute parent summaries for older raws when ≥2 share a level-2
-     *  ancestor. Default true. */
-    summarizeOlder?: boolean;
-    /**
-     * Restrict to a specific scope. v1.6.1 senior-review P1 #3 parity with
-     * `recall`: when set, exact match required (so an authorised caller can
-     * assemble a `slack:private:CSEC` session by passing scope explicitly).
-     * When undefined, default-deny applies to ANY `<source>:private:*` and
-     * `unknown:legacy` rows.
-     */
-    scope?: string;
-    /**
-     * Hard row cap on the SELECT that loads session raws. Default 5000 to
-     * protect against degenerate sessions. When the cap is hit, `truncated`
-     * is set on the result so the caller knows to widen.
-     */
-    rowCap?: number;
-    cost?: AssembleCost;
-}
-export interface AssembleCost {
-    item: (it: AssembledContextItem) => number;
-    fixed: (widest: number) => number;
-}
-export interface AssembledContextItem {
-    id: string;
-    content: string;
-    /** ISO timestamp of the source row's `created` field (or `earliest_at`
-     *  for substituted summaries). */
-    createdAt: string;
-    /** Fresh-tail protected window (last freshTailCount raws). */
-    isFreshTail?: boolean;
-    /** Level-2 summary substituted for older raw rows that share a parent. */
-    isSummary?: boolean;
-    /** When isSummary, the raw ids this summary covers. drillDown
-     *  recovers the originals. */
-    substitutedFor?: string[];
-    /** Decay × retrieval × emotional. Lets callers render a confidence
-     *  hint without re-deriving from MemoryEntry. */
-    strength: number;
-}
-export interface AssembleResult {
-    sessionId: string;
-    items: AssembledContextItem[];
-    tokens: number;
-    /**
-     * Tenant + scope-filtered raw row count for the session — what the caller
-     * could have seen given their grant. Pre-v1.6.1 was pre-filter (confusing
-     * for all-private sessions); pre-v1.6.3 was capped (under-reported on
-     * sessions > rowCap). v1.6.3 reports the FULL post-filter count via a
-     * separate COUNT(*) query so consumers can render "session has N msgs"
-     * accurately even when items[] is the windowed view.
-     */
-    totalRaw: number;
-    summarized: number;
-    evicted: number;
-    /**
-     * True when `rowCap` truncated the loaded window. With v1.6.2's NEWEST-cap
-     * semantics, the items[] array represents the freshest tail of the session;
-     * older rows beyond the cap are silently absent. Use `totalRaw - items.length
-     * - summarized + ...` to estimate how much you didn't see, or widen `rowCap`.
-     */
-    truncated: boolean;
-}
-/**
- * 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 declare function assemble(ctx: Context, sessionId: string, opts?: AssembleOpts): AssembleResult;
-export interface DrillDownOpts {
-    /** Cap on number of children returned. Default 50. */
-    limit?: number;
-    /**
-     * Optional token budget. When set, children are appended in chronological
-     * order (created ASC) until adding the next child would exceed the budget.
-     * Token cost = the child's printed line under `cost`, else ceil(content.length / 4).
-     *
-     * For depth > 1, the budget is GLOBAL cumulative (NOT per-level).
-     */
-    budget?: number;
-    /**
-     * v0.30 / E5 — walk N levels down (default 1 = direct children only).
-     * Higher values include children of children, etc. Internal hard cap 10
-     * to prevent pathological depth walks. BFS uses visited Set for dedup
-     * (defensive against shared-child data anomalies; DAG is acyclic by
-     * construction).
-     */
-    depth?: number;
-    cost?: DrillDownCost;
-}
-export interface DrillDownSummary {
-    id: string;
-    content: string;
-    descendantCount: number;
-    earliestAt: string | null;
-    latestAt: string | null;
-}
-export interface DrillDownChild {
-    id: string;
-    content: string;
-    layer: string;
-    dagLevel: number;
-    created: string;
-}
-export interface DrillDownCost {
-    child: (c: DrillDownChild) => number;
-    fixed: (summary: DrillDownSummary, widest: number) => number;
-}
-export interface DrillDownResult {
-    summary: DrillDownSummary;
-    children: DrillDownChild[];
-    totalChildren: number;
-    truncated: boolean;
-}
-/**
- * v1.6.4 discriminated failure shape. Two reasons distinguishable:
- *   - `not_found`: covers genuinely-missing, wrong-tenant, AND
- *     scope-blocked (codex round 3 P1 — distinguishing scope_blocked
- *     from not_found on non-HTTP surfaces leaked private-row existence
- *     to no-scope callers, even though the HTTP route already collapsed
- *     them. Collapse at the API layer.)
- *   - `not_drillable`: id is a leaf row (level 0/1). Caller-actionable.
- *
- * If a future drillDown gains a `scope` opt for explicit-scope callers,
- * a `scope_blocked` failure could be safely re-introduced ONLY for that
- * code path (caller already proved authorization by passing a scope).
- */
-export interface DrillDownFailure {
-    failure: 'not_found' | 'not_drillable';
-}
-export type DrillDownOutcome = DrillDownResult | DrillDownFailure;
-/**
- * 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 declare function drillDown(ctx: Context, summaryId: string, opts?: DrillDownOpts): DrillDownOutcome;
-/**
- * Apply a positive/negative outcome to a list of recently-recalled memory ids.
- * Used by the MCP `hippo_outcome` tool and the HTTP `POST /v1/outcome` route.
- * Tenant-scoped: ids that don't belong to ctx.tenantId are silently skipped
- * (matches the prior MCP semantics — a stale id from another tenant doesn't
- * crash the call). Each successful outcome emits one audit_log row with
- * op='outcome' tagged with ctx.actor.subject.
- *
- * Returns `{applied, appliedIds}`. `appliedIds` is the tenant-filtered subset
- * of input ids that actually had `applyOutcome` run on them (i.e. ids whose
- * `readEntry(..., ctx.tenantId)` resolved). Callers that surface the id list
- * over a multi-tenant boundary (HTTP /v1/outcome last-recall path, Python SDK)
- * MUST return `appliedIds` instead of the raw input list — otherwise the
- * non-applied (cross-tenant) ids leak to the caller. Added in v1.11.4 to
- * close that disclosure path on POST /v1/outcome.
- *
- * `opts.traceId` (LC1, docs/plans/2026-08-02-lc1-recall-trace-persistence.md):
- * OPTIONAL additive opt so a programmatic caller can link this outcome to
- * the recall_traces row it judges. NOT applied unconditionally — an SDK
- * caller passing explicit ids with no preceding CLI/context recall would
- * otherwise get linked to a stale, unrelated trace. `outcomeForLastRecall`
- * supplies this automatically from `last_trace_id`; every other caller
- * (server.ts explicit-ids path, MCP hippo_outcome) omits it and gets no
- * linkage, which is correct.
- */
-export interface OutcomeResult {
-    applied: number;
-    appliedIds: string[];
-}
-export declare function outcome(ctx: Context, ids: ReadonlyArray<string>, good: boolean, opts?: {
-    traceId?: number;
-}): OutcomeResult;
-/**
- * Delete a memory by id. `deleteEntry` threads ctx.actor.subject into its internal
- * audit hook, so exactly one 'forget' event lands with the supplied actor.
- *
- * Tenant scope: deleteEntry looks up the row by id alone, so without an
- * explicit tenant guard a Bearer for tenant A could delete tenant B's row
- * by guessing or leaking the id. Pre-check the row's tenant_id and deny
- * cross-tenant access with a not-found error (no info leak about whether
- * the id exists in another tenant).
- */
-export interface ForgetResult {
-    ok: true;
-    id: string;
-}
-export declare function forget(ctx: Context, id: string): ForgetResult;
-export interface RejectOpts {
-    /** By-id form: reject the CURRENT content of an existing memory. */
-    memoryId?: string;
-    /** Pre-emptive form: reject a value not currently stored (or already gone). */
-    value?: string;
-    /** Required — the tombstone stores no content; reason is its only identity. */
-    reason: string;
-}
-export interface RejectResult {
-    digest: string;
-    removedIds: string[];
-}
-/**
- * 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 declare function reject(ctx: Context, opts: RejectOpts): RejectResult;
-/**
- * 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 declare function unreject(ctx: Context, digestOrPrefix: string): {
-    ok: boolean;
-    digest: string;
-};
-/** List every rejected-value tombstone for `ctx.tenantId`, newest first. */
-export declare function listRejections(ctx: Context): RejectedValueRow[];
-/**
- * Copy a local memory into the global store. Mirrors `cmdPromote` in cli.ts:
- * the `writeEntry` inside `promoteToGlobal` emits a 'remember' on the global
- * db; we add a 'promote' audit event on the global db so the user-facing
- * intent stays distinct from the underlying upsert.
- *
- * Note: `promoteToGlobal` does not currently take a tenantId override — it
- * reads the entry from the local root via `readEntry` (no tenant filter) and
- * preserves the entry's existing tenantId on the global side. Task 4 may
- * tighten this once writeEntry/readEntry thread tenant context.
- */
-export interface PromoteResult {
-    ok: true;
-    sourceId: string;
-    globalId: string;
-}
-export declare function promote(ctx: Context, id: string): PromoteResult;
-/**
- * Replace an old memory with new content, chaining old.superseded_by = new.id.
- * Mirrors `cmdSupersede` in cli.ts (without flag-driven layer/tag/pin overrides
- * — A1 keeps the API minimal; the CLI handler will continue to handle those
- * flags and pass the resolved values once Task 4 lands).
- */
-export interface SupersedeResult {
-    ok: true;
-    oldId: string;
-    newId: string;
-}
-export declare function supersede(ctx: Context, oldId: string, newContent: string): SupersedeResult;
-/**
- * Archive a kind='raw' memory: snapshot into raw_archive, mark archived, delete.
- *
- * `archiveRawMemory` audits the operation internally (op='archive_raw') using the
- * row's own tenant_id. We DO NOT emit a second audit event here to avoid double-
- * emitting the archive_raw op (unlike Task 1 remember/forget where the underlying
- * helpers hardcode actor='cli'). Instead we pass `ctx.actor.subject` through as `who`,
- * and raw-archive.ts uses that for the audit row.
- */
-export interface ArchiveRawOpts {
-    /**
-     * Connector idempotency hook (v0.39 commit 3). Runs inside the same
-     * SAVEPOINT as the archive — throwing rolls the archive back. Used by the
-     * Slack deletion connector to mark the deletion event seen atomically.
-     */
-    afterArchive?: (db: DatabaseSyncLike, archivedMemoryId: string) => void;
-}
-export interface ArchiveRawResult {
-    ok: true;
-    archivedAt: string;
-}
-export declare function archiveRaw(ctx: Context, id: string, reason: string, opts?: ArchiveRawOpts): ArchiveRawResult;
-export interface AuthCreateOpts {
-    label?: string;
-    /**
-     * v1.12.3: authorization role for the new key. Defaults to `'admin'` for
-     * back-compat with v1.12.0-v1.12.2 (the api_keys.role column DEFAULT also
-     * resolves to 'admin' if omitted from the INSERT). Member keys are
-     * 403-blocked from admin-gated routes (e.g. `POST /v1/sleep`).
-     */
-    role?: 'admin' | 'member';
-}
-export interface AuthCreateResult {
-    keyId: string;
-    plaintext: string;
-    tenantId: string;
-    /** v1.12.3: the role bound to the new key (admin | member). */
-    role: 'admin' | 'member';
-}
-/**
- * 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 declare function authCreate(ctx: Context, opts: AuthCreateOpts): AuthCreateResult;
-/**
- * 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 declare function authList(ctx: Context, opts: {
-    active: boolean;
-}): ApiKeyListItem[];
-/**
- * Revoke an API key.
- *
- * Security: the key must belong to `ctx.tenantId`. Cross-tenant revoke is
- * rejected with the "not found" message used for missing keys, and a member may
- * revoke only its own key (checked first), so no caller can probe other key_ids.
- *
- * Audit: emits 'auth_revoke' with `tenantId` set to the KEY ROW's tenant_id
- * (M1 fix from A5 review, mirrors src/cli.ts:cmdAuthRevoke). Skipped on no-op
- * revoke (already revoked) so re-running doesn't pad the audit log.
- */
-export interface AuthRevokeResult {
-    ok: true;
-    revokedAt: string;
-}
-export declare function authRevoke(ctx: Context, keyId: string): AuthRevokeResult;
-/** Shared result shape for authGrant/authUngrant, named per the file's oxlint anti-slop rule. */
-export interface AuthGrantResult {
-    ok: true;
-}
-/** Grant `keyId` read access to one restricted `scope` (ROADMAP Part VIII EI2). Admin only. */
-export declare function authGrant(ctx: Context, keyId: string, scope: string): AuthGrantResult;
-/** Revoke `keyId`'s grant on `scope`. Same authorization and lookup rules as authGrant. */
-export declare function authUngrant(ctx: Context, keyId: string, scope: string): AuthGrantResult;
-export interface AuditListOpts {
-    op?: AuditOp;
-    /** ISO timestamp lower bound. */
-    since?: string;
-    limit?: number;
-}
-/**
- * Read audit events scoped to `ctx.tenantId`. Read-only — no audit emit (matches
- * A5: cmdAuditList does not record a 'recall'-style read event).
- */
-export declare function auditList(ctx: Context, opts: AuditListOpts): AuditEvent[];
-/**
- * Options for `getContext` — assemble a budget-bounded context bundle
- * (recalled memories + active task snapshot + handoff + recent events).
- * Extracted from `cmdContext` in `cli.ts` in Episode A of the api.ts refactor.
- *
- * Named `getContext` (not `context`) to avoid collision with the `Context`
- * interface above and the ubiquitous `ctx: Context` convention. Follows the
- * existing `getEntry` naming pattern in store.ts.
- *
- * Scope narrow (T5 execute decision): rendering opts (`format`, `framing`,
- * `rendered`) and host-side opts (`auto`) are NOT included here. The print
- * helpers (`printContextMarkdown`, `printActiveTaskSnapshot`, `printHandoff`,
- * `printSessionEvents`) are shared with `cmdRecall` / `cmdSnapshot` /
- * `cmdHandoffShow` — moving them into api.ts would expand T5 to also rewire
- * those commands. CLI handles rendering + auto-resolution. Episode B can add
- * `api.renderContext` once a shared rendering need actually materializes.
- */
-export interface ContextOpts {
-    q?: string;
-    /** Default 1500 tokens. */
-    budget?: number;
-    limit?: number;
-    pinnedOnly?: boolean;
-    scope?: string;
-    /** Envelope scope to match exactly, as in `recall`: admits that scope even when private, after the actor's scope check. */
-    exactScope?: string;
-    /** With `pinnedOnly`, also inject the N most recent writes that pass the
-     *  quality floor (`isContentWorthStoring`, DF3). Filtering happens BEFORE
-     *  the take-N, so a caller asking for 5 gets 5 qualifying entries rather
-     *  than 5-minus-junk; pinned entries bypass the floor. Entries are only
-     *  skipped for this read, never mutated or deleted. Ignored when
-     *  `pinnedOnly` is false — no other path reads it. */
-    includeRecent?: number;
-    /** v39 memory scope isolation: re-include other-project memories that the
-     *  origin partition excludes by default. They come back tagged
-     *  `category: 'cross-project'` so renderers can demarcate them. */
-    crossProject?: boolean;
-    /** The active project name for the origin partition ('' = not in a
-     *  project). Defaults to `resolveProjectIdentity(process.cwd()).name`;
-     *  surfaces whose process cwd is not the caller's project (HTTP server)
-     *  should pass it explicitly. */
-    currentProject?: string;
-    /** DF1 (docs/plans/2026-08-23-df1-snapshot-lifecycle.md, T2): the calling
-     *  session's id. Stamped on this call's recall trace, and the owner-match input to
-     *  `loadFreshActiveTaskSnapshot` — when it strictly equals the active
-     *  snapshot's `session_id`, the read is unbounded (same-session
-     *  continuity); otherwise the snapshot must pass the freshness bound to
-     *  surface. Absent (undefined/null/'') never short-circuits as a match;
-     *  it just means every snapshot goes through the age check. Host-resolved
-     *  (stdin payload, HIPPO_SESSION_ID, else the host's session var) so this stays host-agnostic. */
-    currentSessionId?: string | null;
-    /** Z1: raw hook-payload prompt; only the pinned-only branch reads it, gated on `pinnedInject.promptRecall`. */
-    prompt?: string;
-    /** What the budget pays for, from the caller that renders the block. Absent = the memory text alone. */
-    cost?: ContextCost;
-    /** @internal The CLI's delivery-ledger observer; it only reads, so selection is the same with or without it. */
-    deliveryObserver?: DeliveryObserver;
-}
-/** Budget prices in the text a caller prints, so the budget bounds what reaches the model. */
-export interface ContextCost {
-    /** Tokens of one entry as printed. */
-    entry: (item: Pick<ContextResultEntry, 'entry' | 'isGlobal' | 'promptRecall' | 'origin' | 'category'>) => number;
-    /** Tokens of the headers and footer the block can print at this budget, reserved before any entry. */
-    fixed: (budget: number, can: {
-        cross: boolean;
-        promptRecall: boolean;
-        ambient: boolean;
-    }) => number;
-    /** Tokens of the sections printed ahead of the memories, each as printed. */
-    snapshot: (s: TaskSnapshot) => number;
-    handoff: (h: SessionHandoff) => number;
-    trail: (events: SessionEvent[]) => number;
-}
-export interface ContextResultEntry {
-    entry: MemoryEntry;
-    score: number;
-    /** What this entry cost the budget: its printed line under `ContextOpts.cost`, else its memory text. */
-    tokens: number;
-    isGlobal?: boolean;
-    isFreshTail?: boolean;
-    /** Z1: admitted by the prompt-recall gate, not the recent-N backfill or a pin. */
-    promptRecall?: boolean;
-    /** v39: the entry's owning project ('' = user-global, null = legacy row). */
-    origin?: string | null;
-    /** v39: how the origin relates to the active project. 'cross-project'
-     *  entries only appear when ContextOpts.crossProject was set (or isolation
-     *  is disabled). */
-    category?: 'project' | 'user-global' | 'cross-project';
-}
-export interface ContextResult {
-    entries: ContextResultEntry[];
-    tokens: number;
-    activeSnapshot?: TaskSnapshot | null;
-    sessionHandoff?: SessionHandoff | null;
-    recentEvents?: SessionEvent[];
-    /** The ambient landscape summary over the admitted entries. Present only
-     *  when the store's ambient config is on, the caller is not pinned-only,
-     *  and at least one entry was admitted. */
-    ambientState?: AmbientState;
-}
-/**
- * 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 declare function getContext(ctx: Context, opts?: ContextOpts): Promise<ContextResult>;
-/**
- * Options for `sleep` — run the pure-storage consolidation pipeline
- * (consolidate + dedup + audit + share + ambient) and return structured counts.
- *
- * Extracted from `cmdSleepCore` Phase 2-6 in Episode A. NOT covered by api.sleep:
- * the cli-only auto-learn phase (Phase 1: learnFromRepo + the agent memory import),
- * which is intrinsically host-bound (uses `process.cwd()` / `os.homedir()`).
- * Auto-learn stays in cli.ts cmdSleepCore as a pre-api block.
- *
- * The CLI `cmdSleep` wrapper continues to own the log-file tee + console
- * rendering + `process.exit`; `api.sleep` is pure (no console.log, no IO
- * beyond the store).
- */
-export interface SleepOpts {
-    dryRun?: boolean;
-    noShare?: boolean;
-    /**
-     * @internal Test-only DI seam — see `tests/api-sleep-phase-faults.test.ts`.
-     * Override one or more phase dependencies (typically a throwing stub) to
-     * force mid-phase failure paths deterministically. Production callers
-     * MUST NOT use this field. The runtime defaults at `DEFAULT_SLEEP_PHASES`
-     * preserve all current behaviour when `__phases` is undefined.
-     */
-    __phases?: Partial<SleepPhases>;
-}
-/**
- * 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 declare function recordTokens(ctx: Context, surface: TokenSurface, use: {
-    items: number;
-    tokens: number;
-    sessionId?: string | null;
-}): void;
-/**
- * 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 declare function tokenSummary(ctx: Context, opts?: {
-    days?: number;
-}): TokenSummary;
-/** Failed tool calls by outcome, and repeats across sessions, over the last `days` days (default 30); ROADMAP CD13. */
-export declare function failureSummary(ctx: Context, opts?: {
-    days?: number;
-}): FailureSummary;
-/**
- * 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 declare function listDormant(ctx: Context, opts?: ListDormantOpts): DormantMemory[];
-/**
- * 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 declare function restoreDormant(ctx: Context, id: string): MemoryEntry;
-/**
- * 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 declare function forgetDormant(ctx: Context, id: string): void;
-/** Whether the tenant holds a dormant memory with this id (for "not found" hints). */
-export declare function isDormant(ctx: Context, id: string): boolean;
-export interface QuarantineListItem {
-    id: string;
-    originalScope: string | null;
-    reason: string;
-    status: QuarantineStatus;
-    quarantinedAt: string;
-    decidedAt: string | null;
-    decidedBy: string | null;
-    contentPreview: string;
-}
-/** A tenant's quarantined memories, newest first. Default `status` is 'pending' (the review queue). */
-export declare function quarantineList(ctx: Context, opts?: {
-    status?: QuarantineStatus | 'all';
-    limit?: number;
-}): QuarantineListItem[];
-/** Release a quarantined memory to its original scope. Admin only; the scope guard refuses a row moved since (mirrors restoreDormant). */
-export declare function quarantineApprove(ctx: Context, id: string): void;
-/** Keep a quarantined memory hidden for good. Admin only; the raw row is untouched (append-only). */
-export declare function quarantineReject(ctx: Context, id: string): void;
-export interface SleepResult {
-    active: number;
-    removed: number;
-    /**
-     * Faded memories the decay pass moved to the dormant store instead of
-     * deleting (config `dormant.enabled`). Absent when 0. Per-invocation
-     * activity counter, same class as `removed`.
-     */
-    dormant?: number;
-    /**
-     * Dormant memories deleted for good this sleep because they outlived
-     * `dormant.retentionDays`. Absent when 0. Same per-invocation class as
-     * `removed`.
-     */
-    dormantExpired?: number;
-    mergedEpisodic: number;
-    newSemantic: number;
-    dryRun: boolean;
-    deduped?: {
-        removed: number;
-        semDups: number;
-        epiDups: number;
-        crossDups: number;
-    };
-    audit?: {
-        errorsRemoved: number;
-        warningCount: number;
-    };
-    shared?: number;
-    /**
-     * v1.25.0: count of memories the auto-share secret veto withheld this sleep
-     * — rows that passed every other admission gate (transfer score,
-     * not-already-global) and were blocked solely by `detectSecret`. Absent
-     * when 0 or when auto-share did not run.
-     */
-    secretSkipped?: number;
-    /**
-     * AT1: count of auto-share candidates the GLOBAL store's rejection
-     * tombstone refused this sleep (docs/plans/2026-08-15-at1-rejected-value-tombstone.md
-     * plan §3 — copy paths must not let one rejected candidate abort the
-     * batch). Absent when 0 or when auto-share did not run.
-     */
-    rejectedSkipped?: number;
-    ambient?: AmbientState | null;
-    /**
-     * E3 sleep enqueue-hook: graph re-extraction totals across the tenants rebuilt
-     * this sleep. Absent when no tenant was dirty, and under dryRun (the graph
-     * phase runs only on a real sleep). Cross-tenant aggregate, one reason
-     * /v1/sleep stays loopback-only.
-     */
-    graph?: {
-        tenants: number;
-        entities: number;
-        relations: number;
-    };
-    details?: string[];
-}
-/**
- * Run the pure-storage consolidation pipeline.
- *
- * Tenant scope note: sleep operates on the WHOLE hippoRoot (all tenants in
- * it), matching the pre-refactor cmdSleepCore behavior. Correct for a CLI
- * maintenance op invoked by the operator. Episode B (v1.11.4) exposed this
- * over HTTP `/v1/sleep` with loopback-only enforcement (per-request guard
- * in the handler plus serve()'s boot-time host check). The TODOS.md
- * per-tenant scoping follow-up remains open for the day non-loopback
- * serving lands — at that point the route will need an admin-role gate OR
- * api.sleep itself will need to scope dedup / audit / delete by ctx.tenantId.
- *
- * Dedup and audit deletes each log a `forget` row with the ctx actor and a
- * `metadata.reason`. Pinned, raw, kept and object-backing rows are never auto-deleted (AUTOMATIC_DELETE_SQL).
- * dryRun previews consolidate, dedup and audit, then returns before share/ambient.
- */
-/**
- * v1.12.2: Test-only DI seam shape for `sleep`'s phase dependencies.
- *
- * Each field defaults to the real production implementation imported at the
- * top of this file. Test files pass a `Partial<SleepPhases>` override via
- * `SleepOpts.__phases` (note the `__` prefix — internal-only) to inject
- * deterministic throws for mid-phase failure-path coverage (the
- * `partial: true` + `errorMessage` audit-row branch at line ~2098).
- *
- * Production callers MUST NOT use `__phases`. The field exists solely so
- * `tests/api-sleep-phase-faults.test.ts` can force each phase boundary to
- * throw without depending on store-corruption fragility.
- */
-export interface SleepPhases {
-    consolidate: typeof consolidate;
-    deduplicateStore: typeof deduplicateStore;
-    auditMemories: typeof auditMemories;
-    autoShare: typeof autoShare;
-    loadAllEntries: typeof loadAllEntries;
-    deleteEntry: typeof deleteEntry;
-    computeAmbientState: typeof computeAmbientState;
-    loadConfig: typeof loadConfig;
-    loadPendingExtractionTenants: typeof loadPendingExtractionTenants;
-    extractGraph: typeof extractGraph;
-}
-export declare function sleep(ctx: Context, opts?: SleepOpts): Promise<SleepResult>;
-/**
- * Apply an outcome to the ids most recently returned by `recall()`.
- *
- * Reads `loadIndex(ctx.hippoRoot).last_retrieval_ids` (per-hippoRoot local
- * state; not tenant-scoped at the index layer) and forwards to `outcome()`,
- * which DOES tenant-filter via `readEntry(..., ctx.tenantId)`. Cross-tenant
- * ids in `last_retrieval_ids` are silently skipped, matching the MCP
- * `hippo_outcome` semantics.
- *
- * **Tenant-safe response shape (v1.11.4 security fix):** the returned `ids`
- * field contains ONLY the tenant-filtered subset that actually had outcomes
- * applied (i.e. `appliedIds` from the inner `outcome()` call). Earlier
- * versions returned the raw `last_retrieval_ids` regardless of tenant, which
- * leaked cross-tenant memory IDs to the caller via POST /v1/outcome's
- * no-body last-recall response. The fix is at this helper so all callers
- * (CLI cmdOutcome, HTTP /v1/outcome, MCP `hippo_outcome` if added later)
- * inherit the tenant-safe contract.
- *
- * Do NOT tighten `loadIndex` with `tenantId` inside this helper — doing so
- * would break the (correct) cross-tenant-silent-skip behavior covered by
- * the test in `tests/api-outcome-for-last-recall.test.ts`.
- */
-export interface OutcomeForLastRecallResult {
-    applied: number;
-    ids: string[];
-}
-export declare function outcomeForLastRecall(ctx: Context, good: boolean): OutcomeForLastRecallResult;
+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.d.ts.map