# Focused retrieval, recovery and coverage

## Family and scope

| | Customer tools / Python helper | Operator tools |
| --- | --- | --- |
| Orientation | Reuse authorized query ID/revision; setup/list only when access, ID or published revision needs discovery | `truthgraph.usage_guidance`; status only for diagnosis |
| Repository | Returned indexed query ID; connection UUID/provider ID differs | Indexed system name; omit only for deliberate global discovery |
| Revision | Published generation/revision pinned server-side; arbitrary revision/account/system/filters overrides rejected | Current-only discovery; exact graph workflows have separate rules in operator reference |
| Discovery | Hybrid by default; optional customer `mode` lexical/semantic; exact subjects bypass inference | Resolve's filters.search_mode; search_subjects' top-level search_mode |
| Retrieval | truthgraph_context / truthgraph_workflow; helper mirrors these | truthgraph.resolve_context, then direct get_* drilldowns |

Treat IDs as opaque. Do not derive a customer query ID from GitHub URL or assume a local directory is an operator system. Customer impact can follow connected dependencies across repositories within its own published account graph; selecting a root repository does not make impact repository-only. It never authorizes another customer's graph.

## Match query to task

| Query | Purpose | Boundary |
| --- | --- | --- |
| Exact lookup | Known canonical file, symbol, endpoint or other subject | Can work when discovery times out; verify exact resolution. |
| Lexical discovery | Function names, literal routes, paths, precise identifiers | Candidate limit is not complete inventory. |
| Semantic/hybrid | Natural-language task intent when names are unknown | Requires capability/coverage; similarity is not dependency evidence. Select an exact candidate. |
| Ownership | Endpoint/service/contract/consumer structure | Ownership/membership alone does not establish function use. |
| Impact | Modeled dependents of a proposed change | Symbol for function, file for whole-file boundary; preserve dynamic and cross-repository gaps. |
| Bundle | Selected context/evidence for a coding task/local model | Selection is not exhaustive impact or guaranteed full source bodies. |

For request-ID propagation, inspect the known handler, focused symbol impact and routing/contract ownership. Verify relevant call sites and payload rebuilding against source. Narrow handler impact alone does not cover every transport adapter, schema, runtime path or the full feature.

## Capabilities and actual response evidence

Customer `truthgraph_index_status` (helper `index-status --repository INDEXED_ID`) is read-only and bound to the published generation, repository commit and immutable embedding spec. Check it once per generation and reuse the result. `configured && capture_complete && complete` is required; eligible/embedded document memberships must match and pending/failed/missing capture/missing jobs must be zero. Excluded non-source files and oversized source omissions stay separate. An old successful scan or empty queue is not vector completeness. Do not request reindexing as read-only recovery.

Customer search accepts `mode: hybrid | lexical | semantic`, with hybrid default. Use a short natural-language task question when names are unknown, then an actual returned canonical subject. Inspect `discovery.mode`, `semantic_state`, embedding coverage and fallbacks. Exact/path selectors may legitimately report `not_requested`; that alone says nothing about embedding readiness. An inference failure must be reported as fallback, not an empty semantic success. The generation and revision are selected by the authenticated account; caller-supplied account/system/spec/revision filters remain invalid.

Newer customer responses advertise `context_capabilities`:

- `version` identifies the capability contract; it is independent of installed guidance.
- `implementation_languages` lists available server extractors, with `capability_scope: server_extractors_not_generation_coverage`. It does not establish that a repository generation was rescanned, that a file was parsed, or that extraction was complete.
- `source_bodies: false` means graph context does not promise source bodies. Verify relevant original source rather than retrying bundles to obtain bodies.
- `lookup: bounded_one_hop` and `bundle: bounded_selected_graph_evidence` describe existing retrieval modes, not new request selectors or complete feature coverage.

`returned_evidence` is scoped to `this_response_only`: `inventory_only`, `symbol_count`, `call_edge_count`, and `relationship_types` describe the records actually delivered. A zero call count is not proof that the source makes no calls. Preserve truncation and extraction gaps. Evidence outside the selected response may exist.

On older services, inspect the actual typed graph conservatively. A nonempty graph consisting only of File/Repository/RevisionState records and containment edges is inventory-only. An absent graph, empty unknown response, error or unrecognized entity type is **unknown**, not successful inventory or complete coverage. A source-backed symbol or non-containment relationship is implementation evidence, with its own provenance and confidence; it still may not answer the whole task.

When a file lookup returns only inventory, do not batch more similar file lookups or request repository-wide symbol inventory as an automatic repair. Select one exact implementation symbol when available, or one supported task-focused bundle if selected structural evidence can answer the question. If it is still inventory-only, use focused requested-commit source and disclose the gap. Reuse prior source reads and matching digests rather than restarting discovery.

## Versioned customer ranking

`customer-local-file-navigation/v4` applies to default all-kind natural-language hybrid searches with limits 1–8. It cycles distinct file leaders from captured-source term coverage, a pinned local TinyBERT passage reranker and the unchanged semantic search, in that fixed order. The order is a development-informed preference; it does not compare or add their different score scales. It has no SubQ dependency. A high local-model score or semantic similarity is relevance, not correctness or dependency confidence. Small general-purpose passage models can rank code poorly; verify the selected evidence.

The result unit is explicitly `file`. A file card keeps one actual canonical subject and may contain `match.file_group.companion`, one different subject from that same repository, indexed commit, path and source digest. Each subject retains its own identity, windows and graph meaning. These are separate subjects in a navigation container; they are neither aliases nor a combined entity. Up to five file cards can reference ten subjects. `returned_file_count` and `returned_subject_count` distinguish these counts. Use the exact subject relevant to the task for context; do not automatically expand both.

The primary file-card excerpt keeps the captured chunk limit. All companion excerpts and all additional windows share the existing 8,192-byte response budget. Truncation can omit a companion or its evidence. Hidden windows earn no fact coverage. `reranking_status:"complete"` identifies completed local ranking; `unavailable` or `not_configured` explicitly reports retained v2 subject ranking instead. Candidate/body overflow, busy service and deadlines do not silently become successful v4 ranking. Model tokenizer truncation is reported separately. Exact, quoted, path, explicit-kind, lexical-only and semantic-only requests retain their previous selector/result behavior; larger hybrid limits retain v2 subject results.

`customer-local-evidence/v2` uses normalized source names, paths and code for a cheap lexical candidate pass, then ranks distinct supported query terms using their frequency among pinned files in the bounded request. This is request-local specificity, not a corpus-wide statistic. Exact bare identifiers receive an exact indexed-name preference; an explicit implementation or contract intent uses supported source roles as a tie-break. Unknown roles stay neutral and generated bindings remain eligible. `body_term_coverage` and `query_term_coverage` describe matching terms across a subject's internally retained windows, up to eight; they do not measure answer completeness or guarantee those terms appear in the smaller delivered excerpts. `ranking_score` is the reciprocal final result position; it is not probability, dependency confidence or comparable with v1 scores. Raw rank-fusion values remain separate.

For ordinary prose, standalone implementation directives such as “implemented” and “call” express task intent rather than code topics when other topic terms remain. Their occurrence in a “not implemented” stub does not earn topic coverage. Parts of actual compound/code identifiers stay eligible, and a query containing only directive terms retains its original terms. `ranking_query_terms` and `ranking_ignored_intent_terms` expose this coverage denominator separately from the unchanged lexical query terms and embedding question. This is term matching, not a general interpretation of negation or code behavior.

Lexical and semantic hits for one subject retain their source windows. Bounded nearby captured windows can supply additional context from the same subject and pin. `source_selection` distinguishes direct lexical/semantic evidence from added context. A context window is not evidence that its own vector produced the subject's similarity score. Each primary/additional window has its own document, input/source digests, path and line bounds. `evidence_windows` contains at most three additional excerpts, with an 8,192-byte additional-excerpt cap across a response and explicit truncation. Separated windows do not include omitted intervening code. Use the relevant window to choose a pinned source read; fetching the selected file can complete the investigation without repeating broad discovery.

Strict alias groups cover identical **captured primary chunk bytes**, compatible entity families/roles and the same authorized repository/revision. They do not establish identical whole files, equivalent overloads or shared ownership. Each alias retains its canonical identity and source location. Additional windows and coverage belong to their actual representative; do not transfer another alias's omitted context or graph relationships. `evidence_windows_truncated` also reports when alias-specific windows were omitted. `aliases_total` counts other matches within bounded candidates; at most eight references are delivered and `aliases_truncated` reports the remainder. Do not expand every alias automatically or treat a missing alias as proof of absence.

Exact selectors, quoted/explicit web-search syntax and explicit semantic-only ordering retain their prior behavior. Older responses may contain `customer-fields-roles-chunk-aliases/v1` or omit ranking metadata. Preserve candidate truncation, source omissions, raw pins and embedding readiness independently of ranking. The offline inspector reports bounded orientation without copying source bodies, source IDs or alias records.

## Independent limits

- Discovery limit caps candidates; read `discovery.candidates_truncated` and resolution status. Operator lookup uses it for discovery, not graph depth. Customer inputs accept 1–100; the helper accepts 1–100 for ownership/get_endpoint_contract pages and 1–50 for other retrieval requests.
- Lookup is navigation: operator bounds use `filters.depth`, `max_entities`, `max_edges`; read `retrieval.truncated`. Customer lookup/neighborhood is forced to one hop and projects a bounded graph. Expand relevant exact subjects rather than treating preview neighbors as exhaustive.
- Bundle limits select items; lowering them may reduce delivered selection, but does not guarantee a smaller backend neighborhood or full feature coverage.
- Impact ignores candidate/result-count limit. An explicitly supported operator depth bound can leave a frontier; never call that exhaustive or repository-only.
- `coverage.traversal_complete` concerns the modeled frontier. Source omissions, dynamic dependencies, revision verification and delivered details remain separate.

## Bounded recovery

| Observation | Next action |
| --- | --- |
| Scoped discovery timeout | Prefer a known exact file/symbol. If the failed mode was semantic/hybrid, try one shorter scoped lexical query. If lexical already timed out, do not repeat it. Locate the subject with focused commit-pinned source reads, then optionally one exact graph read. Report the coverage gap. |
| Embeddings pending/unavailable | Use exact/lexical retrieval and read fallback metadata. Do not start workers, backfill or indexing. A lexical timeout does not establish an embedding cause. |
| No match / unresolved subject | Do not substitute a similar file or infer deletion. Verify requested-commit source; retrieval failure may prevent an existence check. |
| Inventory-only response | Stop similar neighborhood retries. Use a relevant known symbol or supported bounded bundle once when it adds task evidence, otherwise commit-pinned source; do not claim missing calls or complete extraction. |
| Lookup truncated / neighborhood deferred | Select an exact relevant returned subject and fetch immediate context. Use focused impact for changes; a lookup is not full dependency review. |
| Impact summary / size error | Follow actual capabilities in [impact-delivery.md](impact-delivery.md). Do not repeat broad requests or lower limit expecting impact closure to shrink. |
| Rate limit / busy / timeout | Avoid duplicate concurrent requests and retry loops. Honor Retry-After when provided; distinguish monthly allowance from transient busy. If blocked, use available source and disclose the gap. |

Record family, repository, subject, requested/indexed revision, error and unreviewed coverage. Retrieval timeout alone does not prove a runtime bug or corrupt index. Do not invent latency guarantees.

## Inspect without flooding context

The skill explicitly requests `view:"files"` on customer search/context/workflow for suggested paths/ranges/pins. Read source or request `presentation.full_request` for evidence; recheck pins. The API remains compatible: native MCP defaults to `presentation.view:"compact"` with `schema:"customer_evidence_v1"`. It preserves result shapes, ownership page edges/entities and provenance while removing diagnostic duplication and selected metadata. Search excerpts can be shortened: `excerpt_truncation` reports original/delivered UTF-8 bytes and `complete:false`; `presentation.source_evidence_omitted:true` flags this. Hidden source cannot support a fact. `presentation.omitted_fields` describes other removals. For needed omitted evidence, invoke the native tool named by `full_request.name` using `full_request.arguments`. This is a new query, not an immutable detail snapshot: recheck returned pin/generation before combining evidence. Retain the compact result too, and store/project full output before printing.

For an older service without this marker, use the already decoded retained value rather than fetching again. For example, project selected legacy evidence in memory:

```js
const v = load("tg:impact"), d = v.impact ?? v.canonical_data ?? v.context ?? v;
const graph = d.graph ?? {}, rows = d.impacted_entities ?? d.items ?? graph.entities ?? [];
const select = (x, keys) => Object.fromEntries(keys.filter(k => x?.[k] !== undefined).map(k => [k,x[k]]));
text({sample:true, records_in_payload:rows.length,
  records:rows.slice(0,5).map(x => ({...select(x,["subject","id","reference","family","relationships","evidence_kind","confidence_score","evidence_refs"]),
    entity:select(x.entity,["id","name","family"]),
    source:select(x.match ?? x.entity?.metadata ?? x.metadata,["path","source_revision","start_line","end_line","source_digest","excerpt"])})),
  revision:d.indexed_head ?? d.revision_scope, coverage:d.coverage ?? v.analysis?.coverage,
  delivery:v.delivery, retrieval:v.retrieval, freshness:v.freshness, source_coverage:v.source_coverage,
  warnings:[...(v.warnings ?? []),...(d.warnings ?? [])]});
```

This is an orientation sample, not full impact/ownership review. Select additional relevant records and their supporting edges from the retained original when a task fact needs them. Do not advance an ownership cursor after inspecting only a lossy page sample: evidence skipped in that page will not reappear on the next one. Preserve the full page, and stop without paging when the requested facts are already established. Unknown shapes require inspection of retained keys, not a claim that no evidence exists.

Save a bounded result privately:

```sh
python3 scripts/truthgraph.py context --repository INDEXED_ID --query EXACT_SUBJECT --intent lookup --output NEW_PRIVATE_FILE
python3 scripts/truthgraph.py inspect-result --input NEW_PRIVATE_FILE
```

Output writes a new owner-only file and prints a small receipt instead of graph content. The inspect-result command is offline: it reports revision/coverage, counts and continuation IDs, without dumping entities or source excerpts. Use focused local JSON processing for selected files and original evidence. Preserve saved pages/initial coverage until the task is complete, then remove temporary private data; never commit it.

Raw MCP wrappers must check isError before parsing. Use structuredContent when present, or parse text JSON once. Forward one representation: MCP can carry duplicate copies. Never print all `ALL_TOOLS` descriptions to discover one tool; filter names and inspect only a needed schema. Avoid printing a full setup/account/repository catalog when a known authorized query ID already suffices. Plain-text MCP errors are not successful malformed JSON and never empty impact sets.

Final answers should retain direct/inferred evidence, confidence, extractor/paths, requested/indexed source, omissions and traversal/delivery limits. State incomplete feature/dependency review. Include unresolved questions in local-model handoffs rather than hiding them to reduce token count.

## Customer ownership pages

Ownership (`truthgraph_context` intent `ownership`, or workflow `get_endpoint_contract`) returns a bounded relevant graph page. A page carries original provenance and a `retrieval.continuation_request` when relevant evidence remains. Repeat that request unchanged: the opaque cursor is bound to repository, root, query/subject, indexed revision, generation and explicit page limit. It is not authentication; the customer key and repository authorization are checked on every page.

Use `retrieval.has_more` and `traversal_complete` only to decide whether more evidence is available. A cursor does not require exhaustive page draining. Follow the chain for unresolved requested facts; otherwise stop and retain the cursor plus coverage limits. Merge repeated root/endpoint anchors by ID; edge evidence does not repeat across the chain. `truncated` may remain true on the final page because that single response does not contain every previous page. Traversal completeness is limited to its declared ownership scope, not arbitrary dependency closure.

The helper accepts `context --intent ownership --cursor TOKEN --limit N` and `workflow --workflow get_endpoint_contract --cursor TOKEN --limit N`, with the same query/subject/repository as the returned continuation request. Explicitly repeat the original limit; the helper refuses to substitute its default. Save pages with distinct `--output` paths. Cursors expire and may be evicted. HTTP410 means that page state is unavailable; preserve the prior pages and restart the original ownership request only if the task still needs it. Do not treat a missing cursor as an empty successful result or switch to another account/operator service.

Discovery `capture_state` describes capture readiness separately from `semantic_state`/phase errors. `excluded_documents_unit` labels source-entity exclusions; authoritative `index_status.excluded_files` counts whole files. A retrieval failure is not proof of absent chunks or embeddings. Phase budgets are separate from the bounded total request deadline; read the actual returned timing and fallback rather than assuming a fixed end-to-end latency.