CR-15: LLM adapter interface + structured contracts + fake

[rianjs]

Source plan: issue-sequence.md draft 6 in /Users/rianjs/dev.

CR-15 — LLM adapter interface + structured contracts + fake

• Design §: §10.2, §9 (Selection/Findings/Rollup + §9.4 caps).
• Scope: internal/llm — the §10.2 interface (nullable Usage/Quota);
  the §9 JSON schemas + validation (agent IDs resolve, files ⊆ changed,
  safe_to_resolve_rationale, severity caps §9.4, harness-assigned finding
  UUIDs, re-prompt-once); maps validated wire JSON into internal/review
  (CR-1A) domain values; a fake adapter replaying canned structured
  responses.
• DoD: each contract validates+rejects malformed output, re-prompts once
  then fails; caps enforced; maps cleanly into internal/review types; fake
  drives downstream tests; green.
• Depends: CR-01, CR-1A.

---

Keep this issue scoped to the section above. Follow the one-issue/one-branch/one-PR sequence and keep the repo green at merge.

[rianjs]

CR-15: LLM adapter interface + structured contracts + fake

Issue: #24
Branch: feat/cr-15-llm-contracts

Scope

Add internal/llm as the host-neutral LLM boundary for later planner/orchestrator work:

• §10.2 adapter interface with nullable usage fields and optional quota support;
• §9 structured JSON contracts for Selection, Findings, and Rollup;
• validation and mapping into existing internal/review domain values;
• one re-prompt attempt when structured output is malformed or contract-invalid;
• a fake adapter that replays canned responses/errors for downstream tests.

Out of scope: concrete API/subscription adapters, prompt construction beyond the retry suffix, CLI wiring, persistence, provider IO, and full PR-diff anchoring/degrade policy from §11.2.

Implementation Plan

1. Add internal/llm/adapter.go.

   • Define Adapter, Request, Stream, Response, Usage, and Quota matching §10.2.
   • Use pointer fields for nullable Usage metrics.
   • Keep the package independent of repo IO and provider packages; import only stdlib plus internal/review where contract mapping needs domain types.

2. Add wire contract types and validation options.

   • Define schema version constant 1.
   • Decode all contract JSON with json.Decoder.DisallowUnknownFields; unknown fields are contract errors.
   • Add wire structs for:
     • Selection: selected agents, thread actions, reasoning;
     • Findings: agent id plus findings without harness-assigned IDs; reject any model-supplied finding_id field instead of ignoring it;
     • Rollup: review event, rationale, dedupe log, ordered findings.
   • Add validation input structs:
     • known agent IDs;
     • changed files;
     • known thread IDs;
     • assigned finding IDs / rendered finding IDs;
     • severity counts after dedupe and a MajorEventRequestsChanges policy knob needed to validate rollup event consistency.

3. Implement decoders that validate and map to domain values.

   • DecodeSelection validates schema, agent IDs, changed-file subset, thread decisions, required safe_to_resolve_rationale, max resolved threads, and sanitizes model-authored summaries/reasoning that can be posted later.
   • DecodeFindings validates schema/agent, rejects unknown fields and model-supplied finding IDs, validates severity enum, body length 1..8000, severity caps per agent, file membership, anchor shape, and sanitizes finding bodies before assigning harness UUID-like IDs through an injected ID generator.
   • ID generation failures are contract failures: generator errors, blank IDs, or duplicate IDs fail the decode and no partial finding set is returned.
   • DecodeRollup validates schema, rejects unknown fields, validates review event and rationale, dedupe references, ordered finding coverage, and event consistency. It sanitizes review-event rationale and dedupe reasons before mapping to review.Rollup.
   • Rollup dedupe/order invariant:
     • all kept and dropped IDs must reference known harness-assigned finding IDs;
     • a dedupe entry's kept ID must not also appear in that entry's dropped list;
     • each dropped ID may appear in exactly one dedupe entry and must not appear in ordered_findings;
     • ordered_findings must contain every known finding ID minus dropped IDs exactly once;
     • every kept ID remains part of the ordered/rendered set.
   • Rollup event consistency uses post-dedupe rendered severities:
     • any rendered blocking finding requires request_changes;
     • no blocking and at least one rendered major allows comment, or request_changes only when MajorEventRequestsChanges is true; approve is invalid;
     • no rendered blocking or major allows approve or comment and rejects request_changes.
   • Treat exact line-in-diff validation/degradation as out of scope for CR-15; this package only validates the domain-local anchor shape and changed-file membership.

4. Implement re-prompt-once helper.

   • Add a generic RunStructured helper that starts the adapter, waits for StructuredOutput, runs a decoder, and on decoder error retries once with a deterministic validation-error suffix appended to the prompt.
   • Return the successful mapped value plus the final Response.
   • If both attempts fail, return an error that preserves both validation failures.
   • Do not call Resume; resume support remains a future adapter capability.

5. Add fake adapter.

   • FakeAdapter implements Adapter.
   • It replays queued Response or error results from Start.
   • Fake streams expose configured session IDs and wait errors.
   • Capture received requests so tests can assert retry count and retry prompt contents.
   • Implement quota support as configurable (Quota, supported, error).

6. Add focused tests.

   • Adapter/fake: nullable usage fields, quota supported/unsupported, start error, wait error, request capture, retry prompt.
   • Selection: valid mapping; bad schema; unknown agent; file outside changed set; bad thread id; summarize-and-resolve missing rationale; resolved-thread cap; marker sanitization in summaries.
   • Findings: valid mapping with harness-assigned IDs; unknown fields rejected; model-supplied finding ID rejected; ID generator error/blank/duplicate rejected; bad severity; body length bounds; caps; bad anchor; file outside changed set; marker sanitization.
   • Rollup: valid mapping; unknown fields rejected; bad event; unknown dedupe/ordered IDs; dropped ID duplicated; dropped ID ordered; ordering coverage mismatch; kept ID missing from ordered set; event inconsistent with post-dedupe severity counts; marker sanitization in rationale and dedupe reason.
   • Re-prompt: invalid first output then valid second succeeds; two invalid outputs fail; adapter start/wait errors are not schema retries unless the error is a decoder error after a response.

Verification

• rtk go test ./internal/llm ./internal/review
• rtk go test ./...
• rtk go test -race ./internal/llm
• rtk make check