feat(chat): the maintainer grounding-tool registry, read-only by construction - #10099
Conversation
…truction First half of #9189, implementing the catalog #9187's spec confirmed. Six tools that return deterministic JSON read from state ORB already holds -- grounding, not generation: a maintainer asking "why is this PR held" gets the recorded verdict, not a paraphrase of one. READ-ONLY IS ENFORCED, NOT PROMISED. GroundingServices is the tools' ENTIRE capability surface, and it holds no Octokit, no token and no mutation. A tool cannot perform a write because there is nothing in scope to write with. Two tests assert that as a property of the source rather than of a runtime object: the interface names no write capability, and the module imports nothing at all -- a tool that reached for its own Octokit would bypass the injected surface entirely. REDACTION IS STRUCTURAL. Every response is built by NAMING its fields. The test that distinguishes this from a blocklist feeds each service a payload carrying walletAddress, hotkey, rewardValue, trustScore, privateRanking and authorEmail, and asserts none reaches the serialized result. A blocklist has to anticipate every field an upstream type might grow; an allowlisted shape cannot leak one nobody wrote down. The accuracy union passes through WHOLE rather than being flattened -- coverage and interval are what make it a claim rather than marketing, which is why fairness_summary reuses buildProofSummary instead of aggregating again, and why chat and /proof cannot disagree about a number. DETERMINISM: identical state produces identical BYTES, so a retry does not re-ground the model differently and a cache means something. Every list is sorted on a stable key; a test drives the same service returning a set in reversed order and asserts the bytes match. An absent source reports `available: false`, never an error and never a zero. A deployment without a ledger is not a broken one, and an empty queue would read as "nothing to do". Two of the spec's eight candidate tools are deliberately ABSENT. decision_record_by_digest and audit_tail have no reader today -- the nearest are by pull number and by sequence respectively -- so shipping them would mean inventing SQL inside a chat PR, which requirement 1 rules out. Recorded on the issue with options; each needs its own authz and redaction review. Registered in STAGED_AHEAD_OF_CONSUMERS because this is a seam landed ahead of its callers: binding GroundingServices to the real readers and wiring the protected route with its authz is the second half of #9189, and it deserves its own pass rather than riding along here. Mutation-tested: spreading the config object instead of naming fields fails 3, dropping a sort fails 2, flattening accuracy to a bare number fails 2. Refs #9189
|
Caution 🛑 LoopOver review result - fixes requiredReview updated: 2026-07-31 07:33:10 UTC
Review summary Nits — 6 non-blocking
CI checks failing
Decision drivers
Context & advisory signals — never blocks the verdict
Linked issue satisfactionPartially addressed Review context
Contributor next steps
Signal definitions
🧪 Chat with LoopOverAsk LoopOver a question about this PR directly in a comment — grounded only in the same cached, public-safe facts shown above, never a new claim.
Full command reference: https://loopover.ai/docs/loopover-commands 🧪 Experimental — new and may change. Decision record
🟩 Safe / merged · 🟦 Advisory · 🟨 Held for review · 🟥 Blocked / closed 💰 Earn for open-source contributions like this. Gittensor lets GitHub contributors earn for the work they already do — register to start earning →. Checked by LoopOver, a quiet PR intelligence layer for OSS maintainers.
|
|
Superagent didn't find any vulnerabilities or security issues in this PR. |
Codecov Report❌ Patch coverage is
Additional details and impacted files@@ Coverage Diff @@
## main #10099 +/- ##
==========================================
- Coverage 91.88% 91.88% -0.01%
==========================================
Files 930 931 +1
Lines 113839 113865 +26
Branches 27470 27479 +9
==========================================
+ Hits 104600 104623 +23
Misses 7940 7940
- Partials 1299 1302 +3
Flags with carried forward coverage won't be shown. Click here to find out more.
|
1 participant
First half of #9189 — the grounding catalog #9187's spec confirmed. Six read-only tools returning deterministic JSON from state ORB already holds.
This does not close #9189. Binding
GroundingServicesto the real readers and wiring the protected route with its authz is the second half, and it deserves its own pass rather than riding along here. Registered inSTAGED_AHEAD_OF_CONSUMERSwith that reason, which is the mechanism the repo provides for a seam landed ahead of its callers.Read-only is enforced, not promised
GroundingServicesis the tools' entire capability surface, and it holds no Octokit, no token, no mutation. A tool cannot write because there is nothing in scope to write with.Two tests assert that as a property of the source, not of a runtime object:
Redaction is structural, and the test proves it is not a blocklist
Every response is built by naming its fields. The distinguishing test feeds each service a payload carrying
walletAddress,hotkey,rewardValue,trustScore,privateRankingandauthorEmail, then asserts none reaches the serialized result. A blocklist must anticipate every field an upstream type might grow; an allowlisted shape cannot leak one nobody wrote down.The accuracy union passes through whole rather than flattened — coverage and interval are what make it a claim rather than marketing (requirement 6). That is also why
fairness_summaryreusesbuildProofSummaryinstead of aggregating again: chat and/proofcannot disagree about a number they compute once.Determinism
Identical state produces identical bytes, so a retry does not re-ground the model differently and a cache means something. Every list sorts on a stable key; one test drives the same service returning a set in reversed order and asserts the bytes match.
An absent source reports
available: false— never an error, never a zero. A deployment without a ledger is not a broken one, and an empty queue would read as "nothing to do".Two tools deliberately absent
decision_record_by_digestandaudit_tailhave no reader today — the nearest areloadDecisionRecordCollapsible(by pull number) and the public ledger row endpoint (by sequence). Shipping them would mean inventing SQL inside a chat PR, which requirement 1 explicitly rules out. Recorded on the issue with options; each needs its own authz and redaction review.Mutation testing
Verification
test/unitsuite 25,491 passedtypecheck,dead-source-files:check,dead-exports:check,checkers-wired:check,coverage-boltons:check,ui:lint,import-specifiers:check,fixture-clock-races:check,validate:no-hand-written-jsgreenRefs #9189