gitnexus 1.6.3-rc.6 → 1.6.3-rc.7

package/dist/_shared/index.d.ts

@@ -6,7 +6,7 @@ export { getLanguageFromFilename, getSyntaxLanguageFromFilename } from './langua
 export type { MroStrategy } from './mro-strategy.js';
 export type { PipelinePhase, PipelineProgress } from './pipeline.js';
 export type { SymbolDefinition } from './scope-resolution/symbol-definition.js';
-export type { ScopeId, DefId, ScopeKind, Range, Capture, CaptureMatch, BindingRef, ImportEdge, TypeRef, Scope, ResolutionEvidence, Resolution, Reference, ReferenceIndex, LookupParams, RegistryContributor, ParsedImport, ParsedTypeBinding, WorkspaceIndex, ScopeTree, Callsite, } from './scope-resolution/types.js';
+export type { ScopeId, DefId, ScopeKind, Range, Capture, CaptureMatch, BindingRef, ImportEdge, TypeRef, Scope, ResolutionEvidence, Resolution, Reference, ReferenceIndex, LookupParams, RegistryContributor, ParsedImport, ParsedTypeBinding, WorkspaceIndex, Callsite, } from './scope-resolution/types.js';
 export { EvidenceWeights, typeBindingWeightAtDepth } from './scope-resolution/evidence-weights.js';
 export { ORIGIN_PRIORITY } from './scope-resolution/origin-priority.js';
 export type { OriginForTieBreak } from './scope-resolution/origin-priority.js';
@@ -22,6 +22,12 @@ export { resolveTypeRef } from './scope-resolution/resolve-type-ref.js';
 export type { ResolveTypeRefContext, ScopeLookup } from './scope-resolution/resolve-type-ref.js';
 export { buildMethodDispatchIndex } from './scope-resolution/method-dispatch-index.js';
 export type { MethodDispatchIndex, MethodDispatchInput, } from './scope-resolution/method-dispatch-index.js';
+export { makeScopeId, clearScopeIdInternPool } from './scope-resolution/scope-id.js';
+export type { ScopeIdInput } from './scope-resolution/scope-id.js';
+export { buildScopeTree, ScopeTreeInvariantError } from './scope-resolution/scope-tree.js';
+export type { ScopeTree } from './scope-resolution/scope-tree.js';
+export { buildPositionIndex } from './scope-resolution/position-index.js';
+export type { PositionIndex } from './scope-resolution/position-index.js';
 export { diffResolutions } from './scope-resolution/shadow/diff.js';
 export type { ShadowAgreement, ShadowCallsite, ShadowDiff, } from './scope-resolution/shadow/diff.js';
 export { aggregateDiffs } from './scope-resolution/shadow/aggregate.js';

package/dist/_shared/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,SAAS,EACT,cAAc,EACd,gBAAgB,EAChB,SAAS,EACT,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,WAAW,EACX,cAAc,EACd,SAAS,EACT,oBAAoB,GACrB,MAAM,4BAA4B,CAAC;AACpC,YAAY,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AAGzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,uBAAuB,EAAE,6BAA6B,EAAE,MAAM,yBAAyB,CAAC;AACjG,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGrD,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAIrE,YAAY,EAAE,gBAAgB,EAAE,MAAM,yCAAyC,CAAC;AAChF,YAAY,EACV,OAAO,EACP,KAAK,EACL,SAAS,EACT,KAAK,EACL,OAAO,EACP,YAAY,EACZ,UAAU,EACV,UAAU,EACV,OAAO,EACP,KAAK,EACL,kBAAkB,EAClB,UAAU,EACV,SAAS,EACT,cAAc,EACd,YAAY,EACZ,mBAAmB,EACnB,YAAY,EACZ,iBAAiB,EACjB,cAAc,EACd,SAAS,EACT,QAAQ,GACT,MAAM,6BAA6B,CAAC;AAGrC,OAAO,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,wCAAwC,CAAC;AACnG,OAAO,EAAE,eAAe,EAAE,MAAM,uCAAuC,CAAC;AACxE,YAAY,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAG/E,OAAO,EACL,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,+CAA+C,CAAC;AACvD,YAAY,EAAE,sBAAsB,EAAE,MAAM,+CAA+C,CAAC;AAG5F,OAAO,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAChE,YAAY,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAChE,OAAO,EAAE,qBAAqB,EAAE,MAAM,0CAA0C,CAAC;AACjF,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AACnG,OAAO,EAAE,uBAAuB,EAAE,MAAM,4CAA4C,CAAC;AACrF,YAAY,EAAE,kBAAkB,EAAE,MAAM,4CAA4C,CAAC;AAGrF,OAAO,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC;AACxE,YAAY,EAAE,qBAAqB,EAAE,WAAW,EAAE,MAAM,wCAAwC,CAAC;AAGjG,OAAO,EAAE,wBAAwB,EAAE,MAAM,6CAA6C,CAAC;AACvF,YAAY,EACV,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,6CAA6C,CAAC;AAGrD,OAAO,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AACpE,YAAY,EACV,eAAe,EACf,cAAc,EACd,UAAU,GACX,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC;AACxE,YAAY,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,wCAAwC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,YAAY,EACV,SAAS,EACT,cAAc,EACd,gBAAgB,EAChB,SAAS,EACT,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,WAAW,EACX,cAAc,EACd,SAAS,EACT,oBAAoB,GACrB,MAAM,4BAA4B,CAAC;AACpC,YAAY,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,4BAA4B,CAAC;AAGzE,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,uBAAuB,EAAE,6BAA6B,EAAE,MAAM,yBAAyB,CAAC;AACjG,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAGrD,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAIrE,YAAY,EAAE,gBAAgB,EAAE,MAAM,yCAAyC,CAAC;AAChF,YAAY,EACV,OAAO,EACP,KAAK,EACL,SAAS,EACT,KAAK,EACL,OAAO,EACP,YAAY,EACZ,UAAU,EACV,UAAU,EACV,OAAO,EACP,KAAK,EACL,kBAAkB,EAClB,UAAU,EACV,SAAS,EACT,cAAc,EACd,YAAY,EACZ,mBAAmB,EACnB,YAAY,EACZ,iBAAiB,EACjB,cAAc,EACd,QAAQ,GACT,MAAM,6BAA6B,CAAC;AAGrC,OAAO,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,wCAAwC,CAAC;AACnG,OAAO,EAAE,eAAe,EAAE,MAAM,uCAAuC,CAAC;AACxE,YAAY,EAAE,iBAAiB,EAAE,MAAM,uCAAuC,CAAC;AAG/E,OAAO,EACL,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,+CAA+C,CAAC;AACvD,YAAY,EAAE,sBAAsB,EAAE,MAAM,+CAA+C,CAAC;AAG5F,OAAO,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAChE,YAAY,EAAE,QAAQ,EAAE,MAAM,iCAAiC,CAAC;AAChE,OAAO,EAAE,qBAAqB,EAAE,MAAM,0CAA0C,CAAC;AACjF,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,0CAA0C,CAAC;AACnG,OAAO,EAAE,uBAAuB,EAAE,MAAM,4CAA4C,CAAC;AACrF,YAAY,EAAE,kBAAkB,EAAE,MAAM,4CAA4C,CAAC;AAGrF,OAAO,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC;AACxE,YAAY,EAAE,qBAAqB,EAAE,WAAW,EAAE,MAAM,wCAAwC,CAAC;AAGjG,OAAO,EAAE,wBAAwB,EAAE,MAAM,6CAA6C,CAAC;AACvF,YAAY,EACV,mBAAmB,EACnB,mBAAmB,GACpB,MAAM,6CAA6C,CAAC;AAGrD,OAAO,EAAE,WAAW,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AACrF,YAAY,EAAE,YAAY,EAAE,MAAM,gCAAgC,CAAC;AACnE,OAAO,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,kCAAkC,CAAC;AAC3F,YAAY,EAAE,SAAS,EAAE,MAAM,kCAAkC,CAAC;AAClE,OAAO,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAC1E,YAAY,EAAE,aAAa,EAAE,MAAM,sCAAsC,CAAC;AAG1E,OAAO,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AACpE,YAAY,EACV,eAAe,EACf,cAAc,EACd,UAAU,GACX,MAAM,mCAAmC,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC;AACxE,YAAY,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,wCAAwC,CAAC"}

package/dist/_shared/index.js

@@ -16,6 +16,10 @@ export { buildQualifiedNameIndex } from './scope-resolution/qualified-name-index
 export { resolveTypeRef } from './scope-resolution/resolve-type-ref.js';
 // Method-dispatch materialized view over HeritageMap (RFC §3.1; Ring 2 SHARED #914)
 export { buildMethodDispatchIndex } from './scope-resolution/method-dispatch-index.js';
+// Scope tree spine + position lookup (RFC §2.2 + §3.1; Ring 2 SHARED #912)
+export { makeScopeId, clearScopeIdInternPool } from './scope-resolution/scope-id.js';
+export { buildScopeTree, ScopeTreeInvariantError } from './scope-resolution/scope-tree.js';
+export { buildPositionIndex } from './scope-resolution/position-index.js';
 // Shadow-mode diff + aggregation (RFC §6.3; Ring 2 SHARED #918)
 export { diffResolutions } from './scope-resolution/shadow/diff.js';
 export { aggregateDiffs } from './scope-resolution/shadow/aggregate.js';

package/dist/_shared/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AASA,mBAAmB;AACnB,OAAO,EACL,WAAW,EACX,cAAc,EACd,SAAS,EACT,oBAAoB,GACrB,MAAM,4BAA4B,CAAC;AAGpC,mBAAmB;AACnB,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,uBAAuB,EAAE,6BAA6B,EAAE,MAAM,yBAAyB,CAAC;AAiCjG,8DAA8D;AAC9D,OAAO,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,wCAAwC,CAAC;AACnG,OAAO,EAAE,eAAe,EAAE,MAAM,uCAAuC,CAAC;AAGxE,yDAAyD;AACzD,OAAO,EACL,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,+CAA+C,CAAC;AAGvD,sEAAsE;AACtE,OAAO,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAEhE,OAAO,EAAE,qBAAqB,EAAE,MAAM,0CAA0C,CAAC;AAEjF,OAAO,EAAE,uBAAuB,EAAE,MAAM,4CAA4C,CAAC;AAGrF,gEAAgE;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC;AAGxE,oFAAoF;AACpF,OAAO,EAAE,wBAAwB,EAAE,MAAM,6CAA6C,CAAC;AAMvF,gEAAgE;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAMpE,OAAO,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AASA,mBAAmB;AACnB,OAAO,EACL,WAAW,EACX,cAAc,EACd,SAAS,EACT,oBAAoB,GACrB,MAAM,4BAA4B,CAAC;AAGpC,mBAAmB;AACnB,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AACpD,OAAO,EAAE,uBAAuB,EAAE,6BAA6B,EAAE,MAAM,yBAAyB,CAAC;AAgCjG,8DAA8D;AAC9D,OAAO,EAAE,eAAe,EAAE,wBAAwB,EAAE,MAAM,wCAAwC,CAAC;AACnG,OAAO,EAAE,eAAe,EAAE,MAAM,uCAAuC,CAAC;AAGxE,yDAAyD;AACzD,OAAO,EACL,uBAAuB,EACvB,oBAAoB,GACrB,MAAM,+CAA+C,CAAC;AAGvD,sEAAsE;AACtE,OAAO,EAAE,aAAa,EAAE,MAAM,iCAAiC,CAAC;AAEhE,OAAO,EAAE,qBAAqB,EAAE,MAAM,0CAA0C,CAAC;AAEjF,OAAO,EAAE,uBAAuB,EAAE,MAAM,4CAA4C,CAAC;AAGrF,gEAAgE;AAChE,OAAO,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC;AAGxE,oFAAoF;AACpF,OAAO,EAAE,wBAAwB,EAAE,MAAM,6CAA6C,CAAC;AAMvF,2EAA2E;AAC3E,OAAO,EAAE,WAAW,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AAErF,OAAO,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,kCAAkC,CAAC;AAE3F,OAAO,EAAE,kBAAkB,EAAE,MAAM,sCAAsC,CAAC;AAG1E,gEAAgE;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,mCAAmC,CAAC;AAMpE,OAAO,EAAE,cAAc,EAAE,MAAM,wCAAwC,CAAC"}

package/dist/_shared/scope-resolution/position-index.d.ts

@@ -0,0 +1,50 @@
+/**
+ * `PositionIndex` — O(log N_file) scope-at-position lookup
+ * (RFC §3.1; Ring 2 SHARED #912).
+ *
+ * Per-file sorted array of `(range, scopeId)` entries, sorted by start
+ * position ASC (`startLine`, then `startCol`). `atPosition(filePath, line,
+ * col)` binary-searches for the last entry whose start ≤ (line, col), then
+ * scans backward through the sorted prefix and returns the first entry
+ * whose range contains the query position.
+ *
+ * **Why this works.** `ScopeTree`'s invariants (parent strictly contains
+ * child; siblings don't overlap) guarantee that the scopes containing a
+ * given point form an **ancestor chain**. When scanning backward through
+ * entries sorted by start position ASC, the first scope we find that
+ * contains the query is the innermost one — any deeper-starting scope
+ * that also contained the query would appear *later* in the sorted array,
+ * but we're only scanning entries with start ≤ query, so anything later
+ * necessarily starts after the query and can't contain it.
+ *
+ * Expected complexity: `O(log N_file + D)` where `D` is the lexical depth
+ * at the query position (typically ≤ 10). Worst-case degrades to `O(N_file)`
+ * only under pathological inputs (many scopes starting at the same line).
+ *
+ * **Line/column conventions.** Matches `Range` in `types.ts`: lines are
+ * 1-based, columns are 0-based. Ranges are **inclusive on both ends** —
+ * a scope whose `endLine:endCol` equals the query position still contains
+ * it. That matches how tree-sitter captures bodies (closing brace
+ * included) and how closed PR #902's `enclosingFunctions` behaved.
+ */
+import type { Scope, ScopeId } from './types.js';
+export interface PositionIndex {
+    /** Total scope entries indexed across all files. */
+    readonly size: number;
+    /**
+     * Innermost scope containing `(line, col)` in `filePath`, or `undefined`
+     * when nothing contains it (position before file start, after file end,
+     * or filePath not indexed).
+     */
+    atPosition(filePath: string, line: number, col: number): ScopeId | undefined;
+}
+/**
+ * Build a `PositionIndex` from a flat list of `Scope` records.
+ *
+ * Duplicate `id`s are tolerated and deduplicated — the caller's
+ * `ScopeTree.buildScopeTree` is the authoritative validator of scope
+ * identity, and the position index does not need to re-check that
+ * invariant.
+ */
+export declare function buildPositionIndex(scopes: readonly Scope[]): PositionIndex;
+//# sourceMappingURL=position-index.d.ts.map

package/dist/_shared/scope-resolution/position-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"position-index.d.ts","sourceRoot":"","sources":["../../src/scope-resolution/position-index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AAEH,OAAO,KAAK,EAAS,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAExD,MAAM,WAAW,aAAa;IAC5B,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;CAC9E;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,GAAG,aAAa,CAqB1E"}

package/dist/_shared/scope-resolution/position-index.js

@@ -0,0 +1,134 @@
+/**
+ * `PositionIndex` — O(log N_file) scope-at-position lookup
+ * (RFC §3.1; Ring 2 SHARED #912).
+ *
+ * Per-file sorted array of `(range, scopeId)` entries, sorted by start
+ * position ASC (`startLine`, then `startCol`). `atPosition(filePath, line,
+ * col)` binary-searches for the last entry whose start ≤ (line, col), then
+ * scans backward through the sorted prefix and returns the first entry
+ * whose range contains the query position.
+ *
+ * **Why this works.** `ScopeTree`'s invariants (parent strictly contains
+ * child; siblings don't overlap) guarantee that the scopes containing a
+ * given point form an **ancestor chain**. When scanning backward through
+ * entries sorted by start position ASC, the first scope we find that
+ * contains the query is the innermost one — any deeper-starting scope
+ * that also contained the query would appear *later* in the sorted array,
+ * but we're only scanning entries with start ≤ query, so anything later
+ * necessarily starts after the query and can't contain it.
+ *
+ * Expected complexity: `O(log N_file + D)` where `D` is the lexical depth
+ * at the query position (typically ≤ 10). Worst-case degrades to `O(N_file)`
+ * only under pathological inputs (many scopes starting at the same line).
+ *
+ * **Line/column conventions.** Matches `Range` in `types.ts`: lines are
+ * 1-based, columns are 0-based. Ranges are **inclusive on both ends** —
+ * a scope whose `endLine:endCol` equals the query position still contains
+ * it. That matches how tree-sitter captures bodies (closing brace
+ * included) and how closed PR #902's `enclosingFunctions` behaved.
+ */
+/**
+ * Build a `PositionIndex` from a flat list of `Scope` records.
+ *
+ * Duplicate `id`s are tolerated and deduplicated — the caller's
+ * `ScopeTree.buildScopeTree` is the authoritative validator of scope
+ * identity, and the position index does not need to re-check that
+ * invariant.
+ */
+export function buildPositionIndex(scopes) {
+    const entriesByFile = new Map();
+    const seen = new Set();
+    for (const scope of scopes) {
+        if (seen.has(scope.id))
+            continue;
+        seen.add(scope.id);
+        let bucket = entriesByFile.get(scope.filePath);
+        if (bucket === undefined) {
+            bucket = [];
+            entriesByFile.set(scope.filePath, bucket);
+        }
+        bucket.push({ id: scope.id, range: scope.range });
+    }
+    for (const bucket of entriesByFile.values()) {
+        bucket.sort(compareEntry);
+    }
+    return freezeIndex(entriesByFile, seen.size);
+}
+/**
+ * Sort by start position ASC, breaking ties by end position DESC so that
+ * larger (outer) scopes appear before their smaller (inner) co-starting
+ * siblings in the array. Makes the backward-scan contract crisp: the
+ * first containing hit from the end of the scanned prefix is the
+ * innermost scope.
+ */
+function compareEntry(a, b) {
+    if (a.range.startLine !== b.range.startLine)
+        return a.range.startLine - b.range.startLine;
+    if (a.range.startCol !== b.range.startCol)
+        return a.range.startCol - b.range.startCol;
+    if (a.range.endLine !== b.range.endLine)
+        return b.range.endLine - a.range.endLine;
+    return b.range.endCol - a.range.endCol;
+}
+/** Whether `(line, col)` is at or after `range`'s start. */
+function startIsAtOrBefore(range, line, col) {
+    if (range.startLine < line)
+        return true;
+    if (range.startLine > line)
+        return false;
+    return range.startCol <= col;
+}
+/** Whether `(line, col)` is at or before `range`'s end (inclusive). */
+function endIsAtOrAfter(range, line, col) {
+    if (range.endLine > line)
+        return true;
+    if (range.endLine < line)
+        return false;
+    return range.endCol >= col;
+}
+/**
+ * Return the largest index `i` in `arr` where `arr[i].range` starts at or
+ * before `(line, col)`. Returns `-1` if no entry starts ≤ the query.
+ *
+ * Classic "upper bound - 1" binary search: find the first entry that
+ * starts *after* the query, then step back one.
+ */
+function findLastStartLteIndex(arr, line, col) {
+    let lo = 0;
+    let hi = arr.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >>> 1;
+        if (startIsAtOrBefore(arr[mid].range, line, col)) {
+            lo = mid + 1;
+        }
+        else {
+            hi = mid;
+        }
+    }
+    return lo - 1;
+}
+function freezeIndex(entriesByFile, size) {
+    return {
+        get size() {
+            return size;
+        },
+        atPosition(filePath, line, col) {
+            const bucket = entriesByFile.get(filePath);
+            if (bucket === undefined || bucket.length === 0)
+                return undefined;
+            const endIdx = findLastStartLteIndex(bucket, line, col);
+            if (endIdx < 0)
+                return undefined;
+            // Scan backward; first containing hit is innermost (see file header).
+            for (let i = endIdx; i >= 0; i--) {
+                const entry = bucket[i];
+                if (endIsAtOrAfter(entry.range, line, col)) {
+                    // `startIsAtOrBefore` is guaranteed true by the binary search.
+                    return entry.id;
+                }
+            }
+            return undefined;
+        },
+    };
+}
+//# sourceMappingURL=position-index.js.map

package/dist/_shared/scope-resolution/position-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"position-index.js","sourceRoot":"","sources":["../../src/scope-resolution/position-index.ts"],"names":[],"mappings":"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"}

package/dist/_shared/scope-resolution/scope-id.d.ts

@@ -0,0 +1,43 @@
+/**
+ * `ScopeId` canonical constructor + string intern pool
+ * (RFC §2.2; Ring 2 SHARED #912).
+ *
+ * `ScopeId` is a deterministic string derived from the scope's file path,
+ * byte range, and kind:
+ *
+ *   scope:{filePath}#{startLine}:{startCol}-{endLine}:{endCol}:{kind}
+ *
+ * Two scopes produced by reparsing the same file at the same positions are
+ * `===`-equal as strings. Beyond the canonical shape, `makeScopeId` also
+ * **interns** the string through a process-local pool, so repeated calls
+ * with structurally identical inputs return the same string reference —
+ * making `Map<ScopeId, ...>` lookups and cache keys identity-fast.
+ *
+ * The intern pool is unbounded. The number of distinct `ScopeId`s across a
+ * single indexing run is O(total scopes in workspace), which is bounded by
+ * source-text size and already in memory; interning adds no asymptotic
+ * pressure. `clearScopeIdInternPool` is exported for test isolation.
+ */
+import type { Range } from './types.js';
+import type { ScopeId, ScopeKind } from './types.js';
+/** Inputs required to construct a canonical `ScopeId`. */
+export interface ScopeIdInput {
+    readonly filePath: string;
+    readonly range: Range;
+    readonly kind: ScopeKind;
+}
+/**
+ * Build a canonical `ScopeId` from its structural parts and intern it.
+ *
+ * Pure + referentially transparent: given the same input shape, always
+ * returns the same string reference for the lifetime of the pool.
+ */
+export declare function makeScopeId(input: ScopeIdInput): ScopeId;
+/**
+ * Drop the intern pool. Intended for test setup/teardown — production code
+ * should not need this, since the pool's memory usage is bounded by the
+ * number of live scopes and cleaning it mid-run would break identity
+ * equality for existing scope ids.
+ */
+export declare function clearScopeIdInternPool(): void;
+//# sourceMappingURL=scope-id.d.ts.map

package/dist/_shared/scope-resolution/scope-id.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-id.d.ts","sourceRoot":"","sources":["../../src/scope-resolution/scope-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACxC,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAErD,0DAA0D;AAC1D,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;CAC1B;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,YAAY,GAAG,OAAO,CAMxD;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C"}

package/dist/_shared/scope-resolution/scope-id.js

@@ -0,0 +1,46 @@
+/**
+ * `ScopeId` canonical constructor + string intern pool
+ * (RFC §2.2; Ring 2 SHARED #912).
+ *
+ * `ScopeId` is a deterministic string derived from the scope's file path,
+ * byte range, and kind:
+ *
+ *   scope:{filePath}#{startLine}:{startCol}-{endLine}:{endCol}:{kind}
+ *
+ * Two scopes produced by reparsing the same file at the same positions are
+ * `===`-equal as strings. Beyond the canonical shape, `makeScopeId` also
+ * **interns** the string through a process-local pool, so repeated calls
+ * with structurally identical inputs return the same string reference —
+ * making `Map<ScopeId, ...>` lookups and cache keys identity-fast.
+ *
+ * The intern pool is unbounded. The number of distinct `ScopeId`s across a
+ * single indexing run is O(total scopes in workspace), which is bounded by
+ * source-text size and already in memory; interning adds no asymptotic
+ * pressure. `clearScopeIdInternPool` is exported for test isolation.
+ */
+/**
+ * Build a canonical `ScopeId` from its structural parts and intern it.
+ *
+ * Pure + referentially transparent: given the same input shape, always
+ * returns the same string reference for the lifetime of the pool.
+ */
+export function makeScopeId(input) {
+    const raw = `scope:${input.filePath}#${input.range.startLine}:${input.range.startCol}-${input.range.endLine}:${input.range.endCol}:${input.kind}`;
+    const existing = INTERN_POOL.get(raw);
+    if (existing !== undefined)
+        return existing;
+    INTERN_POOL.set(raw, raw);
+    return raw;
+}
+/**
+ * Drop the intern pool. Intended for test setup/teardown — production code
+ * should not need this, since the pool's memory usage is bounded by the
+ * number of live scopes and cleaning it mid-run would break identity
+ * equality for existing scope ids.
+ */
+export function clearScopeIdInternPool() {
+    INTERN_POOL.clear();
+}
+/** Internal: shared intern pool (process-local). */
+const INTERN_POOL = new Map();
+//# sourceMappingURL=scope-id.js.map

package/dist/_shared/scope-resolution/scope-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-id.js","sourceRoot":"","sources":["../../src/scope-resolution/scope-id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAYH;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,KAAmB;IAC7C,MAAM,GAAG,GAAG,SAAS,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,KAAK,CAAC,SAAS,IAAI,KAAK,CAAC,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC;IAClJ,MAAM,QAAQ,GAAG,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACtC,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,QAAQ,CAAC;IAC5C,WAAW,CAAC,GAAG,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAC1B,OAAO,GAAG,CAAC;AACb,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB;IACpC,WAAW,CAAC,KAAK,EAAE,CAAC;AACtB,CAAC;AAED,oDAAoD;AACpD,MAAM,WAAW,GAAG,IAAI,GAAG,EAAkB,CAAC"}

package/dist/_shared/scope-resolution/scope-tree.d.ts

@@ -0,0 +1,61 @@
+/**
+ * `ScopeTree` — the lexical-scope spine of the `SemanticModel`
+ * (RFC §2.2 + §3.1; Ring 2 SHARED #912).
+ *
+ * Generalizes the `enclosingFunctions` pattern from closed PR #902 to
+ * arbitrary `ScopeKind`s. Owns the (parent ↔ children) relationship
+ * derived from each `Scope.parent` pointer, and validates the structural
+ * invariants a well-formed scope tree must satisfy.
+ *
+ * Invariants enforced at build time (throw on violation):
+ *
+ *   - Every non-`Module` scope has a non-null parent.
+ *   - Every parent pointer references a scope that was also supplied to
+ *     `buildScopeTree`.
+ *   - Parent range **strictly contains** child range.
+ *   - Sibling ranges under the same parent do not overlap.
+ *   - Parent and child live in the same `filePath`. (Cross-file parent
+ *     pointers would be a category error — a `File` scope is not the
+ *     parent of another file's scopes; imports do that job.)
+ *
+ * Satisfies the `ScopeLookup` contract from #916 (`resolve-type-ref`), so
+ * `resolveTypeRef` can take a `ScopeTree` directly without adapters.
+ *
+ * Immutable surface: `byId` is a `ReadonlyMap`; children arrays are
+ * `Object.freeze`d; miss lookups return a shared frozen empty array.
+ */
+import type { Scope, ScopeId } from './types.js';
+import type { ScopeLookup } from './resolve-type-ref.js';
+export interface ScopeTree extends ScopeLookup {
+    readonly size: number;
+    readonly byId: ReadonlyMap<ScopeId, Scope>;
+    getScope(id: ScopeId): Scope | undefined;
+    getParent(id: ScopeId): Scope | undefined;
+    /** Child `ScopeId`s of `id`, in input order. Frozen empty array on miss. */
+    getChildren(id: ScopeId): readonly ScopeId[];
+    /**
+     * Ancestor chain from the immediate parent up to (and including) the
+     * root module scope. Excludes the starting scope itself. Frozen empty
+     * array on miss / for a root scope.
+     */
+    getAncestors(id: ScopeId): readonly ScopeId[];
+    has(id: ScopeId): boolean;
+}
+/**
+ * Thrown by `buildScopeTree` when the input violates a structural
+ * invariant. Carries the offending ids + the invariant name so failed
+ * extraction pipelines can report actionable diagnostics.
+ */
+export declare class ScopeTreeInvariantError extends Error {
+    readonly invariant: 'non-module-requires-parent' | 'parent-not-found' | 'parent-must-contain-child' | 'sibling-ranges-overlap' | 'parent-must-share-filepath' | 'duplicate-scope-id';
+    constructor(invariant: 'non-module-requires-parent' | 'parent-not-found' | 'parent-must-contain-child' | 'sibling-ranges-overlap' | 'parent-must-share-filepath' | 'duplicate-scope-id', message: string);
+}
+/**
+ * Build an immutable `ScopeTree` from a flat list of `Scope` records.
+ *
+ * Throws `ScopeTreeInvariantError` on the first invariant violation; a
+ * malformed tree is a bug in the extraction pipeline, not a data case for
+ * consumers to handle, so fail-fast is the correct posture.
+ */
+export declare function buildScopeTree(scopes: readonly Scope[]): ScopeTree;
+//# sourceMappingURL=scope-tree.d.ts.map

package/dist/_shared/scope-resolution/scope-tree.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-tree.d.ts","sourceRoot":"","sources":["../../src/scope-resolution/scope-tree.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,OAAO,EAAS,MAAM,YAAY,CAAC;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAIzD,MAAM,WAAW,SAAU,SAAQ,WAAW;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;IAE3C,QAAQ,CAAC,EAAE,EAAE,OAAO,GAAG,KAAK,GAAG,SAAS,CAAC;IACzC,SAAS,CAAC,EAAE,EAAE,OAAO,GAAG,KAAK,GAAG,SAAS,CAAC;IAC1C,4EAA4E;IAC5E,WAAW,CAAC,EAAE,EAAE,OAAO,GAAG,SAAS,OAAO,EAAE,CAAC;IAC7C;;;;OAIG;IACH,YAAY,CAAC,EAAE,EAAE,OAAO,GAAG,SAAS,OAAO,EAAE,CAAC;IAC9C,GAAG,CAAC,EAAE,EAAE,OAAO,GAAG,OAAO,CAAC;CAC3B;AAID;;;;GAIG;AACH,qBAAa,uBAAwB,SAAQ,KAAK;IAE9C,QAAQ,CAAC,SAAS,EACd,4BAA4B,GAC5B,kBAAkB,GAClB,2BAA2B,GAC3B,wBAAwB,GACxB,4BAA4B,GAC5B,oBAAoB;gBANf,SAAS,EACd,4BAA4B,GAC5B,kBAAkB,GAClB,2BAA2B,GAC3B,wBAAwB,GACxB,4BAA4B,GAC5B,oBAAoB,EACxB,OAAO,EAAE,MAAM;CAKlB;AAID;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,GAAG,SAAS,CAiFlE"}

package/dist/_shared/scope-resolution/scope-tree.js

@@ -0,0 +1,185 @@
+/**
+ * `ScopeTree` — the lexical-scope spine of the `SemanticModel`
+ * (RFC §2.2 + §3.1; Ring 2 SHARED #912).
+ *
+ * Generalizes the `enclosingFunctions` pattern from closed PR #902 to
+ * arbitrary `ScopeKind`s. Owns the (parent ↔ children) relationship
+ * derived from each `Scope.parent` pointer, and validates the structural
+ * invariants a well-formed scope tree must satisfy.
+ *
+ * Invariants enforced at build time (throw on violation):
+ *
+ *   - Every non-`Module` scope has a non-null parent.
+ *   - Every parent pointer references a scope that was also supplied to
+ *     `buildScopeTree`.
+ *   - Parent range **strictly contains** child range.
+ *   - Sibling ranges under the same parent do not overlap.
+ *   - Parent and child live in the same `filePath`. (Cross-file parent
+ *     pointers would be a category error — a `File` scope is not the
+ *     parent of another file's scopes; imports do that job.)
+ *
+ * Satisfies the `ScopeLookup` contract from #916 (`resolve-type-ref`), so
+ * `resolveTypeRef` can take a `ScopeTree` directly without adapters.
+ *
+ * Immutable surface: `byId` is a `ReadonlyMap`; children arrays are
+ * `Object.freeze`d; miss lookups return a shared frozen empty array.
+ */
+// ─── Build errors ───────────────────────────────────────────────────────────
+/**
+ * Thrown by `buildScopeTree` when the input violates a structural
+ * invariant. Carries the offending ids + the invariant name so failed
+ * extraction pipelines can report actionable diagnostics.
+ */
+export class ScopeTreeInvariantError extends Error {
+    invariant;
+    constructor(invariant, message) {
+        super(message);
+        this.invariant = invariant;
+        this.name = 'ScopeTreeInvariantError';
+    }
+}
+// ─── Builder ───────────────────────────────────────────────────────────────
+/**
+ * Build an immutable `ScopeTree` from a flat list of `Scope` records.
+ *
+ * Throws `ScopeTreeInvariantError` on the first invariant violation; a
+ * malformed tree is a bug in the extraction pipeline, not a data case for
+ * consumers to handle, so fail-fast is the correct posture.
+ */
+export function buildScopeTree(scopes) {
+    const byId = new Map();
+    const childrenById = new Map();
+    // ── Pass 1: collect by id + duplicate check ───────────────────────────
+    for (const scope of scopes) {
+        if (byId.has(scope.id)) {
+            throw new ScopeTreeInvariantError('duplicate-scope-id', `Two scopes share id '${scope.id}'. Scope ids must be unique per tree.`);
+        }
+        byId.set(scope.id, scope);
+    }
+    // ── Pass 2: validate parent pointers + build children buckets ─────────
+    for (const scope of scopes) {
+        if (scope.parent === null) {
+            if (scope.kind !== 'Module') {
+                throw new ScopeTreeInvariantError('non-module-requires-parent', `Scope '${scope.id}' has kind '${scope.kind}' but no parent. Only 'Module' scopes may be root-level.`);
+            }
+            continue;
+        }
+        const parent = byId.get(scope.parent);
+        if (parent === undefined) {
+            throw new ScopeTreeInvariantError('parent-not-found', `Scope '${scope.id}' references parent '${scope.parent}' which is not part of this tree.`);
+        }
+        if (parent.filePath !== scope.filePath) {
+            throw new ScopeTreeInvariantError('parent-must-share-filepath', `Scope '${scope.id}' (${scope.filePath}) has parent '${parent.id}' in a different file (${parent.filePath}). Parent/child scopes must share filePath.`);
+        }
+        if (!rangeStrictlyContains(parent.range, scope.range)) {
+            throw new ScopeTreeInvariantError('parent-must-contain-child', `Parent scope '${parent.id}' at ${formatRange(parent.range)} does not strictly contain child '${scope.id}' at ${formatRange(scope.range)}.`);
+        }
+        let bucket = childrenById.get(parent.id);
+        if (bucket === undefined) {
+            bucket = [];
+            childrenById.set(parent.id, bucket);
+        }
+        bucket.push(scope.id);
+    }
+    // ── Pass 3: sibling-overlap check ─────────────────────────────────────
+    for (const [parentId, childIds] of childrenById) {
+        if (childIds.length < 2)
+            continue;
+        // Sort siblings by (startLine, startCol) for an O(n log n) pairwise
+        // scan instead of O(n²) all-pairs.
+        const children = childIds.map((id) => byId.get(id)).slice();
+        children.sort((a, b) => comparePosition(a.range, b.range));
+        for (let i = 1; i < children.length; i++) {
+            const prev = children[i - 1];
+            const curr = children[i];
+            if (rangesOverlap(prev.range, curr.range)) {
+                throw new ScopeTreeInvariantError('sibling-ranges-overlap', `Sibling scopes under parent '${parentId}' overlap: '${prev.id}' ${formatRange(prev.range)} and '${curr.id}' ${formatRange(curr.range)}.`);
+            }
+        }
+    }
+    // Freeze children arrays so the surface is truly read-only.
+    const frozenChildren = new Map();
+    for (const [parentId, childIds] of childrenById) {
+        frozenChildren.set(parentId, Object.freeze(childIds.slice()));
+    }
+    return freezeTree(byId, frozenChildren);
+}
+// ─── Internals ──────────────────────────────────────────────────────────────
+const EMPTY_CHILDREN = Object.freeze([]);
+function freezeTree(byId, childrenById) {
+    return {
+        byId,
+        get size() {
+            return byId.size;
+        },
+        getScope(id) {
+            return byId.get(id);
+        },
+        getParent(id) {
+            const scope = byId.get(id);
+            if (scope === undefined || scope.parent === null)
+                return undefined;
+            return byId.get(scope.parent);
+        },
+        getChildren(id) {
+            return childrenById.get(id) ?? EMPTY_CHILDREN;
+        },
+        getAncestors(id) {
+            const start = byId.get(id);
+            if (start === undefined || start.parent === null)
+                return EMPTY_CHILDREN;
+            const out = [];
+            const visited = new Set([id]);
+            let cursor = start.parent;
+            while (cursor !== null && !visited.has(cursor)) {
+                visited.add(cursor);
+                out.push(cursor);
+                const next = byId.get(cursor);
+                cursor = next === undefined ? null : next.parent;
+            }
+            return Object.freeze(out);
+        },
+        has(id) {
+            return byId.has(id);
+        },
+    };
+}
+/**
+ * `outer` strictly contains `inner` when `outer`'s start is at or before
+ * `inner`'s start, `outer`'s end is at or after `inner`'s end, and they are
+ * not the exact same range. Equal ranges are rejected — a child cannot
+ * occupy the exact same span as its parent.
+ */
+function rangeStrictlyContains(outer, inner) {
+    if (outer.startLine === inner.startLine &&
+        outer.startCol === inner.startCol &&
+        outer.endLine === inner.endLine &&
+        outer.endCol === inner.endCol) {
+        return false;
+    }
+    const outerStartsAtOrBefore = outer.startLine < inner.startLine ||
+        (outer.startLine === inner.startLine && outer.startCol <= inner.startCol);
+    const outerEndsAtOrAfter = outer.endLine > inner.endLine ||
+        (outer.endLine === inner.endLine && outer.endCol >= inner.endCol);
+    return outerStartsAtOrBefore && outerEndsAtOrAfter;
+}
+/**
+ * Two ranges overlap when neither finishes before the other begins. Ranges
+ * that merely touch at a single boundary point (`a.end === b.start`) do
+ * NOT overlap — this matches tree-sitter's half-open-like range semantics
+ * and the typical "sibling blocks meet but don't overlap" pattern.
+ */
+function rangesOverlap(a, b) {
+    const aEndsBeforeB = a.endLine < b.startLine || (a.endLine === b.startLine && a.endCol <= b.startCol);
+    const bEndsBeforeA = b.endLine < a.startLine || (b.endLine === a.startLine && b.endCol <= a.startCol);
+    return !(aEndsBeforeB || bEndsBeforeA);
+}
+function comparePosition(a, b) {
+    if (a.startLine !== b.startLine)
+        return a.startLine - b.startLine;
+    return a.startCol - b.startCol;
+}
+function formatRange(r) {
+    return `${r.startLine}:${r.startCol}-${r.endLine}:${r.endCol}`;
+}
+//# sourceMappingURL=scope-tree.js.map

package/dist/_shared/scope-resolution/scope-tree.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scope-tree.js","sourceRoot":"","sources":["../../src/scope-resolution/scope-tree.ts"],"names":[],"mappings":"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"}

package/dist/_shared/scope-resolution/types.d.ts

@@ -167,12 +167,6 @@ export interface ParsedTypeBinding {
  * concretely typed in Ring 2 SHARED (#915).
  */
 export type WorkspaceIndex = unknown;
-/**
- * Scope tree handle consumed by parse-phase hooks (`bindingScopeFor`,
- * `importOwningScope`) to navigate the in-progress scope tree. Opaque
- * placeholder in Ring 1; concretely typed in Ring 2 SHARED (#912).
- */
-export type ScopeTree = unknown;
 /** Call-site description passed to `arityCompatibility`. */
 export interface Callsite {
     /** Number of arguments at the call site. */

package/dist/_shared/scope-resolution/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/scope-resolution/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/scope-resolution/types.ts"],"names":[],"mappings":"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"}

package/dist/core/search/phase-timer.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Per-phase wall-clock timing for the search pipeline and similar
+ * multi-stage flows. Designed to be called from query() with minimal
+ * ceremony and negligible overhead (< 0.1 ms per phase recorded).
+ *
+ * ### Sequential usage
+ *
+ * ```ts
+ * const t = new PhaseTimer();
+ * t.start('bm25'); await bm25Search(...); t.stop();
+ * t.start('merge'); doMerge(); t.stop();
+ * const phases = t.summary(); // { bm25: 42, merge: 3 }
+ * ```
+ *
+ * ### Concurrent usage (Promise.all)
+ *
+ * `start`/`stop` assume a single active phase at a time, which is wrong
+ * for concurrent work inside `Promise.all` — the second `start` would
+ * auto-stop the first and only one of the two would get timed. Use
+ * {@link PhaseTimer.time} to wrap each concurrent promise instead:
+ *
+ * ```ts
+ * const [a, b] = await Promise.all([
+ *   t.time('bm25', bm25Search(...)),
+ *   t.time('vector', semanticSearch(...)),
+ * ]);
+ * ```
+ *
+ * ### Pre-measured durations
+ *
+ * ```ts
+ * t.mark('inherited', 12.5);
+ * ```
+ */
+export declare class PhaseTimer {
+    private phases;
+    private current;
+    private t0;
+    /** Start a new phase. Implicitly stops the previous one, if any. */
+    start(phase: string): void;
+    /** Stop the current phase. No-op if no phase is active. */
+    stop(): void;
+    /**
+     * Record a pre-measured duration without touching the active phase.
+     * Use for concurrent operations inside `Promise.all` where
+     * `start`/`stop` would step on each other, or for durations imported
+     * from sub-systems. Additive across repeated calls with the same
+     * phase name. Ignores negative / non-finite inputs.
+     */
+    mark(phase: string, durationMs: number): void;
+    /**
+     * Wrap a promise with automatic timing. Records wall time via
+     * {@link PhaseTimer.mark} regardless of which other phases are
+     * active — safe to use inside `Promise.all`.
+     */
+    time<T>(phase: string, promise: Promise<T>): Promise<T>;
+    /**
+     * Snapshot of accumulated durations rounded to 0.1 ms. Stops the
+     * current phase if one is still running.
+     */
+    summary(): Record<string, number>;
+    /**
+     * Sum of every recorded phase duration.
+     *
+     * Note: for phases recorded via {@link PhaseTimer.time} or
+     * {@link PhaseTimer.mark} this is the *sum*, not the wall time —
+     * concurrent work overlaps and the sum can exceed the end-to-end
+     * wall time. Record wall time separately with `mark('wall', …)` if
+     * that distinction matters.
+     */
+    totalMs(): number;
+}

package/dist/core/search/phase-timer.js

@@ -0,0 +1,106 @@
+/**
+ * Per-phase wall-clock timing for the search pipeline and similar
+ * multi-stage flows. Designed to be called from query() with minimal
+ * ceremony and negligible overhead (< 0.1 ms per phase recorded).
+ *
+ * ### Sequential usage
+ *
+ * ```ts
+ * const t = new PhaseTimer();
+ * t.start('bm25'); await bm25Search(...); t.stop();
+ * t.start('merge'); doMerge(); t.stop();
+ * const phases = t.summary(); // { bm25: 42, merge: 3 }
+ * ```
+ *
+ * ### Concurrent usage (Promise.all)
+ *
+ * `start`/`stop` assume a single active phase at a time, which is wrong
+ * for concurrent work inside `Promise.all` — the second `start` would
+ * auto-stop the first and only one of the two would get timed. Use
+ * {@link PhaseTimer.time} to wrap each concurrent promise instead:
+ *
+ * ```ts
+ * const [a, b] = await Promise.all([
+ *   t.time('bm25', bm25Search(...)),
+ *   t.time('vector', semanticSearch(...)),
+ * ]);
+ * ```
+ *
+ * ### Pre-measured durations
+ *
+ * ```ts
+ * t.mark('inherited', 12.5);
+ * ```
+ */
+export class PhaseTimer {
+    phases = new Map();
+    current = null;
+    t0 = 0;
+    /** Start a new phase. Implicitly stops the previous one, if any. */
+    start(phase) {
+        this.stop();
+        this.current = phase;
+        this.t0 = performance.now();
+    }
+    /** Stop the current phase. No-op if no phase is active. */
+    stop() {
+        if (this.current !== null) {
+            const elapsed = performance.now() - this.t0;
+            this.phases.set(this.current, (this.phases.get(this.current) ?? 0) + elapsed);
+            this.current = null;
+        }
+    }
+    /**
+     * Record a pre-measured duration without touching the active phase.
+     * Use for concurrent operations inside `Promise.all` where
+     * `start`/`stop` would step on each other, or for durations imported
+     * from sub-systems. Additive across repeated calls with the same
+     * phase name. Ignores negative / non-finite inputs.
+     */
+    mark(phase, durationMs) {
+        if (!Number.isFinite(durationMs) || durationMs < 0)
+            return;
+        this.phases.set(phase, (this.phases.get(phase) ?? 0) + durationMs);
+    }
+    /**
+     * Wrap a promise with automatic timing. Records wall time via
+     * {@link PhaseTimer.mark} regardless of which other phases are
+     * active — safe to use inside `Promise.all`.
+     */
+    async time(phase, promise) {
+        const t0 = performance.now();
+        try {
+            return await promise;
+        }
+        finally {
+            this.mark(phase, performance.now() - t0);
+        }
+    }
+    /**
+     * Snapshot of accumulated durations rounded to 0.1 ms. Stops the
+     * current phase if one is still running.
+     */
+    summary() {
+        this.stop();
+        const out = {};
+        for (const [k, v] of this.phases)
+            out[k] = Math.round(v * 10) / 10;
+        return out;
+    }
+    /**
+     * Sum of every recorded phase duration.
+     *
+     * Note: for phases recorded via {@link PhaseTimer.time} or
+     * {@link PhaseTimer.mark} this is the *sum*, not the wall time —
+     * concurrent work overlaps and the sum can exceed the end-to-end
+     * wall time. Record wall time separately with `mark('wall', …)` if
+     * that distinction matters.
+     */
+    totalMs() {
+        this.stop();
+        let t = 0;
+        for (const v of this.phases.values())
+            t += v;
+        return Math.round(t * 10) / 10;
+    }
+}

package/dist/mcp/local/local-backend.js

@@ -18,6 +18,7 @@ import { listRegisteredRepos, cleanupOldKuzuFiles, } from '../../storage/repo-ma
 import { GroupService } from '../../core/group/service.js';
 import { collectBestChunks } from '../../core/embeddings/types.js';
 import { EMBEDDING_TABLE_NAME, EMBEDDING_INDEX_NAME } from '../../core/lbug/schema.js';
+import { PhaseTimer } from '../../core/search/phase-timer.js';
 // AI context generation is CLI-only (gitnexus analyze)
 // import { generateAIContextFiles } from '../../cli/ai-context.js';
 /**
@@ -134,6 +135,25 @@ function logQueryError(context, err) {
     const msg = err instanceof Error ? err.message : String(err);
     console.error(`GitNexus [${context}]: ${msg}`);
 }
+/**
+ * Structured per-query latency log for production aggregation (#553).
+ *
+ * Emitted on stderr — NOT stdout — because the MCP stdio transport uses
+ * stdout exclusively for JSON-RPC responses (#324), and the CLI e2e test
+ * `tool output goes to stdout via fd 1` asserts that stdout parses cleanly
+ * as JSON. Any `console.log` from inside a tool handler would corrupt the
+ * protocol. Matches the existing `logQueryError` convention above, which
+ * uses stderr for the same reason.
+ *
+ * The `GitNexus [query:timing] …` prefix keeps lines greppable; the
+ * `phases` payload is JSON so log-scraping pipelines can parse it
+ * without custom format knowledge.
+ */
+function logQueryTiming(query, phases) {
+    const totalMs = phases.wall ?? Object.values(phases).reduce((a, b) => a + b, 0);
+    const truncated = query.length > 80 ? `${query.slice(0, 80)}…` : query;
+    console.error(`GitNexus [query:timing] query=${JSON.stringify(truncated)} totalMs=${totalMs} phases=${JSON.stringify(phases)}`);
+}
 export class LocalBackend {
     repos = new Map();
     contextCache = new Map();
@@ -449,15 +469,26 @@ export class LocalBackend {
         const maxSymbolsPerProcess = params.max_symbols || 10;
         const includeContent = params.include_content ?? false;
         const searchQuery = params.query.trim();
-        // Step 1: Run hybrid search to get matching symbols
+        // Per-phase timing instrumentation (#553). Records wall time for each
+        // observable sub-step of the search pipeline so production latency can
+        // be aggregated offline for Pareto analysis and bottleneck detection.
+        // Overhead is <0.1 ms per phase; the timer is passive and never alters
+        // query behaviour.
+        const timer = new PhaseTimer();
+        const wallStart = performance.now();
+        // Step 1: Run hybrid search to get matching symbols. BM25 and vector
+        // search run concurrently via Promise.all — use `timer.time()` for
+        // each so both get independent wall-time records without fighting
+        // over a single `current` phase slot.
         const searchLimit = processLimit * maxSymbolsPerProcess; // fetch enough raw results
         const [bm25SearchResult, semanticResults] = await Promise.all([
-            this.bm25Search(repo, searchQuery, searchLimit),
-            this.semanticSearch(repo, searchQuery, searchLimit),
+            timer.time('bm25', this.bm25Search(repo, searchQuery, searchLimit)),
+            timer.time('vector', this.semanticSearch(repo, searchQuery, searchLimit)),
         ]);
         const bm25Results = bm25SearchResult.results;
         const ftsUsed = bm25SearchResult.ftsUsed;
         // Merge via reciprocal rank fusion
+        timer.start('merge');
         const scoreMap = new Map();
         for (let i = 0; i < bm25Results.length; i++) {
             const result = bm25Results[i];
@@ -486,7 +517,9 @@ export class LocalBackend {
         const merged = Array.from(scoreMap.entries())
             .sort((a, b) => b[1].score - a[1].score)
             .slice(0, searchLimit);
+        timer.stop(); // merge
         // Step 2: For each match with a nodeId, trace to process(es)
+        timer.start('symbol_lookup');
         const processMap = new Map();
         const definitions = []; // standalone symbols not in any process
         for (const [_, item] of merged) {
@@ -590,7 +623,9 @@ export class LocalBackend {
                 }
             }
         }
+        timer.stop(); // symbol_lookup
         // Step 3: Rank processes by aggregate score + internal cohesion boost
+        timer.start('ranking');
         const rankedProcesses = Array.from(processMap.values())
             .map((p) => ({
             ...p,
@@ -598,7 +633,9 @@ export class LocalBackend {
         }))
             .sort((a, b) => b.priority - a.priority)
             .slice(0, processLimit);
+        timer.stop(); // ranking
         // Step 4: Build response
+        timer.start('formatting');
         const processes = rankedProcesses.map((p) => ({
             id: p.id,
             summary: p.heuristicLabel || p.label,
@@ -619,10 +656,18 @@ export class LocalBackend {
             seen.add(s.id);
             return true;
         });
+        timer.stop(); // formatting
+        // End-to-end wall time — deliberately a separate mark so callers can
+        // compare sum(phases) vs wall to see how much Promise.all concurrency
+        // saved. Must come before summary() so it's included.
+        timer.mark('wall', performance.now() - wallStart);
+        const timing = timer.summary();
+        logQueryTiming(searchQuery, timing);
         return {
             processes,
             process_symbols: dedupedSymbols,
             definitions: definitions.slice(0, 20), // cap standalone definitions
+            timing,
             ...(!ftsUsed && {
                 warning: 'FTS extension unavailable - keyword search degraded. Run: gitnexus analyze --force to rebuild indexes.',
             }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gitnexus",
-  "version": "1.6.3-rc.6",
+  "version": "1.6.3-rc.7",
   "description": "Graph-powered code intelligence for AI agents. Index any codebase, query via MCP or CLI.",
   "author": "Abhigyan Patwari",
   "license": "PolyForm-Noncommercial-1.0.0",