# Low-Level Design (LLD)

This document covers the **cross-cutting internals** — the mechanisms that many stages
share. Per-module and per-file internals live in the [module docs](../modules/).

> Companion: [`diagrams/04_module_dependencies.svg`](../../diagrams/04_module_dependencies.svg)
> (generated from CodeGraph), [`05_backend_routing.svg`](../../diagrams/05_backend_routing.svg).

## 1. Data contracts (`vvaharness/models.py`, ~1,850 LOC)

A single Pydantic module defines the objects passed between stages. This is the "type
system" of the pipeline — read it first when tracing data.

Core contracts: `CVE`, `Control`, `AppProfile`, `Asset`, `TrustBoundary`, `Threat`,
`ThreatModel`, `EntryPoint`, `Sink`, `ModuleInfo`, `ContextPackage`, `Chunk`,
`TaskManifest`, `Finding`, `Severity`, `Chain`, `RankedFinding`, `DroppedFinding`,
`ScanMetrics`, `FinalReport`.

Taint sub-model (populated by the call-graph engine): `TaintSymbolRef`,
`TaintTransferEdge`, `TaintEvidencePath`, `CFGNode`, `CFG`, `ConditionTaintEdge`,
`ReflectionFact`, `ReflectionTaintEdge`, `FrameworkMarkerFact`, `RouteTaintFact`,
`ResponseDataflowFact`, `FrameworkTaintEdge`. (The `CFG`/`ConditionTaintEdge` types are
reserved schema for future branch-sensitive analysis; the current scanner does not
populate a branch CFG.)

Helpers coerce loose model output into typed contracts (`_coerce_enum`, `_coerce_int`,
`_coerce_confidence`) and render Markdown safely (`_md_cell`, `_demote_md_headings`).

## 2. Config resolution (`vvaharness/config/__init__.py`)

`Config.load` resolves the active file (`--config` → `./config.yaml` → packaged default),
deep-merges an optional `config.local.yaml`, and expands `${ENV:-default}` placeholders
(`_expand_env`, `_expand`). Merge semantics support replace/append (`_replace_merge`,
`_append_merge`). Per-scan `step1` exclusion overlays are applied by
`apply_step1_overlay`. `is_network_path` guards remote-config trust rules. The overlay is
announced on every command and its SHA-256 is recorded in the manifest.

## 3. Backend dispatch (`vvaharness/backends/`)

```mermaid
flowchart TB
  step[Any pipeline stage] -->|"prompt() / agentic()"| llm["llm.py<br/>dispatcher (resolve on via:)"]
  llm --> cli["claude_cli.py"]
  llm --> sdk["sdk.py (Anthropic SDK)"]
  llm --> oai["oai.py (OpenAI-compat)"]
  sdk -->|S10 fix| asdk["agent_sdk.py (Edit/Write)"]
  cli & sdk & oai --> lt["localtools.py<br/>sandboxed Read/Glob/Grep"]
  reg["harness/registry.py"] --> claudeH["harness/claude (Agent SDK)"]
  reg --> daH["harness/deepagents (LangGraph)"]
```

- **`llm.py`** is the single dispatcher: every stage imports `prompt()`/`agentic()` from
  here; `resolve()` reads the role's `{id, via}`.
- **`localtools.py`** implements read-only Read/Glob/Grep jailed to the target repo (no
  Bash) for `sdk`/`openai`.
- **`agent_sdk.py`** is the Claude Agent SDK backend for the *mutating* remediation role,
  with path confinement (`_within_root`) and redaction hooks.
- **`harness/`** is the post-scan abstraction: a neutral `Harness` contract
  (`harness/base.py`, `harness/contract/`) with two implementations — `claude/`
  (Agent SDK) and `deepagents/` (LangGraph). `registry.get_harness` maps `via:` → factory.
  The contract defines permission policy (`contract/permissions/`), tool policy, effort,
  and message types so the two runtimes are interchangeable.

## 4. State store & checkpoints (`orchestrator/store.py`, `orchestrator/checkpoints.py`)

- **`store.py`** — SQLite state store. `connect`/`_migrate` manage the schema;
  `register_run` records a run; `save_callgraph`/`load_callgraph` persist the S1 call
  graph (as `_graph_rows` of q-nodes) so later stages read it back without re-computing;
  `reset_run`/`delete_run` support re-runs and `gc`.
- **`checkpoints.py`** — per-stage save/load with schema validation (`_validate_schema`,
  `_schema_for`), a run-id derivation (`run_id_for`), and pruning (`prune_checkpoints`).
  S0–S4 checkpoint individually; S5–S7 share the S7 checkpoint; S8/S9 are separate.

## 5. Redaction (`report/redact.py`)

Applied at the MD/SARIF write boundary. Card numbers are Luhn+IIN gated (`_luhn`,
`_cc_network`); SSNs area/group/serial gated (`_ssn_valid`); values after strong
credential keywords are always masked, while prose-ambiguous keywords are left alone
(`_bearer_credential`). `redact_counts`/`redact_tree` support auditing what was masked.

## 6. Scoring engine (`validation/scoring/`, `validation/io/_host_score.py`)

Validation verdicts are **deterministic given the synthesised gates**. Personas emit
per-gate reports; `synthesis/_consensus.py` applies a conservative majority
(`_most_conservative_status`) to produce host-owned gates; `scoring/_engine.py` scores
them against `scoring/_configs.py` weights/thresholds; `io/_host_score.py` re-scores from
the persisted `synthesized_gates.json`. Absent/unparseable gates ⇒ `UNVERIFIABLE` ⇒
`needs_review` (fail-closed). Backend split: under `deepagents` the **host** synthesises;
under `cli`/`sdk` the **in-session orchestrator** synthesises and the host persists it.

## 7. Permission & sandbox model

| Route | Tools | Enforcement |
|---|---|---|
| detection `sdk`/`openai` | Read/Glob/Grep | `localtools.py` jail (no Bash) |
| detection `cli` | native + allowlist | Bash only if explicitly listed (no shipped profile does) |
| S10 `deepagents` fix | Read/Glob/Grep/Edit/Write | repo-confined virtual FS, traversal-safe |
| S10 `sdk` fix | Edit/Write via Agent SDK | Agent SDK permission gate denies Bash |
| S11 all | read-only | `contract/permissions` deny-by-default write gate |

## 8. Observability & accounting

- **`util/tokens.py`** — process-wide token counter bucketed by phase (`_bucket`).
- **`util/metrics.py`** — builds `ScanMetrics` (kept out of the orchestrator hot path).
- **`util/status.py`** — per-stage spinner / structured event emission.
- **`util/scan_progress.py`** — optional per-file `[progress]` stream (S0–S9).
- **`util/errlog.py`** — structured non-fatal error log, counts by stage.
- **`manifest.py`** — run manifest with scrubbed argv, git SHA, config SHA-256, roles.

## 9. DeepAgents runtime mechanics

Expands on §3's `harness/deepagents/` bullet. This is the LangGraph-based implementation of
the `Harness` contract, used only by S10 (Remediate) and S11 (Validate) roles whose
`via: deepagents`.

**Model routing** — `harness/deepagents/options.py::build_model(model_id, env, provider)`:
`provider == "anthropic"`, or `provider` unset and `"claude"` appears in `model_id`
→ `ChatAnthropic` (`langchain-anthropic`); otherwise → `ChatOpenAI` (`langchain-openai`).
This is the literal mechanism behind the `provider:` key in `models.remediate` /
`models.validate.orchestrator` — it is read here, not merely documentation. Validation's
one-vendor-per-panel rule follows directly: every persona inherits the orchestrator's
`via`/`provider`, so a persona `id` from a different vendor fails this same routing check
and validation refuses to start (exit 2).

**Session execution** — `harness/deepagents/client.py::DeepAgentHarness` implements
`run_oneshot`/`run_streaming` against a compiled LangGraph state graph (built by
`options.py::build_oneshot_options`/`build_streaming_agent`). `run_streaming` uses
`graph.astream(..., stream_mode="updates", subgraphs=True)` so each persona's internal tool
steps surface with a namespace tag, which `translate.py` converts into typed
`HarnessMessage`s for the caller.

**Loop budget** — `harness/deepagents/limits.py::RECURSION_HEADROOM = 900`: extra LangGraph
supersteps permitted beyond the role's configured `max_turns`, so a long-but-legitimate tool
loop is captured (a partial-state snapshot is taken and a terminal result yielded) rather
than truncated mid-task on `GraphRecursionError`. `limits.py` is deliberately free of
`deepagents` imports so the budget constant is usable even on Python 3.10.

**S10 vs. S11 — the permission asymmetry, mechanically:**

| | S10 Remediate (`remediation_agent/plugin_runner`) | S11 Validate (`validation/tools/deep_tools.py`) |
|---|---|---|
| `cwd` passed to the harness | the real target repo | a staged, pre-patched **copy** (removed on completion) |
| tools built | generic Read/Glob/Grep/Edit/Write reader/writer set, minus `Bash` (`tools = tuple(t for t in _tools(cfg) if t != "Bash")`, `disallowed_tools=("Bash",)`) | generic Read/Glob/Grep readers (`deepagents/tools.py::build_tools`) **plus** five deterministic read-only fact tools operating on `diff.patch`: `DiffTouched`, `ChangedLines`, `DiffImpactMap`, `PatternScan`, `TestInventory` |
| Can it write to disk? | Yes — the only place in the pipeline that mutates the target repo | No — no Write/Edit/Bash tool exists in its toolset; this is a structural guarantee, not a runtime check |

**Why the lazy import** — `harness/registry.py::_make_deepagents()` imports
`DeepAgentHarness` inside the function body. `deepagents` (the PyPI package) requires
Python ≥ 3.11; importing it eagerly at module load would break every `via: cli`/`via: sdk`
caller on Python 3.10, even though they never touch this backend. The import only executes
when a role's `via` actually resolves to `"deepagents"`.

For how each stage uses these, jump to the [module docs](../modules/).
