@tangle-network/agent-knowledge 6.0.0 → 6.1.1

package/dist/index-CGBctbit.d.ts

@@ -0,0 +1,857 @@
+import { x as SourceRecord } from "./types-DcCCzreS.js";
+import { At as AgentMemoryScope, B as KnowledgeMemoryEvent, Dt as AgentMemoryContext, F as KnowledgeBenchmarkSplit, Ft as RetrievalHoldoutCallContext, It as RetrievalHoldoutConfig, Mt as AgentMemoryWriteInput, Nt as AgentMemoryWriteResult, O as KnowledgeBenchmarkFamily, Ot as AgentMemoryHit, Pt as RetrievalHoldoutBypassReason, R as KnowledgeMemoryBenchmarkCase, Rt as RetrievalHoldoutEvent, Tt as AgentMemoryAdapter, V as KnowledgeMemoryFactMatcher, bt as AgentMemoryRunLease, jt as AgentMemorySearchOptions, vt as AgentMemoryAcquireRunLease, yt as AgentMemoryControllerMode, z as KnowledgeMemoryBenchmarkTaskKind, zt as RetrievalHoldoutResult } from "./index-CIW3G4s_.js";
+import { AgentCandidateJsonValue } from "@tangle-network/agent-interface";
+import { CostChannel, CostReceipt, RunPaidCallInput } from "@tangle-network/agent-eval";
+import { z } from "zod";
+import { CampaignResult, CampaignStorage, CompareOptimizationMethodsOptions, CostLedgerHandle, DispatchContext, HeldoutSignificance, HeldoutSignificanceOptions, JudgeConfig, OptimizationMethod, OptimizationMethodComparison, OptimizationMethodRunOptions, Scenario } from "@tangle-network/agent-eval/campaign";
+import { OffPolicyTrajectory } from "@tangle-network/agent-eval/rl";
+//#region src/optimization.d.ts
+interface SerializedCandidateCodec<TCandidate extends AgentCandidateJsonValue> {
+  serialize(candidate: TCandidate): string;
+  parse(surface: string): TCandidate;
+}
+interface SerializedCandidate<TCandidate extends AgentCandidateJsonValue> {
+  value: TCandidate;
+  surface: string;
+  surfaceHash: string;
+}
+type ComparisonOptions<TScenario extends Scenario, TArtifact> = Omit<CompareOptimizationMethodsOptions<TScenario, TArtifact>, 'methods' | 'baselineSurface' | 'trainScenarios' | 'selectionScenarios' | 'testScenarios' | 'dispatchWithSurface' | 'dispatchRef' | 'optimizationRunOptions'>;
+interface RunSerializedKnowledgeOptimizationOptions<TCandidate extends AgentCandidateJsonValue, TScenario extends Scenario, TArtifact> extends ComparisonOptions<TScenario, TArtifact> {
+  /** Immutable identity for candidate execution, judges, models, indexes, and external settings. */
+  executionRef: string;
+  baseline: TCandidate;
+  method: OptimizationMethod<TScenario, TArtifact>;
+  trainScenarios: readonly TScenario[];
+  selectionScenarios: readonly TScenario[];
+  finalScenarios: readonly TScenario[];
+  dispatchCandidate(input: {
+    candidate: TCandidate;
+    candidateSurface: string;
+    candidateSurfaceHash: string;
+    scenario: TScenario;
+    context: DispatchContext;
+  }): Promise<TArtifact>;
+  codec?: SerializedCandidateCodec<TCandidate>;
+  /** Detects duplicated cases whose IDs differ within or across data partitions. */
+  scenarioFingerprint?: (scenario: TScenario) => string;
+  optimizationRunOptions?: Omit<OptimizationMethodRunOptions<TScenario, TArtifact>, 'dispatchRef'>;
+}
+interface RunSerializedKnowledgeOptimizationResult<TCandidate extends AgentCandidateJsonValue> {
+  methodName: string;
+  baseline: SerializedCandidate<TCandidate>;
+  winner: SerializedCandidate<TCandidate>;
+  comparison: OptimizationMethodComparison;
+}
+/**
+ * Runs one complete agent-eval method over a serialized knowledge candidate.
+ * The method receives train and selection data; agent-eval owns final scoring.
+ */
+declare function runSerializedKnowledgeOptimization<TCandidate extends AgentCandidateJsonValue, TScenario extends Scenario, TArtifact>(options: RunSerializedKnowledgeOptimizationOptions<TCandidate, TScenario, TArtifact>): Promise<RunSerializedKnowledgeOptimizationResult<TCandidate>>;
+declare function jsonCandidateCodec<TCandidate extends AgentCandidateJsonValue>(): SerializedCandidateCodec<TCandidate>;
+declare function jsonObjectCandidateCodec<TCandidate extends Record<string, AgentCandidateJsonValue>>(): SerializedCandidateCodec<TCandidate>;
+declare function scenarioContentFingerprint(scenario: Scenario): string;
+//#endregion
+//#region src/memory/adapter.d.ts
+declare function defaultGetMemoryContext(adapter: Pick<AgentMemoryAdapter, 'search'>, query: string, options?: AgentMemorySearchOptions): Promise<AgentMemoryContext>;
+declare function renderMemoryContext(hits: AgentMemoryHit[]): string;
+//#endregion
+//#region src/memory/branch.d.ts
+type AgentMemoryVisibility = 'private' | 'team' | 'shared';
+type AgentMemoryBranchLifetime = 'resumable' | 'attempt';
+interface AgentMemorySharingPolicy {
+  read: readonly AgentMemoryVisibility[];
+  write: AgentMemoryVisibility;
+}
+interface AgentMemoryJournalEntry {
+  sequence: number;
+  input: AgentMemoryWriteInput;
+  result: AgentMemoryWriteResult;
+}
+interface AgentMemoryBranchSnapshot {
+  branchId: string;
+  lifetime: AgentMemoryBranchLifetime;
+  parentBranchId?: string;
+  adapterId: string;
+  policy: AgentMemorySharingPolicy;
+  baseScope: AgentMemoryScope;
+  journal: readonly AgentMemoryJournalEntry[];
+  digest: `sha256:${string}`;
+}
+interface AgentMemoryBranch extends AgentMemoryAdapter {
+  readonly branchId: string;
+  readonly lifetime: AgentMemoryBranchLifetime;
+  readonly parentBranchId?: string;
+  readonly policy: AgentMemorySharingPolicy;
+  snapshot(): Promise<AgentMemoryBranchSnapshot>;
+  fork(options: {
+    branchId: string;
+    adapter?: AgentMemoryAdapter;
+    policy?: AgentMemorySharingPolicy;
+    baseScope?: AgentMemoryScope;
+    lifetime?: AgentMemoryBranchLifetime;
+  }): Promise<AgentMemoryBranch>;
+}
+interface CreateAgentMemoryBranchOptions {
+  adapter: AgentMemoryAdapter;
+  branchId: string;
+  parentBranchId?: string;
+  policy?: AgentMemorySharingPolicy;
+  baseScope?: AgentMemoryScope;
+  /** Attempt branches use a new ID after a process restart and cannot bind persisted state. */
+  lifetime?: AgentMemoryBranchLifetime;
+  /** Rebind a persisted branch whose external memory is still present. */
+  snapshot?: AgentMemoryBranchSnapshot;
+  /** Optional exact logical scopes allowed to write, used by crash-safe experiments. */
+  allowedWriteScopes?: readonly AgentMemoryScope[];
+}
+interface ForkAgentMemoryBranchSnapshotOptions {
+  snapshot: AgentMemoryBranchSnapshot;
+  adapter: AgentMemoryAdapter;
+  branchId: string;
+  policy?: AgentMemorySharingPolicy;
+  baseScope?: AgentMemoryScope;
+  lifetime?: AgentMemoryBranchLifetime;
+}
+/**
+ * Isolates one candidate branch and records accepted writes for durable resume
+ * or replay into a child branch, including a child backed by another provider.
+ */
+declare function createAgentMemoryBranch(options: CreateAgentMemoryBranchOptions): AgentMemoryBranch;
+/** Replays a durable journal into a fresh provider branch. */
+declare function forkAgentMemoryBranchSnapshot(options: ForkAgentMemoryBranchSnapshotOptions): Promise<AgentMemoryBranch>;
+//#endregion
+//#region src/memory/experiment/types.d.ts
+interface AgentMemorySequenceProbe {
+  id: string;
+  query: string;
+  scope?: AgentMemoryScope;
+  limit?: number;
+  taskKind?: KnowledgeMemoryBenchmarkTaskKind;
+  requiredFacts?: readonly KnowledgeMemoryFactMatcher[];
+  forbiddenFacts?: readonly KnowledgeMemoryFactMatcher[];
+  expectedEventIds?: readonly string[];
+  expectedActorIds?: readonly string[];
+  referenceAnswer?: string;
+}
+interface AgentMemorySequenceStep {
+  id: string;
+  instruction?: string;
+  scope?: AgentMemoryScope;
+  writes?: readonly AgentMemoryWriteInput[];
+  parallelWrites?: boolean;
+  probes?: readonly AgentMemorySequenceProbe[];
+  parallelProbes?: boolean;
+  metadata?: Record<string, unknown>;
+}
+/** Runtime-visible step fields. Evaluation labels and dataset identity are excluded. */
+interface AgentMemoryExecutionStep {
+  ordinal: number;
+  instruction?: string;
+  scope?: AgentMemoryScope;
+}
+type AgentMemoryExecutionPaidCallInput<T> = Omit<RunPaidCallInput<T>, 'channel' | 'phase' | 'tags' | 'signal'> & {
+  channel?: CostChannel;
+};
+type AgentMemoryExecutionCostReceipt = Omit<CostReceipt, 'phase' | 'tags'>;
+type AgentMemoryExecutionPaidCallResult<T> = {
+  succeeded: true;
+  callId: string;
+  value: T;
+  receipt: AgentMemoryExecutionCostReceipt;
+} | {
+  succeeded: false;
+  callId?: string;
+  error: Error;
+  receipt?: AgentMemoryExecutionCostReceipt;
+};
+interface AgentMemoryExecutionCostMeter {
+  runPaidCall<T>(input: AgentMemoryExecutionPaidCallInput<T>): Promise<AgentMemoryExecutionPaidCallResult<T>>;
+}
+/** Execution capabilities with all campaign and evaluation identity removed. */
+interface AgentMemoryExecutionContext {
+  readonly signal: AbortSignal;
+  readonly cost: AgentMemoryExecutionCostMeter;
+}
+interface AgentMemorySequence {
+  id: string;
+  family: KnowledgeBenchmarkFamily | string;
+  split?: KnowledgeBenchmarkSplit;
+  steps: readonly AgentMemorySequenceStep[];
+  /** Exact scopes a runtime callback may write beyond scopes declared by steps. */
+  cleanupScopes?: readonly AgentMemoryScope[];
+  tags?: readonly string[];
+  metadata?: Record<string, unknown>;
+}
+interface BuildAgentMemorySequencesFromBenchmarkCasesOptions {
+  memoryAgentId?: string;
+  eventScope?: (input: {
+    event: KnowledgeMemoryEvent;
+    case: KnowledgeMemoryBenchmarkCase;
+    eventIndex: number;
+  }) => AgentMemoryScope;
+  probeScope?: (testCase: KnowledgeMemoryBenchmarkCase) => AgentMemoryScope;
+}
+interface AgentMemoryExperimentCandidate {
+  id: string;
+  label?: string;
+  /** Change when provider configuration changes so cached cells cannot be reused. */
+  ref: string;
+  /** Local construction is free; call markExternalCall before billable provisioning or reconnects. */
+  createAdapter(input: {
+    branchId: string;
+    purpose: 'execute' | 'recovery';
+    signal: AbortSignal;
+    /** Maximum the adapter must enforce with its provider before external work. */
+    maximumCostUsd: number;
+    markExternalCall(): void;
+    /** Record each observed provider charge. Required for complete positive-cost accounting. */
+    recordExternalCost(actualCostUsd: number): void;
+  }): AgentMemoryAdapter | null | Promise<AgentMemoryAdapter | null>;
+  policy?: AgentMemorySharingPolicy;
+  baseScope?: AgentMemoryScope;
+  /** Maximum the adapter must enforce for one complete history. Zero declares a free path. */
+  externalCostUsdPerSequence?: number;
+  /** Maximum the adapter must enforce for one recovery attempt. Zero declares free recovery. */
+  externalRecoveryCostUsdPerAttempt?: number;
+  /** Requires observed provider receipts for positive external charges. */
+  externalCostAccounting?: 'exact';
+  /** Release resources and, when cleanupBranches is false, delete the isolated state. */
+  disposeAdapter?(adapter: AgentMemoryAdapter): Promise<void>;
+}
+interface AgentMemorySequenceProbeResult {
+  id: string;
+  stepId: string;
+  query: string;
+  score: number;
+  passed: boolean;
+  dimensions: Record<string, number>;
+  applicableDimensions: readonly string[];
+  notes: string;
+  hitIds: readonly string[];
+}
+interface AgentMemorySequenceArtifact {
+  candidateId: string;
+  sequenceId: string;
+  score: number;
+  passed: boolean;
+  dimensions: Record<string, number>;
+  dimensionSampleCounts: Record<string, number>;
+  probes: readonly AgentMemorySequenceProbeResult[];
+  branchDigest: string;
+  journalEntries: number;
+  durationMs: number;
+}
+interface AgentMemorySequenceScenario extends Scenario {
+  kind: 'agent-memory-sequence';
+  candidateId: string;
+  sequenceId: string;
+  sequence: AgentMemorySequence;
+  seedGroup: string;
+}
+interface AgentMemoryExperimentRankingRow {
+  rank: number;
+  candidateId: string;
+  label: string;
+  scoreMean: number;
+  passRate: number;
+  totalSequences: number;
+  totalCells: number;
+  totalProbes: number;
+  cellsFailed: number;
+  totalCostUsd: number;
+  durationMs: number;
+  dimensions: Record<string, number>;
+}
+interface RunAgentMemoryExperimentOptions {
+  experimentId: string;
+  /** Stable external branch namespace; distributed workers must use the same value. */
+  experimentRunId?: string;
+  sequences: readonly AgentMemorySequence[];
+  candidates: readonly AgentMemoryExperimentCandidate[];
+  /** Retired candidates retained only so interrupted branches can be cleaned on resume. */
+  recoveryCandidates?: readonly AgentMemoryExperimentCandidate[];
+  runDir: string;
+  executeStep?: (input: {
+    memory: AgentMemoryBranch;
+    candidateId: string;
+    step: AgentMemoryExecutionStep;
+    context: AgentMemoryExecutionContext;
+  }) => Promise<void>;
+  /** Required with executeStep; identify the runtime/profile behavior in cache keys. */
+  executeStepRef?: string;
+  onBranchSnapshot?: (input: {
+    candidateId: string;
+    sequenceId: string;
+    cellId: string;
+    snapshot: AgentMemoryBranchSnapshot;
+  }) => Promise<void> | void;
+  cleanupBranches?: boolean;
+  storage?: CampaignStorage;
+  repo?: string;
+  seed?: number;
+  reps?: number;
+  resumable?: boolean;
+  costCeiling?: number;
+  /** Shared across nested experiments when an outer improvement run owns spend. */
+  costLedger?: CostLedgerHandle;
+  costPhase?: string;
+  maxConcurrency?: number;
+  dispatchTimeoutMs?: number;
+  /** Total deadline for each provider cleanup, close, or recovery operation. */
+  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;
+  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;
+}
+type AgentMemoryExperimentRunLease = AgentMemoryRunLease;
+interface AgentMemoryAttemptEvent {
+  status: 'started' | 'cleaned';
+  branchId: string;
+  candidateId: string;
+  candidateRef: string;
+  sequenceId: string;
+  rep: number;
+  seed: number;
+  cleanupBranches: boolean;
+  externalCostUsdPerSequence: number;
+  externalRecoveryCostUsdPerAttempt: number;
+  recordedAt: string;
+  recovery: boolean;
+}
+interface RunAgentMemoryExperimentResult {
+  campaign: CampaignResult<AgentMemorySequenceArtifact, AgentMemorySequenceScenario>;
+  rows: readonly AgentMemoryExperimentRankingRow[];
+  totalCostUsd: number;
+  /** Recovery spend for retired candidates, excluded from ranking rows but included in totalCostUsd. */
+  unrankedRecoveryCostUsd: number;
+  leaderCandidateId?: string;
+  rankingJsonPath: string;
+  rankingMarkdownPath: string;
+  attemptLogPath: string;
+  recoveryLogPath: string;
+}
+//#endregion
+//#region src/memory/experiment/cases.d.ts
+declare function buildAgentMemorySequencesFromBenchmarkCases(cases: readonly KnowledgeMemoryBenchmarkCase[], options?: BuildAgentMemorySequencesFromBenchmarkCasesOptions): AgentMemorySequence[];
+declare function buildAgentMemorySequenceScenarios(sequences: readonly AgentMemorySequence[], candidates: readonly Pick<AgentMemoryExperimentCandidate, 'id'>[]): AgentMemorySequenceScenario[];
+declare function agentMemorySequenceJudge<TScenario extends Scenario = AgentMemorySequenceScenario>(): JudgeConfig<AgentMemorySequenceArtifact, TScenario>;
+//#endregion
+//#region src/memory/experiment/run.d.ts
+/** Runs ordered, branch-isolated memory histories across candidate systems. */
+declare function runAgentMemoryExperiment(options: RunAgentMemoryExperimentOptions): Promise<RunAgentMemoryExperimentResult>;
+//#endregion
+//#region src/memory/graphiti.d.ts
+interface GraphitiMcpClientLike {
+  callTool(request: {
+    name: string;
+    arguments?: Record<string, unknown>;
+  }): Promise<unknown>;
+}
+interface GraphitiMemoryAdapterOptions {
+  client: GraphitiMcpClientLike;
+  id?: string;
+  /** Stable server/deployment identity for cache-key helpers. Never put credentials here. */
+  backendRef?: string;
+  defaultScope?: AgentMemoryScope;
+  consistency?: 'queued' | 'visible';
+  ingestionTimeoutMs?: number;
+  pollIntervalMs?: number;
+  /** Maximum episodes inspected to prove a queued write became visible. */
+  episodeScanLimit?: number;
+  provenanceEpisodeLimit?: number;
+  search?: readonly ('facts' | 'nodes')[];
+  toolNames?: Partial<GraphitiToolNames>;
+}
+interface GraphitiToolNames {
+  addMemory: string;
+  searchFacts: string;
+  searchNodes: string;
+  getEpisodes: string;
+  clearGraph: string;
+}
+/** Connects the official Graphiti MCP server without coupling to its Python internals. */
+declare function createGraphitiMemoryAdapter(options: GraphitiMemoryAdapterOptions): AgentMemoryAdapter;
+declare function graphitiMemoryAdapterIdentity(options: Pick<GraphitiMemoryAdapterOptions, 'id' | 'consistency' | 'ingestionTimeoutMs' | 'pollIntervalMs' | 'episodeScanLimit' | 'provenanceEpisodeLimit' | 'search' | 'toolNames' | 'defaultScope'> & {
+  backendRef: string;
+}): string;
+//#endregion
+//#region src/memory/holdout.d.ts
+/**
+ * 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;
+  /**
+   * Reward-model prediction for the observed assignment. Supply this together
+   * with `vHatTarget`; both estimates must come from evaluation data outside
+   * this session.
+   */
+  qHatChosen?: (session: RetrievalHoldoutSessionSummary) => number | null;
+  /** Expected reward-model value under the target policy. */
+  vHatTarget?: (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 not converted because exposure was mixed or retrieval was bypassed. */
+  excluded: RetrievalHoldoutSessionSummary[];
+  /** Events with no sessionIdHash: outside session randomization, cannot join a reward. */
+  unattributableEvents: number;
+}
+/**
+ * Maps retrieval-dropout events onto one `OffPolicyTrajectory` per session for use with
+ * `inverseProbabilityWeighting`, `selfNormalizedImportanceWeighting`, or `doublyRobust`.
+ * Randomization occurs once per session: the arm is selected with P(dropout) = 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: `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, because 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 analysis.
+ */
+declare function toOffPolicyTrajectory(events: RetrievalHoldoutEvent[], options: RetrievalHoldoutOffPolicyOptions): RetrievalHoldoutOffPolicyResult;
+//#endregion
+//#region src/memory/improvement/types.d.ts
+interface AgentMemoryDimensionComparison {
+  dimension: string;
+  n: number;
+  expectedN: number;
+  measured: boolean;
+  meanDelta: number;
+  low: number;
+  high: number;
+  tolerance: number;
+  regressed: boolean;
+}
+interface AgentMemoryPromotionDecision {
+  status: 'promote' | 'hold' | 'no-change';
+  reasons: readonly string[];
+  baselineScore: number;
+  winnerScore: number;
+  lift: number;
+  significance?: HeldoutSignificance;
+  criticalDimensions: readonly AgentMemoryDimensionComparison[];
+}
+interface AgentMemoryFinalPair {
+  sequenceId: string;
+  rep: number;
+  baseline: AgentMemorySequenceArtifact;
+  winner: AgentMemorySequenceArtifact;
+}
+interface AgentMemoryFinalEvaluation {
+  manifestHash: string;
+  baselineCandidateRef: string;
+  winnerCandidateRef: string;
+  pairs: readonly AgentMemoryFinalPair[];
+}
+interface AgentMemoryActivation {
+  id: string;
+  status: 'not-eligible' | 'not-configured' | 'pending' | 'activated' | 'recovered' | 'already-activated';
+  journalPath: string;
+}
+interface AgentMemoryActivationDriver<TConfig extends AgentCandidateJsonValue> {
+  /** Change whenever activation behavior or the external target changes. */
+  ref: string;
+  /** Return the exact currently active configuration. */
+  readCurrent(): Promise<TConfig>;
+  /** Atomically replace expectedConfig with config, or fail on a concurrent change. */
+  compareAndSet(input: {
+    activationId: string;
+    expectedConfig: TConfig;
+    expectedSurfaceHash: string;
+    config: TConfig;
+    surfaceHash: string;
+    decision: AgentMemoryPromotionDecision;
+    optimization: RunSerializedKnowledgeOptimizationResult<TConfig>;
+    finalEvaluation: AgentMemoryFinalEvaluation;
+  }): Promise<void>;
+}
+type AgentMemoryImprovementRunLease = AgentMemoryRunLease;
+type AgentMemoryImprovementCandidate = Omit<AgentMemoryExperimentCandidate, 'id' | 'externalCostUsdPerSequence' | 'externalRecoveryCostUsdPerAttempt' | 'externalCostAccounting'> & Required<Pick<AgentMemoryExperimentCandidate, 'externalCostUsdPerSequence' | 'externalRecoveryCostUsdPerAttempt'>> & {
+  externalCostAccounting: 'exact';
+};
+interface RunAgentMemoryImprovementOptions<TConfig extends AgentCandidateJsonValue> {
+  experimentId: string;
+  baselineConfig: TConfig;
+  method: OptimizationMethod<MemoryConfigScenario, AgentMemorySequenceArtifact>;
+  trainSequences: readonly AgentMemorySequence[];
+  selectionSequences: readonly AgentMemorySequence[];
+  finalSequences: readonly AgentMemorySequence[];
+  createCandidate(input: {
+    config: TConfig;
+    candidateId: string;
+    surfaceHash: string;
+  }): AgentMemoryImprovementCandidate | Promise<AgentMemoryImprovementCandidate>;
+  /**
+   * Immutable digest covering the installed implementation, method config,
+   * candidate construction, execution behavior, and external settings.
+   */
+  implementationRef: string;
+  runDir: string;
+  repo?: string;
+  storage?: CampaignStorage;
+  /** Required with custom storage when all controllers are confined to one process. */
+  controllerMode?: AgentMemoryControllerMode;
+  /** Required for distributed controllers using custom storage. */
+  acquireRunLease?: AgentMemoryAcquireRunLease;
+  seed?: number;
+  reps?: number;
+  resumable?: boolean;
+  sequenceConcurrency?: number;
+  dispatchTimeoutMs?: number;
+  cleanupTimeoutMs?: number;
+  maxRecoveryAttempts?: number;
+  maxRecoveryRetriesPerAttempt?: number;
+  /** Total spend limit across method search and final comparison. Default 0. */
+  maxTotalCostUsd?: number;
+  /** Enforced maximum for one config and one sequence. Required with either spend limit. */
+  maximumEvaluationCostUsd?: number;
+  /** Allow activation when a method cannot fully account for cost. Default false. */
+  allowIncompleteCostAccounting?: boolean;
+  optimizationRunOptions?: OptimizationMethodRunOptions<MemoryConfigScenario, AgentMemorySequenceArtifact>;
+  executeStep?: RunAgentMemoryExperimentOptions['executeStep'];
+  executeStepRef?: string;
+  onBranchSnapshot?: RunAgentMemoryExperimentOptions['onBranchSnapshot'];
+  cleanupBranches?: boolean;
+  serializeConfig?: (config: TConfig) => string;
+  parseConfig?: (surface: string) => TConfig;
+  significance?: HeldoutSignificanceOptions;
+  criticalDimensions?: readonly string[];
+  criticalDimensionTolerance?: number;
+  minFinalScore?: number;
+  activation?: AgentMemoryActivationDriver<TConfig>;
+  activationTimeoutMs?: number;
+  now?: () => Date;
+}
+interface RunAgentMemoryImprovementResult<TConfig extends AgentCandidateJsonValue> {
+  optimization: RunSerializedKnowledgeOptimizationResult<TConfig>;
+  baselineConfig: TConfig;
+  winnerConfig: TConfig;
+  baselineSurface: string;
+  winnerSurface: string;
+  baselineSurfaceHash: string;
+  winnerSurfaceHash: string;
+  decision: AgentMemoryPromotionDecision;
+  finalEvaluation: AgentMemoryFinalEvaluation;
+  activation: AgentMemoryActivation;
+  totalCostUsd: number;
+  resultJsonPath: string;
+}
+interface MemoryConfigScenario extends Scenario {
+  kind: 'agent-memory-config-search';
+  sequenceId: string;
+  sequence: AgentMemorySequence;
+}
+//#endregion
+//#region src/memory/improvement/run.d.ts
+/** Optimizes memory configuration with an external method and activates only a fresh final win. */
+declare function runAgentMemoryImprovement<TConfig extends AgentCandidateJsonValue>(options: RunAgentMemoryImprovementOptions<TConfig>): Promise<RunAgentMemoryImprovementResult<TConfig>>;
+//#endregion
+//#region src/memory/lifecycle.d.ts
+declare const DEFAULT_MEMORY_CLEANUP_TIMEOUT_MS = 180000;
+declare class AgentMemoryLifecycleTimeoutError extends Error {
+  readonly operation: string;
+  readonly timeoutMs: number;
+  constructor(operation: string, timeoutMs: number);
+}
+declare class AgentMemoryLifecycleUnsafeError extends Error {
+  readonly operation: string;
+  readonly priorTimeout: AgentMemoryLifecycleTimeoutError;
+  constructor(operation: string, priorTimeout: AgentMemoryLifecycleTimeoutError);
+}
+declare function resolveMemoryCleanupTimeoutMs(value: number | undefined, label: string): number;
+declare function runBoundedMemoryLifecycle<T>(input: {
+  operation: string;
+  timeoutMs: number;
+  /** Prevent later operations from using the same client while timed-out work may still be running. */
+  resource?: object;
+  /** Cooperatively cancel provider work before reporting a timeout. */
+  abortController?: AbortController;
+  run(): Promise<T> | T;
+}): Promise<T>;
+declare function memoryRecoveryDelayMs(adapter: AgentMemoryAdapter): number;
+declare function sleepForMemoryRecovery(delayMs: number, assertOwned: () => Promise<void>, timeoutMs?: number, operation?: string): Promise<void>;
+declare function createMemoryExecutionPool(limit: number): {
+  run<T>(operation: () => Promise<T>): Promise<T>;
+};
+//#endregion
+//#region src/memory/mem0.d.ts
+type Mem0ClientMode = 'hosted' | 'oss';
+interface Mem0Message {
+  role: 'user' | 'assistant';
+  content: string;
+}
+interface Mem0EntityOptions {
+  userId?: string;
+  agentId?: string;
+  runId?: string;
+}
+interface Mem0SearchOptions {
+  filters?: Record<string, unknown>;
+  topK?: number;
+  threshold?: number;
+  rerank?: boolean;
+  showExpired?: boolean;
+}
+interface Mem0HostedClient {
+  add: (messages: Mem0Message[], options: Mem0EntityOptions & {
+    appId?: string;
+    metadata?: Record<string, unknown>;
+    infer?: boolean;
+  }) => Promise<unknown>;
+  search: (query: string, options: Mem0SearchOptions & {
+    latestOnly?: boolean;
+  }) => Promise<unknown>;
+  getAll?: (options: {
+    filters?: Record<string, unknown>;
+    page?: number;
+    pageSize?: number;
+    latestOnly?: boolean;
+    showExpired?: boolean;
+  }) => Promise<unknown>;
+  delete?: (memoryId: string) => Promise<unknown>;
+}
+interface Mem0OssClient {
+  add: (messages: Mem0Message[], options: Mem0EntityOptions & {
+    metadata?: Record<string, unknown>;
+    filters?: Record<string, unknown>;
+    infer?: boolean;
+  }) => Promise<unknown>;
+  search: (query: string, options: Mem0SearchOptions) => Promise<unknown>;
+  getAll?: (options: {
+    filters?: Record<string, unknown>;
+    topK?: number;
+    showExpired?: boolean;
+  }) => Promise<unknown>;
+  delete?: (memoryId: string) => Promise<unknown>;
+}
+interface Mem0MemoryAdapterBaseOptions {
+  id?: string;
+  infer?: boolean;
+  rerank?: boolean;
+  /** Bounds delayed-delete visibility checks and abandoned hosted-write recovery waits. */
+  ingestionTimeoutMs?: number;
+  pollIntervalMs?: number;
+  /** Stable deployment/account identity for cache-key helpers. Never put credentials here. */
+  backendRef?: string;
+  defaultScope?: AgentMemoryScope;
+}
+interface Mem0HostedMemoryAdapterOptions extends Mem0MemoryAdapterBaseOptions {
+  client: Mem0HostedClient;
+  mode: 'hosted';
+  appId?: string;
+  latestOnly?: boolean;
+}
+interface Mem0OssMemoryAdapterOptions extends Mem0MemoryAdapterBaseOptions {
+  client: Mem0OssClient;
+  mode: 'oss';
+  appId?: never;
+  latestOnly?: never;
+}
+type Mem0MemoryAdapterOptions = Mem0HostedMemoryAdapterOptions | Mem0OssMemoryAdapterOptions;
+/** Connects both the hosted Mem0 client and the open-source `Memory` class. */
+declare function createMem0MemoryAdapter(options: Mem0MemoryAdapterOptions): AgentMemoryAdapter;
+/** Stable identity useful for dispatch/cache keys without exposing client credentials. */
+declare function mem0MemoryAdapterIdentity(options: Pick<Mem0MemoryAdapterOptions, 'mode' | 'id' | 'appId' | 'infer' | 'rerank' | 'latestOnly' | 'ingestionTimeoutMs' | 'pollIntervalMs' | 'defaultScope'> & {
+  backendRef: string;
+}): string;
+//#endregion
+//#region src/memory/neo4j.d.ts
+interface Neo4jAgentMemoryAdapterOptions {
+  client: object;
+  /** Match the transport passed to the official MemoryClient. */
+  transport: 'rest' | 'bridge';
+  /** Use Neo4j's whole-conversation context instead of query-based search. */
+  contextMode?: 'search' | 'native';
+  id?: string;
+  /** Assert that the client owns disposable external state for this exact branch. */
+  branchId?: string;
+}
+declare function createNeo4jAgentMemoryAdapter(options: Neo4jAgentMemoryAdapterOptions): AgentMemoryAdapter;
+//#endregion
+//#region src/memory/schemas.d.ts
+declare const AgentMemoryKindSchema: z.ZodEnum<{
+  entity: "entity";
+  fact: "fact";
+  message: "message";
+  observation: "observation";
+  preference: "preference";
+  "reasoning-trace": "reasoning-trace";
+}>;
+declare const AgentMemoryScopeSchema: z.ZodObject<{
+  tenantId: z.ZodOptional<z.ZodString>;
+  userId: z.ZodOptional<z.ZodString>;
+  agentId: z.ZodOptional<z.ZodString>;
+  teamId: z.ZodOptional<z.ZodString>;
+  runId: z.ZodOptional<z.ZodString>;
+  sessionId: z.ZodOptional<z.ZodString>;
+  namespace: z.ZodOptional<z.ZodString>;
+  tags: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip>;
+declare const AgentMemoryHitSchema: z.ZodObject<{
+  id: z.ZodString;
+  uri: z.ZodString;
+  kind: z.ZodEnum<{
+    entity: "entity";
+    fact: "fact";
+    message: "message";
+    observation: "observation";
+    preference: "preference";
+    "reasoning-trace": "reasoning-trace";
+  }>;
+  text: z.ZodString;
+  title: z.ZodOptional<z.ZodString>;
+  score: z.ZodOptional<z.ZodNumber>;
+  normalizedScore: z.ZodOptional<z.ZodNumber>;
+  confidence: z.ZodOptional<z.ZodNumber>;
+  createdAt: z.ZodOptional<z.ZodString>;
+  validUntil: z.ZodOptional<z.ZodString>;
+  lastVerifiedAt: z.ZodOptional<z.ZodString>;
+  metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+declare const AgentMemoryWriteInputSchema: z.ZodObject<{
+  kind: z.ZodEnum<{
+    entity: "entity";
+    fact: "fact";
+    message: "message";
+    observation: "observation";
+    preference: "preference";
+    "reasoning-trace": "reasoning-trace";
+  }>;
+  text: z.ZodString;
+  id: z.ZodOptional<z.ZodString>;
+  title: z.ZodOptional<z.ZodString>;
+  role: z.ZodOptional<z.ZodEnum<{
+    assistant: "assistant";
+    system: "system";
+    tool: "tool";
+    user: "user";
+  }>>;
+  entityName: z.ZodOptional<z.ZodString>;
+  entityType: z.ZodOptional<z.ZodString>;
+  category: z.ZodOptional<z.ZodString>;
+  predicate: z.ZodOptional<z.ZodString>;
+  subject: z.ZodOptional<z.ZodString>;
+  object: z.ZodOptional<z.ZodString>;
+  confidence: z.ZodOptional<z.ZodNumber>;
+  scope: z.ZodOptional<z.ZodObject<{
+    tenantId: z.ZodOptional<z.ZodString>;
+    userId: z.ZodOptional<z.ZodString>;
+    agentId: z.ZodOptional<z.ZodString>;
+    teamId: z.ZodOptional<z.ZodString>;
+    runId: z.ZodOptional<z.ZodString>;
+    sessionId: z.ZodOptional<z.ZodString>;
+    namespace: z.ZodOptional<z.ZodString>;
+    tags: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+  }, z.core.$strip>>;
+  metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+//#endregion
+//#region src/memory/source-record.d.ts
+declare function memoryHitToSourceRecord(hit: AgentMemoryHit, options?: {
+  now?: () => Date;
+  scope?: AgentMemoryScope;
+}): SourceRecord;
+declare function memoryWriteResultToSourceRecord(result: AgentMemoryWriteResult, text: string, options?: {
+  now?: () => Date;
+  scope?: AgentMemoryScope;
+}): SourceRecord;
+//#endregion
+export { buildAgentMemorySequenceScenarios as $, AgentMemoryFinalPair as A, defaultGetMemoryContext as At, applySessionStickyRetrievalHoldout as B, runBoundedMemoryLifecycle as C, AgentMemoryJournalEntry as Ct, AgentMemoryActivationDriver as D, ForkAgentMemoryBranchSnapshotOptions as Dt, AgentMemoryActivation as E, CreateAgentMemoryBranchOptions as Et, RunAgentMemoryImprovementResult as F, SerializedCandidateCodec as Ft, toOffPolicyTrajectory as G, emitRetrievalHoldoutBypass as H, RetrievalHoldoutOffPolicyOptions as I, jsonCandidateCodec as It, GraphitiToolNames as J, GraphitiMcpClientLike as K, RetrievalHoldoutOffPolicyResult as L, jsonObjectCandidateCodec as Lt, AgentMemoryPromotionDecision as M, RunSerializedKnowledgeOptimizationOptions as Mt, MemoryConfigScenario as N, RunSerializedKnowledgeOptimizationResult as Nt, AgentMemoryDimensionComparison as O, createAgentMemoryBranch as Ot, RunAgentMemoryImprovementOptions as P, SerializedCandidate as Pt, agentMemorySequenceJudge as Q, RetrievalHoldoutSessionSummary as R, runSerializedKnowledgeOptimization as Rt, resolveMemoryCleanupTimeoutMs as S, AgentMemoryBranchSnapshot as St, runAgentMemoryImprovement as T, AgentMemoryVisibility as Tt, resetRetrievalHoldoutRegistry as U, deterministicRng as V, retrievalHoldoutConfigHash as W, graphitiMemoryAdapterIdentity as X, createGraphitiMemoryAdapter as Y, runAgentMemoryExperiment as Z, AgentMemoryLifecycleTimeoutError as _, BuildAgentMemorySequencesFromBenchmarkCasesOptions as _t, AgentMemoryScopeSchema as a, AgentMemoryExecutionPaidCallInput as at, createMemoryExecutionPool as b, AgentMemoryBranch as bt, createNeo4jAgentMemoryAdapter as c, AgentMemoryExperimentCandidate as ct, Mem0HostedMemoryAdapterOptions as d, AgentMemorySequence as dt, buildAgentMemorySequencesFromBenchmarkCases as et, Mem0MemoryAdapterOptions as f, AgentMemorySequenceArtifact as ft, mem0MemoryAdapterIdentity as g, AgentMemorySequenceStep as gt, createMem0MemoryAdapter as h, AgentMemorySequenceScenario as ht, AgentMemoryKindSchema as i, AgentMemoryExecutionCostReceipt as it, AgentMemoryImprovementRunLease as j, renderMemoryContext as jt, AgentMemoryFinalEvaluation as k, forkAgentMemoryBranchSnapshot as kt, Mem0ClientMode as l, AgentMemoryExperimentRankingRow as lt, Mem0OssMemoryAdapterOptions as m, AgentMemorySequenceProbeResult as mt, memoryWriteResultToSourceRecord as n, AgentMemoryExecutionContext as nt, AgentMemoryWriteInputSchema as o, AgentMemoryExecutionPaidCallResult as ot, Mem0OssClient as p, AgentMemorySequenceProbe as pt, GraphitiMemoryAdapterOptions as q, AgentMemoryHitSchema as r, AgentMemoryExecutionCostMeter as rt, Neo4jAgentMemoryAdapterOptions as s, AgentMemoryExecutionStep as st, memoryHitToSourceRecord as t, AgentMemoryAttemptEvent as tt, Mem0HostedClient as u, AgentMemoryExperimentRunLease as ut, AgentMemoryLifecycleUnsafeError as v, RunAgentMemoryExperimentOptions as vt, sleepForMemoryRecovery as w, AgentMemorySharingPolicy as wt, memoryRecoveryDelayMs as x, AgentMemoryBranchLifetime as xt, DEFAULT_MEMORY_CLEANUP_TIMEOUT_MS as y, RunAgentMemoryExperimentResult as yt, applyRetrievalHoldout as z, scenarioContentFingerprint as zt };
+//# sourceMappingURL=index-CGBctbit.d.ts.map