# 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](../modules/README.md) and `architecture.html` §7.

> Companion: [`diagrams/04_module_dependencies.svg`](../../diagrams/04_module_dependencies.svg)
> (generated from a real CodeGraph index — see [Graph Intelligence](../tools/graph-intelligence.md)).

## 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 unified `Diff`
  text, `Insertions`/`Deletions`, `IsDeleted`, and (scan mode only) `NewFileContent`.
- **`model.ScanItem`** (`scan.go`) — one whole file for `ocr scan`: `Path`, `Content`,
  `IsBinary`, `LineCount`. `ScanItem.AsDiff()` adapts it into a synthetic `model.Diff` (empty
  `Diff` field, full content in `NewFileContent`) purely so the line-number resolver and the
  `file_read_diff` tool 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 a `code_comment` tool
  call's JSON arguments deserialize into, before `tool.ParseComments` turns it into an
  `LlmComment`.

## 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/`)

```mermaid
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<br/>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:

- **`ItemID`** is content-*independent* — derived from operation + input mode + normalized
  old/new path — so the same logical file keeps a stable identity across a `--resume`
  chain even though its diff content (and therefore its `Fingerprint`, which *is*
  content-dependent) changes between runs.
- **Registration precedes dispatch.** `RegisterSelected`/`SealSelected` freeze 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`, or `MarkFailed(class, reason)` — before `Finalize`. `Finalize`'s validation
  sweeps any item that never got a Mark* call into `FailureUnknown` rather than silently
  omitting it, so a scheduler bug shows up as an honest "unknown failure," not a missing row.
- **`FailureClass`** (per-item) and **`RunFailureClass`** (whole-run) are deliberately
  separate enums — a run never fails with `provider` or `panic` (those are always one
  item's problem); `RunFailureClass` adds `internal` for scheduler/invariant violations that
  have no per-item equivalent.
- **`TerminalState`** is computed *only* from the coverage sets plus `RunFailure` — never
  from comment count or warning count. A run that reviewed some files and hit the token
  budget on the rest is `partial` with 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`)

```mermaid
flowchart LR
  call[llm.ToolCall] --> known{tool.OfName known?}
  known -->|task_done| td[Complete or Fail]
  known -->|code_comment| cc[Parse + resolve line numbers<br/>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](../modules/README.md) and
`architecture.html` §7.
