---
title: code operations
---

The exact fields each `code.*` operation takes and returns.

<!-- Generated by `python scripts/codegen/docs_reference.py` from the op registry; edit the models, not this page. -->

Every op is `POST /v1/<op>` over HTTP and the MCP tool `loom_<op>`. The identity fields (`org`, `namespace`, `agent`, `user_id`, `session_id`) are filled from the token and the MCP session when a transport can; for an HTTP call with no token on a single-user server, the install's org on every op but `code.*` and `tracker.*` (which keep their plane's), and on [some ops](/zh-CN/reference/http-api#request) its namespace and agent; see [identities and namespaces](/zh-CN/concepts/identities-and-namespaces). The [operations index](/zh-CN/reference/operations) explains role, kind and the MCP `all` listing. Unknown input fields are served and named in `ignored_args`.

<!-- prettier-ignore-start -->

## `code.ask`

Ask a QUESTION about this codebase and get a grounded answer with [file:line] citations — 'how does TTL drop old rows', 'where is the memory limit enforced'.

`POST /v1/code.ask` · MCP `loom_code_ask` · role `viewer` · read

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | `''` | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `consumer` | `str` | `''` | trace attribution: which integration is calling (clickgap\|claude-code\|…) |
| `question` | `str` | required | The question to answer about the indexed code (grounded on a code.search of it). |
| `synthesize` | `bool` | `True` | False = retrieval-only (agent synthesizes); True = grounded server-side answer with citations, memoized across agents and invalidated when any cited file changes at merge. |
| `rerank` | `str` | `''` | Reranker for the retrieval: "" = the deployment default (LOOM_CODE_SEARCH_RERANK_DEFAULT), "none" = off for this request, "builtin:openai" / "builtin:cohere", or the name of an endpoint in LOOM_RERANK_ENDPOINTS_JSON (not a URL). |
| `no_cache` | `bool` | `False` | Skip the cache lookup and synthesize fresh (the fresh answer still refreshes the cache entry). |
| `token_budget` | `int \| None` | `None` | Retrieval context handed to synthesis, in tokens. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `answer` | `str` | The grounded answer text; "" on an abstain or when synthesize=false. |
| `partial` | `bool` | True when retrieval or provider limits prevent a complete response. |
| `partial_reason` | `str` | Sanitized reason for an incomplete response; empty when complete. |
| `note` | `str` | Caller-facing warning about missing retrieval or synthesis. |
| `coverage` | `Literal['', 'full', 'partial', 'none']` | Synthesis self-assessment, not verified correctness; empty on cached answers. |
| `citations` | `list[dict[str, Any]]` | The units the answer used (or was shown when none is cited): {path, start_line, end_line, symbol, unit_id} each; the retrieved units when synthesize=false. |
| `source` | `Literal['cached', 'synthesized', 'abstained']` | cached = served from the answer cache \| synthesized = answered now (or retrieval-only when synthesize=false) \| abstained = no grounded answer (`abstain_reason` says why). |
| `cache_similarity` | `float` | Cosine between this question and the served cached question; 0.0 unless source=cached. |
| `cache` | `str` | What the answer cache did. hit (a cached answer whose key, identifiers and files all matched) \| miss \| stale (the nearest entry's files, prompt version or age invalidated it) \| guarded (the nearest cached question names different… |
| `cache_saved_ms` | `int` | On a served entry: the synthesis wall (ms) and upstream cost (USD) the entry recorded when it was written, i.e. what this call did not pay. |
| `cache_saved_usd` | `float` | Upstream LLM cost in USD the served cache entry recorded; 0.0 when nothing was served. |
| `abstain` | `bool` | true when no grounded answer is returned; `abstain_reason` says why. |
| `abstain_reason` | `str` | Why it abstained (no strong match, off-repository question, ...); "" otherwise. |
| `retrieval_confidence` | `float` | The underlying code.search's calibrated confidence (0-1); 0.0 when it did not run. |
| `tokens_returned` | `int` | Estimated tokens of the answer text (characters / 4); 0 when there is no answer. |
| `context_tokens` | `int` | Retrieval context (tokens) the synthesis was grounded on; 0 for cached hits and abstains. |
| `trace_run_id` | `str` | Id of the loom.code_search_trace row the server writes for this call. |
| `as_of` | `dict[str, Any]` | Provenance + freshness: branch, commit, indexed_at, lag_commits (int, -1 unknown), stale (bool: lag > LOOM_CODE_STALE_AFTER_COMMITS). |

## `code.backport_gap`

Which release branches still carry the bug this fix removed, and the exact PR to cherry-pick there?

`POST /v1/code.backport_gap` · MCP `loom_code_backport_gap` · role `viewer` · read · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | `''` | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `consumer` | `str` | `''` | trace attribution: which integration is calling (clickgap\|claude-code\|…) |
| `pr_number` | `int` | `0` | The merged trunk fix to check; 0 = take it from `issue_number`. |
| `issue_number` | `int` | `0` | An issue the fix closes: the tracker graph's `fixes` edges name the PR. |
| `branches` | `list[str]` | *(computed)* | Release branches to check, as namespaces or versions (`26.4`), at most 8; empty = every configured release branch of the repository the caller can read. |
| `max_symbols` | `int` | `8` | At most this many touched functions (1–8) are looked up on each branch. |
| `exact` | `bool` | `False` | Hunk-level presence per branch, on request (one chunk read per branch and the fix's diff sections from the tracker record) |
| `history` | `bool` | `False` | For the branches the lines leave undecided, the fix's removed lines on the branch's own history in the mirror (git grep at the tip, git log -S over the first-parent history; at most 3 lines, 2 s per branch) — the pre-image at the tip is… |

| Output field | Type | Meaning |
| --- | --- | --- |
| `skipped_branches` | `list[dict[str, str]]` | Configured release branches this caller cannot read, skipped (never silently): [{namespace, reason}]. |
| `verdict` | `str` | gap \| pending \| covered \| not_affected \| unknown — the worst branch's word |
| `causes` | `list[str]` | tracker_unbound \| tracker_unavailable \| fix_not_found \| no_fix \| no_branches \| per-branch unknown reasons (deadline, no_index, no_branch_version, …) |
| `fix` | `dict[str, Any]` | {pr_number, title, url, base_branch, minor_version, merged_at, merge_sha, changelog_category, src_components, files, hunk_contexts, ledger} plus, under `exact`, `patch: {files, hunks, added, removed, symbols}` |
| `issue` | `dict[str, Any]` | from issue_number: {number, title, affected_versions, fix_versions, fixed_by} |
| `fixes` | `list[dict[str, Any]]` | every PR the issue's `fixes` edges name, with merged / backport flags |
| `symbols` | `list[str]` | the touched functions presence was tested with (from the hunk headers) |
| `files` | `list[str]` | the fix's source files (the file leg when no hunk named a function) |
| `branches` | `list[dict[str, Any]]` | one row per branch, gaps first, newest branch first: {namespace, branch, verdict, epistemic exact\|lower_bound, basis, reason, backport, presence, cherry_pick {pr_number, merge_sha}, evidence [...]}; under `exact`, presence.patch = {mode… |
| `summary` | `dict[str, list[str]]` | verdict → [branch versions] |
| `fix_candidate` | `dict[str, Any] \| None` | When no `fixes` edge named a trunk PR, the link pass's top candidate above LOOM_TRACKER_LINKS_MIN_SCORE stood in as the fix ({pr_number, score, rank, why, features, …, epistemic candidate}) and `fix.source` reads `candidate`; absent… |
| `tracker_namespace` | `str` | The tracker namespace bound to the trunk namespace that was read; "" when none is bound. |
| `tracker_unavailable` | `bool` | True when a tracker is bound but its read failed. |
| `ms` | `int` | Wall time of the whole read, in milliseconds. |
| `stage_ms` | `dict[str, int]` | {fix: ms of the record + ledger stage, presence: ms of the presence stage, patch: ms of the hunk-level stage (under `exact` only)} |
| `trace_run_id` | `str` | Id of this call's trace row; pass it to `code.outcome`. |

## `code.backport_gaps`

The set-wide backport report: which merged fixes labelled for backport does a release branch still owe?

`POST /v1/code.backport_gaps` · MCP `loom_code_backport_gaps` · role `viewer` · read · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | `''` | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `consumer` | `str` | `''` | trace attribution: which integration is calling (clickgap\|claude-code\|…) |
| `branch` | `str` | `''` | One release branch, as a namespace or a version (`26.6`); "" = every configured release branch the caller can read. |
| `wanted_only` | `bool` | `True` | Keep only the fixes labelled for backport; false also returns unlabelled fixes. |
| `days` | `int` | `90` | Only fixes merged in the last this many days (1–365). |
| `limit` | `int` | `500` | At most this many rows (1–5000). |

| Output field | Type | Meaning |
| --- | --- | --- |
| `skipped_branches` | `list[dict[str, str]]` | Configured release branches this caller cannot read, skipped (never silently): [{namespace, reason}]. |
| `branch` | `str` | the branch asked for ('' = every configured release branch) |
| `branch_namespace` | `str` | The namespace of the branch asked for; "" when every branch was read. |
| `branches` | `list[str]` | the release-branch namespaces the rows cover, newest first |
| `rows` | `list[dict[str, Any]]` | one row per (fix, branch), gaps first, wanted-on-this-branch first, newest fix first: {pr_number, title, merged_at, minor_version, branch, branch_namespace, verdict, epistemic, basis, reason, cherry_pick {pr_number, merge_sha}, backport_pr… |
| `counts` | `dict[str, int]` | verdict → rows returned |
| `counts_by_branch` | `dict[str, dict[str, int]]` | branch version → verdict → rows |
| `fixes` | `int` | How many distinct fixes the returned rows cover. |
| `wanted_only` | `bool` | Echo of the request's `wanted_only`. |
| `since` | `str` | The merge-time lower bound applied (ISO-8601 UTC): now minus `days`. |
| `computed` | `dict[str, Any]` | the table's state for this trunk: {fixes, rows, first_computed, last_computed} |
| `stale` | `bool` | no pass has written this trunk yet, or the last pass is older than two intervals |
| `ms` | `int` | Wall time of the read, in milliseconds. |

## `code.bisect_candidates`

Rank PRs that may have introduced a bug; Loom does not test or reproduce it.

`POST /v1/code.bisect_candidates` · MCP `loom_code_bisect_candidates` · role `viewer` · read · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | `''` | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `consumer` | `str` | `''` | trace attribution: which integration is calling (clickgap\|claude-code\|…) |
| `symbols` | `list[str]` | *(computed)* | Crashing frames from the stack trace (qualified symbol names, at most 12); the code index resolves them to files, and their specific bare names rank the diffs. |
| `paths` | `list[str]` | *(computed)* | Repo-relative source paths to scan (at most 20), beside the frames' files. |
| `patterns` | `list[str]` | *(computed)* | Greppable literals from the report (an error code, an identifier in the message, a setting name); with `issue_number` they are also derived from the issue's text. |
| `issue_number` | `int` | `0` | A tracker issue number: Loom reads but does not verify its previously recorded triage observations for the release range, its text for patterns, and its `caused_by` / `fixes` edges for the named culprit and fix. 0 = none. |
| `text` | `str` | `''` | The report's own words (title, body, error) when there is no tracker issue to read them from — they feed the fusion's vector and lexical legs and the suspects the report names. |
| `rerank` | `bool` | `False` | One LLM call reranks the fused top 20 (+~2 s); a weak fused top reranks without asking |
| `deadline_ms` | `int \| None` | `None` | Answer within this many milliseconds with the best candidates found so far. |
| `fix_pr` | `int` | `0` | The PR that fixed the regression, when one exists — its rewritten lines, blamed at its parent, name the change that broke them. |
| `bad_version` | `str` | `''` | The first release on which the caller or an upstream test observed the bug (`26.3`, or a full version cut to its minor); Loom does not test it, and the value wins over the issue's `reproduces_on`. "" = from the issue. |
| `before` | `str` | `''` | The inclusive upper bound of an approximate merge-time investigation window when release observations are unavailable; it narrows candidate history and does not mean Loom reproduced the bug. |
| `after` | `str` | `''` | Optional lower bound of the merge-time window (ISO-8601); must be earlier than `before`. |
| `bad_sha` | `str` | `''` | A commit (hex) whose commit time on the code mirror becomes `before` when `before` is unset; a sha the mirror lacks is refused with `BAD_SHA`. |
| `good_version` | `str` | `''` | The newest release that the caller or an upstream test observed as clean; Loom does not test it, and the value wins over the issue's `clean_on`. "" = from the issue, or a lookback from `bad_version`. |
| `widen_to_directories` | `bool` | `True` | widen the candidate set from the frames' files to their directories when frames or patterns can rank within it |
| `wideners` | `list[str]` | *(computed)* | What may bound the scan when no frame resolves to a file — `patterns` (the window's diffs carrying the issue's rarest identifiers), `component` (the directories the issue's component touches), `fix_candidate` (the fix's own files: the… |
| `rescan` | `bool` | `False` | Run the scan even when the record already names the culprit (an introducing commit or a `caused_by` edge) — to check a pin; `introduced_commit` / `named_by_graph` still say what the record holds |
| `limit` | `int` | `10` | At most this many candidates (1–25). |
| `marks` | `bool` | `True` | Marks on the candidates (backport, revert, reverted, re-land, whitespace / rename-only, touches_symbol, named); false returns the ranked candidate dicts unmarked |

| Output field | Type | Meaning |
| --- | --- | --- |
| `verdict` | `str` | candidates \| no_candidates \| already_bisected \| graph_named \| unknown |
| `candidates_from` | `str` | Where the candidates came from — `tracker` (its PR diff scan), `code_history` (loom's own PR ledger of the repository, when no tracker is linked or it holds no changed files), or `none` |
| `causes` | `list[str]` | Why the answer is thin or empty: tracker_unbound \| tracker_unavailable \| no_failing_version \| no_resolved_paths \| introduced_commit_known \| caused_by_edge. |
| `epistemic` | `str` | always lower_bound: the upstream file list and the diff text are what was searched; an empty answer excludes nothing |
| `candidates` | `list[dict[str, Any]]` | {pr_number, title, author, merged_at, minor_version, matched_paths, matched_symbols, matched_patterns, added_patterns, kind change\|meta, has_test, url, score, merge_commit_sha, merge_sha_source stored\|mirror\|"", named_by?}; with `marks`… |
| `marks` | `dict[str, Any]` | what the marks stage did: {status ok\|skipped\|ledger_failed, git_calls, demoted, promoted, relands} |
| `named_by_graph` | `list[int]` | PR numbers the tracker graph's `caused_by` edges name for the issue; when set, the candidates are these and no scan ran |
| `fix_blame` | `dict[str, Any]` | What blaming the fix's rewritten lines found — the fix, its parent, the ranges blamed and the PRs they name; absent without a fix |
| `fusion` | `dict[str, Any]` | What the fusion read — {window_prs, signals: {name: count}, suspects: {named, mentioned}, rerank?}; each fused candidate carries `why` (the signals that ranked it in their top 10); absent when fusion did not run. |
| `patterns` | `list[str]` | the greppable literals the ranking used (given ∪ derived from the issue) |
| `pattern_weights` | `dict[str, float]` | IDF over the issue corpus per pattern — what each is worth in the ranking; absent when the vocabulary was not read |
| `scope` | `str` | file \| directory \| patterns — how wide the candidate set was drawn |
| `widened_by` | `list[str]` | Which frameless wideners bounded the scan — patterns \| component \| fix_candidate — in the order they applied; absent when a frame or a path resolved |
| `dupcheck_fix` | `dict[str, Any]` | With no fix_pr and no issue, the duplicate check matched the report to a reported issue whose linked merged fix became fix_pr — {issue, fix_pr, match: duplicate, namespace}; absent otherwise |
| `component` | `str` | the issue's QA component and the directories it widened the scan to |
| `component_dirs` | `list[str]` | The directories the issue's component widened the scan to; absent when none did. |
| `dropped_after_report` | `int` | Scanned PRs merged AFTER the issue was opened — the fix, or nothing — left out of the list; absent when none was |
| `versions_searched` | `list[str]` | The release minors whose PRs were scanned; empty when a time window bounded it. |
| `bad_version` | `str` | The failing release the range used (given, else the issue's); "" when unknown. |
| `good_version` | `str` | The clean release the range used (given, else the issue's); "" when unknown. |
| `window` | `str` | clean_to_bad_plus_slack \| lookback_from_bad \| master_after_clean — how the release range was drawn |
| `hub_paths_dropped` | `list[str]` | hub files (Settings.cpp, CMake, docs, …) left out of the file filter |
| `resolved` | `list[dict[str, Any]]` | [{symbol, paths}] — what the code index resolved each frame to |
| `paths` | `list[str]` | The files the scan filtered on: fix files, given paths, the frames' files and the widening's, with hub files removed. |
| `frames` | `list[str]` | The bare frame names the diffs were ranked by: distinct, at least 6 characters, generic names dropped. |
| `issue` | `dict[str, Any]` | the issue's QA fact, as the tracker serves it, when issue_number was given |
| `introduced_commit` | `str` | The introducing commit the issue record holds; "" when none. |
| `fix_candidate` | `dict[str, Any] \| None` | The issue's probable fix from the link pass when no `caused_by` edge and no introducing commit exist (score above the floor) — or the record's own `fixes` edge (`source: record`); `paths_used` on it when its source files became the scan's… |
| `tracker_namespace` | `str` | The tracker namespace bound to this code namespace that was read; "" when none is bound. |
| `tracker_unavailable` | `bool` | True when a tracker is bound but its read failed. |
| `trace_run_id` | `str` | Id of this call's trace row; pass it to `code.outcome`. |
| `partial` | `bool` | `deadline_ms` cut an optional stage: the candidates are the best found in the budget, and `partial_reason` names the stages that did not run or finish. |
| `partial_reason` | `str` |  |
| `before` | `str` | The time window the scan ran under, when no release versions bounded it ("" otherwise). |
| `after` | `str` | The window's lower bound (ISO-8601 UTC); "" when releases bounded the scan or no lower bound was given. |

## `code.blame_range`

Which merged PRs last touched these lines, between release A and B?

`POST /v1/code.blame_range` · MCP `loom_code_blame_range` · role `viewer` · read · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | `''` | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `consumer` | `str` | `''` | trace attribution: which integration is calling (clickgap\|claude-code\|…) |
| `path` | `str` | required | The repo-relative file to blame (a leading `/` is stripped). |
| `start_line` | `int` | required | First line of the range, 1-based, at the window's upper end. |
| `end_line` | `int` | required | Last line, inclusive; a range over 400 lines is cut to 400 from `start_line`. |
| `from_version` | `str` | `''` | Window start as a release (`26.3` or a full tag version); "" with no `from_sha` = the oldest release cut. |
| `to_version` | `str` | `''` | Window end as a release; "" with no `to_sha` = this namespace's head. |
| `from_sha` | `str` | `''` | Window start as a commit sha; give a version or a sha, not both. |
| `to_sha` | `str` | `''` | Window end as a commit sha; give a version or a sha, not both. |
| `limit` | `int` | `10` | At most this many candidates (1–25). |
| `reviews_per_pr` | `int` | `3` | review comments per candidate inside the range (0 = none) |
| `stage` | `Literal['introduced', 'last_touched']` | `'introduced'` | introduced: rank toward the change that introduced the behaviour; last_touched: the blame order only |
| `mentions` | `str` | `''` | what misbehaves, in words: a candidate whose linked issue or title names them ranks first |

| Output field | Type | Meaning |
| --- | --- | --- |
| `verdict` | `str` | candidates \| no_candidates \| unknown \| introduced_unknown (stage introduced: blame saw no in-window line; the list is the file-touching fallback) |
| `causes` | `list[str]` | window_unresolved \| path_not_indexed \| blame_failed \| ledger_failed \| tracker_unavailable |
| `epistemic` | `str` | exact when the blame leg ran (line attribution), lower_bound when only the ledger answered (file-level) or the introduced stage is blameless |
| `stage` | `Literal['introduced', 'last_touched']` | the order `candidates` is in |
| `note` | `str` | What the answer can and cannot claim (last touched, not introduced), plus lines blame could not map to a PR. |
| `path` | `str` | The path blamed, normalized. |
| `path_indexed` | `bool` | True when the code index holds the path as a live file. |
| `range` | `dict[str, Any]` | {start, end, requested_end, truncated} |
| `window` | `dict[str, Any]` | {from_ref, to_ref, from_sha, to_sha, base_sha, from_time, to_time, sources{from,to: namespace_head\|mirror_ref\|sha\|default}, error} |
| `candidates` | `list[dict[str, Any]]` | ranked: {pr_number, title, author, merged_at, first_release, lines_blamed, share_of_range, touches_file, evidence blame\|ledger\|both, kind, merge_commit_sha, merge_sha_source stored\|mirror\|"", url, has_test?, caused_by?[], fixes?[]}; stage… |
| `last_touched` | `list[dict[str, Any]]` | the first stage's order, always: {pr_number, rank, lines_blamed, evidence} |
| `symbol` | `dict[str, Any]` | the enclosing function of the range when the index has one: {qualified_name, start_line, end_line} |
| `latest_pr` | `int` | the newest PR among those blame named (0 when none) |
| `lines` | `dict[str, Any]` | {total, attributed, noise, outside_window, unmapped} |
| `legs` | `dict[str, Any]` | {blame{status, warm, ms, window_commits, graph_truncated}, ledger{status, skipped: [{namespace, reason: not_readable}] when the trunk is unreadable}, introduced{status ok\|skipped, ms, git_calls, demoted, promoted, blameless}} |
| `first_release_basis` | `str` | How `first_release` was derived; "" when the mirror has no branch-cut tags. |
| `tracker_namespace` | `str` | The tracker namespace bound to this code namespace; "" when none is bound. |
| `tracker_unavailable` | `bool` | True when a tracker is bound but its read failed; the candidates stand without `has_test` / `caused_by` / `fixes`. |
| `trace_run_id` | `str` | Id of this call's trace row; pass it to `code.outcome`. |

## `code.calibrate`

Derive code-specific abstention thresholds from the authored probe corpus (query/positive/hard-distractor triples over the indexed repo) and persist them as this namespace's calibration.

`POST /v1/code.calibrate` · MCP `loom_code_calibrate` · role `admin` · write · audited · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | `''` | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `consumer` | `str` | `''` | trace attribution: which integration is calling (clickgap\|claude-code\|…) |

| Output field | Type | Meaning |
| --- | --- | --- |
| `noise_floor` | `float` | Cosine below which a hit is noise: the distractors' 90th percentile plus 0.02. |
| `abstain_threshold` | `float` | Cosine below which the search abstains: `noise_floor` plus 0.05. |
| `embedder_model` | `str` | The embedding model the probes ran against; the calibration applies to it. |
| `positives` | `int` | Query/positive pairs read from the probe corpus. |
| `distractors` | `int` | Query/distractor pairs read from the probe corpus. |

## `code.callees`

What does this symbol call — forward call edges (depth<=3), tier-marked like code.callers.

`POST /v1/code.callees` · MCP `loom_code_callees` · role `viewer` · read · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `include_lessons` | `bool` | `True` | Attach `lessons`: the memories about the answer's top files (for code.context_pack, a `task` briefing's only). |
| `lesson_namespaces` | `list[str]` | *(computed)* | The memory namespaces `lessons` reads besides the repository's team rules (over MCP the caller's memory home, filled in); one the caller cannot read is skipped. |
| `pr_files` | `dict[str, str]` | *(computed)* | Repo-relative path -> the file's full text at the PR's head, for the files the PR adds or modifies (at most 50, 1,000,000 characters each). |
| `pr_diff` | `str` | `''` | The PR's unified diff against its merge-base (at most 1,500,000 characters): its hunks say which functions the PR modifies, and its paths name the files it deletes. |
| `pr_head_sha` | `str` | `''` | The PR's head and base commits as the caller knows them; they label the answer (`overlay_head_sha`) and never reach git. '' = derived from the text. |
| `pr_base_sha` | `str` | `''` |  |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | `''` | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `consumer` | `str` | `''` | trace attribution: which integration is calling (clickgap\|claude-code\|…) |
| `name` | `str` | `''` | Bare, qualified or partly qualified name of the seed symbol, or `path:line` for the innermost function containing that line. |
| `symbol_id` | `str` | `''` | An index symbol id for the seed; wins over `name`. |
| `depth` | `int` | `1` | How many hops to walk out from the seed (1–3); 1 = direct callers / callees. |
| `max_nodes` | `int` | `200` | At most this many edges across all hops (1–500); `truncated` says when it held. |
| `min_confidence` | `float` | `0.0` | Drop parser-tier edges below this confidence. |
| `include_ambiguous` | `bool \| None` | `None` | Widen the answer from "what calls it" to "what MAY call it". |
| `candidate_min_confidence` | `float \| None` | `None` | Unset = on; candidates below `candidate_min_confidence` (default the deployment floor, 0.2) are counted in the block's note and not returned. 0 shows every site. |
| `pr_number` | `int` | `0` | An OPEN pull request whose head the mirror holds (`refs/pull/N/head`). |
| `edge_kinds` | `list[str]` | *(computed)* | The edge kinds the walk follows — a subset of calls \| inherits \| overrides \| fixture_use \| reads \| writes. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `lessons` | `list[dict[str, Any]]` | The memories about the answer's top files, best first, capped at `code_result_lessons_tokens`; each row {path, memory_key, namespace, excerpt, code_state}, with `changed_since` and `supersedes_key` when they apply. |
| `lessons_left_out` | `int` | How many rows about those files the lessons' token cap or a cut left out, with the rows another row read for the answer supersedes. |
| `edges` | `list[CodeEdgeWire]` | The call-graph edges found, hop by hop; the far end (`from_*` for callers, `to_*` for callees) is the answer. |
| `seed_symbols` | `list[str]` | Qualified names of the definitions the walk started from; empty when refused as ambiguous. |
| `overlay` | `bool` | On the wire only when `pr_number` was given. |
| `overlay_head_sha` | `str` | The PR head commit whose post-image was parsed; "" when there is no overlay. |
| `overlay_added` | `int` | How many functions the PR adds in its parsed files. |
| `overlay_note` | `str` | Why the overlay is off: `head_not_in_mirror`, `no_merge_base` or `no_repo_entry`; when it is on, "" or how many changed files it did not fully read. |
| `resolved_by` | `str` | How an over-qualified name bound when the exact form missed — `anonymous_namespace` (`(anonymous namespace)::` segments stripped) or `tail` (a namespace the definition does not carry dropped; one definition fit), or `registration` when a… |
| `ambiguous` | `bool` | A bare short name that resolves to many unrelated definitions (setColumns on 60 classes) is not walked: `ambiguous` is set, `candidates` lists the qualified names to pick from, and edges is empty. |
| `candidates` | `list[str]` | With `ambiguous`: up to 20 qualified names to pick from. |
| `dispatch_seeds` | `list[dict[str, str]]` | Virtual dispatch: when the seed is an override, calls in the code go to the BASE declaration, so its callers are included and listed here as {"symbol", "via": "overrides" \| "inherits"}. |
| `note` | `str` | Plain-text notes on how the walk ran: dispatch or member folding, the ambiguity refusal, declined call sites, stale compiler-tier files; "" when none apply. |
| `truncated` | `bool` | True when the walk stopped short: `max_nodes` held or a hop's edge read hit its cap. |
| `counts_floor` | `bool` | Epistemic contract: edge counts are FLOORS, never totals. |
| `unresolved_calls` | `int` | HOW LOW the floor may be (callers direction): call sites in the fast tier's files whose callee is NAMED like the seed but which the resolver declined to bind — `unresolved` (no definition of that name in the index) or `ambiguous` (several… |
| `ambiguous_calls` | `int` | Declined call sites named like the seed with several same-named definitions, none pinned (see `unresolved_calls`). |
| `epistemic` | `str` | Epistemic envelope. |
| `causes` | `list[str]` | Why `epistemic` is `lower_bound`, from the set above; empty when it is `exact`. |
| `by_hop_counts` | `dict[int, int]` | Distinct symbols reached per hop BEFORE any slicing: {1: n, 2: m}. |
| `candidate_sites` | `CodeCandidateSitesWire \| None` | Declined call sites as ranked candidates, on request only (`include_ambiguous`). |
| `trace_run_id` | `str` | Id of this call's trace row; pass it to `code.outcome`. |

## `code.callers`

Who calls this symbol — exact reverse call edges (depth<=3), compiler-resolved where available; `edge_kinds: ['inherits']` narrows the walk to what implements or extends a type.

`POST /v1/code.callers` · MCP `loom_code_callers` · role `viewer` · read

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `include_lessons` | `bool` | `True` | Attach `lessons`: the memories about the answer's top files (for code.context_pack, a `task` briefing's only). |
| `lesson_namespaces` | `list[str]` | *(computed)* | The memory namespaces `lessons` reads besides the repository's team rules (over MCP the caller's memory home, filled in); one the caller cannot read is skipped. |
| `pr_files` | `dict[str, str]` | *(computed)* | Repo-relative path -> the file's full text at the PR's head, for the files the PR adds or modifies (at most 50, 1,000,000 characters each). |
| `pr_diff` | `str` | `''` | The PR's unified diff against its merge-base (at most 1,500,000 characters): its hunks say which functions the PR modifies, and its paths name the files it deletes. |
| `pr_head_sha` | `str` | `''` | The PR's head and base commits as the caller knows them; they label the answer (`overlay_head_sha`) and never reach git. '' = derived from the text. |
| `pr_base_sha` | `str` | `''` |  |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | `''` | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `consumer` | `str` | `''` | trace attribution: which integration is calling (clickgap\|claude-code\|…) |
| `name` | `str` | `''` | Bare, qualified or partly qualified name of the seed symbol, or `path:line` for the innermost function containing that line. |
| `symbol_id` | `str` | `''` | An index symbol id for the seed; wins over `name`. |
| `depth` | `int` | `1` | How many hops to walk out from the seed (1–3); 1 = direct callers / callees. |
| `max_nodes` | `int` | `200` | At most this many edges across all hops (1–500); `truncated` says when it held. |
| `min_confidence` | `float` | `0.0` | Drop parser-tier edges below this confidence. |
| `include_ambiguous` | `bool \| None` | `None` | Widen the answer from "what calls it" to "what MAY call it". |
| `candidate_min_confidence` | `float \| None` | `None` | Unset = on; candidates below `candidate_min_confidence` (default the deployment floor, 0.2) are counted in the block's note and not returned. 0 shows every site. |
| `pr_number` | `int` | `0` | An OPEN pull request whose head the mirror holds (`refs/pull/N/head`). |
| `edge_kinds` | `list[str]` | *(computed)* | The edge kinds the walk follows — a subset of calls \| inherits \| overrides \| fixture_use \| reads \| writes. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `lessons` | `list[dict[str, Any]]` | The memories about the answer's top files, best first, capped at `code_result_lessons_tokens`; each row {path, memory_key, namespace, excerpt, code_state}, with `changed_since` and `supersedes_key` when they apply. |
| `lessons_left_out` | `int` | How many rows about those files the lessons' token cap or a cut left out, with the rows another row read for the answer supersedes. |
| `edges` | `list[CodeEdgeWire]` | The call-graph edges found, hop by hop; the far end (`from_*` for callers, `to_*` for callees) is the answer. |
| `seed_symbols` | `list[str]` | Qualified names of the definitions the walk started from; empty when refused as ambiguous. |
| `overlay` | `bool` | On the wire only when `pr_number` was given. |
| `overlay_head_sha` | `str` | The PR head commit whose post-image was parsed; "" when there is no overlay. |
| `overlay_added` | `int` | How many functions the PR adds in its parsed files. |
| `overlay_note` | `str` | Why the overlay is off: `head_not_in_mirror`, `no_merge_base` or `no_repo_entry`; when it is on, "" or how many changed files it did not fully read. |
| `resolved_by` | `str` | How an over-qualified name bound when the exact form missed — `anonymous_namespace` (`(anonymous namespace)::` segments stripped) or `tail` (a namespace the definition does not carry dropped; one definition fit), or `registration` when a… |
| `ambiguous` | `bool` | A bare short name that resolves to many unrelated definitions (setColumns on 60 classes) is not walked: `ambiguous` is set, `candidates` lists the qualified names to pick from, and edges is empty. |
| `candidates` | `list[str]` | With `ambiguous`: up to 20 qualified names to pick from. |
| `dispatch_seeds` | `list[dict[str, str]]` | Virtual dispatch: when the seed is an override, calls in the code go to the BASE declaration, so its callers are included and listed here as {"symbol", "via": "overrides" \| "inherits"}. |
| `note` | `str` | Plain-text notes on how the walk ran: dispatch or member folding, the ambiguity refusal, declined call sites, stale compiler-tier files; "" when none apply. |
| `truncated` | `bool` | True when the walk stopped short: `max_nodes` held or a hop's edge read hit its cap. |
| `counts_floor` | `bool` | Epistemic contract: edge counts are FLOORS, never totals. |
| `unresolved_calls` | `int` | HOW LOW the floor may be (callers direction): call sites in the fast tier's files whose callee is NAMED like the seed but which the resolver declined to bind — `unresolved` (no definition of that name in the index) or `ambiguous` (several… |
| `ambiguous_calls` | `int` | Declined call sites named like the seed with several same-named definitions, none pinned (see `unresolved_calls`). |
| `epistemic` | `str` | Epistemic envelope. |
| `causes` | `list[str]` | Why `epistemic` is `lower_bound`, from the set above; empty when it is `exact`. |
| `by_hop_counts` | `dict[int, int]` | Distinct symbols reached per hop BEFORE any slicing: {1: n, 2: m}. |
| `candidate_sites` | `CodeCandidateSitesWire \| None` | Declined call sites as ranked candidates, on request only (`include_ambiguous`). |
| `trace_run_id` | `str` | Id of this call's trace row; pass it to `code.outcome`. |

## `code.context_pack`

Briefing at the START of a task, instead of exploring file by file.

`POST /v1/code.context_pack` · MCP `loom_code_context_pack` · role `viewer` · read

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `include_lessons` | `bool` | `True` | Attach `lessons`: the memories about the answer's top files (for code.context_pack, a `task` briefing's only). |
| `lesson_namespaces` | `list[str]` | *(computed)* | The memory namespaces `lessons` reads besides the repository's team rules (over MCP the caller's memory home, filled in); one the caller cannot read is skipped. |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | `''` | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `consumer` | `str` | `''` | trace attribution: which integration is calling (clickgap\|claude-code\|…) |
| `pr_number` | `int` | `0` | Indexed merged PR -> precomputed pack; 0 -> orientation map; unknown PR -> explicit abstention. ge=0 because a negative number would reach ClickHouse as a UInt32 bind and surface as a 500. |
| `task` | `str` | `''` | The change about to be made ("add a new tracker op"). |
| `token_budget` | `int` | `2500` | Token budget for `context` (200..8000): a precomputed pack is cut to it, a task briefing or orientation map is built within it. |
| `sections` | `list[Literal['symbols', 'co_change', 'tests', 'reviews', 'prs', 'qa', 'files']]` | *(computed)* | Precomputed packs only. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `lessons` | `list[dict[str, Any]]` | The memories about the answer's top files, best first, capped at `code_result_lessons_tokens`; each row {path, memory_key, namespace, excerpt, code_state}, with `changed_since` and `supersedes_key` when they apply. |
| `lessons_left_out` | `int` | How many rows about those files the lessons' token cap or a cut left out, with the rows another row read for the answer supersedes. |
| `context` | `str` | The pack as Markdown text; for `unavailable`, a short note saying the PR has no pack yet. |
| `tokens_used` | `int` | Estimated tokens of `context`. |
| `source` | `Literal['precomputed', 'task', 'orientation', 'unavailable']` | precomputed (the PR's stored pack) \| task (a briefing for `task`) \| orientation (the repository map) \| unavailable (no pack for the PR). |
| `truncated` | `bool` | True when a precomputed pack was cut to `token_budget`; false for the other sources. |
| `merge_commit_sha` | `str` | The PR's merge commit, for a precomputed pack; '' otherwise. |
| `trace_run_id` | `str` | Id of this call's trace row; pass it to `code.outcome`. |

## `code.context_packs`

List the stored per-PR context packs of a repository, optionally for one PR.

`POST /v1/code.context_packs` · MCP `loom_code_context_packs` · role `viewer` · read · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | `''` | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `consumer` | `str` | `''` | trace attribution: which integration is calling (clickgap\|claude-code\|…) |
| `limit` | `int` | `50` | At most this many packs per page, newest first (1..200). |
| `offset` | `int` | `0` | Packs to skip before the page starts. |
| `pr_number` | `int` | `0` | Optional exact PR filter (0 = all). |

| Output field | Type | Meaning |
| --- | --- | --- |
| `rows` | `list[CodeContextPackRow]` | Live packs, newest built first; title, author and merged_at are '' when the PR history lacks the PR. |
| `total` | `int` | Every live pack matching the filter, not only this page. |

## `code.conventions`

The repository's recurring maintainer checks as facts over one PR's diff: a setting added or re-defaulted without a SettingsChangesHistory entry; the same setting's docs mention; a new…

`POST /v1/code.conventions` · MCP `loom_code_conventions` · role `viewer` · read · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | `''` | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `consumer` | `str` | `''` | trace attribution: which integration is calling (clickgap\|claude-code\|…) |
| `pr_number` | `int` | `0` | A merged PR in the ledger: its title, labels and merge commit's diff are checked; 0 = none. |
| `head_sha` | `str` | `''` | A commit the mirror holds: the diff from its merge-base with the branch tip is checked; falls back to the ledger's merge commit when the mirror lacks it. |
| `files` | `list[str]` | *(computed)* | An open PR's changed paths; with `diff` they replace any ledger file list. |
| `diff` | `str` | `''` | An open PR's unified diff; its hunks are what the rules check (with `files`). |
| `rules` | `list[str]` | *(computed)* | The rules to run (names from the conventions rule table); empty = every rule. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `pr_number` | `int` | The PR asked about; 0 when none was named. |
| `source` | `str` | ledger \| head_sha \| supplied |
| `title` | `str` | The ledger PR's title; '' when the PR is not in the ledger or none was named. |
| `labels` | `list[str]` | The ledger PR's labels. |
| `category` | `str` | bug_fix \| improvement \| new_feature \| performance \| not_for_changelog \| build \| ci \| documentation \| backward_incompatible \| experimental \| '' |
| `category_source` | `str` | Where `category` came from: `label:<name>`, `changelog_bullet` (the PR body), or ''. |
| `merged_at` | `str` | When the ledger PR merged; '' without a ledger row. |
| `merge_commit_sha` | `str` | The ledger PR's merge commit; '' without a ledger row. |
| `head_sha` | `str` | The commit the diff was read at when `source` is head_sha; otherwise the `head_sha` sent. |
| `files_total` | `int` | Changed paths known for the change (name-status list plus the diff's files). |
| `files_in_diff` | `int` | Files whose hunks were parsed from the diff; fewer than `files_total` when it was cut. |
| `diff_bytes` | `int` | Size of the diff text read, in characters; 0 without a diff. |
| `diff_truncated` | `bool` | True when the mirror diff hit `code_conventions_diff_max_bytes` and its last file was dropped; `notes` says how many files were parsed. |
| `rules` | `list[dict[str, Any]]` | [{rule, verdict: violated\|satisfied\|not_applicable\|unknown\|unusual, evidence: [{path, line, text, ...}], epistemic: exact\|lower_bound, note}] |
| `summary` | `dict[str, int]` | verdict -> count over `rules` |
| `control` | `dict[str, Any]` | {coverage_symbol, ok, ran}: the coverage control rule 7 depends on |
| `notes` | `list[str]` | Why part of the answer is weaker: PR not in the ledger, merged into another branch, commit not in the mirror, diff cut, supplied-diff pre-image; empty when none applies. |
| `trace_run_id` | `str` | Id of this call's trace row; pass it to `code.outcome`. |

## `code.coverage`

Report how much of a repository the index covers at its head: per language, per tier, and the gaps.

`POST /v1/code.coverage` · MCP `loom_code_coverage` · role `viewer` · read

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | `''` | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `consumer` | `str` | `''` | trace attribution: which integration is calling (clickgap\|claude-code\|…) |

| Output field | Type | Meaning |
| --- | --- | --- |
| `org` | `str` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | The namespace the op reads or writes. |
| `as_of_commit` | `str` | git_head |
| `languages` | `list[CodeLanguageCoverage]` | One row per language, the most files first. |
| `tiers` | `list[CodeTierCoverage]` | Call-graph edge counts per tier. |
| `gaps` | `CodeCoverageGaps \| None` | None when the gap queries failed — absence, never a fabricated zero. |
| `pr_history_from` | `str` | The oldest merge time among the stored merged PRs; '' when none are stored. |
| `pr_history_to` | `str` | The newest merge time among the stored merged PRs; '' when none are stored. |
| `pr_history_last_fetch_at` | `str` | When the PR-history poller last wrote a row; '' never. |
| `pr_history_enabled` | `bool` | Whether the PR-history poller is enabled on this deployment. |
| `pr_history_auth` | `str` | token \| anonymous (60 req/h GitHub limit) |
| `context_packs_last_at` | `str` | When the newest live PR context pack was built; '' when none exists. |
| `summaries_last_at` | `str` | When the newest chunk context description was written; '' when none exists. |

## `code.coverage.unwatch`

Cancel a coverage watch on a commit.

`POST /v1/code.coverage.unwatch` · MCP `loom_code_coverage_unwatch` · role `viewer` · idempotent · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | `''` | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `consumer` | `str` | `''` | trace attribution: which integration is calling (clickgap\|claude-code\|…) |
| `commit` | `str` | required | The watched commit: a full 40-hex SHA, or a 7..39-hex abbreviation the mirror resolves. |
| `inbox` | `str` | required | The inbox the watch posts to; the caller must be a writer on its owner namespace. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `commit` | `str` | The full SHA the abbreviation resolved to. |
| `inbox` | `str` | The inbox, as sent. |
| `removed` | `bool` | False when no live watch existed. |

## `code.coverage.watch`

Ask for a task-inbox message when the index covers a commit, instead of polling for it.

`POST /v1/code.coverage.watch` · MCP `loom_code_coverage_watch` · role `viewer` · idempotent · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | `''` | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `consumer` | `str` | `''` | trace attribution: which integration is calling (clickgap\|claude-code\|…) |
| `commit` | `str` | required | Merge commit SHA to watch. |
| `inbox` | `str` | required | Task inbox that receives the code.coverage.ready event; the caller must be a writer on its owner namespace. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `org` | `str` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | The namespace the op reads or writes. |
| `commit` | `str` | the full SHA |
| `inbox` | `str` | The inbox the event is posted to, as sent. |
| `ready` | `bool` | True once every tier covers the commit; the event is then on the inbox. |
| `emitted` | `bool` | True when this call posted the event (an already-covered commit). |
| `delivered_at` | `datetime \| None` | When the ready event was posted to the inbox; None while the commit is not covered. |
| `event_id` | `str` | The event's task_id on the inbox, fixed per (namespace, commit, inbox). |
| `commit_coverage` | `CodeCommitCoverage \| None` | The commit's per-tier coverage at this call, as `code.index_status` reports it. |

## `code.coverage_claim`

Is this already tested?

`POST /v1/code.coverage_claim` · MCP `loom_code_coverage_claim` · role `viewer` · read · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | `''` | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `consumer` | `str` | `''` | trace attribution: which integration is calling (clickgap\|claude-code\|…) |
| `symbol` | `str` | `''` | The subject as a symbol name (qualified or bare) or a SQL-level function name. |
| `path` | `str` | `''` | The subject as a repository-relative source path. |
| `setting` | `str` | `''` | The subject as a setting name. |
| `limit` | `int` | `20` | At most this many `tests` rows (at most 100). |

| Output field | Type | Meaning |
| --- | --- | --- |
| `subject` | `str` | The subject as given (the one of symbol, path, setting that was set). |
| `subject_kind` | `str` | symbol \| path \| setting |
| `verdict` | `str` | covered_by \| weak_evidence \| uncovered \| unknown |
| `tests` | `list[dict[str, Any]]` | {test_path, methods: [...], tier, confidence, evidence} |
| `tests_total` | `int` | Tests found before `limit` (the larger of the rows and the grep's match count). |
| `src_paths` | `list[str]` | The source files the subject lives in: the path itself, the files defining the resolved symbol (first 20), or [] for a setting. |
| `epistemic` | `str` | exact when a test names the subject or the include graph reaches it; lower_bound when only mined co-occurrence or a path convention says so |
| `strongest_tier` | `str` | The strongest evidence tier among the rows (executed \| exact_scoped \| pr_cooccurrence \| short_name_grep \| file_reference \| path_convention), '' when no test was found. |
| `search_terms` | `dict[str, str]` | The literals the grep ran, each with the tier a hit counts as — the SQL names the class registers and the qualified form are `exact_scoped`, the bare method name `short_name_grep`. |
| `resolved_by` | `str` | `registration` when the subject was a SQL-level name bound to its implementing class through the registration statement; '' and off the wire otherwise. |
| `control` | `dict[str, Any]` | {symbol, ok[, via]}: the positive control this call ran; ok=False ⇒ unknown. |
| `measured` | `dict[str, Any]` | Imported execution evidence, {} when none exists: measured, executed, paths, hits, commit (empty for mixed commits), commits, index_commit, run_current, files (per-path commit, indexed_commit, symbol_commits, freshness), freshness… |
| `trace_run_id` | `str` | Id of this call's row in `loom.code_search_trace`. |

## `code.enclosing`

Batched `path:line` -> enclosing function.

`POST /v1/code.enclosing` · MCP `loom_code_enclosing` · role `viewer` · read

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | `''` | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `consumer` | `str` | `''` | trace attribution: which integration is calling (clickgap\|claude-code\|…) |
| `locations` | `list[str]` | required | "src/Foo.cpp:123" — repo-relative path, 1-based line. |
| `include_body` | `bool` | `False` | include_body: ship the enclosing function's whole body with each resolved location, so a grep hit becomes the function it sits in without a follow-up code.symbol or a file read (most index answers are otherwise followed by a read of the… |
| `token_budget` | `int` | `4000` | With `include_body`: token budget for the bodies (200..12000); bodies past it ship elided. |
| `neighbours` | `bool \| None` | `None` | neighbours: a graph evidence block per distinct enclosing function: up to neighbour_k callers, callees (compiler tier preferred, symbols outside the repo dropped, parser guesses below 0.8 confidence dropped) and mapped tests, the module… |
| `neighbour_k` | `int` | `5` | With `neighbours`: at most this many callers and callees per function (1..20). |

| Output field | Type | Meaning |
| --- | --- | --- |
| `results` | `list[dict[str, Any]]` | one entry per input location, input order preserved: {path, line, symbol, symbol_id, qualified_name, signature, tier, kind, start_line, end_line} kind is "function" / "method" / "fixture" for a line inside a function body; "class"… |
| `resolved` | `int` | Locations that landed inside a function, type, or document section. |
| `paths_indexed` | `int` | distinct input paths that have any symbol rows |
| `paths_total` | `int` | Distinct paths among the parseable input locations. |
| `took_ms` | `int` | Server-side wall time of the call, in milliseconds. |
| `as_of` | `dict[str, Any]` | Provenance + freshness: branch, commit, indexed_at, lag_commits (int, -1 unknown), stale (bool: lag > LOOM_CODE_STALE_AFTER_COMMITS). |
| `bodies_returned` | `int` | include_body accounting: distinct bodies served / withheld for budget |
| `bodies_elided` | `int` | Distinct bodies withheld because `token_budget` ran out. |
| `tokens_returned` | `int` | include_body bodies + the neighbours block, in tokens |
| `neighbours` | `list[dict[str, Any]]` | neighbours=true: one entry per distinct enclosing function in first- appearance order, at most 20: {symbol_id, qualified_name, path, module, callers: [qualified names], callees: [...], tests: [paths], epistemic, causes}. |
| `anchors` | `int` | distinct enclosing functions the block covers |
| `anchors_capped` | `bool` | more resolved functions than the 20 cap |
| `neighbour_tokens` | `int` | Tokens of the neighbours block alone; 0 when `neighbours` is off. |

## `code.examples`

Real call sites of a symbol, ranked test-covered-first — a current, tested usage example beats the deprecated one grep finds first.

`POST /v1/code.examples` · MCP `loom_code_examples` · role `viewer` · read · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | `''` | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `consumer` | `str` | `''` | trace attribution: which integration is calling (clickgap\|claude-code\|…) |
| `name` | `str` | `''` | The symbol: a qualified name or a `path:line` inside it; ignored when `symbol_id` is set. |
| `symbol_id` | `str` | `''` | The symbol's id from an earlier code.* answer; wins over `name`. |
| `top_k` | `int` | `3` | At most this many call sites (1..10). |

| Output field | Type | Meaning |
| --- | --- | --- |
| `examples` | `list[dict[str, Any]]` | Call sites, test-covered callers first: {caller, path, line, tier, test_covered, body}, body = the smallest chunk around the line (up to 4,000 chars, '' when none). |
| `trace_run_id` | `str` | Id of this call's trace row; pass it to `code.outcome`. |

## `code.files`

Which indexed files have this NAME — an rg-style glob (`tests/queries/0_stateless/05138_*`, `/*Parquet*.cpp`), a basename stem (`05138_with_fill` matches the stem exactly or as its leading prefix…

`POST /v1/code.files` · MCP `loom_code_files` · role `viewer` · read · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | `''` | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `consumer` | `str` | `''` | trace attribution: which integration is calling (clickgap\|claude-code\|…) |
| `glob` | `str` | `''` | An rg-style glob over the repo-relative path (`/*Parquet*.cpp`); '' = no glob filter. |
| `stem` | `str` | `''` | A basename without extension, matched exactly or as its leading prefix; exact matches sort first. '' = no stem filter. |
| `path_prefix` | `str` | `''` | Only paths under this prefix; '' = no prefix filter. |
| `limit` | `int` | `50` | At most this many files (1..500). |

| Output field | Type | Meaning |
| --- | --- | --- |
| `files` | `list[dict[str, Any]]` | {path, lang, size_bytes, loc, indexed_commit}; exact stem matches first, then path order. |
| `total` | `int` | matching files before `limit` |
| `truncated` | `bool` | True when `total` is larger than the files returned. |
| `as_of` | `dict[str, Any]` | Provenance + freshness: branch, commit, indexed_at, lag_commits (int, -1 unknown), stale (bool: lag > LOOM_CODE_STALE_AFTER_COMMITS). |
| `not_covered` | `bool` | True when `path_prefix` lies outside the indexed prefixes; `files` is then empty. |
| `note` | `str` | With `not_covered`: which prefixes the index holds; '' otherwise. |
| `trace_run_id` | `str` | Id of this call's trace row ('' on a not_covered answer); pass it to `code.outcome`. |

## `code.first_build`

Which CI build first carried this commit?

`POST /v1/code.first_build` · MCP `loom_code_first_build` · role `viewer` · read · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | `''` | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `consumer` | `str` | `''` | trace attribution: which integration is calling (clickgap\|claude-code\|…) |
| `sha` | `str` | `''` | A commit sha, 7–40 hex characters; an abbreviated one is expanded on the mirror. |
| `pr_number` | `int` | `0` | A merged PR; the ledger supplies its merge commit and time. 0 = use `sha`. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `verdict` | `str` | built \| not_yet_built \| unknown |
| `causes` | `list[str]` | tracker_unbound \| tracker_unavailable \| sha_unknown \| candidates_exhausted \| pr_not_merged |
| `epistemic` | `str` | exact: a run names the sha (or the PR's own head builds); lower_bound: the earliest of ≤ 10 checked bases descends from it |
| `sha` | `str` | The full commit sha the answer is about (from the input, the mirror or the ledger). |
| `pr_number` | `int` | The PR the commit merged, from the input or the ledger; 0 when unknown. |
| `merged_at` | `str` | When the PR merged, from the ledger (ISO-8601); "" when the ledger has no row. |
| `commit_time` | `str` | The commit's time on the mirror (ISO-8601); "" when the mirror lacks the sha. |
| `ledger_known` | `bool` | True when the PR ledger knows the subject. |
| `mirror_known` | `bool` | True when the code mirror holds the commit. |
| `first_build` | `dict[str, Any]` | {kind named\|carrier\|own, check_start_time, version, docker_tag, minor_version, git_ref, pull_request_number, commit_sha, base_sha} |
| `lag_hours` | `float \| None` | hours from the merge (or commit) to the first carrying run |
| `later_builds` | `int` | runs started after it inside the window (later bases not individually checked) |
| `window_hours` | `int` | How many hours after the merge (or commit) runs are read for carriers. |
| `candidates_checked` | `int` | How many run bases were checked on the mirror for descent from the commit. |
| `candidates_total` | `int` | How many candidate run bases the window held. |
| `own_builds` | `list[dict[str, Any]]` | the PR's own head builds, oldest first (≤ 8) |
| `containing_branches` | `list[str]` | mirror branches whose head contains the sha, and the namespaces on them |
| `containing_namespaces` | `list[str]` | The repository's namespaces whose branch contains the commit. |
| `nearest_namespace` | `str` | the lowest release-branch namespace containing it, else the own branch's |
| `note` | `str` | What the tracker's build view can show; "" when the tracker was not read. |
| `tracker_namespace` | `str` | The tracker namespace bound to this code namespace; "" when none is bound. |
| `tracker_unavailable` | `bool` | True when a tracker is bound but its read failed. |
| `trace_run_id` | `str` | Id of this call's trace row; pass it to `code.outcome`. |

## `code.grep`

Exact-match lookup over the indexed corpus.

`POST /v1/code.grep` · MCP `loom_code_grep` · role `viewer` · read

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | `''` | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `consumer` | `str` | `''` | trace attribution: which integration is calling (clickgap\|claude-code\|…) |
| `pattern` | `str` | required | The text to find: a literal substring, or an RE2 expression with `regex`. |
| `regex` | `bool` | `False` | True reads `pattern` as RE2; an invalid expression is a 422. |
| `case_sensitive` | `bool` | `True` | False matches `pattern` regardless of letter case. |
| `path_prefix` | `str` | `''` | Only paths under this repo-relative prefix; '' = the whole index. |
| `cursor` | `str` | `''` | Continuation (matches mode): the `next_cursor` of an earlier response to this pattern; the next page of matching lines is one point read of what the first call extracted. |
| `exclude_unit_ids` | `list[str]` | *(computed)* | The caller's seen-set. |
| `mode` | `Literal['matches', 'files', 'presence', 'message']` | `'matches'` | matches: up to `limit` matching LINES with text + enclosing scope. files: up to `limit` matching FILES (path, matching chunk count, first line) and no line text — the coverage question ("which files mention X?") that a 20-line cap cannot… |
| `limit` | `int \| None` | `None` | Default depends on mode: 20 lines, or the 500-file ceiling — a files answer capped at 20 reads like a complete coverage answer to a caller that did not know to send a limit. matches mode is clamped to 200 lines. |
| `path_globs` | `list[str]` | *(computed)* | File filters, rg `-g` / `-t` style: keep paths matching any glob, drop paths matching any exclude, restrict to a language's extension set. |
| `exclude_globs` | `list[str]` | *(computed)* | Drop paths matching any of these rg-style globs. |
| `langs` | `list[str]` | *(computed)* | Keep only files with these languages' extensions (rg `-t` names: cpp, py, ts, go, …); an unknown name is a 422 that lists the known ones. |
| `namespaces` | `list[str]` | *(computed)* | Several namespaces, mode="presence" only: at most 8, trimmed, duplicates removed; `namespace`, when set and absent, leads the list. |
| `neighbours` | `bool \| None` | `None` | The neighbours graph block in the SAME call, matches mode only: the hits' enclosing functions become anchors (at most 20, first appearance) and each carries up to `neighbour_k` callers, callees and mapped tests at edge confidence >= 0.8… |
| `neighbour_k` | `int` | `5` | With `neighbours`: at most this many callers and callees per anchor (1..20). |
| `deadline_ms` | `int \| None` | `None` | The request's wall-clock budget in ms, from arrival (values under 200 read as 200). |

| Output field | Type | Meaning |
| --- | --- | --- |
| `matches` | `list[dict[str, Any]]` | {path, line, text, scope, scope_start_line, scope_end_line} per matching LINE, path/line ordered. scope_* is the span of the enclosing unit named by `scope` (0/0 when the line sits in no unit) — enough to decide whether to fetch the body… |
| `next_cursor` | `str` | Continuation: cursor for the next page of matching lines, "" when the extracted set is exhausted. has_more mirrors it. |
| `has_more` | `bool` | True when `next_cursor` is set. |
| `files` | `list[dict[str, Any]]` | mode=files: {path, chunks, first_line} per matching file, path ordered. |
| `files_total` | `int` | distinct matching files before `limit` (mode=files) |
| `chunks_matched` | `int` | Indexed chunks read that contain the pattern (matches mode over-fetches up to 200). |
| `truncated` | `bool` | True when more lines or files match than were returned, or the chunk read hit its cap. |
| `coverage_floor` | `bool` | Chunk coverage is not byte-complete for a file: absence here cannot prove absence in the repo (same floor contract as code.verify). |
| `as_of` | `dict[str, Any]` | Provenance + freshness: branch, commit, indexed_at, lag_commits (int, -1 unknown), stale (bool: lag > LOOM_CODE_STALE_AFTER_COMMITS). |
| `not_covered` | `bool` | True when path_prefix lies outside the indexed prefixes (hits are then empty by construction, not by absence). |
| `neighbours` | `list[dict[str, Any]]` | The neighbours graph block: one entry per anchor — symbol_id, qualified_name, path, module, callers, callees, tests, epistemic, causes; empty unless `neighbours` ran. |
| `anchors` | `int` | distinct enclosing functions the block covers |
| `anchors_capped` | `bool` | more resolved functions than the 20 cap |
| `neighbour_tokens` | `int` | Tokens of the neighbours block alone; 0 when it did not run. |
| `note` | `str` | A caveat on the answer: the pattern was re-read as a regex or matched literally, the prefix is outside the index, or the embedding coverage is low; '' when none. |
| `verdict` | `str` | mode=message only (dropped from the wire otherwise): raised_at \| no_template_match; the message's `{}` template; the ErrorCodes name for a `Code: N` prefix ("" when unmapped); the best statement's coverage (matched message characters… |
| `template` | `str` | mode=message: the message with `{}` where arguments stood. |
| `error_code` | `str` | mode=message: the ErrorCodes name for a `Code: N` prefix; '' when unmapped. |
| `coverage` | `float` | mode=message: the best statement's matched share of the message characters (0..1). |
| `presence` | `list[dict[str, Any]]` | mode=presence: one row per requested namespace, in request order — {namespace, verdict: present \| absent \| unknown, path, start_line, end_line, tier: "", files_total, indexed_commit, index_status, ms, reason}. |
| `summary` | `dict[str, list[str]]` | mode=presence: {present, absent, unknown}, each the namespaces with that verdict. |
| `trace_run_id` | `str` | Id of this call's trace row ('' on a not_covered answer); pass it to `code.outcome`. |
| `partial` | `bool` | `deadline_ms` stopped the scan (or skipped a later read): the hits are those found in the budget and `partial_reason` says what was cut. |
| `partial_reason` | `str` | What the deadline cut, as `deadline N ms: <stage>; <stage>`. |
| `fallback` | `Literal['', 'literal']` | mode=message whose pattern matched no statement template: "literal" when the same pattern was then run as a plain matches grep and `matches` are its lines (the verdict fields stay the message read's). |

## `code.history`

The merged PRs that most recently touched a symbol or path: number, title, author, labels, and what reviewers said about that file — up to `reviews_per_pr` (default 3, 0 = none) human review comments…

`POST /v1/code.history` · MCP `loom_code_history` · role `viewer` · read

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | `''` | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `consumer` | `str` | `''` | trace attribution: which integration is calling (clickgap\|claude-code\|…) |
| `name` | `str` | `''` | A symbol name or `path:line`; the PRs over its definitions' files are returned. |
| `symbol_id` | `str` | `''` | An index symbol id; wins over `name`. |
| `path` | `str` | `''` | A repo-relative file; wins over `name` / `symbol_id`. |
| `numbers` | `list[int]` | *(computed)* | Issue / PR numbers: the item facts and the merged PRs that are or close them, from the same reads code.search's history section uses. |
| `limit` | `int` | `5` | At most this many PRs (1–20). |
| `reviews_per_pr` | `int` | `3` | review comments per PR row on the queried file (0 = none) |

| Output field | Type | Meaning |
| --- | --- | --- |
| `prs` | `list[dict[str, Any]]` | Merged PRs, newest first: {pr_number, title, author, merged_at, labels, body_excerpt} plus `reviews` / `review_count` when asked; number lookups return the history rows. |
| `paths` | `list[str]` | The files the PRs were read for; for number lookups, the files the returned PRs touched. |
| `items` | `list[dict[str, Any]]` | number lookups only: what each number is (issue / pr, state, title) |
| `trace_run_id` | `str` | Id of this call's trace row; pass it to `code.outcome`. |

## `code.impact`

Symbol-shaped (name/symbol_id) or diff-shaped (files/diff) blast radius.

`POST /v1/code.impact` · MCP `loom_code_impact` · role `viewer` · read

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `include_lessons` | `bool` | `True` | Attach `lessons`: the memories about the answer's top files (for code.context_pack, a `task` briefing's only). |
| `lesson_namespaces` | `list[str]` | *(computed)* | The memory namespaces `lessons` reads besides the repository's team rules (over MCP the caller's memory home, filled in); one the caller cannot read is skipped. |
| `pr_files` | `dict[str, str]` | *(computed)* | Repo-relative path -> the file's full text at the PR's head, for the files the PR adds or modifies (at most 50, 1,000,000 characters each). |
| `pr_diff` | `str` | `''` | The PR's unified diff against its merge-base (at most 1,500,000 characters): its hunks say which functions the PR modifies, and its paths name the files it deletes. |
| `pr_head_sha` | `str` | `''` | The PR's head and base commits as the caller knows them; they label the answer (`overlay_head_sha`) and never reach git. '' = derived from the text. |
| `pr_base_sha` | `str` | `''` |  |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | `''` | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `consumer` | `str` | `''` | trace attribution: which integration is calling (clickgap\|claude-code\|…) |
| `name` | `str` | `''` | Symbol shape: the seed's bare, qualified or partly qualified name, or `path:line`. |
| `symbol_id` | `str` | `''` | Symbol shape: an index symbol id for the seed; wins over `name`. |
| `depth` | `int` | `2` | How many caller hops the radius walks from the seeds (1–2). |
| `files` | `list[str]` | *(computed)* | Diff shape: repo-relative changed paths, and/or a unified diff whose hunk line ranges narrow the touched set from whole files to the symbols actually edited. |
| `diff` | `str` | `''` | A unified diff (at most 200,000 chars); its hunk ranges pick the edited functions as seeds. |
| `exclude_authors` | `list[str]` | *(computed)* | Left out of `owners`: the change's own author(s) are not its reviewers. |
| `summary_only` | `bool` | `False` | Hub-safe ergonomics. |
| `per_hop_limit` | `int` | `200` | At most this many `impacted_symbols` rows from each hop (1–500). |
| `offset` | `int` | `0` | Rows to skip within each hop before `per_hop_limit` applies; pages a hub's radius. |
| `pr_number` | `int` | `0` | An OPEN pull request whose head the mirror holds. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `lessons` | `list[dict[str, Any]]` | The memories about the answer's top files, best first, capped at `code_result_lessons_tokens`; each row {path, memory_key, namespace, excerpt, code_state}, with `changed_since` and `supersedes_key` when they apply. |
| `lessons_left_out` | `int` | How many rows about those files the lessons' token cap or a cut left out, with the rows another row read for the answer supersedes. |
| `impacted_symbols` | `list[dict[str, Any]]` | Each row {qualified_name, path, hop, tier}; a row whose function is a registration function (`REGISTER_FUNCTION(X)`, `registerStorageFoo`) carries `via: "registration"` — the seed is reached through a registry; the key is absent otherwise. |
| `impacted_tests` | `list[dict[str, Any]]` | Tests the test map ties to the seed and impacted paths: {test_path, src_path, confidence}. |
| `co_change_files` | `list[dict[str, Any]]` | Files changed in the same merged PRs as the seed paths, most often first ({path, prs}, at most 20): the last 10 PRs for the symbol shape, 50 for the diff shape. |
| `blast_radius_score` | `float` | impacted/50 + tests/40, capped at 1. |
| `touched_symbols` | `list[dict[str, Any]]` | Diff shape only: the symbols the change touches (hunk-overlap when a diff was given, else every function in the files), and the files that historically co-change with the touched set but are absent from it — the "did you forget to update… |
| `co_change_missing` | `list[dict[str, Any]]` | Diff shape: co-change files absent from the change ({path, prs, of}, at most 5, support at least 4 PRs and 15%); empty for the symbol shape. |
| `owners` | `list[dict[str, Any]]` | Who to ask: {author, share, prs, reviews, last_merged_at} from merged PRs over the seed paths — the PRs a person AUTHORED (`prs`) and the ones they REVIEWED (`reviews`, inline comments), recency-decayed (120-day half-life), share floor, at… |
| `reverts` | `list[dict[str, Any]]` | Merged PRs over the seed paths that were REVERTS ({pr_number, title, merged_at}, newest first, <=5): the one kind of history that says what not to do, invisible to symbol lookups (the code is back) and to co-change (same files as the… |
| `counts_floor` | `bool` | Same epistemic contract as code.callers: radius counts are floors. |
| `unresolved_calls` | `int` | Symbol shape: call sites named like the seed(s) that the fast tier declined to bind — the size of the floor. |
| `ambiguous_calls` | `int` | Declined call sites with several same-named definitions (see `unresolved_calls`). |
| `epistemic` | `str` | Epistemic envelope. |
| `causes` | `list[str]` | Why `epistemic` is `lower_bound`, from the set above; empty when it is `exact`. |
| `by_hop_counts` | `dict[int, int]` | Distinct symbols reached per hop BEFORE any slicing: {1: n, 2: m}. |
| `truncated` | `bool` | True when `impacted_symbols` is a page of the radius (per_hop_limit / offset sliced it, or the per-hop edge read hit its cap). |
| `resolved_by` | `str` | `anonymous_namespace` \| `tail` when the symbol shape's name bound through symbol-form tolerance; "" and off the wire otherwise. |
| `verdict` | `str` | Why the radius is empty, '' when it is not. |
| `paths_seen` | `list[dict[str, str]]` | Diff shape: every path the request named, with its class — `test` \| `doc` \| `config` \| `unindexed` (outside the indexed prefixes, or a source path the index holds no file row for) \| `src` — so the verdict is actionable without re-deriving… |
| `overlay` | `bool` | On the wire only when `pr_number` was given — see CodeCallersOutput. |
| `overlay_head_sha` | `str` | The PR head commit whose post-image was parsed; "" when there is no overlay. |
| `overlay_added` | `int` | How many functions the PR adds in its parsed files, each a `touched_symbols` seed. |
| `overlay_note` | `str` | Why the overlay is off: `head_not_in_mirror`, `no_merge_base` or `no_repo_entry`; when it is on, "" or how many changed files it did not fully read. |
| `trace_run_id` | `str` | Id of this call's trace row; pass it to `code.outcome`. |

## `code.index_errors`

List the files the code index failed to parse or ingest, with the error and the commit.

`POST /v1/code.index_errors` · MCP `loom_code_index_errors` · role `viewer` · read

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | `''` | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `consumer` | `str` | `''` | trace attribution: which integration is calling (clickgap\|claude-code\|…) |
| `limit` | `int` | `100` | At most this many files, newest first (1..1000). |

| Output field | Type | Meaning |
| --- | --- | --- |
| `rows` | `list[CodeIndexErrorRow]` | Files whose last ingest recorded an error, newest first. |
| `total` | `int` | Every errored live file in the namespace, not only the rows returned. |

## `code.index_status`

Health of the code index: indexed head commit, compiler-tier commit, row counts, watermarks, and the weekly tables' state (symbol_stats_rows/at, unit_risk_rows/at; 0 = not written yet).

`POST /v1/code.index_status` · MCP `loom_code_index_status` · role `viewer` · read

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | `''` | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `consumer` | `str` | `''` | trace attribution: which integration is calling (clickgap\|claude-code\|…) |
| `commit` | `str` | `''` | Optional merge commit SHA: report whether every index tier covers it (commit_coverage.ready). |
| `paths` | `list[str]` | *(computed)* | With `commit`: the PR's changed paths; the answer lists those a later merge changed. |
| `brief` | `bool \| None` | `None` | Compact answer without state/op catalogue/workers. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `repo` | `str` | The repository identity. |
| `branch` | `str` | The branch this entry indexes. |
| `org` | `str` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | The namespace the op reads or writes. |
| `provider` | `str` |  |
| `profile` | `str` |  |
| `compiler_candidates` | `list[str]` | Compiler tiers inferred from the indexed tree, even before a compiler worker has produced its first watermark. |
| `quality_warnings` | `list[str]` | Actionable readiness gaps. |
| `git_head` | `str` | The fast tier's watermark: the last commit whose files are ingested; '' before the first pass. |
| `scip_commit` | `str` | `scip_commit` / `scip_lag` are the ENTRY'S compiler tier — the one `scip_producer` names — not the C++ key by name; a TypeScript repository reports its scip-typescript watermark here. |
| `scip_commit_py` | `str` | The scip-python watermark by name, whatever the entry's primary tier; '' when unset. |
| `scip_producer` | `str` | The primary compiler tier's producer (clang \| typescript \| go \| python); '' when no tier has a watermark. |
| `compiler_tiers` | `list[CodeCompilerTier]` | Every compiler tier with a watermark or configured for the entry, the primary first. |
| `tier_health` | `list[CodeTierHealth]` | The last recorded outcome of each tier that has one (fetch, ingest, the compiler tiers and the weekly C++ full run): a failing tier names its error kind, since when, and the fix. |
| `pr_cursor` | `str` | The PR-history poller's cursor: the newest `updated_at` (ISO-8601) of the merged PRs it fetched; '' before its first pass. |
| `commit_coverage` | `CodeCommitCoverage \| None` | Set when the request named a `commit`. |
| `clone_head` | `str` | Freshness. clone_head is the bare clone's branch tip as of the last poller fetch (<= interval old); *_lag = first-parent commits between a watermark and that tip, -1 when a watermark is unset or the clone is unreadable. 0 everywhere ==… |
| `clone_fetched_at` | `str` | When the ingest pass last fetched this entry's mirror (the `clone_head` row's updated_at, ISO-8601 UTC; '' unknown) and whether that is older than `code_fetch_stale_after_seconds`. |
| `fetch_overdue` | `bool` | True when `clone_fetched_at` is older than `code_fetch_stale_after_seconds`. |
| `fast_tier_lag` | `int` | First-parent commits between `git_head` and `clone_head`; -1 when either is unknown. |
| `scip_lag` | `int` | First-parent commits between `scip_commit` and `clone_head`; -1 when either is unknown. |
| `scip_py_lag` | `int` | First-parent commits between `scip_commit_py` and `clone_head`; -1 when either is unknown. |
| `last_refresh_at` | `str` | Last code.refresh request (the CI hook). |
| `last_refresh_detail` | `str` | The caller of that request, as `agent=<agent> expected_head=<first 12 hex>`; a field the caller left empty is left out. |
| `org_readable` | `bool` | Deployment-level read rule (LOOM_CODE_ORG_READABLE / per-entry): when true every org principal reads this entry regardless of visibility. |
| `path_prefixes` | `list[str]` | The path prefixes the entry indexes; `[""]` = the whole tree. |
| `counts` | `dict[str, int]` | Live row counts per code table (`code_files`, `code_chunks`, `code_symbols`, …); empty in the brief answer. |
| `state` | `dict[str, dict[str, str]]` | Every code_index_state row: {key: {value, detail, updated_at}}. |
| `workers` | `dict[str, CodeWorkerStatus]` | Per `code_*` worker, its enabled flag, interval and last pass; empty in the brief answer. |
| `build_commit` | `str` | Capability catalogue: the build this server runs and every served code.* operation with the request fields its input model accepts, so a client checks for a route or a field instead of probing for a 404 or a 422. |
| `ops` | `list[str]` | Every served `code.*` operation, sorted; empty in the brief answer. |
| `request_fields` | `dict[str, list[str]]` | Per served op, the request fields its input model accepts; empty in the brief answer. |
| `op_maturity` | `dict[str, str]` | Per served op, its maturity (stable \| experimental) and the reach kinds a caller has to it. |
| `op_reach` | `dict[str, list[str]]` | Per served op, its reach kinds (mcp_core \| mcp_atomic \| mcp_all \| sdk_method \| sdk_example \| plugin_hook \| dashboard \| http_only); empty in the brief answer. |
| `op_toolsets` | `dict[str, list[str]]` | Per served op, every MCP toolset whose listing carries it (core \| coding \| atomic \| all; empty when hidden). |
| `symbol_stats_rows` | `int` | The weekly symbol fan-in table for this namespace — live rows with callers and the newest pass stamp (ISO 8601, UTC). 0 / "" = the pass has not written it: every `fan_in` field, the fan-in sort and the rank prior answer empty. |
| `symbol_stats_at` | `str` | The newest fan-in pass stamp (ISO-8601 UTC); '' when the pass has not written the table. |
| `unit_risk_rows` | `int` | The precomputed risk table for this namespace — live rows and the newest stamp (ISO 8601, UTC), so an operator sees the weekly leg's progress and a resumed pass's remainder. 0 / "" = no row written (every served unit is read live). |
| `unit_risk_at` | `str` | The newest risk-table stamp (ISO-8601 UTC); '' when no row is written. |
| `chunks_total` | `int` | Live chunks, those carrying a vector, and their ratio (0..1; reference fixtures unembedded by design are outside the denominator). |
| `chunks_embedded` | `int` | Live chunks that carry an embedding vector. |
| `embedding_coverage` | `float` | Embedded share of the embeddable chunks (0..1); 1.0 when the counts do not carry it. |

## `code.map`

PageRank-ordered orientation map of the indexed repository with per-file summary cards, token-budgeted.

`POST /v1/code.map` · MCP `loom_code_map` · role `viewer` · read · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | `''` | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `consumer` | `str` | `''` | trace attribution: which integration is calling (clickgap\|claude-code\|…) |
| `token_budget` | `int` | `1000` | Token budget for the map (200..4000); entries past it are dropped. |
| `module_prefix` | `str` | `''` | Only modules and hubs under this repo-relative prefix; '' = the whole repository. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `map` | `str` | The repository map as Markdown: module cards and call-graph hubs, then the most-called symbols when the fan-in stats exist. |
| `tokens_used` | `int` | Estimated tokens of `map`. |
| `commit_sha` | `str` | The fast-tier watermark (`git_head`) the map reflects; '' before the first pass. |
| `trace_run_id` | `str` | Id of this call's trace row; pass it to `code.outcome`. |

## `code.outcome`

Tell loom what you did with a code answer, by its trace_run_id: 'used_in_answer', 'opened_file' (targets = the paths), 'fell_back_grep' or 'ignored'.

`POST /v1/code.outcome` · MCP `loom_code_outcome` · role `viewer` · idempotent · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | `''` | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `consumer` | `str` | `''` | trace attribution: which integration is calling (clickgap\|claude-code\|…) |
| `trace_run_id` | `str` | `''` | Required for retrieval outcomes; optional (empty) for shunt_* only. |
| `action` | `Literal['opened_file', 'used_in_answer', 'fell_back_grep', 'ignored', 'shunt_hit', 'shunt_pass']` | required | What happened after the answer: opened_file (a returned file was read), used_in_answer, fell_back_grep, ignored; or a batch of shunt-hook decisions (shunt_hit \| shunt_pass). |
| `targets` | `list[str]` | *(computed)* | opened_file: the paths read (matched to the trace's returned paths); shunt_*: one tool name per decision. |
| `source` | `str` | `''` | Who / why. |
| `tokens_saved` | `int` | `0` | shunt_hit: bytes of the file/grep result the model did not ingest ÷ 4. shunt_pass: the same estimate for what the pass LET IN (the addressable tokens, summed per reason). 0 when unknowable (grep). |
| `spans` | `list[str]` | *(computed)* | Aligned with `targets`: the line span each decision / open covered, as `path:start-end` (shunt rows: the file and the lines the Read would cover), `start-end` (opened_file: the Read's offset/limit against the target path) or '' when… |
| `reason` | `str` | `''` | fell_back_grep / ignored: WHY, from OUTCOME_REASONS. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `recorded` | `bool` | True when the row was written; false when the trace log is disabled or the write failed. |

## `code.outline`

"What is in this file?" — the question a whole-file read answers at the price of the whole file.

`POST /v1/code.outline` · MCP `loom_code_outline` · role `viewer` · read

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `include_lessons` | `bool` | `True` | Attach `lessons`: the memories about the answer's top files (for code.context_pack, a `task` briefing's only). |
| `lesson_namespaces` | `list[str]` | *(computed)* | The memory namespaces `lessons` reads besides the repository's team rules (over MCP the caller's memory home, filled in); one the caller cannot read is skipped. |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | `''` | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `consumer` | `str` | `''` | trace attribution: which integration is calling (clickgap\|claude-code\|…) |
| `path` | `str` | required | repo-relative path ("src/Foo.cpp"); a leading ./ is tolerated |
| `kinds` | `list[str]` | *(computed)* | Declaration kinds to list (`function`, `class`, `job`, …); the default covers every kind the symbol table records for code, SQL tests, build files and data models. |
| `token_budget` | `int` | `1500` | Whole-row budgeted: an entry ships complete (signature included) or not at all; the first elided entry names its own code.symbol call. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `lessons` | `list[dict[str, Any]]` | The memories about the answer's top files, best first, capped at `code_result_lessons_tokens`; each row {path, memory_key, namespace, excerpt, code_state}, with `changed_since` and `supersedes_key` when they apply. |
| `lessons_left_out` | `int` | How many rows about those files the lessons' token cap or a cut left out, with the rows another row read for the answer supersedes. |
| `path` | `str` | The repo-relative path read, normalised from the request. |
| `entries` | `list[dict[str, Any]]` | source order: {kind, qualified_name, signature, start_line, end_line, tier} |
| `total` | `int` | declarations found for the requested kinds |
| `returned` | `int` | Entries in `entries`. |
| `elided` | `int` | Declarations left out because `token_budget` ran out (`total - returned`). |
| `next` | `str` | `code.symbol name=<qualified_name>` of the first elided entry ("" when nothing was elided); a larger token_budget re-fetches the whole list. |
| `indexed` | `bool` | False when the path has no live symbol rows: unindexed, renamed, or the index has not caught up — read the file. |
| `verdict` | `str` | Why `entries` is empty, '' when it is not. |
| `tokens_returned` | `int` | Estimated tokens of the entries (and `head`) returned. |
| `took_ms` | `int` | Server-side wall time of the call, in milliseconds. |
| `head` | `str` | A reference fixture (lang `reference`) declares nothing; its indexed head (first 4,000 chars) is returned here instead, with `head_truncated` when the file is longer. |
| `head_truncated` | `bool` | True when the fixture is longer than the `head` returned; omitted with `head`. |
| `as_of` | `dict[str, Any]` | Provenance + freshness: branch, commit, indexed_at, lag_commits (int, -1 unknown), stale (bool: lag > LOOM_CODE_STALE_AFTER_COMMITS). |
| `trace_run_id` | `str` | Id of this call's trace row; pass it to `code.outcome`. |

## `code.path_guards`

The conditions that stand on the call path from `from_symbol` to `to_symbol`: the verify(reaches) chain, and for each hop the guards the call site sits under inside its caller…

`POST /v1/code.path_guards` · MCP `loom_code_path_guards` · role `viewer` · read · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | `''` | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `consumer` | `str` | `''` | trace attribution: which integration is calling (clickgap\|claude-code\|…) |
| `from_symbol` | `str` | required | The symbol the call path starts from. |
| `to_symbol` | `str` | required | a symbol name, or a path prefix (contains '/') like verify(reaches) |
| `mentions` | `str` | `''` | the identifier the question asks about ('' lists the guards only) |
| `depth` | `int` | `4` | The most call hops the walk follows (1..4). |

| Output field | Type | Meaning |
| --- | --- | --- |
| `verdict` | `Literal['guarded_by', 'no_guard_named', 'path_found', 'path_not_found', 'unknown']` | guarded_by a guard on some hop names `mentions` no_guard_named the path was found, no guard on it names `mentions` path_found the path was found and `mentions` was empty (listing) path_not_found the bounded walk emptied its frontier… |
| `causes` | `list[str]` | Machine-readable causes behind `unknown`, and the standing floors of a syntactic read otherwise (empty on guarded_by/no_guard_named/path_found only when nothing further limited the answer). |
| `epistemic` | `Literal['lower_bound']` | Always `lower_bound`: guards are read syntactically inside each caller only. |
| `explanation` | `str` | A human-readable account of how the verdict was reached. |
| `hops` | `list[dict[str, Any]]` | One entry per hop, seed first. |
| `named_at` | `list[str]` | The hops whose guards name `mentions`, as "path:line" — the places to read |
| `visited_symbols` | `int` | Symbols the bounded call walk visited. |
| `trace_run_id` | `str` | Id of this call's trace row; pass it to `code.outcome`. |

## `code.pr_check`

A PR draft asks whether a PR like it already exists.

`POST /v1/code.pr_check` · MCP `loom_code_pr_check` · role `viewer` · read · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | `''` | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `consumer` | `str` | `''` | trace attribution: which integration is calling (clickgap\|claude-code\|…) |
| `title` | `str` | `''` | The draft's title; its tokens (with the symbols') are matched against PR titles. |
| `body` | `str` | `''` | The draft's description: `Fixes #N` links and `#N` mentions add issues, and its words (template boilerplate stripped) add match tokens. |
| `paths` | `list[str]` | *(computed)* | repository-relative paths the draft changes |
| `symbols` | `list[str]` | *(computed)* | symbols the draft adds or changes (function / class / method names) |
| `issues` | `list[int]` | *(computed)* | issues the draft closes, beside the ones its text names (`Fixes #123`, `#123`) |
| `pr_number` | `int` | `0` | the PR already opened for this draft: excluded from the candidates |
| `top_k` | `int` | `5` | At most this many candidates in `items` (1..20). |

| Output field | Type | Meaning |
| --- | --- | --- |
| `verdict` | `str` | duplicate_of \| related \| none — `none` carries no items (open it) |
| `items` | `list[dict[str, Any]]` | [{pr_number, state: open\|merged\|closed, title, author, opened_at, merged_at, closed_at, relation: duplicate\|related, score, evidence: [str], shared_paths, files_total, linked_issues, labels, found_by: [leg], features}] |
| `undecided` | `bool` | the top candidate sits in the upper related band: a human should look |
| `epistemic` | `str` | heuristic (every leg read) \| lower_bound (a leg was unavailable) \| unavailable |
| `thresholds` | `dict[str, float]` | The score cut-offs the verdict used: {duplicate, related}. |
| `legs` | `dict[str, Any]` | rows read per leg, or "unavailable: <reason>" |
| `draft` | `dict[str, Any]` | what the draft became: title_tokens, paths, symbols, issues |
| `trace_run_id` | `str` | Id of this call's trace row; pass it to `code.outcome`. |

## `code.recent_commits`

List the most recently indexed commits of a repository, decorated with subject and time from the clone.

`POST /v1/code.recent_commits` · MCP `loom_code_recent_commits` · role `viewer` · read

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | `''` | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `consumer` | `str` | `''` | trace attribution: which integration is calling (clickgap\|claude-code\|…) |
| `limit` | `int` | `20` | At most this many commits, newest ingest first (1..100). |

| Output field | Type | Meaning |
| --- | --- | --- |
| `rows` | `list[CodeRecentCommitRow]` | Commits the fast tier wrote files at, newest ingest first. |

## `code.refresh`

CI calls this right after a merge lands: run one ingest pass now instead of waiting for the poll interval.

`POST /v1/code.refresh` · MCP `loom_code_refresh` · role `writer` · write · audited · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | `''` | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `consumer` | `str` | `''` | trace attribution: which integration is calling (clickgap\|claude-code\|…) |
| `expected_head` | `str` | `''` | The commit CI just merged; advisory, recorded in `last_refresh_detail` and never checked. |
| `wait` | `bool` | `False` | wait=True blocks until the pass completes (CI wants a sync signal); default fire-and-forget returns immediately. |
| `wait_timeout_seconds` | `int` | `300` | With `wait`: seconds to wait for the pass (10..900); the call fails when the pass outlasts it. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `triggered` | `bool` | True when this call started an ingest pass; false when one was already running. |
| `already_running` | `bool` | True when a pass for this namespace was already in flight; this call started none. |
| `head_before` | `str` | The fast-tier watermark (`git_head`) before the pass; '' when the namespace has none. |
| `head_after` | `str` | With `wait`: the fast-tier watermark after the pass; '' otherwise. |

## `code.reindex`

Operator repair: move the git watermark (e.g. back N commits after a bad pass, or to a specific sha).

`POST /v1/code.reindex` · MCP `loom_code_reindex` · role `admin` · write · audited · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | `''` | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `consumer` | `str` | `''` | trace attribution: which integration is calling (clickgap\|claude-code\|…) |
| `git_head` | `str` | required | full 40-char sha to move the ingest watermark to |

| Output field | Type | Meaning |
| --- | --- | --- |
| `previous_head` | `str` | The fast-tier watermark before the move; '' when it was unset. |
| `new_head` | `str` | The watermark now set; the ingest worker re-walks from it. |

## `code.repo.add`

Add a repository's branch as a new read-only index.

`POST /v1/code.repo.add` · MCP `loom_code_repo_add` · role `viewer` · write · audited

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `repo` | `str` | required | GitHub owner/name or an HTTPS/SSH Git URL. |
| `branch` | `str` | `''` | Blank asks the remote for its symbolic default branch. |
| `join_policy` | `Literal['open', 'approval']` | `'open'` | `open`: any org member joins at once; `approval`: a maintainer approves each request. |
| `classification` | `Literal['standard', 'restricted']` | `'standard'` | `standard` or `restricted` (a reader needs an approved grant and a token that names the namespace). |
| `access_token` | `str` | `''` | Token for a private HTTPS remote; stored encrypted, never returned. |
| `git_proxy_identity` | `str` | `''` | The user name this repository's git presents to the deployment's git proxy; only a platform admin may set it. |
| `path_prefixes` | `list[str]` | *(computed)* | Path prefixes to index (`src/`, `lib/`); blank entries are dropped, [] indexes the whole tree. |
| `exclude` | `list[str]` | *(computed)* | Globs never indexed for this repository (`vendor/`, `*.generated.go`); [] keeps the deployment's default exclude list. |
| `exclude_generated` | `bool` | `True` | Refuse generated content (Go's `// Code generated … DO NOT EDIT.` header, the `@generated` marker, the repository's `.gitattributes` linguist rules) — on unless the maintainer says otherwise |
| `scip_producer` | `Literal['', 'go', 'typescript', 'clang', 'python']` | `''` | The compiler tier's producer; "" infers it from the tree's manifests (go.mod → go, tsconfig / package.json → typescript, a root CMakeLists.txt → clang, pyproject → python) |
| `branches` | `list[str]` | *(computed)* | More branches chosen at add time, each its own index sharing the mirror and inheriting rule, token, git proxy identity and paths; per-branch refusals come back in `skipped`, never undoing the ones registered. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `org` | `str` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | The namespace the op reads or writes. |
| `repo` | `str` | Stable repository identity. |
| `remote` | `str` |  |
| `provider` | `str` |  |
| `branch` | `str` | The branch the new index follows. |
| `join_policy` | `str` | The join policy as registered (`approval` for a restricted repository). |
| `classification` | `str` | The classification as registered: `standard` or `restricted`. |
| `index_stage` | `str` | queued at creation; the worker moves it (see CodeRepoSummary.stage) |
| `my_role` | `str` | `admin` when the caller became the index's first maintainer; '' for a caller with no subject. |
| `remote_head` | `str` | The branch head SHA the remote answered with at add time. |
| `also` | `list[dict[str, str]]` | The other branches registered in the same call ({branch, namespace, remote_head}) |
| `skipped` | `list[dict[str, str]]` | The extra branches refused, per branch {branch, reason}; the others stay registered. |

## `code.repo.add_branch`

Index another branch of a repository the caller maintains.

`POST /v1/code.repo.add_branch` · MCP `loom_code_repo_add_branch` · role `admin` · write · audited

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `branch` | `str` | required | The branch to index as a new namespace; it must exist on the remote. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `org` | `str` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | The namespace the op reads or writes. |
| `repo` | `str` | Stable repository identity. |
| `remote` | `str` |  |
| `provider` | `str` |  |
| `branch` | `str` | The branch the new index follows. |
| `join_policy` | `str` | The join policy as registered (`approval` for a restricted repository). |
| `classification` | `str` | The classification as registered: `standard` or `restricted`. |
| `index_stage` | `str` | queued at creation; the worker moves it (see CodeRepoSummary.stage) |
| `my_role` | `str` | `admin` when the caller became the index's first maintainer; '' for a caller with no subject. |
| `remote_head` | `str` | The branch head SHA the remote answered with at add time. |
| `also` | `list[dict[str, str]]` | The other branches registered in the same call ({branch, namespace, remote_head}) |
| `skipped` | `list[dict[str, str]]` | The extra branches refused, per branch {branch, reason}; the others stay registered. |

## `code.repo.remote_branches`

What a Git remote shows before anything is written — every branch with its head, the default branch, the ones that look like release branches, and the ones indexed here already — so the add dialog…

`POST /v1/code.repo.remote_branches` · MCP `loom_code_repo_remote_branches` · role `viewer` · read

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The org adding the repository. |
| `repo` | `str` | required | GitHub owner/name or an HTTPS/SSH Git URL. |
| `access_token` | `str` | `''` | Token for a private HTTPS remote; used once. |
| `git_proxy_identity` | `str` | `''` | The user name this read presents to the deployment's git proxy; only a platform admin may set it. |
| `query` | `str` | `''` | Case-insensitive substring of the branch name to match. |
| `limit` | `int` | `60` | How many matching branches to return (default 60). |

| Output field | Type | Meaning |
| --- | --- | --- |
| `org` | `str` | The tenant (first element of the identity tuple). |
| `repo` | `str` | Stable repository identity. |
| `remote` | `str` |  |
| `provider` | `str` |  |
| `warnings` | `list[str]` |  |
| `default_branch` | `str` | The branch the remote reports as its default. |
| `branches` | `list[dict[str, str]]` | [{name, sha}] — default first, then release-shaped, then the rest |
| `suggested` | `list[str]` | release-shaped branches not indexed yet (26.8, release/1.2, stable-x) |
| `indexed` | `list[dict[str, str]]` | [{branch, namespace}] already indexed in this org |
| `cap` | `int` | how many more indexes the org may add (code_self_service_max_repos − active) |
| `total` | `int` | `branches` is the first `limit` matches of `query` over `total` heads (the default and the indexed ones always included); `truncated` says a search is needed to see the rest |
| `matched` | `int` | How many heads match `query` (all of them when it is empty). |
| `truncated` | `bool` | True when some matching heads are not in `branches`. |
| `query` | `str` | The filter as applied: trimmed and lower-cased; '' = no filter. |

## `code.repo.remove`

Retire a repository index a person added.

`POST /v1/code.repo.remove` · MCP `loom_code_repo_remove` · role `admin` · idempotent · audited

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `confirm` | `str` | `''` | Must equal `namespace`, or the call is refused with CONFIRM_REQUIRED. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `org` | `str` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | The namespace the op reads or writes. |
| `repo` | `str` | The retired index's GitHub owner/name. |
| `branch` | `str` | The branch the retired index followed. |
| `registry_deactivated` | `bool` | True when the registry row went inactive by this call. |
| `directory_deactivated` | `bool` | True when the namespace's directory row was deleted. |
| `purged_tables` | `int` | How many code tables keyed by the namespace the erasure saga purges. |
| `erasure_id` | `str` | The erasure saga that purges them — follow it with erasure.status; erasure_recovery resumes it. |
| `mirror_removed` | `bool` | True when the bare mirror was deleted because no other branch of the repository uses it. |
| `sources_deactivated` | `list[str]` | The document sources registered on the namespace (knowledge.source.add), now inactive with their credentials cleared. |

## `code.repo.set_access`

A maintainer sets a repository's access — its classification (`standard` | `restricted`) and join policy (`open` | `approval` | `closed`).

`POST /v1/code.repo.set_access` · MCP `loom_code_repo_set_access` · role `admin` · idempotent · audited · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `classification` | `str` | required | `standard` or `restricted` (case-insensitive); anything else is BAD_CLASSIFICATION. |
| `join_policy` | `str` | required | `open`, `approval` or `closed` (case-insensitive); `open` with `restricted` is refused. |
| `confirm` | `str` | `''` | Must equal `namespace` when the call widens `restricted` to `standard`, which also needs an admin grant of the caller's own there (a copy that does not come from one of the repository's operator entries does not count); else unused. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `org` | `str` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | The namespace the op reads or writes. |
| `repo` | `str` | The repository's GitHub owner/name. |
| `classification` | `str` | The classification as written (lower-cased). |
| `join_policy` | `str` | The join policy as written (lower-cased). |
| `previous_classification` | `str` | The entry's classification before this call: `restricted` when either the entry, as this process last read it, or its directory row said so. |
| `previous_join_policy` | `str` | The directory row's join policy before this call (when it had none: `open` for a public entry, else `approval`). |
| `directory_updated` | `bool` | True when the namespace's directory row got the new access too, a branch added from the page with no row yet getting its first one; False for an operator entry with no directory row. |
| `effective_within_s` | `int` | every process re-reads the access row within this many seconds |

## `code.repo.set_source`

A maintainer sets the trackers this repository reads (records of issues, PRs, tests and incidents registered with `tracker.source.add`), in order.

`POST /v1/code.repo.set_source` · MCP `loom_code_repo_set_source` · role `admin` · idempotent · audited · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | required | The tenant (first element of the identity tuple). |
| `namespace` | `str` | required | The namespace the op reads or writes. |
| `tracker_namespaces` | `list[str]` | required | Tracker namespaces of this org, primary first (duplicates dropped; [] unlinks all); a new link needs the tracker's admin. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `org` | `str` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | The namespace the op reads or writes. |
| `tracker_namespaces` | `list[str]` | the links as written (primary first) |
| `previous_tracker_namespaces` | `list[str]` | The links before this call, primary first ([] = none). |
| `effective_within_s` | `int` | Seconds within which every process re-reads the links. |
| `not_covering` | `list[str]` | Linked trackers that do not list this repository (they read only the repositories they name, so they answer nothing here), and the sentence that says so |
| `warning` | `str` | One clause per `not_covering` tracker naming the repositories it reads, and one naming the registered branches that read these links too; '' when neither. |

## `code.repos`

Lists the code namespaces (repo@branch entries) configured on this deployment that the caller is authorized to read, across orgs — each row carries its org.

`POST /v1/code.repos` · MCP `loom_code_repos` · role `viewer` · read

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | `''` | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `consumer` | `str` | `''` | trace attribution: which integration is calling (clickgap\|claude-code\|…) |
| `repo` | `str` | `''` | A caller standing in one checkout (the plugin's code shunt, from the origin remote) names it, and the answer is that repository's entries only — one status read instead of one per configured repository. |
| `repos` | `list[str]` | *(computed)* | The checkout's remotes as ordered candidates (origin, upstream, then the rest; each owner/name or a URL, as `repo`). |
| `fields` | `list[str] \| None` | `None` | The output fields the caller reads (a whitelist resolved against the row model; an unknown name is a 422); unset, every field. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `repos` | `list[CodeRepoSummary]` | One row per entry the caller reads (plus unreadable rows an org admin may adopt), narrowed to the `repo` / `repos` match when either was given; [] when none. |

## `code.review_brief`

A merged PR's review brief: the point read of what the ingest built at merge — touched symbols with callers and fan-in, coverage verdicts, setting facts, regression history, blame of the deleted…

`POST /v1/code.review_brief` · MCP `loom_code_review_brief` · role `viewer` · read · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `pr_files` | `dict[str, str]` | *(computed)* | Repo-relative path -> the file's full text at the PR's head, for the files the PR adds or modifies (at most 50, 1,000,000 characters each). |
| `pr_diff` | `str` | `''` | The PR's unified diff against its merge-base (at most 1,500,000 characters): its hunks say which functions the PR modifies, and its paths name the files it deletes. |
| `pr_head_sha` | `str` | `''` | The PR's head and base commits as the caller knows them; they label the answer (`overlay_head_sha`) and never reach git. '' = derived from the text. |
| `pr_base_sha` | `str` | `''` |  |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | `''` | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `consumer` | `str` | `''` | trace attribution: which integration is calling (clickgap\|claude-code\|…) |
| `pr_number` | `int` | `0` | The PR to brief; 0 = find it by `merge_sha`. |
| `merge_sha` | `str` | `''` | The PR's merge commit (hex, up to 40 chars); '' = find it by `pr_number`. |
| `sections` | `list[Literal['paths', 'symbols', 'tests', 'settings', 'history', 'blame', 'qa', 'risk', 'do_not_flag', 'rationale']]` | *(computed)* | Serve only these of the tier's sections; empty = every section the tier carries. |
| `tier` | `Literal['trivial', 'standard', 'full']` | `'standard'` | Which sections and default budget: trivial (paths, symbols), standard (+ tests, settings, history, risk, rationale) or full (+ blame, qa). |
| `token_budget` | `int` | `0` | Token budget for the served sections; 0 = the tier's (700 / 2,500 / 4,000). |
| `store` | `bool` | `True` | Whether a brief this call builds on a miss is stored for the next reader (the default). |
| `open` | `bool` | `False` | The PR is OPEN — brief its head (`refs/pull/N/head` on the mirror) diffed against its merge-base with the indexed branch, with the post-image overlay on the impact read (added functions are seeds). |

| Output field | Type | Meaning |
| --- | --- | --- |
| `pr_number` | `int` | The PR the brief is of (from the stored brief when the request named only `merge_sha`). |
| `merge_sha` | `str` | The PR's merge commit; '' on an open brief or when no brief was found. |
| `source` | `Literal['precomputed', 'built', 'built_from_mirror', 'missing']` | precomputed (the ingest built it) \| built (this call built it from the ledger's row) \| built_from_mirror (no ledger row; the merge commit, title and files came from the mirror's first-parent chain and the reviewers from the tracker record)… |
| `ledger` | `Literal['', 'present', 'absent']` | what the ledger said: present (this build read its row) \| absent (this or the stored build came from the mirror because the ledger had no row) \| "" (not consulted: the ingest built the row) |
| `stored` | `bool` | True when this call built the brief and stored it |
| `provenance` | `dict[str, Any]` | A mirror-built brief's disclosure — source, ledger, merge_commit, files, title (qa \| mirror), qa status, reviewers, author, has_test, is_backport_pr; {} for a ledger- or ingest-built brief |
| `overlay` | `bool` | On the wire only for `open: true`. |
| `overlay_head_sha` | `str` | The open PR's head the brief was read or built at; '' when the mirror lacks it. |
| `overlay_added` | `int` | Functions the open PR adds (the symbols section's `via: added` rows). |
| `overlay_note` | `str` | Why no open brief exists (`head_not_in_mirror` \| `no_merge_base` \| `no_repo_entry`); when one was served, '' or how many changed files its overlay did not fully read (a brief whose overlay left files unreached is not stored). |
| `tier` | `str` | The tier served. |
| `built_at` | `str` | When the brief was built (ISO-8601 UTC); '' when `source` is missing. |
| `indexed_commit` | `str` | The fast-tier watermark the brief was built against; '' when it was unread. |
| `build_ms` | `int` | How long building the brief took, in milliseconds (at build time, not this call). |
| `tokens_used` | `int` | Estimated tokens of the sections served. |
| `token_budget` | `int` | The budget the sections were cut to: the request's, else the tier's. |
| `decisions` | `dict[str, bool]` | one-bit answers read off the section verdicts: test_only, symbol_with_regressions, uncovered_symbol, randomized_setting, deleted_lines_blamed |
| `sections` | `dict[str, dict[str, Any]]` | name -> {status, verdict, epistemic, causes, rows, rows_total, tokens, truncated} |
| `trace_run_id` | `str` | Id of this call's trace row; pass it to `code.outcome`. |

## `code.scip_ingest`

Accept one part of a SCIP index upload (compiler-tier symbols and references) for a batch.

`POST /v1/code.scip_ingest` · MCP `loom_code_scip_ingest` · role `writer` · idempotent · audited · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | `''` | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `consumer` | `str` | `''` | trace attribution: which integration is calling (clickgap\|claude-code\|…) |
| `batch_id` | `str` | required | The staging tables key on a UUID column: a malformed id is refused here, not by the insert. |
| `seq` | `int` | required | This part's position in the batch, 0-based (`0 <= seq < total_parts`). |
| `total_parts` | `int` | required | How many parts the batch has; capped by `code_scip_max_parts`. |
| `commit_sha` | `str` | `''` | The commit the index was built at; once applied it becomes the producer's tier watermark. |
| `base_sha` | `str` | `''` | The commit the delta was computed from; recorded on the batch row. |
| `producer` | `str` | `''` | The indexer that built the delta (scip-clang, scip-python, scip-typescript, scip-go); it picks the watermark key the batch advances, '' = the C++ key `scip_commit`. |
| `payload` | `str` | required | one part of the JSON-encoded ScipDelta |
| `entry_lease_holder` | `str` | `''` | The holder of the entry's lease the delta was built under (`loom code entry-lock` hands it to its command); when set, the part is refused unless that holder still holds the lease. '' = unfenced (CI pushes). |

| Output field | Type | Meaning |
| --- | --- | --- |
| `batch_id` | `str` | The batch this part was stored under, as sent. |
| `parts_received` | `int` | Distinct parts of the batch stored so far. |
| `total_parts` | `int` | The batch's part count, as sent. |
| `complete` | `bool` | True once every part is stored; the apply worker then picks the batch up. |

## `code.scip_status`

Report the progress of a SCIP upload batch: parts received and apply status.

`POST /v1/code.scip_status` · MCP `loom_code_scip_status` · role `viewer` · read · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | `''` | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `consumer` | `str` | `''` | trace attribution: which integration is calling (clickgap\|claude-code\|…) |
| `batch_id` | `str` | required | The UUID the parts were uploaded under. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `batch_id` | `str` | The batch asked about. |
| `status` | `str` | pending \| applied \| failed |
| `parts_received` | `int` | Distinct parts of the batch stored so far. |
| `total_parts` | `int` | The batch's part count, as uploaded. |
| `error` | `str` | Why the apply failed (exception type and message); '' unless `status` is failed. |
| `commit_sha` | `str` | The commit the batch was built at. |
| `applied_at` | `str` | When the apply worker applied the batch; '' until then. |

## `code.search`

Search the shared code index of this repository (fresh to the last merged PR).

`POST /v1/code.search` · MCP `loom_code_search` · role `viewer` · read

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `include_lessons` | `bool` | `True` | Attach `lessons`: the memories about the answer's top files (for code.context_pack, a `task` briefing's only). |
| `lesson_namespaces` | `list[str]` | *(computed)* | The memory namespaces `lessons` reads besides the repository's team rules (over MCP the caller's memory home, filled in); one the caller cannot read is skipped. |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | `''` | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `consumer` | `str` | `''` | trace attribution: which integration is calling (clickgap\|claude-code\|…) |
| `query` | `str` | required | The question, identifier or phrase to search for; a symbol-shaped query tries the symbol table first (`route` says which path answered). |
| `top_k` | `int` | `5` | At most this many results per page (1-25). |
| `token_budget` | `int \| None` | `None` | Response budget in tokens; results are whole units, overflow elides. |
| `path_prefix` | `str` | `''` | Keep only units whose path starts with this prefix; "" = the whole namespace. |
| `cursor` | `str` | `''` | Continuation: the `next_cursor` of an earlier response to this query. |
| `exclude_unit_ids` | `list[str]` | *(computed)* | The caller's seen-set: unit ids not to serve again. |
| `rerank` | `str` | `''` | Reranker over the fused pool: "" = the deployment default (LOOM_CODE_SEARCH_RERANK_DEFAULT, for prose questions of its kinds), "none" = off for this request, "builtin:openai" / "builtin:cohere", or the name of an endpoint in… |
| `expand` | `bool` | `False` | Vocabulary bridge: one LLM hop proposes codebase identifiers for the lexical leg (natural-language wording often misses the implementing subsystem's vocabulary). |
| `annotate` | `bool` | `True` | Risk annotations + one-hop callee context per result (churn/amp/tested/ callees on each unit). |
| `bodies` | `Literal['auto', 'none'] \| None` | `None` | "auto" (default): granularity scales with budget-per-slot — cards when the budget can't fit any body (~<200 tok/slot), whole units in the normal range, and top hits expand toward their WHOLE FILE when the budget is generous. "none": cards… |
| `kind_prior` | `Literal['off', 'default', 'flat', 'structural'] \| None` | `None` | Chunk-kind prior override: None = code_search_kind_prior; "default" / "flat" pick a table, "structural" applies only the phrasing rule, "off" disables. |
| `pr_leg_before` | `datetime \| None` | `None` | Only PRs merged strictly before this instant may vote — the time-travel pin a bench mined from merged PRs needs so the fix PR cannot vote for its own files. |
| `embedding_model` | `str` | `''` | Bench-only override of the embedding_model label the legs read: "" = the deployment embedder's model name. |
| `fresh` | `bool` | `False` | true = bypass the served-response memo and compute. |
| `min_fan_in` | `int` | `0` | Symbol fan-in (loom.code_symbol_stats, weekly). |
| `sort_by` | `Literal['score', 'fan_in']` | `'score'` | "score" = ranked relevance order; "fan_in" = order the pool by `fan_in`, most-called first. |
| `pattern` | `str` | `''` | Constrained search: a literal (default) or RE2 regex that every returned chunk must contain — applied to BOTH legs' pools before ranking, so one call replaces grep-then-search. |
| `regex` | `bool` | `False` | true = `pattern` is an RE2 regex (an invalid one is a 422); false = a literal substring. |
| `case_sensitive` | `bool` | `False` | true = `pattern` matches case-sensitively; false (default) ignores case. |
| `path_globs` | `list[str]` | *(computed)* | Indexed-route file filters, rg `-g` / `-t` style: keep paths matching any glob (`*.cpp`, `src/Parsers/`), drop paths matching any exclude, restrict to a language's extension set (cpp, python, sql, ...). |
| `exclude_globs` | `list[str]` | *(computed)* | Drop paths matching any of these globs (same syntax as path_globs); at most 8. |
| `langs` | `list[str]` | *(computed)* | Keep only files of these languages by extension (cpp, c, python/py, js, ts, go, rust, java, sql, md, ...); an unknown name is a 422 listing the known ones. |
| `legs` | `Literal['hybrid', 'lexical', 'vector'] \| None` | `None` | Leg ablation for A/B: None/"hybrid" = both legs; "lexical" skips the vector leg AND the embedding call; "vector" skips the lexical leg. |
| `track_path` | `str` | `''` | Developer diagnostic, not exposed to the shunt: the path of the file the caller EXPECTED to see. |
| `vector_model` | `str` | `''` | Second vector model: the spec of an embedder the deployment lists in LOOM_CODE_SEARCH_VECTOR_MODELS. |
| `vector_shortlist` | `int \| None` | `None` | With vector_model set: > 0 = the second model shortlists this many chunk ids and the served model's vectors rescore them exactly; 0 = the second model's own distances rank the pool; None = the deployment's code_search_vector_shortlist. |
| `llm_legs` | `Literal['auto', 'none'] \| None` | `None` | `none` skips the model-backed legs — HyDE (an LLM passage, a second embed and a full scan) and a model-named concept source; `auto` (None = the deployment default, LOOM_CODE_SEARCH_LLM_LEGS_DEFAULT) runs what the deployment configures. |
| `deadline_ms` | `int \| None` | `None` | The request's wall-clock budget in ms, from arrival (values under 200 read as 200). |
| `namespaces` | `list[str]` | *(computed)* | Several namespaces at once: the single-namespace search runs once per entry, concurrently, and the rankings are interleaved by RANK in this order — scores are not comparable across namespaces (the lexical idf is per namespace). |

| Output field | Type | Meaning |
| --- | --- | --- |
| `lessons` | `list[dict[str, Any]]` | The memories about the answer's top files, best first, capped at `code_result_lessons_tokens`; each row {path, memory_key, namespace, excerpt, code_state}, with `changed_since` and `supersedes_key` when they apply. |
| `lessons_left_out` | `int` | How many rows about those files the lessons' token cap or a cut left out, with the rows another row read for the answer supersedes. |
| `results` | `list[CodeUnit]` | The ranked units served on this page, cut to top_k and the token budget; empty on an abstain with no pool or a not-covered path. |
| `route` | `str` | symbol_exact \| hybrid \| symbol_miss_hybrid |
| `next_cursor` | `str` | Continuation: opaque cursor for the next page of the ranked pool, "" when nothing ranked remains past this page (symbol routes issue none). has_more mirrors it. |
| `has_more` | `bool` | true when `next_cursor` is set, i.e. more ranked results remain past this page. |
| `history` | `dict[str, Any]` | History section: {intent: number\|phrase, numbers, items: [{number, kind, state, title, ...}], prs: [{pr_number, title, author, merged_at, files, files_total, role}], anchored: [{path, placed}], tokens}. |
| `abstain` | `bool` | true = the server does not stand behind these results (they may still be listed); `abstain_code` says why. |
| `abstain_code` | `Literal['', 'no_match', 'below_threshold', 'low_calibrated_confidence', 'not_covered', 'pattern_too_broad', 'identifier_absent', 'off_domain']` | Why it abstained: no_match (nothing survived) \| below_threshold (top cosine under the abstain threshold) \| low_calibrated_confidence \| not_covered (path outside the index) \| pattern_too_broad \| identifier_absent (no file names it) \|… |
| `abstain_reason` | `str` | Human-readable reason for the abstain, with what to do instead; "" when not abstaining. |
| `retrieval_risk` | `Literal['low', 'medium', 'high', 'abstain']` | Calibrated risk band from `retrieval_confidence`: low (>= 0.75), medium (>= 0.55), high, or abstain (below the abstain cut-off or the top cosine under its threshold). |
| `retrieval_confidence` | `float` | Calibrated confidence 0-1 from the top similarity, its margin over the second hit, `route_agreement` and the pool size; 0.0 on an abstain with no results. |
| `route_agreement` | `float` | Share (0-1) of the retrieval routes that ran and agreed: the primary hit, lexical and vector legs sharing a top-10 chunk, a fuzzy-symbol hit; 1.0 on an exact symbol hit. |
| `calibration_explanation` | `str` | The calibration inputs as text (top_similarity, margin, route_agreement, ...), plus the legs the answer ranked without past the deadline. |
| `tokens_returned` | `int` | Estimated tokens of the served page (results, history section and annotations). |
| `constrained` | `bool` | Constrained search: true when a pattern / path filter narrowed the pool; `matched_files` is the pre-count of files the constraint admits (0 when unconstrained or not counted). |
| `matched_files` | `int` | How many files the pattern / path constraint admits; 0 when unconstrained or not counted. |
| `as_of` | `dict[str, Any]` | Provenance + freshness: branch, commit, indexed_at, lag_commits (int, -1 unknown), stale (bool: lag > LOOM_CODE_STALE_AFTER_COMMITS). |
| `score_explanation` | `str` | How the answer was reached as text: fusion kind and leg row counts, legs agreement, the constraint and matched_files, priors and history votes that applied. |
| `retrieval_work` | `dict[str, int \| str]` | Counters per stage, plus `risk_source` — "table" \| "live" \| "mixed": where the served risk block came from when the precomputed table is on. |
| `trace_run_id` | `str` | Id of the loom.code_search_trace row the server writes for this call. |
| `top_similarity` | `float` | Raw cosine of the top vector-leg hit (0.0 when the vector leg did not run or the route was symbol_exact). |
| `tracked` | `dict[str, Any]` | track_path diagnostic: {path, verdict, chunks, pool, best: {chunk_id, scope, start_line, lexical_rank, vector_rank, lex_score, distance, served_rank}, lexical_floor, vector_ceiling}. |
| `fanout` | `dict[str, Any]` | Fan-out disclosure: {namespaces, interleave: "rank", timeout_ms, per_namespace: {ns: {ms, results, abstain, route, commit, trace_run_id}}, dropped: [ns...]}. |
| `note` | `str` | Caller-facing warning when retrieval is unavailable or vector indexing is incomplete; empty when neither limitation applies. |
| `legs_timed_out` | `list[str]` | The legs the deadline (or the model-leg grace) dropped — their rows are not in the ranking — and `epistemic` "partial" then, or when a content leg failed (`retrieval_work` names it). |
| `epistemic` | `Literal['', 'partial']` | "partial" when a leg timed out or a content leg failed; off the wire otherwise. |
| `partial` | `bool` | True when retrieval is unavailable, a leg timed out or a deadline cut a stage; false (and off the wire) when no such limitation was observed. |
| `partial_reason` | `str` | Explanation of unavailable or timed-out retrieval and deadline cuts; empty (and off the wire) when no such limitation was observed. |

## `code.setting_facts`

One ClickHouse setting, the four places that define it: its declaration and tier (production / important / beta / experimental / obsolete), every default change with the release it shipped in…

`POST /v1/code.setting_facts` · MCP `loom_code_setting_facts` · role `viewer` · read · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | `''` | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `consumer` | `str` | `''` | trace attribution: which integration is calling (clickgap\|claude-code\|…) |
| `name` | `str` | required | The setting name as declared (`max_threads`); a name that cannot be a setting answers `not_a_setting`. |
| `history_limit` | `int` | `10` | At most this many default changes in `history`, newest release first (1..50). |

| Output field | Type | Meaning |
| --- | --- | --- |
| `name` | `str` | The setting asked about, trimmed. |
| `verdict` | `str` | known \| not_a_setting \| unknown |
| `causes` | `list[str]` | control_failed \| no_declaration \| invalid_name \| history_unread |
| `declaration` | `dict[str, Any]` | {file, line, type, default, description, tier, alias} |
| `tier` | `str` | The declaration's tier (production \| important \| beta \| experimental \| obsolete); '' without a declaration. |
| `history` | `list[dict[str, Any]]` | [{version, old, new, reason, line}], newest release first |
| `randomized_in_ci` | `dict[str, Any]` | {randomized, file, line, sampler, randomizer} |
| `tests_total` | `int` | test files under tests/ whose chunks name the setting (a floor) |
| `control` | `dict[str, Any]` | {setting, ok}: the positive control this call ran; ok=False ⇒ unknown |
| `trace_run_id` | `str` | Id of this call's trace row ('' for an invalid name); pass it to `code.outcome`. |

## `code.symbol`

Exact symbol lookup: definition, signature, doc comment, and body of a function/class/enum by (qualified) name — compiler-grade where available (tier='scip'), resolved across C++ overloads…

`POST /v1/code.symbol` · MCP `loom_code_symbol` · role `viewer` · read

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | `''` | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `consumer` | `str` | `''` | trace attribution: which integration is calling (clickgap\|claude-code\|…) |
| `name` | `str` | `''` | bare, qualified, or partially qualified name — or `path:line` ("src/Foo.cpp:123"), which resolves to the innermost function containing that line: a grep hit or review comment becomes the whole function in one call. |
| `symbol_id` | `str` | `''` | An index symbol id (a definition's `unit_id`, an edge's `*_symbol_id`); when set it wins over `name` and resolves exactly that definition. |
| `include_body` | `bool` | `True` | Read each definition's body; a 200+ line class ships its skeleton plus member outline instead. |
| `include_history` | `bool` | `True` | Attach `recent_prs` (merged PRs over the definitions' paths) to the first definition. |
| `include_examples` | `bool` | `True` | Attach `examples` (call sites that use the symbol) to the first definition. |
| `include_lessons` | `bool` | `True` | Attach `lessons` to the first definition: the memories linked to the symbol from `lesson_namespaces` (over MCP the caller's memory home by default) and the repository's team namespace, each with its `code_state` (`fresh`, `moved`, or… |
| `lesson_namespaces` | `list[str]` | *(computed)* | The memory namespaces whose linked memories `lessons` reads besides the repository's team rules (over MCP the caller's memory home by default); one the caller cannot read is skipped. |
| `token_budget` | `int` | `2500` | Estimated-token budget for the answer; definitions past it are served elided (signature, doc, pointer), and the `uses_brief` block is paid out of it first. |
| `min_fan_in` | `int` | `0` | Definitions carry `fan_in` when the weekly stats are enabled; min_fan_in drops the rest, sort_by='fan_in' puts the most-called definition of an overloaded/ambiguous name first. |
| `sort_by` | `Literal['score', 'fan_in']` | `'score'` | `score` keeps the resolver's order; `fan_in` puts the most-called definition first. |
| `uses` | `bool \| None` | `None` | `uses=true` returns the definition AND the lines that mention its bare name — what a separate code.grep on the name would return, read beside the definition from the same chunk index — minus the definition's own span(s). |
| `uses_limit` | `int` | `50` | At most this many `uses` lines (1–200) when `uses` is true. |
| `uses_brief` | `bool` | `False` | Serve the compact `uses` block when the lookup resolves to one definition; ignored when `uses` is true. |
| `near_paths` | `list[str]` | *(computed)* | When several definitions match, rank them by the change at hand — the files in `near_paths` (<= 20) or the merged PR's file list for `pr_number` from the ledger: same file, same directory, co-change in code_pr_history, then path distance. |
| `pr_number` | `int` | `0` | A merged PR whose file list (from the PR ledger) ranks several matching definitions; 0 = no PR ranking. |
| `namespaces` | `list[str]` | *(computed)* | Presence on several namespaces: `presence: true` runs the resolve once per entry of `namespaces` (at most 8; `namespace`, when set and absent, leads the list; unset list = the addressed namespace alone), concurrently under… |
| `presence` | `bool` | `False` | Answer per namespace in `namespaces` whether the definition is there (the `presence` / `summary` blocks) instead of returning definitions. |
| `neighbours` | `bool \| None` | `None` | The neighbours graph block for the resolved definitions themselves — k callers, callees, tests and citing documents per definition, in the same call. |
| `neighbour_k` | `int` | `5` | How many callers, callees, tests and citing documents (each) the `neighbours` block lists per definition. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `definitions` | `list[CodeUnit]` | The resolved definitions (at most 10), fitted to `token_budget`; empty when nothing resolved (see `candidates`) or on a presence answer. |
| `ambiguous` | `bool` | True when the served definitions carry more than one distinct name/signature pair. |
| `hierarchy` | `dict[str, list[dict[str, Any]]]` | For a class / interface / enum definition, its type hierarchy from the `inherits` edges of both tiers, folded by qualified name: {"supertypes": [...], "subtypes": [...]} of {symbol, kind, via (extends \| implements), tier, confidence, path… |
| `candidates` | `list[dict[str, Any]]` | When nothing resolved: cheap fuzzy candidates (names + paths only). |
| `tokens_returned` | `int` | Estimated tokens of the answer: definitions, uses, cited documents, neighbours and hierarchy blocks together. |
| `trace_run_id` | `str` | Id of this call's trace row; pass it to `code.outcome`. |
| `uses` | `list[dict[str, Any]] \| dict[str, Any]` | uses=true: {path, line, text, scope, scope_start_line, scope_end_line, kind} per line mentioning the symbol's bare name, path/line ordered, the definition span(s) excluded. |
| `uses_truncated` | `bool` | True when the `uses` list stopped at `uses_limit`. |
| `uses_tokens` | `int` | Estimated tokens the compact `uses` block cost out of `token_budget`. |
| `picked_by` | `str` | Which context key ranked the definitions when `near_paths` / `pr_number` was given — same_file \| same_dir \| co_change \| path_distance \| none. "" and off the wire when no context was given. |
| `resolved_by` | `str` | `anonymous_namespace` \| `tail` when an over-qualified name bound through symbol-form tolerance; "" and off the wire otherwise. |
| `documented_in` | `list[dict[str, Any]]` | The document sections that cite the definition (the Markdown lane's `reads` edges) — section qualified name, path, line; at most five distinct sections, first by confidence. |
| `neighbours` | `list[dict[str, Any]]` | The neighbours graph block on the definitions (one entry per definition anchor); empty unless `neighbours` ran. |
| `anchors` | `int` | How many definitions the `neighbours` block was built for; 0 when it is off. |
| `neighbour_tokens` | `int` | Estimated tokens the `neighbours` block cost (counted in `tokens_returned`). |
| `presence` | `list[dict[str, Any]]` | presence=true: one row per requested namespace, in request order — {namespace, verdict: present \| absent \| unknown, path, start_line, end_line, tier, indexed_commit, index_status, ms, reason, definitions}. |
| `summary` | `dict[str, list[str]]` | Presence summary: {present, absent, unknown} lists of namespaces; also filled from the entry's `depends_on` namespaces when the name is not defined here. |

## `code.symbol_history`

The regression history of one function: the merged PRs that touched it (with linked issues, reverts, inline review comments inside its span), and — through the tracker namespace bound to this code…

`POST /v1/code.symbol_history` · MCP `loom_code_symbol_history` · role `viewer` · read · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | `''` | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `consumer` | `str` | `''` | trace attribution: which integration is calling (clickgap\|claude-code\|…) |
| `name` | `str` | `''` | A qualified symbol name or `path:line`. |
| `symbol_id` | `str` | `''` | An index symbol id; wins over `name`. |
| `limit` | `int` | `15` | At most this many PR rows (1–60). |

| Output field | Type | Meaning |
| --- | --- | --- |
| `verdict` | `str` | history \| no_history \| unknown |
| `causes` | `list[str]` | symbol_unresolved \| symbol_ambiguous \| tracker_unavailable |
| `epistemic` | `str` | Always `lower_bound`: the PRs are those the ledger holds over the definition's file. |
| `symbol` | `dict[str, Any]` | {qualified_name, path, start_line, end_line, tier} |
| `ambiguous` | `bool` | As on code.callers: the name resolved to several distinct definitions; no history was read, `candidates` are their qualified names (qualify the name or pass symbol_id). |
| `candidates` | `list[str]` | With `ambiguous`: up to 20 qualified names to pick from. |
| `prs` | `list[dict[str, Any]]` | newest first: {pr_number, title, author, merged_at, is_revert, is_fix, touches_symbol true\|named\|false\|unknown, linked_issues[{number,title,state}], comments_on_symbol, qa{has_test, ci_result, first_release, caused[], names[]}} |
| `review_comments` | `list[dict[str, Any]]` | inline review comments inside the symbol's span, newest first (≤5) |
| `open_issues_naming` | `list[dict[str, Any]]` | open issues whose text names the function (QA), most severe first (≤5) |
| `summary` | `dict[str, Any]` | {prs_total, named_prs, fix_prs, named_fix_prs, reverts, caused_issues[], open_issues_naming, last_touched, oldest_in_window, authors[], note} |
| `tracker_namespace` | `str` | The tracker namespace that answered the QA side; "" when none is bound or its read failed. |
| `tracker_unavailable` | `bool` | True when a tracker is bound but its read failed. |
| `trace_run_id` | `str` | Id of this call's trace row; pass it to `code.outcome`. |

## `code.test_gate`

The pre-PR question in one call: for THIS change, which tests must run, and which touched code no test reaches.

`POST /v1/code.test_gate` · MCP `loom_code_test_gate` · role `viewer` · read · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | `''` | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `consumer` | `str` | `''` | trace attribution: which integration is calling (clickgap\|claude-code\|…) |
| `files` | `list[str]` | *(computed)* | Changed file paths; a test file here is itself a test to run. |
| `diff` | `str` | `''` | A unified diff; its hunks (line spans, hunk-header names) pick the touched functions. |
| `depth` | `int` | `2` | Reverse-edge hops to look for tests through. |
| `limit` | `int` | `30` | At most this many rows in each of `tests` and `untested` (at most 200). |

| Output field | Type | Meaning |
| --- | --- | --- |
| `tests` | `list[dict[str, Any]]` | {test_path, why, evidence, run, run_unknown, [src_path], [confidence], [hop]} why in {changed_test, stem_partner, test_map, graph_hop}, strongest first. |
| `untested` | `list[dict[str, Any]]` | Touched source symbols no test reaches by any evidence class: {qualified_name, path, start_line}. |
| `changed_files` | `list[str]` | The change as the gate saw it. |
| `touched_symbols` | `list[dict[str, Any]]` | The source symbols the change touches, {qualified_name, path, start_line, tier}, by path and line (first 200). |
| `obligations` | `bool` | True while either list is non-empty: run the tests, then rely on green; write a test for (or explain) the untested rows. |
| `tests_total` | `int` | Rows of `tests` before `limit`. |
| `untested_total` | `int` | Rows of `untested` before `limit`. |
| `tests_capped` | `bool` | True when `limit` cut `tests` short of `tests_total`. |
| `untested_capped` | `bool` | True when `limit` cut `untested` short of `untested_total`. |
| `counts_floor` | `bool` | Same epistemic contract as code.callers: the graph is a floor, so "no test reaches this" means none the index can see. |
| `epistemic` | `str` | Epistemic envelope, as on code.callers: "exact" when the compiler tier covers every seed file, no call site named like a seed was declined, and no override seed lacks its base; otherwise "lower_bound" with `causes` from {unresolved_calls… |
| `causes` | `list[str]` | Why `epistemic` is lower_bound (values above); [] when it is exact. |
| `by_hop_counts` | `dict[int, int]` | Distinct symbols reached per hop BEFORE any slicing: {1: n, 2: m}. |
| `trace_run_id` | `str` | Id of this call's row in `loom.code_search_trace`. |

## `code.test_home`

Where does a new test case belong?

`POST /v1/code.test_home` · MCP `loom_code_test_home` · role `viewer` · read · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | `''` | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `consumer` | `str` | `''` | trace attribution: which integration is calling (clickgap\|claude-code\|…) |
| `file_stems` | `list[str]` | *(computed)* | Source file stems the change affects (a path or extension is stripped); matched in test content and against indexed source paths. |
| `settings` | `list[str]` | *(computed)* | Setting names the test uses (lower snake_case); others are dropped. |
| `engine` | `str` | `''` | The engine class (`MergeTree`; parameters stripped), matched as `ENGINE = <name>`. |
| `symbols` | `list[str]` | *(computed)* | Symbols the test exercises; the part after the last `::` is what is matched. |
| `limit` | `int` | `10` | At most this many `candidates` (at most 50). |

| Output field | Type | Meaning |
| --- | --- | --- |
| `verdict` | `str` | add_case_to \| new_file_justified \| unknown |
| `home` | `str` | The top candidate's path when the verdict is add_case_to; '' otherwise. |
| `candidates` | `list[dict[str, Any]]` | {path, matched: ["setting:x", "engine:MergeTree", …], map_confidence, score, reference: the candidate's indexed expectation file or null} |
| `parts` | `list[str]` | The fingerprint as normalized, `kind:value` per part (stem, setting, engine, symbol). |
| `src_paths` | `list[str]` | Indexed source files whose stem is one of `file_stems` (first 20). |
| `next_free_stateless_number` | `int` | The highest stateless test number in the index plus one; 0 when none was found. |
| `control` | `dict[str, Any]` | {symbol, ok}: the positive control this call ran; ok=False ⇒ unknown |
| `trace_run_id` | `str` | Id of this call's row in `loom.code_search_trace`. |

## `code.tests_for`

Which stateless tests carry EVERY named facet: the tests that `SET` a setting, call a function, create an `ENGINE`, read a `system.*` table, use a `FORMAT`, carry a `-- Tags:` tag, or expect an error…

`POST /v1/code.tests_for` · MCP `loom_code_tests_for` · role `viewer` · read · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | `''` | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `consumer` | `str` | `''` | trace attribution: which integration is calling (clickgap\|claude-code\|…) |
| `facets` | `list[dict[str, str]]` | required | {kind, name} per facet (kinds above; an unknown kind or an empty name is refused); duplicates are dropped. |
| `limit` | `int` | `50` | At most this many `tests` rows (at most 500). |
| `closest` | `bool` | `False` | `closest: true` answers "the existing test most like this one" instead of "the tests carrying every facet": candidates share at least one facet and rank by a weighted per-kind Jaccard over their whole facet sets; each row carries… |

| Output field | Type | Meaning |
| --- | --- | --- |
| `tests` | `list[dict[str, Any]]` | {path, ordinals, lines, confidence, same_statement}, keyword-bound matches (confidence 1.0) before call-shaped ones (0.8), then by path; with `closest`: {path, similarity, shared, missing, extra_facets} by similarity descending. |
| `total` | `int` | matching tests before `limit` |
| `truncated` | `bool` | True when `total` exceeds the rows returned. |
| `facets` | `list[dict[str, str]]` | as resolved |
| `verdict` | `str` | '' when rows were returned; `no_match` when the namespace holds facet rows of every asked kind but none carry these names (an answer); `not_covered` when some asked kind has no row in the namespace at all (its lanes never wrote that kind… |
| `abstain` | `bool` | True only for `not_covered` (the index cannot answer; grep instead). |
| `uncovered_kinds` | `list[str]` | the kinds behind not_covered |
| `as_of` | `dict[str, Any]` | Provenance + freshness: branch, commit, indexed_at, lag_commits (int, -1 unknown), stale (bool: lag > LOOM_CODE_STALE_AFTER_COMMITS), status. |
| `tokens_returned` | `int` | Estimated tokens of the returned paths (about 4 characters per token). |
| `took_ms` | `int` | Server time spent on the call, in milliseconds. |
| `trace_run_id` | `str` | Id of this call's row in `loom.code_search_trace`. |

## `code.trace`

Paste a stack trace / backtrace; get each frame resolved to its definition in one call — the incident-workflow entry point.

`POST /v1/code.trace` · MCP `loom_code_trace` · role `viewer` · read

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | `''` | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `consumer` | `str` | `''` | trace attribution: which integration is calling (clickgap\|claude-code\|…) |
| `trace` | `str` | required | The stack trace or backtrace text; qualified `a::b` names and C/C++ `dir/file.cpp:N` locations are read as frames (`std::`, `boost::`, `absl::`, `__*` frames skipped). |
| `max_frames` | `int` | `15` | Resolve at most this many distinct frames, in trace order (1..40). |
| `token_budget` | `int` | `3000` | Token budget for `definitions` (200..12000); units past it are dropped. |

| Output field | Type | Meaning |
| --- | --- | --- |
| `frames` | `list[dict[str, Any]]` | One entry per recognized frame, trace order: {frame, qualified_name, path, line, symbol_id, resolved}. |
| `definitions` | `list[CodeUnit]` | The resolved definitions, whole units within `token_budget`. |
| `tokens_returned` | `int` | Estimated tokens of `definitions`. |
| `trace_run_id` | `str` | Id of this call's trace row; pass it to `code.outcome`. |

## `code.verify`

Verify one closed-form claim against the index and return a three-valued verdict.

`POST /v1/code.verify` · MCP `loom_code_verify` · role `viewer` · read

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | `''` | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `consumer` | `str` | `''` | trace attribution: which integration is calling (clickgap\|claude-code\|…) |
| `kind` | `Literal['calls', 'unused', 'defines', 'contains', 'reaches']` | required | The claim's shape: calls \| unused \| defines \| contains \| reaches (see above). |
| `subject` | `str` | required | What the claim is about: a symbol name, or a repo-relative path for defines/contains. |
| `object` | `str` | `''` | The claim's other end: a symbol, a literal (contains) or a path prefix (reaches); '' for unused. |
| `depth` | `int` | `4` | For calls and reaches: the most call hops the walk follows (1..6). |

| Output field | Type | Meaning |
| --- | --- | --- |
| `verdict` | `Literal['confirmed', 'refuted', 'not_established']` | A subject or object that resolves no symbol is a RESOURCE_NOT_FOUND refusal, not a verdict; its detail carries `role` (subject \| object) and `did_you_mean`, up to 5 of code.symbol's near misses {qualified_name, path, kind, tier, start_line… |
| `reason` | `str` | Machine-readable cause, stable for bots to branch on. |
| `explanation` | `str` | A human-readable account of how the verdict was reached. |
| `evidence` | `list[dict[str, Any]]` | Positive rows behind the verdict: edges (a call chain, in order), symbol rows, or content excerpts — shape depends on kind. |
| `floors` | `dict[str, Any]` | Why refutation was unavailable when the verdict is not_established: what was searched, how far, and which blind spots apply. |
| `index_verdict` | `str` | The index's own verdict behind a `not_established` claim ('' otherwise). |
| `trace_run_id` | `str` | Id of this call's trace row; pass it to `code.outcome`. |

## `code.verify_citations`

Every citation a draft carries, resolved against the index before the draft is posted somewhere public and irreversible.

`POST /v1/code.verify_citations` · MCP `loom_code_verify_citations` · role `viewer` · read · not listed under the MCP `all` toolset

| Input field | Type | Default | Meaning |
| --- | --- | --- | --- |
| `pr_files` | `dict[str, str]` | *(computed)* | Repo-relative path -> the file's full text at the PR's head, for the files the PR adds or modifies (at most 50, 1,000,000 characters each). |
| `pr_diff` | `str` | `''` | The PR's unified diff against its merge-base (at most 1,500,000 characters): its hunks say which functions the PR modifies, and its paths name the files it deletes. |
| `pr_head_sha` | `str` | `''` | The PR's head and base commits as the caller knows them; they label the answer (`overlay_head_sha`) and never reach git. '' = derived from the text. |
| `pr_base_sha` | `str` | `''` |  |
| `org` | `str` | `''` | The tenant (first element of the identity tuple). |
| `namespace` | `str` | `''` | The namespace the op reads or writes. |
| `agent` | `str` | `'-'` | The writing or reading agent; `'-'` or `'*'` means any agent where the op allows it. |
| `user_id` | `str` | `'-'` | The end user the row belongs to; `'-'` for none. |
| `consumer` | `str` | `''` | trace attribution: which integration is calling (clickgap\|claude-code\|…) |
| `text` | `str` | required | The draft to check: a review comment, PR body or answer, as plain text or Markdown. |
| `at_commit` | `str` | `''` | The commit the draft was written against; '' = check against the index head only (or the PR's merge commit with `pr_number`). |
| `pr_number` | `int` | `0` | The reviewed PR; 0 = no PR-diff leg |
| `base_namespace` | `str` | `''` | Namespace read after the addressed one for citations it did not resolve; '' = the mirror's default-branch entry when the addressed one is a release branch. |
| `limit` | `int` | `200` | citations verified per call, first-appearance order; the rest are counted in `truncated` |

| Output field | Type | Meaning |
| --- | --- | --- |
| `verdict` | `str` | all_resolved \| has_unresolved \| has_stale \| no_citations. |
| `counts` | `dict[str, int]` | total, resolved, unresolved, stale, ambiguous, kind_<kind> counts |
| `citations` | `list[dict[str, Any]]` | one per distinct citation, first-appearance order: {kind, text, verdict, reason, epistemic, occurrences, path?, start_line?, end_line?, number?, name?, rev?, form?, in_pr_diff?, in_code_block?, target?, candidates?}. form: basename \|… |
| `skipped` | `list[dict[str, Any]]` | names not verified because their outermost scope is an external library (std::, boost::, …): {kind, text, reason} |
| `truncated` | `bool` | True when the draft held more distinct citations than `limit`; the rest are unchecked. |
| `epistemic` | `dict[str, str]` | per check: path / number / name / commit -> exact; line -> lower_bound |
| `at_commit` | `dict[str, Any]` | {requested, sha, known, calls, capped, ms, error} — the mirror leg |
| `pr_diff` | `dict[str, Any]` | only with `pr_number`: {pr_number, merge_sha, source: ledger \| mirror_log \| "", files_in_diff, in_diff, off_diff, unknown, calls, ms, error: "" \| pr_unknown \| log_failed \| diff_failed \| hunks_failed} |
| `namespaces` | `list[str]` | The namespaces read, in order: the addressed one, then the base one if any. |
| `took_ms` | `int` | Server-side wall time of the call, in milliseconds. |
| `as_of` | `dict[str, Any]` | Provenance + freshness: branch, commit, indexed_at, lag_commits (int, -1 unknown), stale (bool: lag > LOOM_CODE_STALE_AFTER_COMMITS). |
| `note` | `str` | How far the checks can be trusted, plus why a leg was cut (unknown commit, capped mirror leg, PR not found, truncated citations). |
| `trace_run_id` | `str` | Id of this call's trace row; pass it to `code.outcome`. |

<!-- prettier-ignore-end -->
