orb(chat): read-only grounding tool registry over maintainer surfaces — authz and redaction enforced by tests

[JSONbored]

Context

Part of the ORB maintainer chat platform epic; implements the grounding side per the spec sub-issue's recorded decisions (do not start before that spec closes — the tool list below is the candidate set, and the spec may trim or extend it). Mirrors the contributor pattern of #6517: read-only, deterministic, JSON tool results that the chat model consumes — grounding, not generation.

Requirements

1. A tool-registry module in src/ exposing the spec-confirmed read-only tools over existing services (queue snapshot, per-PR status + gate verdict + blocker reasons, decision-record fetch, ledger-verify proxy, calibration summary, effective-config resolution, audit-event tail, repo-settings snapshot). Each tool wraps an existing service/module — no new data paths, no new SQL surfaces invented for chat.
2. Authz on every call: per-repo maintainer verification through the existing helpers (the authz doc-comment over src/api/routes.ts's helpers is the source of truth). Cross-repo access denies. Affiliation-tier behavior exactly as the spec decided.
3. Redaction is structural: every tool response passes the existing public-safety redaction path before leaving the API; wallet/hotkey/reward/private-ranking/raw-trust fields are unreachable by construction (allowlisted response shapes, not blocklist filtering).
4. Read-only is enforced, not promised: no tool may hold an installation Octokit in write mode; add a unit test asserting the registry performs zero GitHub writes (mirroring the no-direct-octokit invariant style).
5. Per-tool response token budgets and deterministic ordering (stable sort keys) so identical state produces identical grounding.
6. Accuracy/calibration responses always carry coverage and confidence interval alongside any accuracy figure.

Deliverables

• The tool registry + route wiring on the protected API, feature-flagged off by default (LOOPOVER_REVIEW_*-style flag, ships OFF).
• Unit tests: per-tool authz-deny (cross-repo actor), redaction shape tests, the zero-writes invariant test, determinism test (two identical calls, identical bytes).
• Docs: a short tool-catalog reference section (the spec's catalog, as-built).

Expected outcome

The chat backend can answer "what's blocking the queue?" and "why did the gate close #123?" from real ORB state, with authz and redaction guaranteed by tests rather than convention.

[linear-code]

JSO-6349

[JSONbored]

Correcting a reference before implementation starts, per this epic's "re-check the sub-issues against the decisions" deliverable.

Two of the three authz helpers named in #9187's requirement 3 do not exist: requireRepoMaintainer and requireSessionRepoAccess are not in the tree. What exists is:

• authenticateSessionToken — src/auth/security.ts
• verifyInstallationAdmin — src/orb/oauth.ts

The second is the one that matters for dispatch gating: it binds to the immutable account_id rather than the renameable/re-registerable login, which is the property that makes it safe to gate writes on.

Per the draft decision record on #9187: reads gate on authenticateSessionToken plus repo scope from the session's installation; dispatches additionally require verifyInstallationAdmin; affiliation-tier maintainers get read-only chat with no dispatch.

Flagging here so this issue is not implemented against an API that was never built.

[JSONbored]

Scope set by #9187's recorded decision

The v1 grounding catalog is confirmed at eight tools, each bound to a module that already exists — no new data paths:

queue_snapshot, pr_status, decision_record_by_digest, ledger_verify, fairness_summary, effective_config, audit_tail, repo_settings.

Nothing was trimmed from or added to the candidate set.

One binding decision worth pulling out: fairness_summary must be buildProofSummary, not a new aggregation. That module already enforces this epic's own "accuracy never as a bare scalar" rule — the figure travels with its coverage and a Wilson interval, and is null below the sample floor rather than a masked zero. It is also exactly what /proof/:owner/:repo renders (shipped in #9989), so reusing it is what keeps chat and the public page from disagreeing about a number. A second summariser here would reintroduce precisely the divergence #9193's "one implementation, two renderings" clause exists to prevent.

Authz for reads: authenticateSessionToken plus repo scope from the session's installation. Every tool is repo-scoped; there is no fleet-wide read in v1. Note that requireRepoMaintainer and requireSessionRepoAccess do not exist — see the correction above.

Tenant model (#4927): a maintainer whose repo has no running deployment still gets the hosted-side tools (ledger_verify, fairness_summary, decision_record_by_digest). The queue and config tools report unavailable neutrally — not an error, and not an empty queue, which would read as "nothing to do".

[JSONbored]

Correction — I was wrong about the authz helpers

I claimed earlier in this thread that requireRepoMaintainer and requireSessionRepoAccess do not exist. That is false, and I am retracting it before it misdirects any implementation.

Both exist and are the live guards:

• requireSessionRepoAccess — src/api/routes.ts:6232, 16 call sites
• requireRepoMaintainer — src/api/routes.ts:6250, 26 call sites

My error was a too-narrow search: I grepped src/auth/ for exported require* functions. Both are module-local to src/api/routes.ts and therefore unexported, so nothing matched and I read absence-of-match as absence. Asserting non-existence from one failed grep was the mistake — the same class of error I flagged on #8639 earlier today.

The authorization model is documented in src/api/routes.ts above canSessionAccessPath, and it is more precise than what I wrote. Two independent axes, identity per-login and authority per-repo, with two maintainer tiers:

• Affiliation tier — owns/installed the repo, or authored a PR there with a maintainer association. Gates maintainer-data reads. This is requireSessionRepoAccess.
• Verified write/admin/maintain, resolved live via the installation. Additionally gates repo-visible settings writes and secret BYOK writes. This is requireRepoWriteAccess.
• requireRepoMaintainer is the per-repo maintainer guard used by the protected routes.
• Operators (ADMIN_GITHUB_LOGINS) and server-to-server tokens bypass per-repo scope by design.

What this changes in the recorded decision

The substance of item 3 stands — reads gate on repo-scoped session access, dispatches additionally require verified admin authority, affiliation tier stays read-only. But it should be implemented against the real helpers rather than the ones I named:

Purpose	Use
Grounding-tool reads	requireSessionRepoAccess / requireRepoMaintainer
Action dispatch (#9190)	requireRepoWriteAccess — the tier that already gates writes

verifyInstallationAdmin remains the live installation-admin check underneath, but the route-level guard to call is requireRepoWriteAccess, which is what every other write path here already uses. Inventing a parallel authz path for chat would be exactly the drift the authorization doc-comment exists to prevent.

Also worth noting for whoever implements: canSessionAccessPath is a coarse path allowlist that runs in global middleware before the handler. A new chat path must be added there and scoped by a per-route guard — the comment states plainly that a path added to the allowlist MUST be scoped by a guard in its handler.