Architecture

Layers

LayerComponentsTrust
Presentationpackages/cli, HTML/Markdown/JSON reportsuntrusted input from argv and files
Domaincore/hardware, core/runtime, core/bench, core/privacy, core/install, core/auditvalidates everything it receives
Infrastructurenode:os, statfs, nvidia-smi (fixed argv), loopback fetchexternal, treated as untrusted data
Optional servicepackages/servertoken, GET only, 127.0.0.1
Agent layerskills/, .claude/agents/, agents/manifest.jsoninstructions only; no execution authority

Context diagram

user / IDE agent --argv--> CLI --> core --> node:os, statfs, nvidia-smi    (measured)
                                     |--> http://127.0.0.1:PORT           (runtime-reported, on request)
                          CLI --> reporting --> JSON + Markdown + HTML
                          optional: server --> one sealed report, bearer token

Key design decisions

  1. Zero dependencies to shrink supply-chain risk.
  2. Concrete loopback IPs (127.0.0.1, [::1]) instead of localhost, to avoid resolver ambiguity.
  3. Shell-free nvidia-smi with fixed arguments, a 4-second timeout and a strict parser; unparseable output means unknown.
  4. Create-only file writes protect user data.
  5. Single block model feeds both Markdown and HTML renderers so they stay identical.
  6. Seals are integrity, not identity; signatures are planned.
  7. The audit executes real code on hostile inputs (real loopback servers that redirect, hang, flood and send junk).

Data flow for probe

argv → runtimeEndpoint (policy check) → fetch with redirect: error, timeout → bounded body read (256 KB) → JSON parse and shape check → sealed report with a stable failure code.

Data flow for audit

Create temp dir → run 37 checks (each in try/catch, recorded as pass/fail/skipped) → build samples from fixture host and mock loopback runtime → compute verdict → seal → write JSON, Markdown, HTML and per-artifact reports → delete temp dir.

Quality attributes

AttributeHow
PortabilityNode 22+, Linux/macOS/Windows in CI
Safetyloopback only, bounded, create-only
Honestyevidence labels, not-tested list
Maintainabilitysmall modules, one renderer model, tests per control
Accessibilitysemantic HTML, lang, table headers, contrast, light/dark, print

Extension points

Runtime adapters (llama.cpp completion, ONNX Runtime, MLX), GPU probes per vendor, signed attestations, dashboard. Each must keep the loopback policy, bounds and evidence labels. All planned.