@tangle-network/agent-knowledge 3.2.1 → 4.0.0

package/dist/index-Bqg1mBPt.d.ts

@@ -0,0 +1,822 @@
+import { JsonValue, Scenario, DispatchContext, RunImprovementLoopResult, ParameterCandidate, JudgeConfig, Gate, RunImprovementLoopOptions, MutableSurface, SurfaceProposer, CampaignStorage, CostLedgerHandle, CampaignResult } from '@tangle-network/agent-eval/campaign';
+import { c as KnowledgeIndex, S as SourceRecord } from './types-6x0OpfW6.js';
+import { OffPolicyTrajectory } from '@tangle-network/agent-eval/rl';
+
+type RetrievalConfig = Record<string, JsonValue>;
+type RetrievalParameterSearchSpace = Record<string, readonly JsonValue[]>;
+type RetrievalGoldTarget = {
+    kind: 'page';
+    pageId: string;
+} | {
+    kind: 'page-path';
+    path: string;
+} | {
+    kind: 'source';
+    sourceId: string;
+} | {
+    kind: 'source-anchor';
+    sourceId: string;
+    anchorId: string;
+} | {
+    kind: 'source-span';
+    sourceId: string;
+    charStart: number;
+    charEnd: number;
+};
+interface RetrievalEvalScenario extends Scenario {
+    kind: 'retrieval-eval';
+    query: string;
+    expected: RetrievalGoldTarget | readonly RetrievalGoldTarget[];
+    k?: number;
+}
+interface RetrievedSourceSpan {
+    sourceId: string;
+    anchorId?: string;
+    charStart?: number;
+    charEnd?: number;
+}
+interface RetrievedKnowledgeHit {
+    pageId: string;
+    path: string;
+    title?: string;
+    rank: number;
+    score?: number;
+    normalizedScore?: number;
+    sourceIds?: readonly string[];
+    sourceSpans?: readonly RetrievedSourceSpan[];
+    snippet?: string;
+    metadata?: Record<string, JsonValue>;
+}
+interface RetrievalEvalArtifact {
+    config: RetrievalConfig;
+    query: string;
+    requestedK: number;
+    hits: readonly RetrievedKnowledgeHit[];
+    durationMs: number;
+    /** Informational copy. Billable retrievers account through context.cost.runPaidCall. */
+    costUsd?: number;
+    metadata?: Record<string, JsonValue>;
+}
+interface RetrievalMetricSummary {
+    recall: number;
+    mrr: number;
+    ndcg: number;
+    precisionAtK: number;
+    expectedCount: number;
+    matchedCount: number;
+    relevantHitCount: number;
+    firstHitRank: number | null;
+    matchedTargetIds: readonly string[];
+}
+interface RetrievalEvalRetrieverInput {
+    index?: KnowledgeIndex;
+    config: RetrievalConfig;
+    scenario: RetrievalEvalScenario;
+    k: number;
+    signal: AbortSignal;
+    context: DispatchContext;
+}
+interface RetrievalEvalRetrieverResult {
+    hits: readonly RetrievedKnowledgeHit[];
+    /** Informational copy. Billable retrievers account through context.cost.runPaidCall. */
+    costUsd?: number;
+    metadata?: Record<string, JsonValue>;
+}
+type RetrievalEvalRetriever = (input: RetrievalEvalRetrieverInput) => Promise<readonly RetrievedKnowledgeHit[] | RetrievalEvalRetrieverResult>;
+interface BuildRetrievalEvalDispatchOptions {
+    index?: KnowledgeIndex;
+    defaultK?: number;
+    retrieve?: RetrievalEvalRetriever;
+}
+interface RetrievalMetricWeights {
+    recall?: number;
+    mrr?: number;
+    ndcg?: number;
+    precisionAtK?: number;
+}
+interface RetrievalRecallJudgeOptions {
+    name?: string;
+    weights?: RetrievalMetricWeights;
+}
+interface BuildRetrievalParameterCandidatesOptions {
+    baseline?: RetrievalConfig;
+}
+interface RetrievalParameterSweepProposerOptions {
+    candidates?: readonly ParameterCandidate[];
+    searchSpace?: RetrievalParameterSearchSpace;
+    baseline?: RetrievalConfig;
+}
+type RetrievalLoopBaseOptions = RunImprovementLoopOptions<RetrievalEvalScenario, RetrievalEvalArtifact>;
+interface RunRetrievalImprovementLoopOptions {
+    baseline: RetrievalConfig;
+    scenarios: readonly RetrievalEvalScenario[];
+    holdoutScenarios?: readonly RetrievalEvalScenario[];
+    index?: KnowledgeIndex;
+    defaultK?: number;
+    retrieve?: RetrievalEvalRetriever;
+    candidates?: readonly ParameterCandidate[];
+    searchSpace?: RetrievalParameterSearchSpace;
+    judges?: readonly JudgeConfig<RetrievalEvalArtifact, RetrievalEvalScenario>[];
+    gate?: Gate<RetrievalEvalArtifact, RetrievalEvalScenario>;
+    metricWeights?: RetrievalMetricWeights;
+    targetRecall?: number;
+    holdoutFraction?: number;
+    splitSeed?: number;
+    deltaThreshold?: number;
+    runDir?: RetrievalLoopBaseOptions['runDir'];
+    seed?: RetrievalLoopBaseOptions['seed'];
+    reps?: RetrievalLoopBaseOptions['reps'];
+    resumable?: RetrievalLoopBaseOptions['resumable'];
+    costCeiling?: RetrievalLoopBaseOptions['costCeiling'];
+    maxConcurrency?: RetrievalLoopBaseOptions['maxConcurrency'];
+    dispatchTimeoutMs?: RetrievalLoopBaseOptions['dispatchTimeoutMs'];
+    expectUsage?: RetrievalLoopBaseOptions['expectUsage'];
+    tracing?: RetrievalLoopBaseOptions['tracing'];
+    storage?: RetrievalLoopBaseOptions['storage'];
+    populationSize?: RetrievalLoopBaseOptions['populationSize'];
+    maxGenerations?: RetrievalLoopBaseOptions['maxGenerations'];
+    promoteTopK?: RetrievalLoopBaseOptions['promoteTopK'];
+    maxImprovementShots?: RetrievalLoopBaseOptions['maxImprovementShots'];
+    report?: RetrievalLoopBaseOptions['report'];
+    findings?: RetrievalLoopBaseOptions['findings'];
+    now?: RetrievalLoopBaseOptions['now'];
+}
+interface RunRetrievalImprovementLoopResult extends RunImprovementLoopResult<RetrievalEvalArtifact, RetrievalEvalScenario> {
+    baselineConfig: RetrievalConfig;
+    winnerConfig: RetrievalConfig;
+    trainScenarios: readonly RetrievalEvalScenario[];
+    holdoutScenarios: readonly RetrievalEvalScenario[];
+    candidates: readonly ParameterCandidate[];
+    targetRecall?: number;
+}
+declare function retrievalConfigSurface(config: RetrievalConfig): string;
+declare function retrievalConfigFromSurface(surface: MutableSurface): RetrievalConfig;
+declare function buildRetrievalEvalDispatch(options: BuildRetrievalEvalDispatchOptions): (surface: MutableSurface, scenario: RetrievalEvalScenario, context: DispatchContext) => Promise<RetrievalEvalArtifact>;
+declare function retrievalRecallJudge(options?: RetrievalRecallJudgeOptions): JudgeConfig<RetrievalEvalArtifact, RetrievalEvalScenario>;
+declare function scoreRetrievalArtifact(artifact: RetrievalEvalArtifact, scenario: RetrievalEvalScenario): RetrievalMetricSummary;
+declare function buildRetrievalParameterCandidates(searchSpace: RetrievalParameterSearchSpace, options?: BuildRetrievalParameterCandidatesOptions): ParameterCandidate[];
+declare function retrievalParameterSweepProposer(options: RetrievalParameterSweepProposerOptions): SurfaceProposer;
+declare function runRetrievalImprovementLoop(options: RunRetrievalImprovementLoopOptions): Promise<RunRetrievalImprovementLoopResult>;
+
+interface AgentMemoryRunLease {
+    assertOwned(): Promise<void> | void;
+    release(): Promise<void> | void;
+}
+type AgentMemoryAcquireRunLease = (input: {
+    experimentId: string;
+    runDir: string;
+}) => AgentMemoryRunLease | Promise<AgentMemoryRunLease>;
+type AgentMemoryControllerMode = 'process-local';
+interface OwnedAgentMemoryRunLease {
+    assertOwned(): Promise<void>;
+    release(): Promise<void>;
+}
+declare function acquireAgentMemoryRunLease(input: {
+    experimentId: string;
+    runDir: string;
+    storage: CampaignStorage;
+    customStorage: boolean;
+    lockFileName: string;
+    label: string;
+    controllerMode?: AgentMemoryControllerMode;
+    acquireRunLease?: AgentMemoryAcquireRunLease;
+}): Promise<OwnedAgentMemoryRunLease>;
+
+interface RetrievalHoldoutConfig {
+    /** Per-session probability that one eligible watchlist item is suppressed. 0 logs the full schema without ever dropping. */
+    epsilon: number;
+    /** Item ids eligible for suppression. Empty or absent means no item can ever be dropped. */
+    watchlist?: string[];
+    /** Ties every event to the exact epsilon/watchlist in force, for audit and replay. */
+    configVersion?: string;
+    /** Copied onto every event so multi-adapter logs stay attributable. */
+    adapterId?: string;
+    /** Corpus/store version stamp; an edited item under the same id is a different treatment. */
+    corpusVersion?: string;
+    /**
+     * Emit plaintext sessionId and scope on events. Default false: events carry only
+     * sessionIdHash/scopeHash, so PII-bearing identifiers (tenantId/userId/tags) never reach a
+     * consumer-controlled sink unless the consumer explicitly owns that decision. Note that
+     * replaying assignment draws from logs alone needs the plaintext sessionId, so
+     * privacy-default logs require the consumer's own sessionId mapping for replay audits.
+     */
+    includePlaintextIdentifiers?: boolean;
+    /**
+     * Cap on tracked sessions per experiment config in the sticky wrapper's registry.
+     * Exists so tests can exercise eviction; production should keep the default (10,000).
+     */
+    maxTrackedSessions?: number;
+    /**
+     * Uniform-[0,1) generator keyed by a string. Defaults to a sha256-derived deterministic
+     * generator so every assignment is replayable from the logged keys alone (design rule D5).
+     */
+    rng?: (key: string) => number;
+    /** Receives one event per retrieval call, INCLUDING no-drop calls: control-arm membership is half the data. */
+    onEvent: (event: RetrievalHoldoutEvent) => void;
+}
+interface RetrievalHoldoutEligibleItem {
+    id: string;
+    /** 1-based position in the post-filter hit list. */
+    rank: number;
+    score?: number;
+    kind: string;
+    /** sha256(hit.text) prefix; effects are estimated per (id, contentHash) pair. */
+    contentHash: string;
+}
+interface RetrievalHoldoutEvent {
+    v: 1;
+    eventId: string;
+    ts: string;
+    adapterId?: string;
+    /** Plaintext session id — emitted ONLY when config.includePlaintextIdentifiers is true. */
+    sessionId?: string;
+    /** Consumer-supplied experiment/outcome join id (scope.tags.taskId); deliberately plaintext. */
+    taskId?: string;
+    /** 1-based call counter within the session; 0 when the call is outside session randomization. */
+    callIndex: number;
+    /**
+     * sha256(sessionId) prefix — the default privacy-preserving session join key AND the seed-key
+     * reference for the assignment draws (previously named rngKey; identical derivation, deduped).
+     */
+    sessionIdHash?: string;
+    queryHash?: string;
+    /** Verbatim scope — emitted ONLY when config.includePlaintextIdentifiers is true (PII risk). */
+    scope?: AgentMemoryScope;
+    /** sha256 prefix of the canonical-JSON scope (keys sorted, undefined stripped). */
+    scopeHash?: string;
+    config: {
+        epsilon: number;
+        watchlist: string[];
+        configVersion?: string;
+    };
+    /**
+     * Value-hash of the experiment-defining knobs, sha256({epsilon, sorted watchlist}) prefix.
+     * The estimator groups events by it; the sticky-session registry is keyed by it.
+     */
+    configHash: string;
+    /**
+     * False when no sessionId is available or the adapter answered without retrieval
+     * (see bypassReason), so the fraction-under-experiment denominator stays honest.
+     */
+    holdoutEligible: boolean;
+    /** Present only on adapter paths that bypassed retrieval, where no suppression could apply. */
+    bypassReason?: RetrievalHoldoutBypassReason;
+    /** The full post-filter eligibility set E, logged on every call (control arm + interference probes). */
+    eligible: RetrievalHoldoutEligibleItem[];
+    /** Ids in watchlist ∩ E, in eligibility order. */
+    watchlistEligible: string[];
+    sessionHoldout: boolean;
+    /** The session's sticky drop target once drawn; distinguishes "target absent from E" from "not yet drawn". */
+    sessionTargetId: string | null;
+    /** The item suppressed in THIS call, or null. */
+    droppedId: string | null;
+    /** 1/|watchlist ∩ E| recorded at draw time; the exact inverse-propensity weight input. */
+    pickPropensity: number | null;
+    /** epsilon * pickPropensity, recorded at draw time so analysis never re-derives assignment probabilities. */
+    dropPropensity: number | null;
+    deliveredIds: string[];
+    corpusVersion?: string;
+}
+interface RetrievalHoldoutSessionState {
+    sessionId: string;
+    /** Calls observed so far in this session. */
+    callCount: number;
+    sessionHoldout: boolean;
+    /** Sticky drop target; drawn once at the first call whose eligibility set intersects the watchlist. */
+    targetId: string | null;
+    pickPropensity: number | null;
+}
+interface RetrievalHoldoutCallContext {
+    sessionId?: string;
+    taskId?: string;
+    /** Raw query; only its sha256 prefix is logged. */
+    query?: string;
+    scope?: AgentMemoryScope;
+    /** State returned by the previous call of this session; threading it is what makes suppression sticky. */
+    session?: RetrievalHoldoutSessionState;
+}
+interface RetrievalHoldoutResult {
+    delivered: AgentMemoryHit[];
+    event: RetrievalHoldoutEvent;
+    session?: RetrievalHoldoutSessionState;
+}
+/** Adapter context paths that answer without retrieval, so no holdout draw can happen. */
+type RetrievalHoldoutBypassReason = 'short-term-context' | 'raw-string-context';
+/**
+ * Deterministic uniform [0,1) for assignment draws. The sha256 key derivation is ours — it makes
+ * every draw replayable from the logged keys alone (design rule D5) — while the generator core is
+ * the substrate's `mulberry32` (@tangle-network/agent-eval statistics vocabulary), seeded with the
+ * top 32 bits of the digest, so the statistical machinery is reused rather than forked.
+ */
+declare function deterministicRng(key: string): number;
+/**
+ * Value-hash of the knobs that DEFINE the experiment (epsilon + watchlist, order-independent).
+ * Everything else on the config (callbacks, attribution stamps, privacy flags) does not change
+ * which assignments are drawn, so it stays out of the hash.
+ */
+declare function retrievalHoldoutConfigHash(config: Pick<RetrievalHoldoutConfig, 'epsilon' | 'watchlist'>): string;
+/**
+ * Pure per-call holdout: takes post-filter hits, returns delivered hits plus the log event
+ * and the next session state. Suppression only removes items (no backfill), and it happens
+ * before rendering so a drop session's context is byte-identical to a natural smaller retrieval.
+ */
+declare function applyRetrievalHoldout(hits: AgentMemoryHit[], config: RetrievalHoldoutConfig, ctx?: RetrievalHoldoutCallContext): RetrievalHoldoutResult;
+/**
+ * Logs a holdout event for adapter context paths that answer WITHOUT going through the
+ * search→render seam (Neo4j short-term conversation context, raw-string getContext results),
+ * so a consumer with a holdout configured still sees every call and the fraction-under-experiment
+ * denominator stays honest instead of silently losing these calls. No suppression is applied:
+ * dropping is only meaningful for retrieved memory hits, never for conversation context.
+ */
+declare function emitRetrievalHoldoutBypass(hits: AgentMemoryHit[], config: RetrievalHoldoutConfig, ctx: Omit<RetrievalHoldoutCallContext, 'session'>, bypassReason: RetrievalHoldoutBypassReason): RetrievalHoldoutEvent;
+/**
+ * Clears all sticky-session state. For test isolation and experiment-epoch boundaries;
+ * sessions in flight afterwards re-draw deterministically (same rng keys), so with the default
+ * rng a reset is invisible in the logs unless eligibility sets changed in between.
+ */
+declare function resetRetrievalHoldoutRegistry(): void;
+/**
+ * Convenience wrapper that threads session state internally, keyed by the VALUE of the
+ * experiment-defining knobs (configHash = epsilon + sorted watchlist) plus sessionId, so a fresh
+ * config object per call — the natural pattern when options are built inline — keeps full
+ * stickiness. Distinct experiments never share session state; two config objects with the same
+ * epsilon/watchlist are the same experiment by definition.
+ */
+declare function applySessionStickyRetrievalHoldout(hits: AgentMemoryHit[], config: RetrievalHoldoutConfig, ctx?: Omit<RetrievalHoldoutCallContext, 'session'>): RetrievalHoldoutResult;
+/** Aggregated view of one session's holdout exposure — the randomization unit of this design. */
+interface RetrievalHoldoutSessionSummary {
+    /** `${configHash}:${sessionIdHash}` — the trajectory's runId. */
+    runId: string;
+    configHash: string;
+    sessionIdHash: string;
+    sessionHoldout: boolean;
+    sessionTargetId: string | null;
+    /** Item actually suppressed in this session (equals sessionTargetId when a drop occurred). */
+    droppedId: string | null;
+    /** |watchlist ∩ E| at the session's first intersecting randomized call; 0 when never intersecting. */
+    firstCandidateCount: number;
+    /** Randomized retrieval calls observed for this session. */
+    callCount: number;
+    /** Adapter bypass calls observed for this session (logged, never randomized). */
+    bypassCallCount: number;
+    /** Session-level probability of the OBSERVED assignment under the behavior policy. */
+    behaviorProb: number;
+    /** True when the session's events disagree on arm or target (e.g. registry eviction re-draw). */
+    mixedExposure: boolean;
+    /** Present only on sessions surfaced in `excluded` rather than converted. */
+    exclusionReason?: 'mixed-exposure' | 'no-randomized-calls';
+}
+interface RetrievalHoldoutOffPolicyOptions {
+    /**
+     * Realized outcome PER SESSION, keyed by sessionIdHash — the session is the randomization
+     * unit, so rewards are per session, never per call. A missing entry for an included session
+     * throws: silently dropping unscored sessions would corrupt the estimator's denominator, so
+     * filter events to scored sessions upstream instead.
+     */
+    rewards: Record<string, number>;
+    /**
+     * Target-policy probability of the session's observed assignment. Default models the
+     * always-deliver-in-full policy: 1 for full-delivery sessions, 0 for drop sessions.
+     */
+    targetProb?: (session: RetrievalHoldoutSessionSummary) => number;
+    /** Per-session reward-model prediction enabling `doublyRobust`; when absent, qHat is null. */
+    qHat?: (session: RetrievalHoldoutSessionSummary) => number | null;
+}
+interface RetrievalHoldoutOffPolicyResult {
+    /** One trajectory per (configHash, sessionIdHash) — never per call. */
+    trajectories: OffPolicyTrajectory[];
+    /** 1:1 with `trajectories` (same order): the diagnostic view of each converted session. */
+    sessions: RetrievalHoldoutSessionSummary[];
+    /** Sessions surfaced but NOT converted (mixed exposure, bypass-only) — counted, never hidden. */
+    excluded: RetrievalHoldoutSessionSummary[];
+    /** Events with no sessionIdHash: outside session randomization, cannot join a reward. */
+    unattributableEvents: number;
+}
+/**
+ * Maps holdout logs onto agent-eval's `OffPolicyTrajectory`, ONE TRAJECTORY PER SESSION, so
+ * EXP-007's analysis consumes the substrate's `inverseProbabilityWeighting` /
+ * `selfNormalizedImportanceWeighting` / `doublyRobust` estimators directly. This matches the
+ * PREREG estimator (session-sticky self-normalized IPW): the design randomizes per SESSION —
+ * the arm coin is flipped once (P(holdout) = epsilon) and the sticky target is drawn once,
+ * uniformly over watchlist ∩ E at the session's first intersecting call.
+ *
+ * Session-level action space and behavior probabilities (they sum to 1 by construction):
+ * - full delivery (control arm observed): `1 − epsilon`;
+ * - drop candidate i of k = |watchlist ∩ E_first|: `epsilon / k` each (the draw event's logged
+ *   `dropPropensity`);
+ * - sessions whose eligibility sets never intersect the watchlist: probability 1 — full
+ *   delivery was certain in either arm.
+ *
+ * Per-call events are repeated observations WITHIN one session-level randomization; per-call
+ * IPW is statistically invalid for this design (per-call "propensities" imply an action
+ * distribution summing to more than 1 and bias IPS downward). Calls where the sticky target is
+ * absent from E, and adapter bypass calls, fold into the session summary (callCount /
+ * bypassCallCount) instead of generating independent propensities.
+ *
+ * Join contract: `rewards` is keyed by `sessionIdHash` (sha256(sessionId) first 16 hex — compute
+ * the same prefix over the outcome table's session ids, or log with
+ * `includePlaintextIdentifiers: true` and join on raw ids upstream). Events are grouped per
+ * (configHash, sessionIdHash) so different experiment configs are never pooled. Mixed-exposure
+ * sessions (arm or target disagreement, e.g. after registry eviction) are excluded from the
+ * trajectories and surfaced in `excluded` for the analysis to count.
+ * Pre-registration for EXP-007 stays in the research repo by design; the manifest vocabulary for
+ * it is agent-eval's `HypothesisManifest` / `signManifest` / `evaluateHypothesis` exports.
+ */
+declare function toOffPolicyTrajectory(events: RetrievalHoldoutEvent[], options: RetrievalHoldoutOffPolicyOptions): RetrievalHoldoutOffPolicyResult;
+
+type AgentMemoryKind = 'message' | 'entity' | 'fact' | 'preference' | 'observation' | 'reasoning-trace';
+interface AgentMemoryScope {
+    tenantId?: string;
+    userId?: string;
+    agentId?: string;
+    teamId?: string;
+    runId?: string;
+    sessionId?: string;
+    namespace?: string;
+    tags?: Record<string, string>;
+}
+interface AgentMemoryHit {
+    id: string;
+    uri: string;
+    kind: AgentMemoryKind;
+    text: string;
+    title?: string;
+    score?: number;
+    normalizedScore?: number;
+    confidence?: number;
+    createdAt?: string;
+    validUntil?: string;
+    lastVerifiedAt?: string;
+    metadata?: Record<string, unknown>;
+}
+interface AgentMemoryContext {
+    query: string;
+    text: string;
+    hits: AgentMemoryHit[];
+    sourceRecords: SourceRecord[];
+    metadata?: Record<string, unknown>;
+}
+interface AgentMemorySearchOptions {
+    scope?: AgentMemoryScope;
+    limit?: number;
+    minScore?: number;
+    kinds?: AgentMemoryKind[];
+    metadata?: Record<string, unknown>;
+    /**
+     * Opt-in randomized retrieval holdout (epsilon-dropout) for treatment-effect logging.
+     * Absent by default; when absent, retrieval behavior is unchanged. See ./holdout.
+     */
+    holdout?: RetrievalHoldoutConfig;
+}
+interface AgentMemoryWriteInput {
+    kind: AgentMemoryKind;
+    text: string;
+    id?: string;
+    title?: string;
+    role?: 'system' | 'user' | 'assistant' | 'tool';
+    entityName?: string;
+    entityType?: string;
+    category?: string;
+    predicate?: string;
+    subject?: string;
+    object?: string;
+    confidence?: number;
+    scope?: AgentMemoryScope;
+    metadata?: Record<string, unknown>;
+}
+interface AgentMemoryWriteResult {
+    accepted: boolean;
+    id: string;
+    uri: string;
+    kind: AgentMemoryKind;
+    sourceRecord?: SourceRecord;
+    metadata?: Record<string, unknown>;
+}
+type AgentMemoryBranchIsolation = {
+    mode: 'scoped';
+    /** False when writes may outlive the worker process that issued them. */
+    processExitSafe?: boolean;
+    /** Wait before clearing an abandoned branch so accepted asynchronous writes become visible. */
+    recoveryDelayMs?: number;
+} | {
+    mode: 'instance';
+    branchId: string;
+    /** True only when the dedicated instance also enforces every logical scope. */
+    supportsLogicalScopes?: boolean;
+} | {
+    mode: 'unsupported';
+    reason: string;
+};
+interface AgentMemoryAdapter {
+    readonly id: string;
+    /** How this adapter prevents candidate branches from reading each other's state. */
+    readonly branchIsolation?: AgentMemoryBranchIsolation;
+    search(query: string, options?: AgentMemorySearchOptions): Promise<AgentMemoryHit[]>;
+    getContext(query: string, options?: AgentMemorySearchOptions): Promise<AgentMemoryContext>;
+    write(input: AgentMemoryWriteInput): Promise<AgentMemoryWriteResult>;
+    /** Delete exactly this scope. Repeated and concurrent calls for the same scope must be safe. */
+    clear?(scope?: AgentMemoryScope): Promise<void>;
+    flush?(): Promise<void>;
+    close?(): Promise<void>;
+}
+
+type KnowledgeBenchmarkTaskKind = 'retrieval' | 'rag-answer' | 'hallucination' | 'kb-improvement' | 'memory-ingest' | 'memory-recall' | 'memory-temporal' | 'memory-update' | 'memory-forgetting' | 'memory-reasoning' | 'memory-summarization' | 'memory-recommendation' | 'memory-multiparty';
+type KnowledgeAnswerBenchmarkTaskKind = 'rag-answer' | 'hallucination' | 'kb-improvement';
+type KnowledgeMemoryBenchmarkTaskKind = Exclude<KnowledgeBenchmarkTaskKind, 'retrieval' | KnowledgeAnswerBenchmarkTaskKind>;
+type KnowledgeBenchmarkFamily = 'beir' | 'mteb-retrieval' | 'msmarco' | 'trec-dl' | 'miracl' | 'lotte' | 'bright' | 'crag' | 'hotpotqa' | 'kilt' | 'ragtruth' | 'faithbench' | 'locomo' | 'longmemeval' | 'longmemeval-v2' | 'memora' | 'memoryagentbench' | 'memorybank' | 'groupmembench' | 'first-party' | 'custom';
+type KnowledgeBenchmarkSplit = 'search' | 'dev' | 'holdout' | string;
+interface KnowledgeBenchmarkSource {
+    name?: string;
+    url?: string;
+    version?: string;
+    license?: string;
+    citation?: string;
+}
+interface KnowledgeBenchmarkSpec {
+    id: string;
+    family: KnowledgeBenchmarkFamily;
+    taskKind: KnowledgeBenchmarkTaskKind;
+    primaryMetrics: readonly string[];
+    adapter: string;
+    notes: string;
+}
+interface KnowledgeBenchmarkCaseBase {
+    id: string;
+    family: KnowledgeBenchmarkFamily | string;
+    taskKind: KnowledgeBenchmarkTaskKind;
+    split?: KnowledgeBenchmarkSplit;
+    tags?: readonly string[];
+    source?: KnowledgeBenchmarkSource;
+    metadata?: Record<string, unknown>;
+}
+interface KnowledgeRetrievalBenchmarkCase extends KnowledgeBenchmarkCaseBase {
+    taskKind: 'retrieval';
+    query: string;
+    expected: RetrievalGoldTarget | readonly RetrievalGoldTarget[];
+    k?: number;
+}
+interface KnowledgeClaimMatcher {
+    id: string;
+    anyOf: readonly string[];
+    weight?: number;
+}
+interface KnowledgeMemoryEvent {
+    id: string;
+    text: string;
+    actorId?: string;
+    sessionId?: string;
+    timestamp?: string;
+    metadata?: Record<string, unknown>;
+}
+interface KnowledgeMemoryFactMatcher extends KnowledgeClaimMatcher {
+    sourceEventIds?: readonly string[];
+    validAt?: string;
+    obsolete?: boolean;
+}
+interface KnowledgeAnswerBenchmarkCase extends KnowledgeBenchmarkCaseBase {
+    taskKind: KnowledgeAnswerBenchmarkTaskKind;
+    prompt: string;
+    requiredClaims?: readonly KnowledgeClaimMatcher[];
+    forbiddenClaims?: readonly KnowledgeClaimMatcher[];
+    expectedSourceIds?: readonly string[];
+    referenceAnswer?: string;
+}
+interface KnowledgeMemoryBenchmarkCase extends KnowledgeBenchmarkCaseBase {
+    taskKind: KnowledgeMemoryBenchmarkTaskKind;
+    events: readonly KnowledgeMemoryEvent[];
+    prompt: string;
+    requiredFacts?: readonly KnowledgeMemoryFactMatcher[];
+    forbiddenFacts?: readonly KnowledgeMemoryFactMatcher[];
+    expectedEventIds?: readonly string[];
+    expectedActorIds?: readonly string[];
+    referenceAnswer?: string;
+}
+type KnowledgeBenchmarkCase = KnowledgeRetrievalBenchmarkCase | KnowledgeAnswerBenchmarkCase | KnowledgeMemoryBenchmarkCase;
+interface KnowledgeBenchmarkArtifact {
+    answer?: string;
+    text?: string;
+    hits?: readonly RetrievedKnowledgeHit[];
+    citedSourceIds?: readonly string[];
+    rememberedFacts?: readonly string[];
+    citedEventIds?: readonly string[];
+    usedMemoryIds?: readonly string[];
+    actorIds?: readonly string[];
+    /** Informational copy. Billable responders account through context.cost.runPaidCall. */
+    costUsd?: number;
+    durationMs?: number;
+    metadata?: Record<string, unknown>;
+}
+interface KnowledgeBenchmarkEvaluation {
+    score: number;
+    passed: boolean;
+    dimensions: Record<string, number>;
+    /** Dimensions for which this case declared an actual target. */
+    applicableDimensions?: readonly string[];
+    notes: string;
+    raw: Record<string, unknown>;
+}
+interface KnowledgeBenchmarkScenario extends Scenario {
+    kind: 'knowledge-benchmark';
+    family: KnowledgeBenchmarkFamily | string;
+    taskKind: KnowledgeBenchmarkTaskKind;
+    splitTag: KnowledgeBenchmarkSplit;
+    case: KnowledgeBenchmarkCase;
+}
+type KnowledgeBenchmarkResponder<TArtifact = KnowledgeBenchmarkArtifact> = (input: {
+    case: KnowledgeBenchmarkCase;
+    scenario: KnowledgeBenchmarkScenario;
+    context: DispatchContext;
+}) => Promise<TArtifact> | TArtifact;
+interface RunKnowledgeBenchmarkSuiteOptions<TArtifact = KnowledgeBenchmarkArtifact> {
+    cases: readonly KnowledgeBenchmarkCase[];
+    respond: KnowledgeBenchmarkResponder<TArtifact>;
+    /** Versioned identity for the model, prompt, retrieval, and runtime behavior. */
+    respondRef?: string;
+    runDir: string;
+    splits?: readonly KnowledgeBenchmarkSplit[];
+    repo?: string;
+    seed?: number;
+    reps?: number;
+    resumable?: boolean;
+    costCeiling?: number;
+    /** Shared across nested benchmark suites when an outer run owns spend. */
+    costLedger?: CostLedgerHandle;
+    costPhase?: string;
+    maxConcurrency?: number;
+    dispatchTimeoutMs?: number;
+    expectUsage?: 'assert' | 'warn' | 'off';
+    storage?: CampaignStorage;
+    now?: () => Date;
+}
+interface KnowledgeBenchmarkDistribution {
+    n: number;
+    min: number;
+    mean: number;
+    median: number;
+    p90: number;
+    max: number;
+}
+interface KnowledgeBenchmarkSliceSummary {
+    n: number;
+    meanScore: number;
+    passRate: number;
+    score: KnowledgeBenchmarkDistribution;
+}
+interface KnowledgeBenchmarkReport {
+    totalCases: number;
+    totalCells: number;
+    cellsFailed: number;
+    cellsCached: number;
+    totalCostUsd: number;
+    bySplit: Record<string, KnowledgeBenchmarkSliceSummary>;
+    byFamily: Record<string, KnowledgeBenchmarkSliceSummary>;
+    byTaskKind: Record<string, KnowledgeBenchmarkSliceSummary>;
+    dimensions: Record<string, KnowledgeBenchmarkDistribution>;
+    score: KnowledgeBenchmarkDistribution;
+}
+interface RunKnowledgeBenchmarkSuiteResult<TArtifact = KnowledgeBenchmarkArtifact> {
+    scenarios: readonly KnowledgeBenchmarkScenario[];
+    campaign: CampaignResult<TArtifact, KnowledgeBenchmarkScenario>;
+    report: KnowledgeBenchmarkReport;
+    reportJsonPath: string;
+    reportMarkdownPath: string;
+}
+interface MemoryAdapterBenchmarkCandidate {
+    id: string;
+    /** Versioned adapter and configuration identity used by resumable caches. */
+    ref: string;
+    /** Expected adapter.id. Defaults to candidate id and permits lazy no-work resume. */
+    adapterId?: string;
+    label?: string;
+    /** Local construction is free; call markExternalCall before billable provisioning or reconnects. */
+    createAdapter: (input: {
+        purpose: 'execute' | 'recovery';
+        signal: AbortSignal;
+        markExternalCall(): void;
+    }) => AgentMemoryAdapter | Promise<AgentMemoryAdapter>;
+    /** Conservative charge for one billable adapter provisioning or reconnect call. */
+    adapterCreationCostUsd?: number;
+    searchLimit?: number;
+    costUsdPerCase?: number;
+    /** Conservative extra provider charge for recovering one interrupted case. */
+    recoveryCostUsdPerAttempt?: number;
+    scope?: AgentMemoryScope;
+}
+interface RunMemoryAdapterBenchmarkOptions {
+    cases: readonly KnowledgeMemoryBenchmarkCase[];
+    candidates: readonly MemoryAdapterBenchmarkCandidate[];
+    /** Retired candidates retained only so interrupted scopes can be cleaned on resume. */
+    recoveryCandidates?: readonly MemoryAdapterBenchmarkCandidate[];
+    runDir: string;
+    storage?: CampaignStorage;
+    repo?: string;
+    seed?: number;
+    reps?: number;
+    resumable?: boolean;
+    costCeiling?: number;
+    /** Shared with nested benchmark suites so the dollar limit applies to the whole comparison. */
+    costLedger?: CostLedgerHandle;
+    costPhase?: string;
+    maxConcurrency?: number;
+    dispatchTimeoutMs?: number;
+    cleanupTimeoutMs?: number;
+    /** Refuse a damaged run with more unfinished attempts than this. Default 1000. */
+    maxRecoveryAttempts?: number;
+    /** Bound repeated provider cleanup after process crashes. Default 3 per attempt. */
+    maxRecoveryRetriesPerAttempt?: number;
+    expectUsage?: 'assert' | 'warn' | 'off';
+    now?: () => Date;
+    /** Required with custom storage when all controllers are confined to one process. */
+    controllerMode?: AgentMemoryControllerMode;
+    /** Required for distributed controllers that share custom storage. */
+    acquireRunLease?: AgentMemoryAcquireRunLease;
+}
+interface MemoryAdapterBenchmarkRankingRow {
+    rank: number;
+    candidateId: string;
+    label: string;
+    adapterId: string;
+    scoreMean: number;
+    passRate: number;
+    totalCases: number;
+    totalCells: number;
+    cellsFailed: number;
+    totalCostUsd: number;
+    reportJsonPath: string;
+    reportMarkdownPath: string;
+    report: KnowledgeBenchmarkReport;
+}
+interface RunMemoryAdapterBenchmarkResult {
+    rows: readonly MemoryAdapterBenchmarkRankingRow[];
+    totalCostUsd: number;
+    /** Recovery spend for retired candidates, excluded from ranking rows but included in totalCostUsd. */
+    unrankedRecoveryCostUsd: number;
+    rankingJsonPath: string;
+    rankingMarkdownPath: string;
+    attemptLogPath: string;
+    recoveryLogPath: string;
+}
+interface KnowledgeRetrievalBenchmarkQuery {
+    id: string;
+    text: string;
+    split?: KnowledgeBenchmarkSplit;
+    tags?: readonly string[];
+    metadata?: Record<string, unknown>;
+}
+interface KnowledgeRetrievalBenchmarkQrel {
+    queryId: string;
+    documentId: string;
+    score: number;
+}
+interface BuildRetrievalBenchmarkCasesFromQrelsOptions {
+    benchmarkId: string;
+    family: KnowledgeBenchmarkFamily | string;
+    queries: readonly KnowledgeRetrievalBenchmarkQuery[];
+    qrels: readonly KnowledgeRetrievalBenchmarkQrel[];
+    source?: KnowledgeBenchmarkSource;
+    tags?: readonly string[];
+    k?: number;
+    targetKind?: 'page' | 'page-path' | 'source';
+    documentTarget?: (documentId: string, qrel: KnowledgeRetrievalBenchmarkQrel) => RetrievalGoldTarget;
+    splitOf?: (queryId: string) => KnowledgeBenchmarkSplit;
+}
+declare const INDUSTRY_RAG_BENCHMARKS: readonly (KnowledgeBenchmarkSpec & {
+    taskKind: 'retrieval' | KnowledgeAnswerBenchmarkTaskKind;
+})[];
+declare const INDUSTRY_MEMORY_BENCHMARKS: readonly (KnowledgeBenchmarkSpec & {
+    taskKind: KnowledgeMemoryBenchmarkTaskKind;
+})[];
+declare function buildIndustryRagBenchmarkSmokeCases(specs?: readonly (KnowledgeBenchmarkSpec & {
+    taskKind: 'retrieval' | KnowledgeAnswerBenchmarkTaskKind;
+})[]): KnowledgeBenchmarkCase[];
+declare function respondToIndustryRagBenchmarkSmokeCase(input: {
+    case: KnowledgeBenchmarkCase;
+}): KnowledgeBenchmarkArtifact;
+declare function buildIndustryMemoryBenchmarkSmokeCases(specs?: readonly (KnowledgeBenchmarkSpec & {
+    taskKind: KnowledgeMemoryBenchmarkTaskKind;
+})[]): KnowledgeMemoryBenchmarkCase[];
+declare function respondToIndustryMemoryBenchmarkSmokeCase(input: {
+    case: KnowledgeMemoryBenchmarkCase;
+}): KnowledgeBenchmarkArtifact;
+declare function buildFirstPartyMemoryLifecycleBenchmarkCases(): KnowledgeMemoryBenchmarkCase[];
+declare function runMemoryAdapterBenchmark(options: RunMemoryAdapterBenchmarkOptions): Promise<RunMemoryAdapterBenchmarkResult>;
+declare function createNoopMemoryBenchmarkAdapter(id?: string): AgentMemoryAdapter;
+declare function createInMemoryBenchmarkAdapter(options?: {
+    id?: string;
+}): AgentMemoryAdapter;
+declare function parseKnowledgeBenchmarkJsonl<T = unknown>(text: string): T[];
+declare function parseKnowledgeBenchmarkQrels(text: string): KnowledgeRetrievalBenchmarkQrel[];
+declare function buildRetrievalBenchmarkCasesFromQrels(options: BuildRetrievalBenchmarkCasesFromQrelsOptions): KnowledgeRetrievalBenchmarkCase[];
+declare function runKnowledgeBenchmarkSuite<TArtifact = KnowledgeBenchmarkArtifact>(options: RunKnowledgeBenchmarkSuiteOptions<TArtifact>): Promise<RunKnowledgeBenchmarkSuiteResult<TArtifact>>;
+declare function renderKnowledgeBenchmarkReportMarkdown(report: KnowledgeBenchmarkReport): string;
+declare function buildKnowledgeBenchmarkScenarios(cases: readonly KnowledgeBenchmarkCase[], splits?: readonly KnowledgeBenchmarkSplit[]): KnowledgeBenchmarkScenario[];
+declare function knowledgeBenchmarkJudge<TArtifact = KnowledgeBenchmarkArtifact>(): JudgeConfig<TArtifact, KnowledgeBenchmarkScenario>;
+declare function scoreKnowledgeBenchmarkArtifact<TArtifact>(testCase: KnowledgeBenchmarkCase, artifact: TArtifact): KnowledgeBenchmarkEvaluation;
+declare function summarizeKnowledgeBenchmarkCampaign<TArtifact>(input: {
+    scenarios: readonly KnowledgeBenchmarkScenario[];
+    campaign: CampaignResult<TArtifact, KnowledgeBenchmarkScenario>;
+}): KnowledgeBenchmarkReport;
+declare function scoreMemoryBenchmarkArtifact<TArtifact>(testCase: KnowledgeMemoryBenchmarkCase, artifact: TArtifact): KnowledgeBenchmarkEvaluation;
+declare function isKnowledgeMemoryBenchmarkCase(testCase: KnowledgeBenchmarkCase): testCase is KnowledgeMemoryBenchmarkCase;
+
+export { type RetrievalHoldoutBypassReason as $, type AgentMemoryAcquireRunLease as A, type BuildRetrievalBenchmarkCasesFromQrelsOptions as B, type KnowledgeBenchmarkSource as C, type KnowledgeBenchmarkSpec as D, type KnowledgeBenchmarkSplit as E, type KnowledgeBenchmarkTaskKind as F, type KnowledgeClaimMatcher as G, type KnowledgeMemoryBenchmarkCase as H, INDUSTRY_MEMORY_BENCHMARKS as I, type KnowledgeMemoryBenchmarkTaskKind as J, type KnowledgeAnswerBenchmarkCase as K, type KnowledgeMemoryEvent as L, type KnowledgeMemoryFactMatcher as M, type KnowledgeRetrievalBenchmarkCase as N, type KnowledgeRetrievalBenchmarkQrel as O, type KnowledgeRetrievalBenchmarkQuery as P, type MemoryAdapterBenchmarkCandidate as Q, type RunRetrievalImprovementLoopResult as R, type MemoryAdapterBenchmarkRankingRow as S, type OwnedAgentMemoryRunLease as T, type RetrievalConfig as U, type RetrievalEvalArtifact as V, type RetrievalEvalRetriever as W, type RetrievalEvalRetrieverInput as X, type RetrievalEvalRetrieverResult as Y, type RetrievalEvalScenario as Z, type RetrievalGoldTarget as _, type RunRetrievalImprovementLoopOptions as a, type RetrievalHoldoutCallContext as a0, type RetrievalHoldoutConfig as a1, type RetrievalHoldoutEligibleItem as a2, type RetrievalHoldoutEvent as a3, type RetrievalHoldoutOffPolicyOptions as a4, type RetrievalHoldoutOffPolicyResult as a5, type RetrievalHoldoutResult as a6, type RetrievalHoldoutSessionState as a7, type RetrievalHoldoutSessionSummary as a8, type RetrievalMetricSummary as a9, parseKnowledgeBenchmarkJsonl as aA, parseKnowledgeBenchmarkQrels as aB, renderKnowledgeBenchmarkReportMarkdown as aC, resetRetrievalHoldoutRegistry as aD, respondToIndustryMemoryBenchmarkSmokeCase as aE, respondToIndustryRagBenchmarkSmokeCase as aF, retrievalConfigFromSurface as aG, retrievalConfigSurface as aH, retrievalHoldoutConfigHash as aI, retrievalParameterSweepProposer as aJ, retrievalRecallJudge as aK, runKnowledgeBenchmarkSuite as aL, runMemoryAdapterBenchmark as aM, runRetrievalImprovementLoop as aN, scoreKnowledgeBenchmarkArtifact as aO, scoreMemoryBenchmarkArtifact as aP, scoreRetrievalArtifact as aQ, summarizeKnowledgeBenchmarkCampaign as aR, toOffPolicyTrajectory as aS, type RetrievalMetricWeights as aa, type RetrievalParameterSearchSpace as ab, type RetrievalParameterSweepProposerOptions as ac, type RetrievalRecallJudgeOptions as ad, type RetrievedKnowledgeHit as ae, type RetrievedSourceSpan as af, type RunKnowledgeBenchmarkSuiteOptions as ag, type RunKnowledgeBenchmarkSuiteResult as ah, type RunMemoryAdapterBenchmarkOptions as ai, type RunMemoryAdapterBenchmarkResult as aj, acquireAgentMemoryRunLease as ak, applyRetrievalHoldout as al, applySessionStickyRetrievalHoldout as am, buildFirstPartyMemoryLifecycleBenchmarkCases as an, buildIndustryMemoryBenchmarkSmokeCases as ao, buildIndustryRagBenchmarkSmokeCases as ap, buildKnowledgeBenchmarkScenarios as aq, buildRetrievalBenchmarkCasesFromQrels as ar, buildRetrievalEvalDispatch as as, buildRetrievalParameterCandidates as at, createInMemoryBenchmarkAdapter as au, createNoopMemoryBenchmarkAdapter as av, deterministicRng as aw, emitRetrievalHoldoutBypass as ax, isKnowledgeMemoryBenchmarkCase as ay, knowledgeBenchmarkJudge as az, type AgentMemoryAdapter as b, type AgentMemoryBranchIsolation as c, type AgentMemoryContext as d, type AgentMemoryControllerMode as e, type AgentMemoryHit as f, type AgentMemoryKind as g, type AgentMemoryRunLease as h, type AgentMemoryScope as i, type AgentMemorySearchOptions as j, type AgentMemoryWriteInput as k, type AgentMemoryWriteResult as l, type BuildRetrievalEvalDispatchOptions as m, type BuildRetrievalParameterCandidatesOptions as n, INDUSTRY_RAG_BENCHMARKS as o, type KnowledgeAnswerBenchmarkTaskKind as p, type KnowledgeBenchmarkArtifact as q, type KnowledgeBenchmarkCase as r, type KnowledgeBenchmarkCaseBase as s, type KnowledgeBenchmarkDistribution as t, type KnowledgeBenchmarkEvaluation as u, type KnowledgeBenchmarkFamily as v, type KnowledgeBenchmarkReport as w, type KnowledgeBenchmarkResponder as x, type KnowledgeBenchmarkScenario as y, type KnowledgeBenchmarkSliceSummary as z };