04 Operations Reference

Operations Reference

All 22 facade operations, the answer envelope, and how to read it. Surface mapping: 22 facade op_* · 23 MCP tools (ragraf_* — adds ensure, omits calibrate) · 23 CLI query ops (adds usage, served via telemetry).

---

The envelope (every answer, every channel)

{
  "op": "impact",
  "index_rev": "rev-0007",
  "capability": "full",              // full | degraded
  "drift": { "files": 3, "symbols": 7, "entries": 4 },
  "provenance": "index",             // index | live | mixed
  "freshness": { "changed_since_index": false, "...": "..." },
  "limits": ["static analysis; runtime dynamics not covered"],
  "found": true,
  "result": [ /* ... */ ],
  "stale_warnings": [
    { "path": "src/x.php", "reason": "modify after rev-0007",
      "since": "2026-10-04T14:32:00+03:00", "suggest": "live_read" }
  ]
}

Reading rules:

• found=false with exit code 0 = «not found», not a failure. Exit 3 = «operation cannot run now» (e.g. slice at capability≠full).
• Non-empty stale_warnings → the fact may have been touched by post-revision edits. Never present it as current without the mark; live_read first.
• provenance=live → data came from reading the file, not the index; its evidence is the file itself.
• limits is mandatory reading: ignoring it means concluding on an incomplete picture.
• Blocks stated and derived are separated wherever links are served (impact, callers). A conclusion resting on derived requires verification.

---

Navigation & search

search — «where is this written about»

Hybrid: FTS5/BM25 lexicon + 384-dim vector, RRF merge (vector list is excluded from the merge when it doesn't discriminate — all-equal scores). Each hit: chunk_id, path, line range, score, why. Params: query (required), limit (20), with_text (adds snippet from the index — saves the second call), text_width (160). text_from_index: true confirms the source; hits without text are counted in limits, never silent. Does not show: link evidence — this is search, not the graph.

symbol — «where is it defined»

Node(s) by name/fqn (+ optional path filter): kind, file, start_line/end_line, signature, parsed parameters. Includes the parameter contract: signature_params (types, optionality, defaults, by-ref, variadic), array_shape from docblock array{k:type, k?:type} notation, signature_truncated marker, params_hint when the composition is unknown. Does not show: the body (use code).

references — «where else is it used»

All usage sites with path:line and line context. Does not show: execution order.

repo_map — «the overall structure»

Modules → files → key symbols within a budget (--budget, default 2000; ranked by connectivity/centrality). The budget counts actual serialized characters (chars_used), not synthetic estimates. Does not show: links between entries.

code — «show the text» (explicit request only)

Symbol bodies by name/path or by --entry-ids (node_id/chunk_id from search hits; unrecognized ids come back as unresolved, never dropped). Source per span: text_source: index|disk; default reads from the index (--source disk for the working tree, auto falls back). --include-containers adds enclosing-class headers. changed_since_index fires when the file moved past the revision — trust decision stays with the caller. Does not show: the meaning of calling sites.

Graph operations

callers / callees — «who calls / what it calls»

By fqn, depth 1..3. Proven (calls, from CPG-confirmed links) and heuristic (calls_heuristic: variable-functions, call_user_func, include wrappers) are separate blocks. --hard / hard_only=true → proven only. Does not show: calls through strings or data references.

impact — «what will my edit break»

From a node, path or table name; --mode hard|full (default full). Affected files/symbols/tables/routes/tests split by provability; recursive CTEs over edge at depth ≤ 3. Does not show: branch conflicts, runtime behavior. Always run before editing a public method or a table.

slice — structural slice (requires capability=full)

Nodes + edges + line ranges around a symbol, --direction back|forward — without function bodies (bodies only via code). Refuses with exit code 3 and the reason when the CPG is absent — that is the contract, not a bug. Note: the shipped slice traverses confirmed call links; merging the extracted CFG/DFG (444 K + 930 K edges on the pilot) into a true dependency slice is roadmap R-CPG-2.

Database & contracts

schema — «what is in the table»

Tables, columns, types, keys, FKs — parsed from migrations (works with no DBMS access) and/or information_schema when configured; every table carries its source. Divergences between sources are reported, not merged silently. Does not show: the live database's actual state. Facts here have no line numbers by nature (why overall verifiability is 24.4% while code operations are at 100%).

table_usage — «who reads/writes it»

Read and write sites with path:line, split by --mode all|read|write; access kind (select/insert/update/delete/ddl) from edge properties. Does not show: DB-level grants.

write_check — «is this write valid» (before running it)

Table + --columns "A,B,C" + --operation insert|update|delete → missing columns with the nearest existing names (UpdatedBy → UpdatedAt, DeletedBy), required-for-insert columns, primary key, similar_tables on a table-name typo. The operation that turned «SQLSTATE at runtime» into «never written wrong». Does not show: value types and constraints.

routes — «entry points»

HTTP routes and handlers with evidence. Does not show: behavior behind the handler.

Policy & presentation

policy_trace — «who gets this permission, and why»

Decision branches of a permission function: allow/deny points with file:line, the case value, default behavior, fail-closed control, application points (callers). --operation <action> filters to one action. Found the most expensive class of defect statically: an early return true before the switch granting every journal holder approve/mark_paid/sign/archive. Does not show: a concrete user's actual role.

class_usage — «styling classes»

Is the class described in the stylesheets, where is it applied, what diverges (--mode all|missing|unused). A missing rule is not an error — the page renders with browser defaults; this operation makes the gap visible (the login-page case: 25 classes used, 9 absent from CSS). Does not show: the final rendered look, the cascade.

Freshness, state & meta

freshness — «is the index current»

Checksum comparison (15-s cache; --force bypasses), auto-reindex per the accumulated-edits thresholds (1–19 fast, 20+ or >15 min full). Result rides in every envelope too. Does not show: the quality of the facts themselves.

index_status — call first in any session

Revision, parse completeness, coverage, stages with timings, capability + reason, ledger size, compute state (GPU/CPU + reason).

drift_report / drift_ack

The ledger: what changed after the revision (files, symbols, affected edges), --since <id>. drift_ack appends an acknowledgment — it never deletes an entry (append-only invariant I2).

live_read — «the file as it is now»

Current content with mandatory highlighting of fragments differing from the index; provenance: mixed. Use when a path is in stale_warnings or definitely changed.

usage — «what did this give us»

Call telemetry: per-op counts, facts, facts-with-span share, saved reads/tokens estimates; filters --agent, --agent-kind, --task (the RAGRAF_TASK label), --reset for a clean before/after. Reading usage never writes telemetry.

catalog — «what is registered»

The machine's development registry: per corpus — revision, checksum, hash_matches state, file/node/edge counts, run history with triggers (register, ensure:index, guard:fast, …).

calibrate — thresholds (facade/CLI only, not an MCP tool)

Recomputes thresholds/confidence levels from samples; writes a calibration row.

ensure — (MCP tool + CLI subcommand, not a facade op)

Find-or-create-or-refresh a corpus by project directory; statuses actual|reindexed|created|not_a_project|error. The agent's one-call «make RAGRAF ready for this repo».

---

Choice rules (from the field skill)

1. Navigation is an operation; content is reading. «Where» → operation; «how exactly» → read the fragment it pointed to.
2. A write plan is always write_check — the only check that catches a nonexistent column before the code runs.
3. Permission decisions are always policy_trace — an unknown action left allowed-by-default is visible only statically.
4. Before markup edits — class_usage — a missing style rule throws no error.
5. slice only at capability=full — exit 3 otherwise is expected behavior.
6. live_read only when the file definitely changed — otherwise the index is cheaper.
7. Whole-file reads are the last resort — after «not found» or a stale mark.

What does not exist (by design)

• No graph query language. Text resembling Cypher/CPGQL in arguments is rejected with -32602. (Known issue: the substring check false-positives on legitimate text containing e.g. «return » — R-SEC-2.)
• No writes through the facade. The index changes only via index/reindex/the guard.
• No unified test runner yet and no dependency version-check command (despite requirements.txt promising one) — both in the roadmap (R-T5, R-PKG-2).

---

Next: CLI Reference → · Agent-side usage: MCP Integration →