@atomicmemory/core 1.0.0

package/dist/services/retrieval-policy.js

@@ -0,0 +1,275 @@
+/**
+ * Adaptive retrieval and repair-loop policy helpers.
+ */
+import { isCurrentStateQuery, isHistoricalQuery } from './current-state-ranking.js';
+import { isTemporalOrderingQuery } from './temporal-query-expansion.js';
+const SIMPLE_QUERY_LIMIT = 5;
+const MEDIUM_QUERY_LIMIT = 5;
+const COMPLEX_QUERY_LIMIT = 8;
+const MULTI_HOP_QUERY_LIMIT = 12;
+export const AGGREGATION_QUERY_LIMIT = 25;
+/** Hard ceiling for aggregation queries (prevents runaway candidate pools). */
+const AGGREGATION_HARD_CAP = 50;
+const RECALL_ORIENTED_QUERY_LABELS = new Set(['complex', 'multi-hop', 'aggregation']);
+const RECALL_BYPASS_REASONS = {
+    AS_OF_QUERY: 'as-of-query',
+    SOURCE_SITE_FILTER: 'source-site-filter',
+    TEMPORAL_STATE_QUERY: 'temporal-state-query',
+    recallOriented: (queryLabel) => `recall-oriented-${queryLabel}-query`,
+};
+/**
+ * Markers indicating temporal/relational complexity (multi-hop or comparison).
+ *
+ * The "current" marker reclassifies current-state attribute queries from
+ * MEDIUM/5 → MULTI_HOP/12 so the retrieval window is broad enough to
+ * distinguish current state from historical mentions (commit 122ae26).
+ *
+ * Validated 2026-04-01: 0/15 false positives across 2,173 benchmark queries
+ * (7 datasets). 4 borderline date-pinned queries are harmless (extra depth,
+ * no accuracy impact). See: docs/.../current-marker-fp-analysis-2026-04-01.md
+ *
+ * If editing this list, re-run the FP scan:
+ *   classifyQueryDetailed() against all eval dataset queries.
+ */
+const MULTI_HOP_MARKERS = ['compare', 'difference between', 'relationship between', 'how does .* relate', 'connection between', 'all the times', 'everything about', 'full history', 'current'];
+/**
+ * Toggle "current" in MULTI_HOP_MARKERS for controlled A/B eval comparisons.
+ * Not for production use — only called by run-balanced12-validation.ts.
+ */
+function addCurrentToMultiHopMarkers() {
+    if (!MULTI_HOP_MARKERS.includes('current'))
+        MULTI_HOP_MARKERS.push('current');
+}
+function removeCurrentFromMultiHopMarkers() {
+    const idx = MULTI_HOP_MARKERS.indexOf('current');
+    if (idx >= 0)
+        MULTI_HOP_MARKERS.splice(idx, 1);
+}
+const COMPLEX_MARKERS = ['before', 'after', 'change', 'switched', 'why', 'how', 'relationship', 'history', 'used to', 'when', 'timeline', 'order', 'how long', 'sequence'];
+/**
+ * Aggregation query markers: count, sum, total, list-all patterns.
+ * These need high recall across many sessions to avoid undercounting.
+ */
+const AGGREGATION_MARKERS = [
+    'how many', 'how much',
+    'total amount', 'total cost', 'total spent', 'total price',
+    'total duration', 'total number', 'total time',
+    'list all', 'list every', 'name all', 'name every',
+    'what are all', 'what were all',
+];
+export function resolveSearchLimit(query, requestedLimit, runtimeConfig) {
+    return resolveSearchLimitDetailed(query, requestedLimit, runtimeConfig).limit;
+}
+export function resolveSearchLimitDetailed(query, requestedLimit, runtimeConfig) {
+    // When the caller passed an explicit limit AND adaptive is enabled, take the
+    // MAX of (requested, classification) so aggregation queries get high recall
+    // even when the caller defaulted to a low limit. v19 evidence at n=80: AMB
+    // sends limit=10 which short-circuited the adaptive path, leaving MSR
+    // questions starving for context (8/8 questions scored 0). This change keeps
+    // the explicit-limit contract for non-aggregation queries while letting
+    // aggregation/multi-hop scale up automatically.
+    if (requestedLimit !== undefined && runtimeConfig.adaptiveRetrievalEnabled) {
+        const classification = applyConfiguredLimit(classifyQueryDetailed(query), runtimeConfig);
+        const classLimit = classification.label === 'aggregation'
+            ? Math.min(AGGREGATION_HARD_CAP, classification.limit)
+            : clampLimit(classification.limit, runtimeConfig.maxSearchResults);
+        const requestedClamped = clampLimit(requestedLimit, runtimeConfig.maxSearchResults);
+        const final = Math.max(requestedClamped, classLimit);
+        return { limit: final, classification };
+    }
+    if (requestedLimit !== undefined) {
+        return { limit: clampLimit(requestedLimit, runtimeConfig.maxSearchResults), classification: { limit: requestedLimit, label: 'medium' } };
+    }
+    if (!runtimeConfig.adaptiveRetrievalEnabled) {
+        return { limit: clampLimit(runtimeConfig.maxSearchResults, runtimeConfig.maxSearchResults), classification: { limit: runtimeConfig.maxSearchResults, label: 'medium' } };
+    }
+    const classification = applyConfiguredLimit(classifyQueryDetailed(query), runtimeConfig);
+    // Aggregation queries bypass the normal maxSearchResults clamp to improve
+    // recall for count/sum/list-all questions spanning many sessions.
+    const limit = classification.label === 'aggregation'
+        ? Math.max(1, Math.min(AGGREGATION_HARD_CAP, classification.limit))
+        : clampLimit(classification.limit, runtimeConfig.maxSearchResults);
+    return { limit, classification };
+}
+export function shouldRunRepairLoop(query, memories, runtimeConfig) {
+    if (!runtimeConfig.repairLoopEnabled)
+        return false;
+    // Selective repair: only escalate queries where the rewrite improves retrieval.
+    // Multi-hop and aggregation always benefit. Complex queries benefit unless they
+    // are temporal-ordering (the rewrite strips time-specific phrasing and hurts
+    // sequencing evidence). Simple/medium queries are fast-pathed without repair.
+    const classification = classifyQueryDetailed(query);
+    const isEligible = classification.label === 'multi-hop'
+        || classification.label === 'aggregation'
+        || (classification.label === 'complex' && !isTemporalOrderingQuery(query));
+    if (!isEligible)
+        return false;
+    if (memories.length === 0)
+        return true;
+    if (memories[0].similarity < runtimeConfig.repairLoopMinSimilarity)
+        return true;
+    return isComplexQuery(query.toLowerCase()) && memories.length < resolveSearchLimit(query, undefined, runtimeConfig);
+}
+/**
+ * Decides whether to accept repaired results over initial results.
+ * Gates on two heuristics:
+ *   1. Similarity-delta anti-thrash: reject if top-1 similarity didn't improve enough.
+ *   2. Confidence floor: reject if repaired top-1 similarity is still too low.
+ * Both thresholds default to 0 (always accept) to preserve current behavior.
+ */
+export function shouldAcceptRepair(initial, repaired, runtimeConfig) {
+    const initialTopSim = initial.length > 0 ? initial[0].similarity : 0;
+    const repairedTopSim = repaired.length > 0 ? repaired[0].similarity : 0;
+    const simDelta = repairedTopSim - initialTopSim;
+    const base = { initialTopSim, repairedTopSim, simDelta };
+    // Anti-sabotage gating: If initial results are strong (>0.6) and repair degrades 
+    // similarity, always reject.
+    if (initialTopSim > 0.6 && simDelta < 0) {
+        return { ...base, accepted: false, reason: 'sabotage-detected' };
+    }
+    const deltaThreshold = runtimeConfig.repairDeltaThreshold || 0.01;
+    if (simDelta < deltaThreshold) {
+        return { ...base, accepted: false, reason: 'delta-below-threshold' };
+    }
+    if (runtimeConfig.repairConfidenceFloor > 0 && repairedTopSim < runtimeConfig.repairConfidenceFloor) {
+        return { ...base, accepted: false, reason: 'below-confidence-floor' };
+    }
+    return { ...base, accepted: true, reason: 'accepted' };
+}
+export function mergeSearchResults(primary, repair, limit, runtimeConfig) {
+    const merged = new Map();
+    mergeWeightedResults(merged, primary, runtimeConfig.retrievalProfileSettings.repairPrimaryWeight);
+    mergeWeightedResults(merged, repair, runtimeConfig.retrievalProfileSettings.repairRewriteWeight);
+    return [...merged.values()].sort((left, right) => right.score - left.score).slice(0, clampLimitWide(limit));
+}
+export function resolveRerankDepth(limit, runtimeConfig) {
+    return Math.max(clampLimitWide(limit), runtimeConfig.retrievalProfileSettings.rerankDepth);
+}
+export function applyRankingEligibility(query, candidates, runtimeConfig, context = {}) {
+    const queryLabel = classifyQueryDetailed(query).label;
+    const bypassReason = resolveRecallBypass(query, queryLabel, context);
+    if (bypassReason) {
+        return {
+            results: candidates,
+            decisions: [],
+            removedIds: [],
+            threshold: null,
+            reason: bypassReason,
+            queryLabel,
+            triggered: false,
+        };
+    }
+    const threshold = clampUnit(runtimeConfig.retrievalProfileSettings.rankingMinSimilarity);
+    if (threshold <= 0) {
+        return {
+            results: candidates,
+            decisions: [],
+            removedIds: [],
+            threshold: null,
+            reason: 'non-positive-ranking-threshold',
+            queryLabel,
+            triggered: false,
+        };
+    }
+    const decisions = candidates.map((candidate) => buildRankingEligibilityDecision(candidate, threshold));
+    const removedIds = decisions
+        .filter((decision) => decision.decision === 'filtered')
+        .map((decision) => decision.id);
+    const keptIds = new Set(decisions.filter((decision) => decision.decision === 'eligible').map((decision) => decision.id));
+    return {
+        results: candidates.filter((candidate) => keptIds.has(candidate.id)),
+        decisions,
+        removedIds,
+        threshold,
+        reason: 'direct-query-ranking-floor',
+        queryLabel,
+        triggered: true,
+    };
+}
+function applyConfiguredLimit(classification, runtimeConfig) {
+    const limits = {
+        simple: runtimeConfig.adaptiveSimpleLimit,
+        medium: runtimeConfig.adaptiveMediumLimit,
+        complex: runtimeConfig.adaptiveComplexLimit,
+        'multi-hop': runtimeConfig.adaptiveMultiHopLimit,
+        aggregation: runtimeConfig.adaptiveAggregationLimit,
+    };
+    return { ...classification, limit: limits[classification.label] };
+}
+function classifyQueryComplexity(query) {
+    return classifyQueryDetailed(query).limit;
+}
+export function classifyQueryDetailed(query) {
+    const lower = query.toLowerCase();
+    const aggMarker = AGGREGATION_MARKERS.find((m) => lower.includes(m));
+    if (aggMarker)
+        return { limit: AGGREGATION_QUERY_LIMIT, label: 'aggregation', matchedMarker: aggMarker };
+    const hopMarker = MULTI_HOP_MARKERS.find((m) => new RegExp(m).test(lower));
+    if (hopMarker)
+        return { limit: MULTI_HOP_QUERY_LIMIT, label: 'multi-hop', matchedMarker: hopMarker };
+    if (isComplexQuery(lower))
+        return { limit: COMPLEX_QUERY_LIMIT, label: 'complex' };
+    if (lower.split(/\s+/).length > 9)
+        return { limit: MEDIUM_QUERY_LIMIT, label: 'medium' };
+    if (lower.endsWith('?') && lower.split(/\s+/).length <= 5)
+        return { limit: SIMPLE_QUERY_LIMIT, label: 'simple' };
+    return { limit: MEDIUM_QUERY_LIMIT, label: 'medium' };
+}
+export function resolveRecallBypass(query, queryLabel, context) {
+    if (context.asOf || context.referenceTime)
+        return RECALL_BYPASS_REASONS.AS_OF_QUERY;
+    if (context.sourceSite)
+        return RECALL_BYPASS_REASONS.SOURCE_SITE_FILTER;
+    // State queries need recall even when the adaptive-depth classifier calls
+    // them simple/medium; regression tests pin representative cross-classifier
+    // cases so these regex classifiers do not drift unnoticed.
+    if (isCurrentStateQuery(query) || isHistoricalQuery(query))
+        return RECALL_BYPASS_REASONS.TEMPORAL_STATE_QUERY;
+    if (RECALL_ORIENTED_QUERY_LABELS.has(queryLabel))
+        return RECALL_BYPASS_REASONS.recallOriented(queryLabel);
+    return null;
+}
+function isMultiHopQuery(lowerQuery) {
+    return MULTI_HOP_MARKERS.some((marker) => new RegExp(marker).test(lowerQuery));
+}
+function isComplexQuery(lowerQuery) {
+    return COMPLEX_MARKERS.some((marker) => lowerQuery.includes(marker));
+}
+export function isAggregationQuery(lowerQuery) {
+    return AGGREGATION_MARKERS.some((marker) => lowerQuery.includes(marker));
+}
+function clampLimit(limit, maxSearchResults) {
+    return Math.max(1, Math.min(maxSearchResults, Math.floor(limit)));
+}
+/** Wider clamp for pipeline internals — respects aggregation ceiling, not profile cap. */
+function clampLimitWide(limit) {
+    return Math.max(1, Math.min(AGGREGATION_HARD_CAP, Math.floor(limit)));
+}
+function buildRankingEligibilityDecision(candidate, threshold) {
+    const similarity = finiteOrZero(candidate.similarity);
+    const eligible = similarity >= threshold;
+    return {
+        id: candidate.id,
+        similarity,
+        threshold,
+        decision: eligible ? 'eligible' : 'filtered',
+        reason: eligible ? 'meets-ranking-floor' : 'below-ranking-floor',
+    };
+}
+function finiteOrZero(value) {
+    return Number.isFinite(value) ? value : 0;
+}
+function clampUnit(value) {
+    if (!Number.isFinite(value))
+        return 0;
+    return Math.max(0, Math.min(1, value));
+}
+function mergeWeightedResults(merged, results, weight) {
+    for (const memory of results) {
+        const weighted = { ...memory, score: memory.score * weight };
+        const existing = merged.get(memory.id);
+        if (!existing || weighted.score > existing.score) {
+            merged.set(memory.id, weighted);
+        }
+    }
+}

package/dist/services/retrieval-profiles.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Retrieval profile definitions for safe, balanced, and quality modes.
+ */
+export type RetrievalProfileName = 'safe' | 'balanced' | 'quality';
+export interface RetrievalProfile {
+    name: RetrievalProfileName;
+    maxSearchResults: number;
+    repairLoopEnabled: boolean;
+    adaptiveRetrievalEnabled: boolean;
+    hybridSearchEnabled: boolean;
+    repairLoopMinSimilarity: number;
+    repairSkipSimilarity: number;
+    rerankDepth: number;
+    repairPrimaryWeight: number;
+    repairRewriteWeight: number;
+    lexicalWeight: number;
+    mmrEnabled: boolean;
+    mmrLambda: number;
+    linkExpansionEnabled: boolean;
+    linkExpansionMax: number;
+    linkSimilarityThreshold: number;
+    scoringWeightSimilarity: number;
+    scoringWeightImportance: number;
+    scoringWeightRecency: number;
+    /**
+     * Minimum semantic similarity required before importance/recency ranking
+     * boosts apply, and before direct simple/medium queries consider a candidate
+     * eligible for injection. Safe is stricter; quality keeps a little more
+     * recall for borderline matches.
+     */
+    rankingMinSimilarity: number;
+    linkExpansionBeforeMMR: boolean;
+    repairDeltaThreshold: number;
+    repairConfidenceFloor: number;
+}
+export declare function parseRetrievalProfile(value: string | undefined): RetrievalProfileName;
+export declare function getRetrievalProfile(name: RetrievalProfileName): RetrievalProfile;

package/dist/services/retrieval-profiles.js

@@ -0,0 +1,90 @@
+/**
+ * Retrieval profile definitions for safe, balanced, and quality modes.
+ */
+const PROFILES = {
+    safe: {
+        name: 'safe',
+        maxSearchResults: 5,
+        repairLoopEnabled: false,
+        adaptiveRetrievalEnabled: false,
+        hybridSearchEnabled: false,
+        repairLoopMinSimilarity: 0.8,
+        repairSkipSimilarity: 0.65,
+        rerankDepth: 5,
+        repairPrimaryWeight: 1,
+        repairRewriteWeight: 0,
+        lexicalWeight: 0.4,
+        mmrEnabled: false,
+        mmrLambda: 0.7,
+        linkExpansionEnabled: false,
+        linkExpansionMax: 0,
+        linkSimilarityThreshold: 0.5,
+        scoringWeightSimilarity: 2.0,
+        scoringWeightImportance: 1.0,
+        scoringWeightRecency: 1.0,
+        rankingMinSimilarity: 0.35,
+        linkExpansionBeforeMMR: false,
+        repairDeltaThreshold: 0,
+        repairConfidenceFloor: 0,
+    },
+    balanced: {
+        name: 'balanced',
+        maxSearchResults: 12,
+        repairLoopEnabled: true,
+        adaptiveRetrievalEnabled: true,
+        hybridSearchEnabled: false,
+        repairLoopMinSimilarity: 0.72,
+        repairSkipSimilarity: 0.65,
+        rerankDepth: 16,
+        repairPrimaryWeight: 1,
+        repairRewriteWeight: 0.92,
+        lexicalWeight: 0.8,
+        mmrEnabled: true,
+        mmrLambda: 0.85,
+        linkExpansionEnabled: true,
+        linkExpansionMax: 3,
+        linkSimilarityThreshold: 0.5,
+        scoringWeightSimilarity: 2.0,
+        scoringWeightImportance: 1.0,
+        scoringWeightRecency: 1.0,
+        rankingMinSimilarity: 0.3,
+        linkExpansionBeforeMMR: false,
+        repairDeltaThreshold: 0,
+        repairConfidenceFloor: 0,
+    },
+    quality: {
+        name: 'quality',
+        maxSearchResults: 12,
+        repairLoopEnabled: true,
+        adaptiveRetrievalEnabled: true,
+        hybridSearchEnabled: true,
+        repairLoopMinSimilarity: 0.78,
+        repairSkipSimilarity: 0.65,
+        rerankDepth: 12,
+        repairPrimaryWeight: 1,
+        repairRewriteWeight: 1.05,
+        lexicalWeight: 1.15,
+        mmrEnabled: true,
+        mmrLambda: 0.6,
+        linkExpansionEnabled: true,
+        linkExpansionMax: 4,
+        linkSimilarityThreshold: 0.45,
+        scoringWeightSimilarity: 2.0,
+        scoringWeightImportance: 1.0,
+        scoringWeightRecency: 1.0,
+        rankingMinSimilarity: 0.25,
+        linkExpansionBeforeMMR: false,
+        repairDeltaThreshold: 0,
+        repairConfidenceFloor: 0,
+    },
+};
+export function parseRetrievalProfile(value) {
+    if (!value)
+        return 'balanced';
+    if (value === 'safe' || value === 'balanced' || value === 'quality')
+        return value;
+    throw new Error('Invalid RETRIEVAL_PROFILE. Must be "safe", "balanced", or "quality"');
+}
+export function getRetrievalProfile(name) {
+    return PROFILES[name];
+}

package/dist/services/retrieval-side-effects.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Fire-and-forget side effects for completed searches.
+ *
+ * Centralizes the "after the search returns, what else happens" concerns
+ * so memory-search.ts can stay focused on orchestration. Currently:
+ *   - touchMemory for each returned result (updates last-accessed time)
+ *   - audit event emission when auditLoggingEnabled is on
+ *
+ * Historically inline in memory-search.ts; extracted in Phase 7 Item 4.
+ */
+import type { SearchResult } from '../db/repository-types.js';
+import type { MemoryServiceDeps } from './memory-service-types.js';
+/** Run post-search side effects. Swallows per-memory touch failures. */
+export declare function recordSearchSideEffects(deps: MemoryServiceDeps, outputMemories: SearchResult[], userId: string, query: string, sourceSite: string | undefined, asOf: string | undefined): void;

package/dist/services/retrieval-side-effects.js

@@ -0,0 +1,26 @@
+/**
+ * Fire-and-forget side effects for completed searches.
+ *
+ * Centralizes the "after the search returns, what else happens" concerns
+ * so memory-search.ts can stay focused on orchestration. Currently:
+ *   - touchMemory for each returned result (updates last-accessed time)
+ *   - audit event emission when auditLoggingEnabled is on
+ *
+ * Historically inline in memory-search.ts; extracted in Phase 7 Item 4.
+ */
+import { emitAuditEvent } from './audit-events.js';
+/** Run post-search side effects. Swallows per-memory touch failures. */
+export function recordSearchSideEffects(deps, outputMemories, userId, query, sourceSite, asOf) {
+    if (!asOf) {
+        for (const memory of outputMemories) {
+            deps.stores.memory.touchMemory(memory.id).catch(() => { });
+        }
+    }
+    if (deps.config.auditLoggingEnabled) {
+        emitAuditEvent('memory:retrieve', userId, {
+            query: query.slice(0, 200),
+            resultCount: outputMemories.length,
+            topScore: outputMemories[0]?.score ?? 0,
+        }, { sourceSite });
+    }
+}

package/dist/services/retrieval-trace.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Retrieval observability trace logger.
+ *
+ * Captures structured per-query traces through the retrieval pipeline:
+ * query → candidates → repair → MMR → link expansion → final selection.
+ *
+ * Traces are persisted as JSON artifacts when RETRIEVAL_TRACE_ENABLED=true.
+ */
+import type { SearchResult } from '../db/memory-repository.js';
+import type { RelevanceFilterDecision } from './relevance-policy.js';
+/** A snapshot of a single memory at a pipeline stage. */
+interface TracedMemory {
+    id: string;
+    similarity: number;
+    semanticSimilarity: number;
+    score: number;
+    rankingScore: number;
+    relevance: number;
+    importance: number;
+    sourceSite: string;
+    namespace: string | null;
+    contentPreview: string;
+    tier?: string;
+}
+/** One stage in the retrieval pipeline. */
+interface TraceStage {
+    name: string;
+    count: number;
+    memories: TracedMemory[];
+    meta?: Record<string, unknown>;
+    timestamp: number;
+}
+/** Full trace for one retrieval operation. */
+export interface RetrievalTrace {
+    traceId: string;
+    query: string;
+    userId: string;
+    timestamp: string;
+    durationMs: number;
+    stages: TraceStage[];
+    finalResultCount: number;
+    retrieval?: RetrievalTraceSummary;
+    packaging?: PackagingTraceSummary;
+    assembly?: AssemblyTraceSummary;
+}
+export interface RetrievalTraceSummary {
+    candidateIds: string[];
+    candidateCount: number;
+    queryText: string;
+    skipRepair: boolean;
+    relevanceThreshold?: number | null;
+    relevanceFilterSource?: string;
+    relevanceFilterReason?: string;
+    filteredCandidateIds?: string[];
+    filterDecisions?: RelevanceFilterDecision[];
+    traceId?: string;
+    stageCount?: number;
+    stageNames?: string[];
+}
+export type PackagingType = 'subject-pack' | 'timeline-pack' | 'tiered';
+export type PackagingEvidenceRole = 'primary' | 'supporting' | 'historical' | 'contextual';
+export interface PackagingTraceSummary {
+    packageType: PackagingType;
+    includedIds: string[];
+    droppedIds: string[];
+    evidenceRoles: Record<string, PackagingEvidenceRole>;
+    episodeCount: number;
+    dateCount: number;
+    hasCurrentMarker: boolean;
+    hasConflictBlock: boolean;
+    tokenCost: number;
+}
+export interface AssemblyTraceSummary {
+    finalIds: string[];
+    finalTokenCost: number;
+    tokenBudget: number | null;
+    primaryEvidencePosition: number | null;
+    blocks: string[];
+}
+/**
+ * Accumulates trace stages during a single search operation.
+ */
+export declare class TraceCollector {
+    private stages;
+    private retrieval?;
+    private packaging?;
+    private assembly?;
+    private startTime;
+    private traceId;
+    private query;
+    private userId;
+    private enabled;
+    constructor(query: string, userId: string);
+    /** Record a pipeline stage with its current result set and optional metadata. */
+    stage(name: string, results: SearchResult[], meta?: Record<string, unknown>): void;
+    /** Event-only stage (no memories, just metadata). */
+    event(name: string, meta?: Record<string, unknown>): void;
+    setRetrievalSummary(summary: RetrievalTraceSummary): void;
+    setPackagingSummary(summary: PackagingTraceSummary): void;
+    setAssemblySummary(summary: AssemblyTraceSummary): void;
+    getRetrievalSummary(): RetrievalTraceSummary | undefined;
+    getPackagingSummary(): PackagingTraceSummary | undefined;
+    getAssemblySummary(): AssemblyTraceSummary | undefined;
+    /** Persist the full trace to disk and optionally log to stdout. */
+    finalize(finalResults: SearchResult[]): string | null;
+    private persistTrace;
+}
+export {};