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.
model.Diff(diff.go) — one changed file:OldPath/NewPath, the unifiedDifftext,Insertions/Deletions,IsDeleted, and (scan mode only)NewFileContent.model.ScanItem(scan.go) — one whole file forocr scan:Path,Content,IsBinary,LineCount.ScanItem.AsDiff()adapts it into a syntheticmodel.Diff(emptyDifffield, full content inNewFileContent) purely so the line-number resolver and thefile_read_difftool can treat scan and review uniformly downstream — see §5.model.LlmComment(review.go) — the finding contract:Path,Content,SuggestionCode/ExistingCode,StartLine/EndLine,Thinking,Category(bug / security / performance / maintainability / test / style / documentation / other),Severity(critical / high / medium / low).model.CodeReviewResult(review.go) — the raw pre-parse shape acode_commenttool call's JSON arguments deserialize into, beforetool.ParseCommentsturns it into anLlmComment.
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:
- Environment variables —
OCR_LLM_PROTOCOL(normalized viaNormalizeProtocol, validated viaValidateProtocol) plus the matching URL/token/model env vars. IfOCR_LLM_PROTOCOLis unset, the presence of an Anthropic- vs. OpenAI-shaped env var set decides the protocol. config.json'sllm.protocol(normalized the same way) — takes priority over the legacyuse_anthropicboolean, which is kept only as a fallback for old config files.- A named provider preset (
internal/llm/providers.go's built-in registry:anthropic,openai, or a custom provider entry with its ownurl+protocol) selected byconfig.json'sproviderkey.
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/)
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:
resolveFromHunk— match the comment'sExistingCodeagainst 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.resolveFromFileContent— if hunk matching fails (or in scan mode, wheremodel.Diff.Diffis empty andNewFileContentcarries the whole file per §1), scan the full file content line-by-line for the same normalized text.- Only if both fail does
llmloop'sexecuteToolCallfall back to a dedicated re-location LLM call (diff.BuildReLocationMessages/diff.ReLocateComment), gated on the template defining are_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:
ItemIDis content-independent — derived from operation + input mode + normalized old/new path — so the same logical file keeps a stable identity across a--resumechain even though its diff content (and therefore itsFingerprint, which is content-dependent) changes between runs.- Registration precedes dispatch.
RegisterSelected/SealSelectedfreeze the full set of dispatchable items before any goroutine starts — the coverage denominator is fixed up front, not accumulated as files finish. - Every item must reach exactly one terminal Mark* call —
MarkCompleted,MarkReused, orMarkFailed(class, reason)— beforeFinalize.Finalize's validation sweeps any item that never got a Mark* call intoFailureUnknownrather than silently omitting it, so a scheduler bug shows up as an honest "unknown failure," not a missing row. FailureClass(per-item) andRunFailureClass(whole-run) are deliberately separate enums — a run never fails withproviderorpanic(those are always one item's problem);RunFailureClassaddsinternalfor scheduler/invariant violations that have no per-item equivalent.TerminalStateis computed only from the coverage sets plusRunFailure— never from comment count or warning count. A run that reviewed some files and hit the token budget on the rest ispartialwith a non-zero exit code's worth of context, not silently reported as if nothing happened.
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)
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.