mirror of
https://github.com/abhigyanpatwari/GitNexus.git
synced 2026-11-16 09:22:00 +00:00
docs(mcp): stop defining lower-bound as proof that callers were missed
The CLI header was corrected in round 8; the MCP tool contract still made the assertion the CLI stopped making. `context` said lower-bound "means callers exist that this view provably does not list" and `impact` said "the walk provably missed callers" — but `callableValueReferenceBoundaries` also publishes lower-bound when its probe could not RUN, and says in its own note that whether the symbol is registered is unknown. A client following the contract would read an unanswered question as evidence of an omission. Both now define it as a FLOOR with two possible causes — the walk provably missed callers, or a probe that would have established completeness could not run — and point at `boundaries` for which. That keeps the common case exactly as strong as it was; it only stops the contract asserting the one case it cannot support. The `causes.callableValueReferences` bullet already documented the probe-failure branch, so the headline was contradicting the body. `local-backend.ts` quotes that definition to justify hedging; the quote is updated to name which half it relies on.
This commit is contained in:
parent
8c77c4272d
commit
2e1904c6ac
2 changed files with 7 additions and 4 deletions
|
|
@ -900,8 +900,11 @@ function undecidedSatisfactionBoundaries(
|
|||
* value is not, because it happens later through a struct field, a registry
|
||||
* lookup or comptime reflection.
|
||||
*
|
||||
* That gap is precisely `tools.ts`'s definition of `lower-bound` — "the walk
|
||||
* provably missed callers" — and it was previously reported as `exact`. A
|
||||
* 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.
|
||||
|
|
|
|||
|
|
@ -291,7 +291,7 @@ 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, 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.
|
||||
|
|
@ -489,7 +489,7 @@ 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, 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.
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue