@tangle-network/agent-knowledge 3.2.1 → 4.0.1

package/dist/types-ZzY_x0r7.d.ts

@@ -0,0 +1,661 @@
+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';
+
+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>;
+
+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>;
+}
+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';
+
+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>;
+
+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;
+}
+
+export { type RetrievalHoldoutConfig as $, type AgentMemoryAcquireRunLease as A, type BuildRetrievalBenchmarkCasesFromQrelsOptions as B, type KnowledgeBenchmarkSpec as C, type KnowledgeBenchmarkSplit as D, type KnowledgeBenchmarkTaskKind as E, type KnowledgeClaimMatcher as F, type KnowledgeMemoryBenchmarkCase as G, type KnowledgeMemoryBenchmarkTaskKind as H, type KnowledgeMemoryEvent as I, type KnowledgeMemoryFactMatcher as J, type KnowledgeAnswerBenchmarkCase as K, type KnowledgeRetrievalBenchmarkCase as L, type KnowledgeRetrievalBenchmarkQrel as M, type KnowledgeRetrievalBenchmarkQuery as N, type MemoryAdapterBenchmarkCandidate as O, type MemoryAdapterBenchmarkRankingRow as P, type OwnedAgentMemoryRunLease as Q, type RunRetrievalImprovementLoopResult as R, type RetrievalConfig as S, type RetrievalEvalArtifact as T, type RetrievalEvalRetriever as U, type RetrievalEvalRetrieverInput as V, type RetrievalEvalRetrieverResult as W, type RetrievalEvalScenario as X, type RetrievalGoldTarget as Y, type RetrievalHoldoutBypassReason as Z, type RetrievalHoldoutCallContext as _, type RunRetrievalImprovementLoopOptions as a, type RetrievalHoldoutEligibleItem as a0, type RetrievalHoldoutEvent as a1, type RetrievalHoldoutResult as a2, type RetrievalHoldoutSessionState as a3, type RetrievalMetricSummary as a4, type RetrievalMetricWeights as a5, type RetrievalParameterSearchSpace as a6, type RetrievalParameterSweepProposerOptions as a7, type RetrievalRecallJudgeOptions as a8, type RetrievedKnowledgeHit as a9, type RetrievedSourceSpan as aa, type RunKnowledgeBenchmarkSuiteOptions as ab, type RunKnowledgeBenchmarkSuiteResult as ac, type RunMemoryAdapterBenchmarkOptions as ad, type RunMemoryAdapterBenchmarkResult as ae, acquireAgentMemoryRunLease as af, buildRetrievalEvalDispatch as ag, buildRetrievalParameterCandidates as ah, retrievalConfigFromSurface as ai, retrievalConfigSurface as aj, retrievalParameterSweepProposer as ak, retrievalRecallJudge as al, runRetrievalImprovementLoop as am, scoreRetrievalArtifact as an, 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, type KnowledgeAnswerBenchmarkTaskKind as o, type KnowledgeBenchmarkArtifact as p, type KnowledgeBenchmarkCase as q, type KnowledgeBenchmarkCaseBase as r, type KnowledgeBenchmarkDistribution as s, type KnowledgeBenchmarkEvaluation as t, type KnowledgeBenchmarkFamily as u, type KnowledgeBenchmarkReport as v, type KnowledgeBenchmarkResponder as w, type KnowledgeBenchmarkScenario as x, type KnowledgeBenchmarkSliceSummary as y, type KnowledgeBenchmarkSource as z };