cogmem 3.6.2

package/dist/retrieval/QueryTimePendingEntityResolver.js

@@ -0,0 +1,260 @@
+import { extractRelativeReferences, inferReferenceType, isLatestReference, isPreviousReference, normalizeLexiconText } from '../lexicon/coreMemoryLexicon.js';
+export class QueryTimePendingEntityResolver {
+    entityStore;
+    getNeuronById;
+    resolveBeforeTime;
+    constructor(entityStore, getNeuronById, resolveBeforeTime) {
+        this.entityStore = entityStore;
+        this.getNeuronById = getNeuronById;
+        this.resolveBeforeTime = resolveBeforeTime;
+    }
+    resolve(input) {
+        const references = this.collectRelativeReferences(input);
+        if (references.length === 0) {
+            return {
+                overallStatus: 'not_applicable',
+                overallReason: 'no_relative_pending_reference_in_query',
+                resolvedEntityIds: [],
+                candidateEntityIds: [],
+                candidateNeuronIds: [],
+                results: [],
+                pendingCaptureMetrics: emptyPendingCaptureMetrics()
+            };
+        }
+        const pendingRecords = this.entityStore.listPendingResolutions({ status: 'pending' });
+        const beforeTime = this.resolveBeforeTime(input.ir);
+        const results = [];
+        for (const reference of references) {
+            const matchingPending = this.findMatchingPendingRecords(reference, pendingRecords, input);
+            if (matchingPending.length === 0) {
+                const queryTimeResolutionReason = this.inferNoPendingReason(reference, pendingRecords, input);
+                results.push({
+                    reference,
+                    queryTimeResolutionStatus: 'not_needed',
+                    queryTimeResolutionReason,
+                    resolutionConfidence: 0,
+                    candidateEntityIds: [],
+                    narrowedCandidates: [],
+                    matchedPendingIds: [],
+                    contextNeuronIds: []
+                });
+                continue;
+            }
+            const normalizedReference = normalizePendingReference(reference);
+            const contextNeuronIds = matchingPending
+                .map((record) => record.contextNeuronId)
+                .filter((id) => Boolean(id));
+            const effectiveProjectId = this.inferPendingScopedProjectId(matchingPending) || input.projectId;
+            const typeHint = matchingPending[0]?.entityType || inferReferenceType(normalizedReference, input.query);
+            const candidates = this.entityStore.listReferenceCandidatesWithRelativeSupport(reference, typeHint, {
+                projectId: effectiveProjectId,
+                beforeTime
+            }).slice(0, 4);
+            const narrowedCandidates = candidates.map((candidate) => ({
+                entityId: candidate.entity.entityId,
+                score: candidate.score,
+                reasons: candidate.reasons
+            }));
+            if (candidates.length === 0) {
+                results.push({
+                    reference,
+                    queryTimeResolutionStatus: 'unresolved_explicit',
+                    queryTimeResolutionReason: 'pending_reference_still_unresolved',
+                    resolutionConfidence: 0.12,
+                    candidateEntityIds: [],
+                    narrowedCandidates: [],
+                    matchedPendingIds: matchingPending.map((record) => record.pendingId),
+                    contextNeuronIds
+                });
+                continue;
+            }
+            const topCandidate = candidates[0];
+            const secondCandidate = candidates[1];
+            const canResolveNarrowly = this.canResolveNarrowly(topCandidate, secondCandidate);
+            if (canResolveNarrowly && topCandidate) {
+                results.push({
+                    reference,
+                    queryTimeResolutionStatus: 'resolved_narrowly',
+                    queryTimeResolutionReason: 'pending_relative_reference_narrowed',
+                    resolutionConfidence: topCandidate.score,
+                    candidateEntityIds: narrowedCandidates.map((candidate) => candidate.entityId),
+                    narrowedCandidates,
+                    matchedPendingIds: matchingPending.map((record) => record.pendingId),
+                    contextNeuronIds,
+                    resolvedInstanceId: topCandidate.entity.entityId
+                });
+                continue;
+            }
+            results.push({
+                reference,
+                queryTimeResolutionStatus: 'narrowed_but_still_ambiguous',
+                queryTimeResolutionReason: 'pending_relative_reference_ambiguous_after_narrowing',
+                resolutionConfidence: topCandidate?.score || 0.36,
+                candidateEntityIds: narrowedCandidates.map((candidate) => candidate.entityId),
+                narrowedCandidates,
+                matchedPendingIds: matchingPending.map((record) => record.pendingId),
+                contextNeuronIds
+            });
+        }
+        return {
+            overallStatus: this.inferOverallStatus(results),
+            overallReason: this.inferOverallReason(results),
+            resolvedEntityIds: Array.from(new Set(results
+                .filter((result) => result.queryTimeResolutionStatus === 'resolved_narrowly')
+                .map((result) => result.resolvedInstanceId)
+                .filter((id) => Boolean(id)))),
+            candidateEntityIds: Array.from(new Set(results.flatMap((result) => result.candidateEntityIds))),
+            candidateNeuronIds: Array.from(new Set(results.flatMap((result) => result.contextNeuronIds))),
+            results,
+            pendingCaptureMetrics: this.computePendingCaptureMetrics(pendingRecords, results)
+        };
+    }
+    collectRelativeReferences(input) {
+        return Array.from(new Set([
+            ...input.semanticCompilation.relativeReferences,
+            ...input.ir.entities,
+            ...input.ir.semantics.entityHints
+        ]))
+            .map((reference) => reference.trim())
+            .filter(Boolean)
+            .filter((reference) => extractRelativeReferences(normalizeLexiconText(reference)).length > 0);
+    }
+    findMatchingPendingRecords(reference, pendingRecords, input) {
+        const normalizedReference = normalizePendingReference(reference);
+        const referenceSignals = new Set(extractRelativeReferences(normalizedReference).map(normalizePendingReference));
+        if (referenceSignals.size === 0)
+            referenceSignals.add(normalizedReference);
+        const matchingPending = pendingRecords.filter((record) => {
+            const normalizedPending = normalizePendingReference(record.referenceText);
+            const pendingSignals = new Set(extractRelativeReferences(normalizedPending).map(normalizePendingReference));
+            if (pendingSignals.size === 0)
+                pendingSignals.add(normalizedPending);
+            const sharesRelativePolarity = Array.from(referenceSignals).some((signal) => Array.from(pendingSignals).some((pendingSignal) => (isPreviousReference(signal) && isPreviousReference(pendingSignal))
+                || (isLatestReference(signal) && isLatestReference(pendingSignal))));
+            return normalizedPending === normalizedReference
+                || normalizedPending.includes(normalizedReference)
+                || normalizedReference.includes(normalizedPending)
+                || Array.from(referenceSignals).some((signal) => pendingSignals.has(signal))
+                || sharesRelativePolarity;
+        });
+        if (!input.projectId) {
+            if (matchingPending.length > 0)
+                return matchingPending;
+            return this.findSameTypePendingFallback(reference, pendingRecords, input);
+        }
+        const scopedPending = matchingPending.filter((record) => {
+            if (!record.contextNeuronId)
+                return true;
+            const neuron = this.getNeuronById(record.contextNeuronId);
+            return !neuron?.metadata.projectId || neuron.metadata.projectId === input.projectId;
+        });
+        const projectScopedPending = scopedPending.length > 0 ? scopedPending : matchingPending;
+        if (projectScopedPending.length > 0)
+            return projectScopedPending;
+        return this.findSameTypePendingFallback(reference, pendingRecords, input);
+    }
+    canResolveNarrowly(topCandidate, secondCandidate) {
+        if (!topCandidate)
+            return false;
+        if (topCandidate.score < 0.7)
+            return false;
+        if (!secondCandidate)
+            return true;
+        return (topCandidate.score - secondCandidate.score) >= 0.2;
+    }
+    inferOverallStatus(results) {
+        if (results.some((result) => result.queryTimeResolutionStatus === 'resolved_narrowly'))
+            return 'resolved_narrowly';
+        if (results.some((result) => result.queryTimeResolutionStatus === 'narrowed_but_still_ambiguous'))
+            return 'narrowed_but_still_ambiguous';
+        if (results.some((result) => result.queryTimeResolutionStatus === 'unresolved_explicit'))
+            return 'unresolved_explicit';
+        if (results.some((result) => result.queryTimeResolutionStatus === 'not_needed'))
+            return 'not_needed';
+        return 'not_applicable';
+    }
+    inferOverallReason(results) {
+        const priority = [
+            'pending_relative_reference_narrowed',
+            'pending_relative_reference_ambiguous_after_narrowing',
+            'pending_reference_still_unresolved',
+            'pending_capture_missing_or_too_weak',
+            'no_matching_pending_reference',
+            'write_time_resolution_already_sufficient'
+        ];
+        for (const reason of priority) {
+            if (results.some((result) => result.queryTimeResolutionReason === reason))
+                return reason;
+        }
+        return 'no_relative_pending_reference_in_query';
+    }
+    inferNoPendingReason(reference, pendingRecords, input) {
+        if (this.hasWriteTimeSufficientEntityResolution(reference, input)) {
+            return 'write_time_resolution_already_sufficient';
+        }
+        if (pendingRecords.length === 0)
+            return 'pending_capture_missing_or_too_weak';
+        return 'no_matching_pending_reference';
+    }
+    hasWriteTimeSufficientEntityResolution(reference, input) {
+        const normalizedReference = normalizePendingReference(reference);
+        return input.semanticCompilation.relativeReferences.some((item) => normalizePendingReference(item) === normalizedReference)
+            && input.baseEntityResolution.disambiguation.some((item) => normalizePendingReference(item.reference) === normalizedReference
+                && item.candidates.length > 0);
+    }
+    computePendingCaptureMetrics(pendingRecords, results) {
+        const expectedButMissing = results.filter((result) => result.queryTimeResolutionReason === 'pending_capture_missing_or_too_weak').length;
+        const notNeededSufficient = results.filter((result) => result.queryTimeResolutionReason === 'write_time_resolution_already_sufficient').length;
+        const matchedResults = results.filter((result) => result.matchedPendingIds.length > 0);
+        return {
+            pending_record_emitted_count: pendingRecords.length,
+            pending_record_expected_but_missing_count: expectedButMissing,
+            pending_candidate_set_nonempty_count: results.filter((result) => result.candidateEntityIds.length > 0).length,
+            pending_candidate_set_empty_count: matchedResults.filter((result) => result.candidateEntityIds.length === 0).length,
+            referential_signal_preserved_count: matchedResults.length + notNeededSufficient,
+            referential_signal_lost_count: expectedButMissing,
+            query_time_not_needed_due_to_write_time_sufficient_count: notNeededSufficient,
+            query_time_not_needed_due_to_missing_pending_capture_count: expectedButMissing
+        };
+    }
+    inferPendingScopedProjectId(records) {
+        const projectIds = new Set(records
+            .map((record) => record.contextNeuronId ? this.getNeuronById(record.contextNeuronId)?.metadata.projectId : undefined)
+            .filter((projectId) => Boolean(projectId)));
+        return projectIds.size === 1 ? Array.from(projectIds)[0] : undefined;
+    }
+    findSameTypePendingFallback(reference, pendingRecords, input) {
+        const normalizedReference = normalizePendingReference(reference);
+        const inferredType = inferReferenceType(normalizedReference, input.query);
+        if (!inferredType || hasDirectionalRelativeSignal(normalizedReference))
+            return [];
+        const sameTypePending = pendingRecords.filter((record) => {
+            if (record.entityType && record.entityType !== inferredType)
+                return false;
+            if (!input.projectId || !record.contextNeuronId)
+                return true;
+            const neuron = this.getNeuronById(record.contextNeuronId);
+            return !neuron?.metadata.projectId || neuron.metadata.projectId === input.projectId;
+        });
+        return sameTypePending;
+    }
+}
+function emptyPendingCaptureMetrics() {
+    return {
+        pending_record_emitted_count: 0,
+        pending_record_expected_but_missing_count: 0,
+        pending_candidate_set_nonempty_count: 0,
+        pending_candidate_set_empty_count: 0,
+        referential_signal_preserved_count: 0,
+        referential_signal_lost_count: 0,
+        query_time_not_needed_due_to_write_time_sufficient_count: 0,
+        query_time_not_needed_due_to_missing_pending_capture_count: 0
+    };
+}
+function normalizePendingReference(reference) {
+    return normalizeLexiconText(reference).toLowerCase();
+}
+function hasDirectionalRelativeSignal(reference) {
+    const relativeSignals = extractRelativeReferences(reference).map((signal) => normalizePendingReference(signal));
+    return relativeSignals.some((signal) => isPreviousReference(signal) || isLatestReference(signal));
+}

package/dist/retrieval/RetrievalPlanner.d.ts

@@ -0,0 +1,42 @@
+import type { QueryIR } from '../types/query-ir.js';
+export type RetrievalIntent = 'fact_lookup' | 'preference_lookup' | 'decision_lookup' | 'trace' | 'constraint_lookup' | 'debug_context' | 'recall';
+export interface RetrievalExecutionPlan {
+    intent: RetrievalIntent;
+    routeOrder: Array<'beliefs' | 'vector' | 'fts' | 'graph'>;
+    topK: {
+        beliefs: number;
+        vector: number;
+        fts: number;
+        graph: number;
+    };
+    weights: {
+        beliefs: number;
+        vector: number;
+        fts: number;
+        graph: number;
+    };
+    aggregation: {
+        strategy: 'belief_first' | 'weighted_fusion' | 'graph_expansion' | 'fts_backfill';
+        suppressSupersededBeliefs: boolean;
+        suppressArchivedNeurons: boolean;
+    };
+    filters: {
+        projectId?: string;
+        filePath?: string;
+        fileType?: string;
+        temporal: QueryIR['temporal'];
+        mustMatch: string[];
+        shouldMatch: string[];
+        semantics: QueryIR['semantics'];
+    };
+    diagnostics: {
+        plannerVersion: 'v0.3';
+        reasons: string[];
+    };
+}
+export declare class RetrievalPlanner {
+    plan(ir: QueryIR): RetrievalExecutionPlan;
+    private inferIntent;
+    private normalizeWeights;
+}
+//# sourceMappingURL=RetrievalPlanner.d.ts.map

package/dist/retrieval/RetrievalPlanner.js

@@ -0,0 +1,209 @@
+export class RetrievalPlanner {
+    plan(ir) {
+        const normalizedQuery = ir.rawQuery.toLowerCase();
+        const intent = this.inferIntent(ir, normalizedQuery);
+        const plan = {
+            intent,
+            routeOrder: ['vector', 'fts', 'graph', 'beliefs'],
+            topK: { beliefs: 6, vector: 24, fts: 10, graph: 8 },
+            weights: { beliefs: 0.2, vector: 0.5, fts: 0.18, graph: 0.12 },
+            aggregation: {
+                strategy: 'weighted_fusion',
+                suppressSupersededBeliefs: true,
+                suppressArchivedNeurons: true
+            },
+            filters: {
+                projectId: ir.spatial.projectId,
+                filePath: ir.spatial.filePath,
+                fileType: ir.spatial.fileType,
+                temporal: ir.temporal,
+                mustMatch: ir.mustMatch,
+                shouldMatch: ir.shouldMatch,
+                semantics: ir.semantics
+            },
+            diagnostics: {
+                plannerVersion: 'v0.3',
+                reasons: []
+            }
+        };
+        switch (intent) {
+            case 'trace':
+                plan.routeOrder = ['graph', 'vector', 'fts', 'beliefs'];
+                plan.topK = { beliefs: 4, vector: 36, fts: 12, graph: 18 };
+                plan.weights = { beliefs: 0.05, vector: 0.35, fts: 0.15, graph: 0.45 };
+                plan.aggregation.strategy = 'graph_expansion';
+                plan.diagnostics.reasons.push('trace intent prioritizes graph-local expansion');
+                break;
+            case 'preference_lookup':
+                plan.routeOrder = ['beliefs', 'vector', 'fts', 'graph'];
+                plan.topK = { beliefs: 10, vector: 14, fts: 8, graph: 6 };
+                plan.weights = { beliefs: 0.62, vector: 0.18, fts: 0.12, graph: 0.08 };
+                plan.aggregation.strategy = 'belief_first';
+                plan.diagnostics.reasons.push('preference lookup prefers canonical beliefs');
+                break;
+            case 'decision_lookup':
+                plan.routeOrder = ['beliefs', 'graph', 'vector', 'fts'];
+                plan.topK = { beliefs: 8, vector: 16, fts: 8, graph: 12 };
+                plan.weights = { beliefs: 0.5, vector: 0.14, fts: 0.08, graph: 0.28 };
+                plan.aggregation.strategy = 'belief_first';
+                plan.diagnostics.reasons.push('decision lookup requires belief plus supporting episodes');
+                break;
+            case 'fact_lookup':
+            case 'constraint_lookup':
+                plan.routeOrder = ['beliefs', 'fts', 'vector', 'graph'];
+                plan.topK = { beliefs: 10, vector: 16, fts: 14, graph: 6 };
+                plan.weights = { beliefs: 0.55, vector: 0.14, fts: 0.23, graph: 0.08 };
+                plan.aggregation.strategy = 'belief_first';
+                plan.diagnostics.reasons.push('fact/constraint lookup uses belief-first with lexical backfill');
+                break;
+            case 'debug_context':
+                plan.routeOrder = ['vector', 'graph', 'fts', 'beliefs'];
+                plan.topK = { beliefs: 5, vector: 30, fts: 10, graph: 14 };
+                plan.weights = { beliefs: 0.08, vector: 0.42, fts: 0.18, graph: 0.32 };
+                plan.diagnostics.reasons.push('debug context prefers vector plus graph evidence');
+                break;
+            case 'recall':
+            default:
+                plan.diagnostics.reasons.push('generic recall uses weighted fusion');
+                break;
+        }
+        if (ir.mustMatch.length > 0) {
+            plan.topK.fts += 6;
+            plan.weights.fts += 0.08;
+            plan.weights.vector -= 0.04;
+            plan.weights.graph -= 0.04;
+            plan.diagnostics.reasons.push('mustMatch raises lexical recall priority');
+        }
+        if (ir.semantics.entityHints.length > 0 && plan.routeOrder.includes('beliefs')) {
+            plan.topK.beliefs += 2;
+            plan.weights.beliefs += 0.05;
+            plan.weights.vector -= 0.03;
+            plan.weights.graph -= 0.02;
+            plan.diagnostics.reasons.push('semantic entity hints boost structured belief recall');
+        }
+        if (ir.semantics.asksForHistory) {
+            plan.topK.graph += 4;
+            plan.weights.graph += 0.06;
+            plan.weights.beliefs += 0.02;
+            plan.weights.vector -= 0.04;
+            plan.weights.fts -= 0.04;
+            plan.diagnostics.reasons.push('history-oriented query increases graph and belief history weight');
+        }
+        if (ir.temporal.start || ir.temporal.end || ir.temporal.relative) {
+            plan.topK.fts += 2;
+            plan.topK.vector += 4;
+            plan.weights.fts += 0.03;
+            plan.weights.vector += 0.02;
+            plan.weights.graph -= 0.03;
+            plan.weights.beliefs -= 0.02;
+            plan.diagnostics.reasons.push('temporal hint boosts time-verifiable channels');
+        }
+        if (ir.spatial.projectId || ir.spatial.filePath || ir.spatial.fileType) {
+            plan.topK.fts += 4;
+            plan.weights.fts += 0.04;
+            plan.weights.vector -= 0.02;
+            plan.weights.graph -= 0.02;
+            plan.diagnostics.reasons.push('project/file hint boosts exact-match recall');
+        }
+        if (ir.semantics.conditionHints.length > 0) {
+            plan.topK.beliefs += 3;
+            plan.weights.beliefs += 0.07;
+            plan.weights.vector -= 0.03;
+            plan.weights.fts -= 0.04;
+            plan.diagnostics.reasons.push('condition hints boost conditional belief retrieval');
+        }
+        if (ir.semantics.environmentHints.length > 0 || ir.semantics.stateHints.length > 0 || ir.semantics.policyHints.length > 0) {
+            plan.topK.beliefs += 2;
+            plan.weights.beliefs += 0.05;
+            plan.weights.vector -= 0.02;
+            plan.weights.fts -= 0.03;
+            plan.diagnostics.reasons.push('runtime semantic hints boost field-level belief recall');
+        }
+        if (ir.semantics.stateHints.length > 0 && ir.semantics.policyHints.length > 0) {
+            plan.topK.graph += 2;
+            plan.weights.graph += 0.03;
+            plan.weights.vector -= 0.01;
+            plan.weights.fts -= 0.02;
+            plan.diagnostics.reasons.push('state+policy hints boost execution-graph retrieval');
+        }
+        if (ir.semantics.guardHints.length > 0
+            || ir.semantics.executorHints.length > 0
+            || ir.semantics.validationHints.length > 0
+            || ir.semantics.mergeHints.length > 0) {
+            plan.topK.beliefs += 3;
+            plan.topK.graph += 2;
+            plan.weights.beliefs += 0.06;
+            plan.weights.graph += 0.03;
+            plan.weights.vector -= 0.04;
+            plan.weights.fts -= 0.05;
+            plan.diagnostics.reasons.push('execution field hints boost field-level plan belief retrieval');
+        }
+        if (/(execute|executor|执行|validate|校验|merge|传播)/i.test(ir.rawQuery)) {
+            plan.topK.beliefs += 2;
+            plan.topK.graph += 2;
+            plan.weights.beliefs += 0.04;
+            plan.weights.graph += 0.03;
+            plan.weights.vector -= 0.03;
+            plan.weights.fts -= 0.04;
+            plan.diagnostics.reasons.push('execution-oriented query boosts plan runtime retrieval');
+        }
+        if (ir.semantics.predicateHint === 'graph') {
+            plan.routeOrder = ['beliefs', 'graph', 'fts', 'vector'];
+            plan.topK.graph += 6;
+            plan.weights.graph += 0.08;
+            plan.weights.vector -= 0.05;
+            plan.weights.fts -= 0.03;
+            plan.diagnostics.reasons.push('graph semantic hint prioritizes graph-shaped fact retrieval');
+        }
+        if (ir.semantics.predicateHint === 'sequence') {
+            plan.routeOrder = ['beliefs', 'fts', 'graph', 'vector'];
+            plan.topK.beliefs += 3;
+            plan.weights.beliefs += 0.08;
+            plan.weights.vector -= 0.04;
+            plan.weights.graph -= 0.04;
+            plan.diagnostics.reasons.push('sequence semantic hint prioritizes workflow sequence beliefs');
+        }
+        if (ir.semantics.predicateHint === 'plan') {
+            plan.routeOrder = ['beliefs', 'graph', 'fts', 'vector'];
+            plan.topK.beliefs += 4;
+            plan.topK.graph += 4;
+            plan.weights.beliefs += 0.1;
+            plan.weights.graph += 0.06;
+            plan.weights.vector -= 0.08;
+            plan.weights.fts -= 0.08;
+            if (ir.semantics.valueHints.length > 0) {
+                plan.topK.beliefs += 2;
+                plan.weights.beliefs += 0.04;
+                plan.weights.vector -= 0.02;
+                plan.weights.fts -= 0.02;
+            }
+            plan.diagnostics.reasons.push('plan semantic hint prioritizes executable plan graph beliefs');
+        }
+        this.normalizeWeights(plan.weights);
+        return plan;
+    }
+    inferIntent(ir, normalizedQuery) {
+        if (ir.intentType === 'trace')
+            return 'trace';
+        if (/(喜欢|讨厌|偏好|prefer|preference|dislike)/i.test(normalizedQuery))
+            return 'preference_lookup';
+        if (/(决定|选择|choose|decision|decide)/i.test(normalizedQuery))
+            return 'decision_lookup';
+        if (/(约束|限制|必须|不能|constraint|rule)/i.test(normalizedQuery))
+            return 'constraint_lookup';
+        if (/(事实|配置|地址|api|endpoint|what is|which)/i.test(normalizedQuery))
+            return 'fact_lookup';
+        if (/(debug|bug|error|exception|报错)/i.test(normalizedQuery))
+            return 'debug_context';
+        return 'recall';
+    }
+    normalizeWeights(weights) {
+        const total = weights.beliefs + weights.vector + weights.fts + weights.graph;
+        if (total <= 0)
+            return;
+        weights.beliefs /= total;
+        weights.vector /= total;
+        weights.fts /= total;
+        weights.graph /= total;
+    }
+}

package/dist/retrieval/TemporalBranchSearch.d.ts

@@ -0,0 +1,38 @@
+import type { TopologyStore } from '../store/TopologyStore.js';
+import type { TemporalAdjacencyStore, TemporalSurfaceSegment } from '../store/TemporalAdjacencyStore.js';
+export interface TemporalTraversalSegment extends TemporalSurfaceSegment {
+    branchIds: string[];
+    taskIds: string[];
+    clusterIds: string[];
+}
+export interface TemporalBranchSearchResult {
+    neuronIds: string[];
+    branchIds: string[];
+    taskIds: string[];
+    clusterIds: string[];
+    temporalTraversal: {
+        bucketType: 'day' | 'week' | 'month';
+        bucketIds: string[];
+        labels: string[];
+        neuronIds: string[];
+        segments: TemporalTraversalSegment[];
+        traversalMode: 'surface' | 'adjacent_fallback' | 'nearest_fallback';
+    };
+    denseJointNeuronIds: string[];
+    reasons: string[];
+}
+export declare class TemporalBranchSearch {
+    private topologyStore;
+    private temporalAdjacencyStore;
+    constructor(topologyStore: TopologyStore, temporalAdjacencyStore: TemporalAdjacencyStore);
+    search(input: {
+        projectId?: string;
+        startTime?: number;
+        endTime?: number;
+        terms: string[];
+        temporalBucketIds?: string[];
+        entityNeuronIds?: string[];
+    }): TemporalBranchSearchResult;
+    private formatTemporalWindow;
+}
+//# sourceMappingURL=TemporalBranchSearch.d.ts.map

package/dist/retrieval/TemporalBranchSearch.js

@@ -0,0 +1,109 @@
+export class TemporalBranchSearch {
+    topologyStore;
+    temporalAdjacencyStore;
+    constructor(topologyStore, temporalAdjacencyStore) {
+        this.topologyStore = topologyStore;
+        this.temporalAdjacencyStore = temporalAdjacencyStore;
+    }
+    search(input) {
+        const candidates = this.topologyStore.collectCandidateNeuronIds({
+            projectId: input.projectId,
+            startTime: input.startTime,
+            endTime: input.endTime,
+            terms: input.terms,
+            limit: 120
+        });
+        const branches = this.topologyStore.collectBranchNavigation({
+            projectId: input.projectId,
+            terms: input.terms,
+            limit: 80,
+            siblingDepth: 1
+        });
+        const aggregatedBranchIds = new Set(branches.branchIds);
+        const aggregatedTaskIds = new Set(branches.taskIds);
+        const aggregatedClusterIds = new Set(branches.clusterIds);
+        const aggregatedNeuronIds = new Set([...candidates, ...branches.neuronIds]);
+        const temporalSurface = this.temporalAdjacencyStore.collectContinuousSurface({
+            bucketIds: input.temporalBucketIds || [],
+            startTime: input.startTime,
+            endTime: input.endTime,
+            preferredBucketType: 'day',
+            hopLimit: input.startTime || input.endTime ? 3 : 2,
+            limit: 72
+        });
+        const fallbackLabels = temporalSurface.labels.length > 0
+            ? temporalSurface.labels
+            : input.startTime || input.endTime
+                ? [this.formatTemporalWindow(input.startTime, input.endTime)]
+                : [];
+        const fallbackBucketIds = temporalSurface.bucketIds.length > 0
+            ? temporalSurface.bucketIds
+            : fallbackLabels.map((_, index) => `derived:${index}:${input.startTime || 0}:${input.endTime || 0}`);
+        const fallbackTemporalNeuronIds = temporalSurface.neuronIds.length > 0
+            ? temporalSurface.neuronIds
+            : branches.neuronIds.slice(0, 24);
+        const traversalMode = temporalSurface.segments.some((segment) => segment.source === 'window' || segment.source === 'seed')
+            ? 'surface'
+            : temporalSurface.segments.some((segment) => segment.source === 'adjacent')
+                ? 'adjacent_fallback'
+                : 'nearest_fallback';
+        const linkedSegments = temporalSurface.segments.map((segment) => {
+            const navigation = this.topologyStore.collectNavigationFromNeuronIds({
+                neuronIds: segment.neuronIds,
+                projectId: input.projectId,
+                limit: 16,
+                siblingDepth: 0
+            });
+            for (const branchId of navigation.branchIds)
+                aggregatedBranchIds.add(branchId);
+            for (const taskId of navigation.taskIds)
+                aggregatedTaskIds.add(taskId);
+            for (const clusterId of navigation.clusterIds)
+                aggregatedClusterIds.add(clusterId);
+            for (const neuronId of navigation.neuronIds)
+                aggregatedNeuronIds.add(neuronId);
+            return {
+                ...segment,
+                branchIds: navigation.branchIds,
+                taskIds: navigation.taskIds,
+                clusterIds: navigation.clusterIds
+            };
+        });
+        const denseJointNeuronIds = Array.from(new Set([
+            ...(input.entityNeuronIds || []).slice(0, 40),
+            ...fallbackTemporalNeuronIds.slice(0, 40),
+            ...branches.neuronIds.slice(0, 40)
+        ])).slice(0, 120);
+        return {
+            neuronIds: Array.from(new Set([
+                ...aggregatedNeuronIds,
+                ...fallbackTemporalNeuronIds,
+                ...denseJointNeuronIds
+            ])).slice(0, 120),
+            branchIds: Array.from(aggregatedBranchIds).slice(0, 80),
+            taskIds: Array.from(aggregatedTaskIds).slice(0, 80),
+            clusterIds: Array.from(aggregatedClusterIds).slice(0, 80),
+            temporalTraversal: {
+                bucketType: temporalSurface.bucketType,
+                bucketIds: fallbackBucketIds,
+                labels: fallbackLabels,
+                neuronIds: fallbackTemporalNeuronIds,
+                segments: linkedSegments,
+                traversalMode
+            },
+            denseJointNeuronIds,
+            reasons: [
+                input.projectId ? 'project branch root constrained traversal' : 'global branch traversal',
+                input.startTime || input.endTime ? 'continuous temporal surface navigation across adjacent windows' : 'term-only branch traversal',
+                input.entityNeuronIds?.length ? 'dense time-branch-entity joint search' : 'branch-local dense search'
+            ]
+        };
+    }
+    formatTemporalWindow(startTime, endTime) {
+        if (!startTime && !endTime)
+            return 'temporal window';
+        const startLabel = startTime ? new Date(startTime).toISOString().slice(0, 10) : 'open';
+        const endLabel = endTime ? new Date(endTime).toISOString().slice(0, 10) : 'open';
+        return `${startLabel}..${endLabel}`;
+    }
+}