gitnexus 1.6.12-rc.2 → 1.6.12-rc.21

package/dist/core/lbug/schema.js

@@ -60,6 +60,28 @@ CREATE NODE TABLE Class (
   frameworkAnnotations STRING[],
   PRIMARY KEY (id)
 )`;
+export const PROTOCOL_SCHEMA = `
+CREATE NODE TABLE Protocol (
+  id STRING,
+  name STRING,
+  filePath STRING,
+  startLine INT64,
+  endLine INT64,
+  content STRING,
+  description STRING,
+  PRIMARY KEY (id)
+)`;
+export const CATEGORY_SCHEMA = `
+CREATE NODE TABLE Category (
+  id STRING,
+  name STRING,
+  filePath STRING,
+  startLine INT64,
+  endLine INT64,
+  content STRING,
+  description STRING,
+  PRIMARY KEY (id)
+)`;
 export const INTERFACE_SCHEMA = `
 CREATE NODE TABLE Interface (
   id STRING,
@@ -550,6 +572,9 @@ export const STRUCTURAL_PAIR_DDL = `  FROM File TO Folder,
   FROM \`Module\` TO \`Namespace\`,
   FROM \`Namespace\` TO Function,
   FROM CodeElement TO CodeElement,
+  FROM CodeElement TO Class,
+  FROM CodeElement TO Category,
+  FROM CodeElement TO Method,
   FROM CodeElement TO \`Module\`,
   FROM CodeElement TO \`Property\`,
   FROM Section TO Section,
@@ -674,6 +699,8 @@ export const NODE_SCHEMA_QUERIES = [
     FOLDER_SCHEMA,
     FUNCTION_SCHEMA,
     CLASS_SCHEMA,
+    PROTOCOL_SCHEMA,
+    CATEGORY_SCHEMA,
     INTERFACE_SCHEMA,
     METHOD_SCHEMA,
     CODE_ELEMENT_SCHEMA,

package/dist/core/search/fts-indexes.js

@@ -267,10 +267,19 @@ export async function createSearchFTSIndexes(options) {
         // the old name+content index would silently persist. `dropFTSIndex` no-ops
         // when the index is absent (first-ever analyze) and clears the per-connection
         // memo so the create below actually runs.
-        // ponytail: this rebuilds every FTS index on every analyze instead of
-        // skipping when present; FTS build is proportional to symbol-table size and
-        // runs inside the existing FTS phase. Gate on a stored schema fingerprint if
-        // this rebuild cost ever shows up in analyze profiles.
+        // The cost DID show up in analyze profiles — 7.5s of a 31.7s edit loop on a
+        // 5350-file repo, `bench/analyze-phase-breakdown.md` — and a "skip when the
+        // index is already present" gate is NOT the answer, so don't reach for it.
+        // Every caller that reaches this loop has already dropped the indexes it
+        // passes in `tables`: the incremental writeback drops them because Ladybug
+        // cannot DML a table with a live FTS index (#2589), and a full rebuild
+        // builds into a fresh staging DB that never had one. A presence gate would
+        // therefore never fire. The cost is inherent — Ladybug's FTS is not
+        // incremental, so one changed row means re-tokenizing the whole table, and
+        // `File` alone is ~33MB of file content at ~10MB/s. The measured floor and
+        // the four exits that were tried and closed (narrow further, build
+        // concurrently, raise the connection thread count, drop `content`) are in
+        // that document.
         try {
             await dropFTSIndex(table, indexName);
             await createFTSIndex(table, indexName, [...properties], stemmer);

package/dist/core/search/fts-schema.js

@@ -18,6 +18,8 @@ export const FTS_INDEXES = [
     // Original 5 (minus File) gain `description`.
     { table: 'Function', indexName: 'function_fts', properties: FTS_PROPERTIES },
     { table: 'Class', indexName: 'class_fts', properties: FTS_PROPERTIES },
+    { table: 'Protocol', indexName: 'protocol_fts', properties: FTS_PROPERTIES },
+    { table: 'Category', indexName: 'category_fts', properties: FTS_PROPERTIES },
     { table: 'Method', indexName: 'method_fts', properties: FTS_PROPERTIES },
     { table: 'Interface', indexName: 'interface_fts', properties: FTS_PROPERTIES },
     // Remaining EMBEDDABLE_LABELS symbol tables — all CODE_ELEMENT_BASE-shaped

package/dist/core/tree-sitter/parser-loader.js

@@ -41,6 +41,16 @@ const SOURCES = {
         load: () => _require('tree-sitter-cpp'),
         unavailableNote: 'C++ parsing requires `tree-sitter-cpp`. Check the install and native binding.',
     },
+    [SupportedLanguages.ObjectiveC]: {
+        load: () => requireVendoredGrammar('tree-sitter-objc'),
+        optional: true,
+        severity: 'error',
+        unavailableNote: 'Objective-C parsing disabled: vendored `tree-sitter-objc` (under ' +
+            '`gitnexus/vendor/tree-sitter-objc`) could not be loaded. GitNexus ships ' +
+            'prebuilt binaries for supported macOS/Linux runner architectures; this usually ' +
+            'indicates a corrupted install or native ABI mismatch with the bundled ' +
+            'tree-sitter@0.21.1 runtime.',
+    },
     [SupportedLanguages.Go]: {
         load: () => _require('tree-sitter-go'),
         unavailableNote: 'Go parsing requires `tree-sitter-go`. Check the install and native binding.',

package/dist/core/tree-sitter/vendored-grammars.d.ts

@@ -20,7 +20,7 @@ export declare const vendoredGrammarDir: (packageName: string) => string;
 /**
  * Load a vendored tree-sitter grammar by its absolute path under `vendor/`.
  *
- * GitNexus vendors six grammars (c/dart/proto/swift/kotlin/zig) inside its own
+ * GitNexus vendors seven grammars (c/dart/proto/swift/kotlin/objc/zig) inside its own
  * package under `vendor/`, each shipping committed per-platform prebuilds. They
  * are deliberately NOT npm dependencies and must NEVER be copied into
  * `node_modules`: an undeclared package under `node_modules` is "extraneous" to

package/dist/core/tree-sitter/vendored-grammars.js

@@ -24,6 +24,7 @@ export const VENDORED_GRAMMAR_PACKAGES = new Set([
     'tree-sitter-proto',
     'tree-sitter-swift',
     'tree-sitter-kotlin',
+    'tree-sitter-objc',
     'tree-sitter-zig',
 ]);
 /** Absolute directory of a vendored grammar package under `vendor/`. */
@@ -31,7 +32,7 @@ export const vendoredGrammarDir = (packageName) => path.join(VENDOR_ROOT, packag
 /**
  * Load a vendored tree-sitter grammar by its absolute path under `vendor/`.
  *
- * GitNexus vendors six grammars (c/dart/proto/swift/kotlin/zig) inside its own
+ * GitNexus vendors seven grammars (c/dart/proto/swift/kotlin/objc/zig) inside its own
  * package under `vendor/`, each shipping committed per-platform prebuilds. They
  * are deliberately NOT npm dependencies and must NEVER be copied into
  * `node_modules`: an undeclared package under `node_modules` is "extraneous" to

package/dist/mcp/local/local-backend.d.ts

@@ -142,6 +142,39 @@ export interface EpistemicCauses {
      * "nothing was undecided", and a re-index is what tells the two apart.
      */
     readonly undecidedSatisfaction: number;
+    /**
+     * Symbols that name this callable in VALUE position rather than calling it
+     * (#3399) — a registration table (`bridge.accessor(Element.getNamespaceUri,
+     * …)`), a callback argument, a function pointer stored in a field.
+     *
+     * Unit: SYMBOLS — distinct referrers, the same unit and the same reason as
+     * `dispatchBoundary`: the reference edge is per-site but the walk's question
+     * is "who else might reach this", and a referrer that names the callable
+     * twice is still one place the value escapes from.
+     *
+     * Kept separate from `dispatchBoundary` even though both describe dispatch
+     * the walk cannot follow. That slot counts implementations and
+     * interface-level consumers found by the heritage probe; these are neither,
+     * and folding them in would tell a consumer branching on the numbers that an
+     * interface boundary exists where there is none. The distinction is also the
+     * actionable one: a dispatch boundary is irreducible, whereas a callable
+     * value CAN often be followed once the language models the store/load that
+     * carries it.
+     *
+     * The reference itself IS modelled — that is what makes it countable. What is
+     * missing is the invocation through the value: it happens later, through a
+     * struct field, a registry lookup, or comptime reflection, and no CALLS edge
+     * connects the eventual call site back to this symbol.
+     *
+     * Zero when the property-dispatch pass DID synthesize that invocation
+     * (`x.<key>()` through a registered object-literal key): the walk followed
+     * the registration, so nothing was missed and the result stays `exact`.
+     *
+     * Also zero — WITH a boundary note — when the probe itself could not run.
+     * The note is the signal there; the count is not, which is why a reader must
+     * branch on `epistemic` first and read the causes as explanation.
+     */
+    readonly callableValueReferences: number;
 }
 interface RepoHandle {
     id: string;

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

@@ -61,6 +61,7 @@ import { compareCodeUnits } from '../../lib/utils.js';
 import { lookupExternalCallCount, lookupUnresolvedCallCount, } from '../../core/ingestion/scope-resolution/unresolved-receivers.js';
 import { scopeExtractionFailureTotal } from '../../core/ingestion/scope-resolution/scope-extraction-failures.js';
 import { lookupCount } from '../../core/ingestion/scope-resolution/summary-maps.js';
+import { VALUE_REF_EDGE_REASON } from '../../core/ingestion/scope-resolution/value-ref-edges.js';
 import { DEFERRED_IMPORT_REASON_SUFFIX, TYPE_ONLY_IMPORT_REASON_SUFFIX, } from '../../core/ingestion/scope-resolution/graph-bridge/imports-to-edges.js';
 import { fnLineOf, isPdgDegradedLayerStatus, makePdgImpactErrorResult, makePdgLayerDegradedResult, pdgLayerStatus, pdgStampForMode, runImpactPDG, validateImpactMode, pdgBridgeEvidenceForImpact, betterBridgeEvidence, composeUnifiedPdgImpactResult, splitCalleeIds, } from './pdg-impact.js';
 /**
@@ -164,7 +165,13 @@ function normalizeToolParams(method, params) {
             // Internal CLI callers materialize omitted optional flags as undefined.
             if (value === undefined)
                 continue;
-            if (typeof value !== 'string' || !value.trim()) {
+            // Strict OpenAI/Anthropic adapters also materialize omitted optional
+            // string aliases as "". Treat those exactly like undefined. Required
+            // canonical values are still rejected by the method-specific check
+            // below, and non-string aliases remain invalid.
+            if (typeof value === 'string' && !value.trim())
+                continue;
+            if (typeof value !== 'string') {
                 return { error: `MCP parameter ${method}.${key} must be a non-empty string.` };
             }
             supplied.push({ key, value: value.trim() });
@@ -177,8 +184,8 @@ function normalizeToolParams(method, params) {
                     .join(', ')} must agree.`,
             };
         }
-        for (const alias of aliases)
-            delete normalized[alias];
+        for (const key of keys)
+            delete normalized[key];
         if (supplied.length > 0)
             normalized[canonical] = supplied[0].value;
     }
@@ -199,6 +206,8 @@ export const VALID_NODE_LABELS = new Set([
     'Folder',
     'Function',
     'Class',
+    'Protocol',
+    'Category',
     'Interface',
     'Method',
     'CodeElement',
@@ -460,6 +469,7 @@ function epistemicFrom(dropped) {
                     dispatchBoundary: dropped.dispatch,
                     externalBoundary: dropped.external,
                     undecidedSatisfaction: 0,
+                    callableValueReferences: dropped.callableValueReferences,
                 },
             }
             : { epistemic: 'exact' }
@@ -476,6 +486,7 @@ function epistemicFrom(dropped) {
                 dispatchBoundary: dropped.dispatch,
                 externalBoundary: dropped.external,
                 undecidedSatisfaction: dropped.undecided,
+                callableValueReferences: dropped.callableValueReferences,
             },
         };
 }
@@ -561,6 +572,138 @@ function undecidedSatisfactionBoundaries(summary, names) {
     }
     return { notes, undecided };
 }
+/**
+ * Boundary evidence for callables named in VALUE position (#3399).
+ *
+ * `bridge.accessor(Element.getNamespaceUri, null, .{})`, `{ onClick: handler }`,
+ * `qsort(xs, n, sz, compareItems)` — each REGISTERS a function somewhere
+ * instead of calling it. The registration is modelled (`value-ref` → a USES
+ * edge, Kythe `ref` / Joern `METHOD_REF`); the invocation through the stored
+ * value is not, because it happens later through a struct field, a registry
+ * lookup or comptime reflection.
+ *
+ * That gap is precisely the first half of `tools.ts`'s definition of
+ * `lower-bound` — the walk provably missed callers — and it was previously
+ * reported as `exact`. (The second half, a probe that could not run, is what
+ * the failure branch below publishes; the contract states both because this
+ * function can produce either.) A
+ * public DOM accessor bound into a JS bridge table came back LOW/exact with two
+ * internal callers, which is worse than no answer: `lower-bound` invites the
+ * reader to look further, `exact` tells them not to bother.
+ *
+ * Counted as DISTINCT REFERRERS rather than sites: the question the count
+ * serves is "how many places does this value escape from", and a table that
+ * registers the same callable twice is still one table.
+ *
+ * NOT every value reference is a gap. Where the property-dispatch pass
+ * synthesized the invocation side, the walk followed it and the answer stays
+ * `exact` — see the second probe below.
+ *
+ * Three failure modes, three different answers, none of them silence:
+ *   - the query cannot run       → hedge, count 0 (a probe that did not answer
+ *                                  is not evidence of completeness);
+ *   - the query returns nothing  → no hedge (a real, measured zero);
+ *   - the reference was followed → no hedge (nothing was missed).
+ *
+ * The probe reads the edge's `reason`, which is why writer and reader share
+ * {@link VALUE_REF_EDGE_REASON}. Language-neutral by construction — every
+ * provider that emits a `value-ref` capture participates, and one that emits
+ * none simply gets no rows.
+ */
+async function callableValueReferenceBoundaries(lbugPath, symId) {
+    // `COUNT(DISTINCT …)`, not a capped row list. A `LIMIT n` here would make the
+    // published cause silently understate a target with more than n
+    // registrations — and this number is documented as "how many symbols", so a
+    // reader comparing its magnitude against `receiverTyping` would be comparing
+    // a truth to a ceiling. Aggregating in the database keeps the work bounded
+    // without capping the answer; scalar `sym.id` equality plus an implicit
+    // group-by is the shape `countByType` below already relies on.
+    //
+    // `null`, not `[]`, on failure: see below — an empty result set and an
+    // unanswerable query must not be the same value.
+    const rows = await executeParameterized(lbugPath, `MATCH (other)-[r:CodeRelation]->(sym)
+     WHERE sym.id = $symId AND r.type = 'USES' AND r.reason = $reason
+     RETURN COUNT(DISTINCT other.id) AS cnt`, { symId, reason: VALUE_REF_EDGE_REASON }).catch(() => null);
+    // A probe that could not run must never read as certainty — the same rule the
+    // `loadMeta` read above states, and the whole reason this function exists.
+    // Returning zero here would publish `exact` on the strength of a query that
+    // never answered.
+    if (rows === null) {
+        return {
+            referrers: 0,
+            notes: [
+                'The callable-value-reference probe could not be run against this index, so whether ' +
+                    'this symbol is registered somewhere as a value is unknown. Treat the caller list as ' +
+                    'incomplete until it can be re-checked.',
+            ],
+        };
+    }
+    const referrers = rows.length > 0 ? Number(rows[0].cnt ?? rows[0][0] ?? 0) : 0;
+    if (!Number.isFinite(referrers) || referrers <= 0)
+        return { notes: [], referrers: 0 };
+    // Registrations whose invocation side the analyzer ALREADY synthesized are
+    // not a gap. `emitPropertyDispatchCalls` sweep 2 connects `x.<key>()` member
+    // calls to every function registered under `<key>` and stamps those edges
+    // `property-dispatch`; where that happened, the walk did not "provably miss"
+    // the caller and `lower-bound` would be noise sprayed over an answer the
+    // analyzer actually computed. Zig — the case this was built for — never sets
+    // a property key (no object-literal key to dispatch through), so it is never
+    // excluded here; the exclusion exists to keep TypeScript/JavaScript hook
+    // tables that ARE followed from being downgraded.
+    //
+    // SYMBOL-LEVEL, NOT PER-EDGE, and that is only sound because of an invariant
+    // that lives nowhere near this line. The graph does not record which
+    // registration produced which synthesized call, so if one symbol could carry
+    // both a followed and an unfollowed registration, this would zero the note
+    // over a gap the analyzer provably did not close — #3399 returning through a
+    // side door. Today no symbol can:
+    //
+    //   - sweep 2 synthesizes CALLS only for a registration whose site carried a
+    //     `propertyKey` (sweep 1 skips the index when it is undefined);
+    //   - every JS/TS `@reference.value-ref` rule also captures
+    //     `@reference.property-key` — both are object-literal shapes;
+    //   - no Zig `@reference.value-ref` rule captures one.
+    //
+    // So a dispatchable registration is always a JS/TS one, an undispatchable
+    // registration is always a Zig one, and the two never meet on one symbol.
+    // `test/unit/scope-resolution/value-ref-dispatchability.test.ts` FAILS the day
+    // that stops holding — a JS/TS rule for a bare callback argument
+    // (`register(handler)`), a Zig rule that grows a key. When it does, the
+    // choice to make here is between (a) splitting the edge `reason` into
+    // dispatchable / undispatchable so this probe can count them apart, and
+    // (b) hedging any symbol with an undispatchable registration regardless of
+    // dispatch. (a) is precise and costs a graph-content change; (b) is cheap and
+    // over-hedges. What is NOT acceptable is leaving this as-is, because a signal
+    // that quietly stops firing is the defect this whole feature removes.
+    //
+    // Given the invariant, the residual today is only the coarseness of the
+    // exclusion within JS/TS, and hedging every property-value registration in
+    // every JS/TS codebase is worse: a signal that fires on everything stops
+    // carrying information, and the fan-out cap warning still sits behind it.
+    const dispatched = await executeParameterized(lbugPath, `MATCH (other)-[r:CodeRelation]->(sym)
+     WHERE sym.id = $symId AND r.type = 'CALLS' AND r.reason = 'property-dispatch'
+     RETURN COUNT(r) AS cnt`, { symId }).catch(() => null);
+    // Failure here is NOT a reason to skip the hedge: we already know a value
+    // reference exists, and being unable to prove it was followed leaves the
+    // conservative answer standing.
+    const dispatchedCount = dispatched === null || dispatched.length === 0
+        ? 0
+        : Number(dispatched[0].cnt ?? dispatched[0][0] ?? 0);
+    if (Number.isFinite(dispatchedCount) && dispatchedCount > 0) {
+        return { notes: [], referrers: 0 };
+    }
+    const one = referrers === 1;
+    return {
+        referrers,
+        notes: [
+            `${referrers} ${one ? 'symbol references' : 'symbols reference'} this callable as a VALUE ` +
+                `rather than calling it (a registration table, a callback argument, a stored function ` +
+                `pointer). The reference is recorded, but the call made THROUGH that value is not: it is ` +
+                `dispatched later from wherever the value is stored. Callers reached that way are absent ` +
+                `from this result — actual impact may be higher.`,
+        ],
+    };
+}
 /** Resolve symlinks for path comparison; falls back to path.resolve on error.
  * Uses `realpathSync.native` (not the pure-JS `realpathSync`) so that Windows
  * 8.3 short names (e.g. RUNNER~1 → runneradmin) are expanded to long form,
@@ -3338,7 +3481,8 @@ export class LocalBackend {
         const [incomingRows, incomingAdvisedRows] = await Promise.all([
             executeParameterized(repo.lbugPath, `
       MATCH (caller)-[r:CodeRelation]->(n {id: $symId})
-      WHERE r.type IN ['CALLS', 'IMPORTS', 'EXTENDS', 'IMPLEMENTS', 'USES', 'HAS_METHOD', 'HAS_PROPERTY', 'METHOD_OVERRIDES', 'OVERRIDES', 'METHOD_IMPLEMENTS', 'ACCESSES']
+      WHERE r.type IN ['CALLS', 'IMPORTS', 'EXTENDS', 'IMPLEMENTS', 'MEMBER_OF', 'USES', 'DECLARES', 'HAS_METHOD', 'HAS_PROPERTY', 'METHOD_OVERRIDES', 'OVERRIDES', 'METHOD_IMPLEMENTS', 'ACCESSES']
+        AND (r.type <> 'MEMBER_OF' OR labels(n) <> 'Community')
       RETURN r.type AS relType, caller.id AS uid, caller.name AS name, caller.filePath AS filePath, labels(caller)[0] AS kind
       ORDER BY uid, relType
       LIMIT 30
@@ -3461,7 +3605,8 @@ export class LocalBackend {
         const [outgoingRows, outgoingAdvisedRows] = await Promise.all([
             executeParameterized(repo.lbugPath, `
       MATCH (n {id: $symId})-[r:CodeRelation]->(target)
-      WHERE r.type IN ['CALLS', 'IMPORTS', 'EXTENDS', 'IMPLEMENTS', 'USES', 'HAS_METHOD', 'HAS_PROPERTY', 'METHOD_OVERRIDES', 'OVERRIDES', 'METHOD_IMPLEMENTS', 'ACCESSES']
+      WHERE r.type IN ['CALLS', 'IMPORTS', 'EXTENDS', 'IMPLEMENTS', 'MEMBER_OF', 'USES', 'DECLARES', 'HAS_METHOD', 'HAS_PROPERTY', 'METHOD_OVERRIDES', 'OVERRIDES', 'METHOD_IMPLEMENTS', 'ACCESSES']
+        AND (r.type <> 'MEMBER_OF' OR labels(target) <> 'Community')
       RETURN r.type AS relType, target.id AS uid, target.name AS name, target.filePath AS filePath, labels(target)[0] AS kind
       ORDER BY uid, relType
       LIMIT 30
@@ -5685,6 +5830,18 @@ export class LocalBackend {
         const convexDispatchPromise = direction === 'downstream'
             ? Promise.resolve(undefined)
             : queryConvexDispatchMetadata(repo.lbugPath, symId, symName, symType);
+        // #3399 — callables named in value position. Upstream only: the question
+        // "who can reach this symbol" is the one a registration makes unanswerable.
+        // A downstream walk asks what THIS symbol reaches, which a reference INTO
+        // it does not affect.
+        //
+        // Issued alongside the heritage probe rather than after it, and read into
+        // `droppedBoundaries` below, so it hedges even when that probe finds
+        // nothing AND when it throws — a value reference is an independent reason
+        // a count is short, exactly as the receiver drops above are.
+        const valueRefPromise = direction === 'downstream'
+            ? Promise.resolve({ notes: [], referrers: 0 })
+            : callableValueReferenceBoundaries(repo.lbugPath, symId);
         const interfaceRowsPromise = executeParameterized(repo.lbugPath, `MATCH (x)-[r:CodeRelation]->(iface)
        WHERE x.id = $symId AND r.type IN $heritage
        RETURN DISTINCT iface.id AS id, iface.name AS name, labels(iface)[0] AS label
@@ -5700,12 +5857,14 @@ export class LocalBackend {
                     : []),
             ]);
         const convexDispatch = await convexDispatchPromise;
+        const valueRefDrops = await valueRefPromise;
         const droppedBoundaries = {
             ...receiverDrops,
             notes: [
                 ...receiverDrops.notes,
                 ...scopeExtractionDrops.notes,
                 ...undecidedDrops.notes,
+                ...valueRefDrops.notes,
                 ...(convexDispatch === undefined ? [] : [convexDispatch.boundary]),
             ],
             undecided: undecidedDrops.undecided,
@@ -5714,6 +5873,7 @@ export class LocalBackend {
             // inventing one from the presence of a note.
             dispatch: 0,
             scopeExtraction: scopeExtractionDrops.files,
+            callableValueReferences: valueRefDrops.referrers,
         };
         try {
             // Discover the interface / abstract supertypes on the target's boundary.
@@ -5794,6 +5954,7 @@ export class LocalBackend {
                     dispatchBoundary: droppedBoundaries.dispatch + dispatchBoundarySymbols,
                     externalBoundary: droppedBoundaries.external,
                     undecidedSatisfaction: droppedBoundaries.undecided,
+                    callableValueReferences: droppedBoundaries.callableValueReferences,
                 },
             };
         }

package/dist/mcp/tools.js

@@ -250,14 +250,15 @@ Handles disambiguation: if multiple symbols share the same name, returns ranked
 NOTE: ACCESSES edges (field read/write tracking) are included in context results with reason 'read' or 'write'. CALLS edges resolve through field access chains and method-call chains (e.g., user.address.getCity().save() produces CALLS edges at each step).
 
 COMPLETENESS OF incoming: alongside symbol/incoming/outgoing the result carries the same epistemic envelope impact() returns:
-- epistemic: 'exact' | 'lower-bound' — 'lower-bound' means callers exist that this view provably does not list.
+- epistemic: 'exact' | 'lower-bound' — 'lower-bound' means incoming is a FLOOR: either the walk provably missed callers, or a probe that would have established completeness could not run. Do not read it as proof that an omitted caller exists — read boundaries for which of the two it is.
 - boundaries: string[] — one plain-language sentence per reason. Prose for humans; branch on causes instead.
-- causes: { scopeExtractionFiles, receiverTyping, dispatchBoundary, externalBoundary, undecidedSatisfaction } — machine-readable WHY. Every field counts MISSING THINGS, never sentences:
+- causes: { scopeExtractionFiles, receiverTyping, dispatchBoundary, externalBoundary, undecidedSatisfaction, callableValueReferences } — machine-readable WHY. Every field counts MISSING THINGS, never sentences:
   - causes.scopeExtractionFiles (unit: files) > 0 — scope extraction still failed after the fallback pass, so scope-resolution edges from those files are absent. A value of 0 does not prove completeness when epistemic is 'lower-bound' because an older or unverified index has no measured file count. Re-run \`gitnexus analyze --force\`; if the reason persists, inspect the extraction warnings.
   - causes.receiverTyping (unit: call sites) > 0 — RESOLVER GAP: the analyzer dropped that many call sites on this name because it could not type the receiver, so they are missing from incoming. Do not read an absent caller as proof none exists.
   - causes.externalBoundary (unit: call sites) > 0 — the calls left the indexed program (System.out.println, fetch(...)). NOT a defect: no in-graph node could have been reached. An epistemic:'exact' result can carry this.
   - causes.dispatchBoundary (unit: symbols) > 0 — DI or interface dispatch: that many symbols sit on or beyond a boundary static analysis cannot cross. Irreducible. A symbol count, not a site count — per-site multiplicity is not retained for these edges — so compare its magnitude with receiverTyping, not its exact value. A framework runtime-proxy boundary can make epistemic lower-bound while this value remains 0 because endpoint metadata proves the gap but cannot count omitted symbols.
   - causes.undecidedSatisfaction (unit: unjudged interface/type pairs) > 0 — the analyzer could not decide whether a type satisfies an interface, so no IMPLEMENTS edge exists and no dispatch boundary was left for the walk to notice. Usually fixable by making the missing dependency available to analysis.
+  - causes.callableValueReferences (unit: symbols) > 0 — that many symbols name this callable as a VALUE instead of calling it (a Zig registration table or const initialiser, a JS/TS object-literal property value). A bare callback argument in JS/TS is not captured today and is not counted, so a 0 does not rule that shape out; nor does it, on an index built before the language emitted these captures — re-analyze first. The reference is in the graph as a USES edge; the call made THROUGH the value is not, because it is dispatched later from wherever the value was stored. incoming.calls is therefore a floor. Follow the USES edges to find the registration, then the code that reads it. It is 0 when the analyzer DID synthesize the dispatch through a registered property key. That exclusion is per SYMBOL, not per registration: a target with BOTH a followed registration and an unfollowed escape reads 0 here, so a 0 means 'no unfollowed registration was proven', not 'this symbol escapes nowhere'. A 0 alongside epistemic 'lower-bound' can also mean the probe itself could not run — read boundaries for which.
 
 REQUIRES RE-INDEX: causes.scopeExtractionFiles, causes.receiverTyping, causes.externalBoundary, causes.undecidedSatisfaction, and framework runtime-proxy boundary detection depend on index-time metadata that only a current analyzer writes. Against an older index the metadata can be absent, which is indistinguishable from "nothing was dropped" unless the schema probe detects the stale index — re-run \`gitnexus analyze\` before trusting a zero or an apparently exact result.
 
@@ -443,15 +444,16 @@ Output includes:
 - affected_processes: which execution flows break and at which step
 - affected_modules: which functional areas are hit (direct vs indirect; classification-unavailable when that secondary query fails)
 - byDepth: affected symbols grouped by traversal depth (paginated by limit/offset; omitted when summaryOnly:true — use byDepthCounts for totals per depth, pagination object when truncated). Each item includes a processes:[{id,label,processType,step}] field listing the execution flows that symbol participates in. Empty when the symbol has no process membership. Can ALSO be empty when partial:true is set — either the process-aggregation pass hit its cap before detecting affected processes, or per-symbol enrichment was capped on a very large page. When partial:true, do NOT treat processes:[] as proof of no participation; cross-check the top-level affected_processes list. An item carries staticGated:true only when the edge that reached it is provably unreachable at compile time from the indexed source (today: Zig calls inside an 'if (CONST_FALSE)' body or the else of 'if (CONST_TRUE)'); the field is absent when the edge is live or the language does not model it. Traversal and risk do NOT filter or rank on it: it is metadata for the caller to weigh.
-- epistemic: 'exact' | 'lower-bound' — whether impactedCount is the whole story. 'lower-bound' means the walk provably missed callers, so the count is a floor. Absent only on skipped probes (ambiguous-candidate lists, group fan-out).
+- epistemic: 'exact' | 'lower-bound' — whether impactedCount is the whole story. 'lower-bound' means the count is a FLOOR: either the walk provably missed callers, or a probe that would have established completeness could not run (a failed callable-value-reference query says so in boundaries). It is not itself proof that an omitted caller exists — branch on causes and read boundaries. Absent only on skipped probes (ambiguous-candidate lists, group fan-out).
 - boundaries: string[] — one plain-language sentence per reason the count is short. Prose for humans; branch on causes instead.
-- causes: { scopeExtractionFiles, receiverTyping, dispatchBoundary, externalBoundary, undecidedSatisfaction } — the machine-readable split of WHY, so an agent gating its own edits can tell a fixable analyzer gap from an irreducible one. Every field counts MISSING THINGS, never sentences:
+- causes: { scopeExtractionFiles, receiverTyping, dispatchBoundary, externalBoundary, undecidedSatisfaction, callableValueReferences } — the machine-readable split of WHY, so an agent gating its own edits can tell a fixable analyzer gap from an irreducible one. Every field counts MISSING THINGS, never sentences:
   - causes.scopeExtractionFiles (unit: files) > 0 — scope extraction still failed after the fallback pass, so scope-resolution edges from those files are absent. A value of 0 does not prove completeness when epistemic is 'lower-bound' because an older or unverified index has no measured file count. Re-run \`gitnexus analyze --force\`; if the reason persists, inspect the extraction warnings.
   - causes.receiverTyping (unit: call sites) > 0 — the RESOLVER GAP signal: the analyzer dropped that many call sites because it could not establish the receiver's type (unresolved constructor, factory, chained expression). Those callers are absent from byDepth. Treat the result as incomplete: grep the symbol name before deleting or renaming.
   - causes.externalBoundary (unit: call sites) > 0 — those calls left the indexed program (System.out.println, fetch(...), os.environ.*). NOT a defect and NOT a reason the count is short: there is no in-graph node any edge could have reached. An epistemic:'exact' result can carry this.
   - causes.dispatchBoundary (unit: symbols) > 0 — DI or interface dispatch: that many symbols sit on or beyond a boundary a static walk cannot cross. Irreducible. A symbol count, not a site count — per-site multiplicity is not retained for these edges — so compare its magnitude with receiverTyping, not its exact value. A framework runtime-proxy boundary can make epistemic lower-bound while this value remains 0 because endpoint metadata proves the gap but cannot count omitted symbols.
 
   - causes.undecidedSatisfaction (unit: unjudged interface/type pairs) > 0 — the analyzer could not DECIDE whether a type satisfies an interface (a type in a required signature named a package it could not resolve), so no IMPLEMENTS edge exists and no dispatch boundary was left for the walk to notice. Distinct from every cause above, which count decided facts that could not be attributed; this one counts questions never answered. It is the only cause that shortens a result WITHOUT leaving a trace in the graph, so an unhedged zero on a symbol reached only through such an interface would otherwise read as 'nobody calls this'. Usually fixable: it most often means a dependency is missing from the analyzed tree.
+  - causes.callableValueReferences (unit: symbols) > 0 — that many symbols name this callable as a VALUE rather than calling it: 'bridge.accessor(Element.getNamespaceUri, ...)' and 'pub const h = onReset;' in Zig, '{ onClick: handler }' in JS/TS. Those are the shapes actually captured today — a bare callback argument in JS/TS ('qsort'-style, 'setTimeout(tick)') is NOT one of them and is not counted, so a 0 here does not rule that shape out. The registration IS modelled (a USES edge); the invocation through the stored value is NOT, because it happens later via a struct field, a registry lookup or comptime reflection. So impactedCount is a floor and a LOW risk verdict on such a symbol is a floor too. Unlike dispatchBoundary this is often reducible — it usually means the language provider does not yet follow that store/load — but until it is, do NOT read an empty or small caller set as 'safe to change'. It is an exact count, not a capped sample. It is 0 when the analyzer DID synthesize the dispatch through a registered property key, and epistemic stays 'exact' on that account. That exclusion is symbol-level, not edge-level — the graph does not record which registration produced which synthesized call — so a symbol with a mix of followed and unfollowed registrations also reads 0: treat a 0 as 'no unfollowed registration was proven', not as proof the value escapes nowhere. A 0 alongside epistemic 'lower-bound' can instead mean the probe could not run at all, so read boundaries to tell those apart. Read from the graph, so it needs no index-time metadata BEYOND the edges being there: an index built by an analyzer that did not yet emit this language's value-ref captures has none, and reports 0. Re-analyze before reading a 0 as measured.
 
 REQUIRES RE-INDEX: causes.scopeExtractionFiles, causes.receiverTyping, causes.externalBoundary, causes.undecidedSatisfaction, and framework runtime-proxy boundary detection depend on index-time metadata that only a current analyzer writes. Against an older index the metadata can be absent, which is indistinguishable from "nothing was dropped" unless the schema probe detects the stale index — re-run \`gitnexus analyze\` before trusting a zero or an apparently exact result.
 

package/dist/server/analyze-job.d.ts

@@ -53,6 +53,13 @@ export interface AnalyzeJob {
     repoUrl?: string;
     repoPath?: string;
     repoName?: string;
+    /**
+     * Index-branch selector this job was started with, part of the job's dedup
+     * identity. A repo is not "the same repo" for reuse purposes when a different
+     * branch was asked for — reusing across branches would hand the caller a 202
+     * for a job indexing something else.
+     */
+    branch?: string;
     progress: AnalyzeJobProgress;
     error?: string;
     /** Set only when a terminal `failed` job still persisted usable work. */
@@ -70,10 +77,21 @@ export declare class JobManager {
     private emitter;
     private cleanupTimer;
     constructor();
-    /** Create a new job, or return existing active job for the same repo. */
+    /**
+     * Create a new job, or return the existing active job for the same repo AND
+     * the same branch.
+     *
+     * Branch is part of the identity deliberately. Deduping on repo alone would
+     * return the in-flight job for branch A to a caller that asked for branch B,
+     * and that caller would read the resulting 202/`complete` as "B is indexed"
+     * — the same silent wrong-branch outcome that made `branch` worth honoring in
+     * the first place. Falling through instead lets the single-slot guard below
+     * reject the request outright, which is a truthful answer.
+     */
     createJob(params: {
         repoUrl?: string;
         repoPath?: string;
+        branch?: string;
     }): AnalyzeJob;
     getJob(id: string): AnalyzeJob | undefined;
     /** Return a snapshot of all tracked jobs for inspection. */

package/dist/server/analyze-job.js

@@ -34,14 +34,24 @@ export class JobManager {
     constructor() {
         this.cleanupTimer = setInterval(() => this.cleanup(), CLEANUP_INTERVAL_MS);
     }
-    /** Create a new job, or return existing active job for the same repo. */
+    /**
+     * Create a new job, or return the existing active job for the same repo AND
+     * the same branch.
+     *
+     * Branch is part of the identity deliberately. Deduping on repo alone would
+     * return the in-flight job for branch A to a caller that asked for branch B,
+     * and that caller would read the resulting 202/`complete` as "B is indexed"
+     * — the same silent wrong-branch outcome that made `branch` worth honoring in
+     * the first place. Falling through instead lets the single-slot guard below
+     * reject the request outright, which is a truthful answer.
+     */
     createJob(params) {
-        // Dedup: return existing active job for the same repo (by URL or path)
+        // Dedup: return existing active job for the same repo (by URL or path) and branch
         for (const job of this.jobs.values()) {
             if (!this.isTerminal(job.status)) {
                 const isSameRepo = (params.repoUrl && job.repoUrl === params.repoUrl) ||
                     (params.repoPath && job.repoPath === params.repoPath);
-                if (isSameRepo) {
+                if (isSameRepo && job.branch === params.branch) {
                     return job;
                 }
             }
@@ -57,6 +67,7 @@ export class JobManager {
             status: 'queued',
             repoUrl: params.repoUrl,
             repoPath: params.repoPath,
+            branch: params.branch,
             progress: { phase: 'queued', percent: 0, message: 'Waiting to start...' },
             startedAt: Date.now(),
             retryCount: 0,

package/dist/server/analyze-launch.d.ts

@@ -31,6 +31,20 @@ export interface LaunchOptions {
     springActuatorPath?: string;
     asyncApiSpecPath?: string;
     registryName?: string;
+    /**
+     * Index-branch selector, forwarded to `AnalyzeOptions.branch`.
+     *
+     * Setting it does not by itself mean a `branches/<slug>/` sub-directory:
+     * `resolveBranchPlacement` (storage/branch-index.ts) keeps the run on the flat
+     * slot when that slot has no recorded owner, or when its owner already IS this
+     * label. Only a label that differs from the flat slot's owner gets its own
+     * sub-directory.
+     *
+     * The caller is responsible for having the branch checked out —
+     * `resolveWriteTarget` in core refuses a label that disagrees with the working
+     * tree, which is what keeps one branch's content out of another's slot (#2106).
+     */
+    branch?: string;
 }
 export declare function createLaunchAnalysisWorker(deps: LaunchDeps): (job: {
     id: string;