serve the configured graphs and their inventory, read-only (ADR-0029)

[kikashy]

Closes #126.

What

ADR-0029: experimental_list_graphs + experimental_get_graph { graph_id } — the graph siblings of list_packs/get_pack — plus the CLI twin experimental graph list, all served from one inventory function so the surfaces cannot disagree.

Design points, each argued in the ADR:

• Separate payload types (GraphInventory/GraphDocument) — folding into PackInventory would put a removable experimental member inside a stable command's payload, the coupling ADR-0015/0017/0026 each refused.
• Experimental-prefixed names — the marker is a stability statement the tool name must carry on MCP (ADR-0007/0021; get_pack_diagram's withdrawal is the cautionary precedent).
• Serve-don't-validate — lenient identity reads (bare carrier decode, never the closed-schema Load); undecodable documents are listed with the reason and served with status undecodable.
• sha256 bare hex per the payload convention; formatVersion on these payloads is the document's own declaration (the walk-payload meaning is untouched and the distinction stated).
• No engine constructed — the three-site census and CONFORMANCE.md's eight-surfaces sentence do not move; the reference-only scan admits the new descriptions.

Tests

MCP: inventory + document against the graph fixture (exact-bytes equality, digest, identity echoes), the undecodable fixture (listed with reason, served undecodable), missing-configuration asymmetry, and argument discipline (null, case-folded alias via exactMembers, absent). CLI: the inventory in both formats. tools/list census updated to 13.

Review

Cross-vendor round to follow per the regime; disposition table will be posted with the reviewed SHA.

Material-decision impact: public-surface; review: #130 (comment) (r1), #130 (comment) (r2), plus the round-3 table on this PR

🤖 Generated with Claude Code

[kikashy]

Cross-vendor review round 1 — disposition table

Reviewer: Codex (codex-cli 0.145.0). Reviewed SHA: cd8c495. 12 findings: 10 confirmed (5 medium, 5 low), 2 refuted (core implementation and roster mechanics verified clean, incl. the three-engine census and the rooted reader). All applied in ce5ca72 under the regime's dispositioned-finding exception.

#	Finding	Severity	Disposition
1	"Exact bytes" false for invalid UTF-8: the JSON text frame transcodes to U+FFFD, disagreeing with bytes/sha256 — same live defect inherited by get_pack	medium	Fixed — both fetch tools serve through one servedDocument helper that refuses non-UTF-8 bytes with the path to read directly; ADR/changelog narrowed; mutation-verified
2	Malformed-but-decodable nodes/edges silently reported as honest zeros	medium	Fixed — nullable nodeCount/edgeCount, absent (never zero) for non-collection members; future fixture pins it on the raw wire
3	nodes/rows member names collide with the walk payloads' array-typed members	low	Fixed — nodeCount, edgeCount, rowsDeclared
4	PACK_ID is a live case-fold bypass on get_pack (only the new tool had the hold)	medium	Fixed — exactMembers on get_pack, exact-message test, mutation-verified; recorded in the changelog as a companion defect fix
5	Graph decode details lacked the pack-style path framing	low	Fixed — wrapped via project.ReadFailureMessage
6	ADR overstated CLI/MCP parity for missing configuration	low	Fixed — narrowed to the resolved inventories; the CLI's packs-list-style error stated in ADR, changelog, and command comment
7	README "Implemented commands" roster omitted the new verb	low	Fixed
8	experimental graph list --help escaped the conformance-claim scans	medium	Fixed — added to claimSurfaces and the required-names list
9	doc.go "every payload" overclaim, made conspicuous by the new claim-free payloads	low	Fixed — "every evaluation payload"
10	Test adequacy: struct round-trips, hardcodable formatVersion, unpinned notes/Experimental/oversized/escape	medium	Fixed (with one declared exception) — raw-wire-key assertions, "formatVersion":"future" served as declared, byte-identical missing-config notes across the pair, experimental asserted on both payloads, oversized and symlink-escape and binary fixtures each refused with reasons. Declined: the counting/mutating reader seam for the single-read property — finding 11 verified single-read structurally, and a reader-injection seam is test infrastructure whose weight outbuys the residual risk; recorded here rather than silently skipped
11–12	Suspected single/double-read, limit, escape, engine-census, roster, ADR-mechanics defects	—	Refuted by reviewer — verified clean against source

One pre-existing get_pack test asserting the old unknown-key message was updated to the sharper exactMembers diagnostic. Gate green at ce5ca72 (fmt, vet, full suite, bundled conformance).

🤖 Generated with Claude Code

[kikashy]

Cross-vendor review round 2 — disposition table

Reviewer: Codex (codex-cli 0.145.0). Reviewed SHA: ce5ca72. 16 findings; findings 2–16 were captured: 7 confirmed (all low), 8 refuted (every round-1 fix verified correct in source: the UTF-8 gate on both fetches, end-to-end nullable counts, the renames, the PACK_ID hold, path framing, parity narrowing, README roster, claim-scan closure).

Process defect, declared: finding 1 and the reviewer's SHA statement were lost to output truncation on the orchestrating side (a tail cap). Rather than disposition an invisible finding, round 3 runs as a full fresh review of the current SHA — anything finding 1 named that remains unfixed will re-surface there.

Confirmed findings, applied in 6053efe:

#	Finding	Disposition
2	JSON invocation errors misname the new CLI verb (roster switch omitted list)	Fixed
3	UTF-8 refusal named an unquoted path with no configuration context	Fixed — quoted, and "relative to the configuration at …"
4	exactMembers grammatical number wrong for a single member	Fixed — "the accepted member is "pack_id""
5	Serving claims overbroad after the UTF-8 fix (tool description, ADR clause 2, changelog)	Fixed — the exact served/refused boundary stated at all three
6	Count-condition prose described the wrong condition (nodes:[] IS a collection)	Fixed — "present exactly when identity decoding succeeded and nodes is a JSON object / edges a JSON array", everywhere incl. the tool description
7	"Every evaluation payload" still false (refusal envelopes, corpus)	Fixed — doc.go enumerates the three actual contracts
8	Tests under-discriminating (struct round-trips for positive counts, no human "unknown", UTF-8 only via graph, whole suite skipped on Windows)	Fixed — raw positive counts + legacy keys forbidden, detail-framing prefix pinned, UTF-8 refusal pinned on both fetch tools with quoted paths, human unknown/number labels asserted, symlink case POSIX-only while the rest runs everywhere. The declined reader-seam stands as dispositioned in round 1

Gate green at 6053efe. Round 3 (full) to follow.

🤖 Generated with Claude Code

[kikashy]

Cross-vendor review round 3 (full fresh review) — disposition table

Reviewer: Codex (codex-cli 0.145.0). Reviewed SHA: 6053efe, stated in the review's first line and captured in full this time (findings-first, no output cap — the round-2 truncation cannot recur). 6 findings: 1 medium, 5 low, all confirmed; the review's own summary verifies everything else on inspection (nullable counts, rowsDeclared, exact-byte digest/size, document-declared formatVersion, rooted reads, byte limit, missing-config asymmetry, get_pack hold, evaluator census, rosters, no-write/no-engine claims), and it ran go test ./..., go vet, and git diff --check itself. All fixes in 0bb201f under the dispositioned-finding exception.

#	Finding	Severity	Disposition
1	Inventory resource amplification: unbounded graph entries × 1 MiB documents × per-row echoes ⇒ multi-GiB from small files	medium	Fixed — reads cached by unique path (charged once), row echoes charged per row, 8 MiB budget refusing with JPS-GRAPH-INVENTORY-BUDGET (the walk's report-budget sibling: a truncated inventory would under-report silently); injectable-budget test, charging mutation-verified
2	experimental_list_graphs ignored its closed empty schema	low	Fixed — member/null/non-object each refused before any project read; exactMembers grows the zero-member grammar; hostile raw-frame tests, hold mutation-verified
3	Fetch descriptions and both client guides contradicted the UTF-8/text behavior ("JSON text", "exactly the bytes on disk")	low	Fixed — all five sites state: text; exact when valid UTF-8; refused with the configured path when not
4	Human label called every detailed row "document unreadable", undecodable included	low	Fixed — "identity unavailable", with the detail line saying which
5	Renderer comment attached to the wrong function	low	Fixed — each renderer carries its own
6	Tests under-discriminating (honest zeros, null's exact refusal, path/description echoes, full undecodable emptiness, requestedCommand roster)	low	Fixed — all five pinned, on wire and human output

Gate green at 0bb201f. Three rounds complete, every finding across them dispositioned; flipping the ADR to accepted for merge.

🤖 Generated with Claude Code

[github-actions]

🎉 Thank you for your contribution to Judgment Pack!

If you’d like another task, choose a path that interests you:

• Go runtime
• Gateway and provenance
• Python and evaluator experiments
• Demos and applications
• Specification and documentation