rulake-query

name	rulake-query
description	Query the witness-anchored ruLake cache — search, verify, explain, or refresh. Returns ranked results plus a decision_trace block with cost, latency, witness match, and substrates used.

/rulake-query

Wraps the rulake_query MCP tool with sensible defaults so a fresh operator can issue their first query without thinking about the intent / risk / freshness / target axes.

Inputs (all optional except the question)

• question (required): natural-language query
• intent: search | verify | explain | refresh (default: search)
• freshness_ms: tolerance for stale cache hits (default: 5000)
• risk: low | medium | high (default: low)
• target_collection: limit to a specific backend.collection (default: federated across all)

What you get back

{
  "result": [ /* ranked retrieval */ ],
  "decision_trace": {
    "chosen_path": "deterministic-retrieval-path-v0.1",
    "intent": "search",
    "freshness": { "budget_ms": 5000, "actual_ms": 1031 },
    "cache":  { "hit": true, "hit_ratio_session": 0.87 },
    "substrates_used": ["gcs-backend", "rvdna-backend"],
    "kernel": { "id": "cpu-naive", "deterministic": true },
    "witness": { "match": true },
    "cost":    { "compute_kernel": 0.0, "backend_fetch": 0.0, "cache_hit_discount": -1.0 },
    "latency": { "total_ms": 1.02, "cache_ms": 0.4, "witness_ms": 0.6 },
    "refusals": []
  }
}

The decision_trace block is the new contract from ADR-009 — it lets a calling agent negotiate cost vs trust vs latency without reaching around the abstraction. Note: the trace shape ships in v2.4 — until then, responses carry the data only and the trace is in the JSONL audit log on the server side.

Examples

/rulake-query "what does ADR-157 commit to?"

/rulake-query --intent verify --freshness_ms 0 "is bundle b1f4...3d valid?"

/rulake-query --target_collection adrs.rulake "list all merged ADRs"

See also

• ADR-004 §4b — the eight tool tier matrix
• ADR-009 — the deterministic retrieval path + decision_trace shape