Design · Open Code Review (OCR)

Low-Level Design (LLD)

↩ architecture.html · generated 2026-08-14

Low-Level Design (LLD)

This document covers the cross-cutting internals — the mechanisms several packages share, and the ones a code reviewer usually has to trace by hand. Per-package internals live in the module docs and architecture.html §7.

Companion: diagrams/04_module_dependencies.svg (generated from a real CodeGraph index — see Graph Intelligence).

1. Data contracts (internal/model/)

The smallest package in the repo (118 LOC) is also the one every other package agrees on — read it first when tracing data between packages.

2. LLM endpoint resolution (internal/llm/resolver.go)

ResolveEndpointWithOptions is the single function every other package's "which model gets called" question ultimately answers by calling. Precedence, checked in this order:

  1. Environment variables — OCR_LLM_PROTOCOL (normalized via NormalizeProtocol, validated via ValidateProtocol) plus the matching URL/token/model env vars. If OCR_LLM_PROTOCOL is unset, the presence of an Anthropic- vs. OpenAI-shaped env var set decides the protocol.
  2. config.json's llm.protocol (normalized the same way) — takes priority over the legacy use_anthropic boolean, which is kept only as a fallback for old config files.
  3. A named provider preset (internal/llm/providers.go's built-in registry: anthropic, openai, or a custom provider entry with its own url+protocol) selected by config.json's provider key.

The resolved value is an llm.ResolvedEndpoint{URL, Token, Model, Protocol, AuthHeader, Source} — Source records which of the three layers actually won, which is what the CLI's ocr llm test command prints back to the operator for debugging.

3. LLM transport & protocol dispatch (internal/llm/)

flowchart TB req[llm.ChatRequest] --> dispatch{Protocol} dispatch -->|anthropic| ac[client.go: Anthropic SDK path] dispatch -->|openai| oc[client.go: OpenAI Chat Completions path] dispatch -->|openai-responses| rc[responses_client.go] ac & oc & rc --> retry[retry_boundary.go
classify + backoff] retry --> resp[llm.ChatResponse]

client.go/responses_client.go implement CompletionsWithCtx for each of the three canonical protocol names (protocol.go). retry_boundary.go is the error-classification layer sitting between the SDK's own retry loop and the caller: it distinguishes a boundary error (surfaced only after the SDK's internal retries are exhausted — HTTP status / typed SDK error, matched with errors.As, never message text) from a stream integrity error (a failure detected by OCR itself mid-SSE-stream, not reported by the transport) from a stream error (any other failure while consuming an already-established stream). The file's own comments are explicit about why this split exists: classification may only read HTTP status and Go error types, never free-text error messages — an unrecognized error is left unclassified rather than guessed at, because a wrong guess is worse than an honest "unknown."

retry_meta.go/retry_report.go/retry_observer.go build a per-run retry report — every logical request's identity (RequestMeta{Provider, Model, FilePath, TaskType, RequestNo}, built once per request by agent.newRequestMeta/passed through llmloop.Runner.requestCtx) plus its attempts, so ocr review --emit-retry-report (or similar diagnostic output) can show exactly which files hit a retryable error and how many times. Only internal/agent's review path populates a NewRequestMeta factory — internal/scan deliberately leaves it nil (see llmloop.Deps.NewRequestMeta's own comment) so scan requests never pollute the review retry report the two packages otherwise share the same Runner for.

4. Context-size management — three-zone compression (internal/llmloop/compression.go)

Every RunPerFile conversation is checked against Template.MaxTokens after each round (addNextMessage, in loop.go):

Zone Threshold Action
Under soft limit < 60% of MaxTokens No action.
Soft zone ≥ 60%, < PromptTokenLimit (80%) A background compression job is triggered (triggerAsyncCompression) — the loop continues immediately; the compressed result is applied to the next round via tryApplyPendingCompression.
Warn / hard zone ≥ PromptTokenLimit (80%) Synchronous compression (runCompression) blocks the loop until it finishes; if the conversation is still over the limit afterward, the loop reports StopCompression and ends that file's review rather than sending an oversized request.

A background compression job is per-conversation, not global — RunPerFile cancels any job still pending for its own conversation on exit (cancelPendingCompression, deferred), and Runner.WaitBackground() joins every still-running job across all files before the caller (agent.Run) freezes the retry report, so a request in flight when a file's review ends can never be observed half-finished by the report.

5. Comment line-number resolution & relocation (internal/diff/resolver.go, relocation.go)

ResolveComment is the deterministic-first path every code_comment tool call goes through before any model call is considered:

  1. resolveFromHunk — match the comment's ExistingCode against the file's actual diff hunks, new-side first (context + added lines → new-file line numbers), then old-side (context + deleted lines → old-file line numbers) as a fallback.
  2. resolveFromFileContent — if hunk matching fails (or in scan mode, where model.Diff.Diff is empty and NewFileContent carries the whole file per §1), scan the full file content line-by-line for the same normalized text.
  3. Only if both fail does llmloop's executeToolCall fall back to a dedicated re-location LLM call (diff.BuildReLocationMessages / diff.ReLocateComment), gated on the template defining a re_location_task.

normalizeLine strips leading/trailing whitespace and any leading +/- diff marker before comparison, so the resolver isn't defeated by a comment that copied a line straight out of the diff text including its marker.

6. Concurrency & token-budget gating (internal/agent/agent.go, internal/scan/agent.go)

Both packages dispatch one goroutine per file behind a buffered-channel semaphore (sem := make(chan struct{}, concurrency), default concurrency = 8). Before acquiring the semaphore for the next file, if MaxTokensBudget > 0, the dispatcher checks used + estimateDiffFileTokens(next) > budget and — if true — stops scheduling new files but does not cancel any file already in flight. This is a deliberate bound: an overrun past the configured budget is capped at the concurrency limit's worth of in-flight work (≤ 8 files by default), never a whole extra batch, and no half-written session record results from a mid-file cancellation.

7. Session manifest — coverage as a strict state machine (internal/session/manifest.go)

The manifest is not a log; it's a state machine with an explicit, fixed vocabulary, designed so a coverage gap can never be silently invisible:

8. Resume matching (internal/session/resume.go, agent.applyResume)

A --resume run's ResumeState indexes a prior run's completed/reused items by reviewItemFingerprint(mode, diff) — SHA-256(mode + "\x00" + OldPath + "\x00" + NewPath + "\x00" + diffTextTrimmed). applyResume looks up each of the current run's diffs by this fingerprint: a hit means the exact same mode + paths + diff content was already reviewed and its prior comments are reused verbatim (session.RecordReviewItemReused); a miss — whether because the file is new, unchanged-but-never-tried, or genuinely changed since the prior run — goes back on the dispatch list. This is why a moved/renamed ref or a rebase that alters diff content correctly forces a re-review instead of silently reusing stale results: the fingerprint is keyed on content, not on file path alone.

9. Deterministic identity hashing (internal/agent/agent.go)

Three SHA-256 digests are computed per run and recorded in the manifest, all through the same hashFields helper (an unambiguous 8-byte big-endian length prefix before each field, so no two distinct field sequences can collide at a boundary):

Digest Inputs Purpose
source_artifact_sha256 every selected item's (ItemID, Fingerprint) pair, sorted by ID Identity of exactly what was reviewed.
rule_config_sha256 the resolver's canonical rule-text layers + applied include/exclude filter Identity of the rule configuration in effect.
runtime_config_sha256 protocol, model, sanitized endpoint host (never the full URL/token), language, timeout, concurrency, token budget Identity of the non-secret runtime settings — deliberately excludes every secret.

10. Path safety (internal/pathutil/, internal/tool/filereader.go)

Every file-tool read validates its target path with pathutil.WithinBase() both before and after symlink resolution — a two-check design specifically because a symlink can point outside the repo even when the link itself lives inside it, and checking only the pre-resolution path would miss that. This is the mechanism behind ASSURANCE_CASE.md's T3 (path traversal) mitigation and is exercised from both the built-in file_read/file_find tools and any dynamically-registered MCP tool that touches the filesystem.

11. Tool dispatch routing (internal/llmloop/loop.go, executeToolCall)

flowchart LR call[llm.ToolCall] --> known{tool.OfName known?} known -->|task_done| td[Complete or Fail] known -->|code_comment| cc[Parse + resolve line numbers
optionally async via CommentWorkerPool] known -->|file_read/find/read_diff/code_search| sync[Synchronous Provider.Execute] known -->|no| dyn{Registered in tool.Registry?} dyn -->|yes| mcp[MCP Provider.Execute] dyn -->|no| err[NotAvailableMsg]

code_comment is the one tool call that can run asynchronously: when Deps.CommentWorkerPool is set, line-number resolution (and the possible re-location LLM call from §5) is submitted to a background worker keyed by file path (pool.SubmitFor(newPath, ...)), and the main loop immediately continues with a (async) placeholder recorded in the session — this is what lets the model keep making tool calls for the same file while its already-submitted comments are still being resolved off the critical path. Runner.deps.CommentWorkerPool.AwaitKey(newPath) is called after the main loop completes (before the review-filter pass) specifically keyed to that one file, never pool-wide, because a pool-wide Await here would race concurrently-dispatched files' own Submit calls.

12. Deterministic vs. LLM-driven tool use — and the "no agent framework" finding

This question — where exactly the model is versus where plain code is — is the single most important thing to get right in any AI-tool-use system, and it's worth stating as a direct verified finding rather than leaving it implicit in the module boxes.

Verified against go.mod and a full-repo grep: OCR depends on no agent-orchestration framework. There is no LangChain, no LangGraph, no "DeepAgents"-style runtime anywhere in the dependency graph (go.mod's only AI-related dependencies are the raw anthropics/anthropic-sdk-go and openai/openai-go/v3 client SDKs — HTTP client libraries, not agent frameworks) and no matching string anywhere in the Go source. This is a deliberate and meaningful architectural choice, not an oversight: the entire tool-use loop — send messages, parse tool calls, dispatch them, decide when to stop, compress context — is hand-written Go in internal/llmloop.Runner (§6 of the HLD), roughly 1,250 lines across three files (loop.go, compression.go, pool.go).

Contrast with the Visa Vulnerability Agentic Harness (VVAH) project — a useful reference point because it's the sibling project this documentation methodology comes from. VVAH's S10 (Remediate) and S11 (Validate) stages do run on a third-party agent runtime, DeepAgents built on LangGraph, specifically because those stages need an agent that plans several steps and loops with tools across a whole session (see VVAH's docs/design/HLD.md §6). OCR's tool-use loop is architecturally simpler by design — one file, one model, one bounded round-based loop per review — and that simplicity is exactly what a hand-rolled ~1,250-line loop can own outright without needing a graph-execution engine underneath it. Neither choice is "more correct"; they solve different shapes of problem: VVAH's remediation agent needs open-ended multi-step planning with drift-prone preview/re-run states, while OCR's per-file review loop is a much more constrained, bounded conversation the project's own code fully owns end to end.

What is deterministic (no model call, ever) — by package:

Deterministic mechanism Package What it decides
File eligibility internal/config/rules, internal/config/allowlist Which files are reviewed at all
Rule-text resolution internal/config/rules Which rule text a file sees (custom > project > global > system)
Diff retrieval & parsing internal/diff What "changed" means for a given mode
Comment line-number resolution internal/diff/resolver.go Where a finding actually is — tried before any model call, not after
Concurrency & token-budget gating internal/agent, internal/scan How many files run at once, when to stop scheduling
Coverage/manifest state machine internal/session What "done" means for the whole run
Resume fingerprint matching internal/session/resume.go What can be safely reused across runs
Tool-name collision resolution internal/mcp Whether an external MCP tool is allowed to register
Path validation internal/pathutil Whether a file-tool call is allowed to touch a given path
Endpoint/protocol resolution internal/llm/resolver.go Which provider/model a run talks to (the choice, not the conversation)

What is genuinely AI-driven (a real model call, with real non-determinism):

AI-driven step Trigger Package
Plan phase Optional, per file above a line-count threshold internal/agent / internal/scan (dispatch) → internal/llmloop (executes)
Main tool-use loop's own reasoning Every dispatched file internal/llmloop.Runner.RunPerFile
Comment re-location Only when deterministic resolution (§5) fails internal/diff.ReLocateComment via internal/llmloop
Review filter Optional, per file, after the main loop internal/llmloop (same loop, filter template)
Dedup task (scan only) Optional, per batch internal/scan
Project summary (scan only) Optional, post-run internal/scan

The pattern that falls out of this table is the same one the README states as OCR's core philosophy: every "must not go wrong" decision is deterministic; every "requires judgment" decision is a model call — and there is no framework layer in between doing either job. The tool-use loop that carries those model calls is plain, auditable Go code that the project itself owns and tests (90% coverage enforced in CI), not a third-party agent-framework black box.

For how each package uses these mechanisms, see the module docs and architecture.html §7.