Skip to content

vox-audit API Reference (generated)

Crate: vox-audit · Version: 0.6.0 · Target: Library (lib.rs)

Umbrella CR-L gate runner. Hosts the vox audit <thing> subcommand registry and implements the canonical JSON report shape defined in contracts/ci/vox-audit-contract.v1.yaml.

Umbrella crate hosting the [Subcommand] trait and the canonical vox audit <thing> registry. One subcommand per CR-L gate (CR-L0..CR-L8 / CR-L-retirement) from docs/src/architecture/v1-release-criteria.md §5, behaviorally conforming to contracts/ci/vox-audit-contract.v1.yaml.

Council-ratified 2026-05-15 (D21 in docs/src/architecture/v1-llm-target-implementation-plan-2026.md §8.1): new top-level crate, NOT a submodule of vox-cli — vox-cli is at TOESTUB sprawl limit and this concern deserves its own home.

  • Library API (this file + report.rs + subcommands/): callable from tests, vox-cli, and the vox-gui audit panel.
  • CLI binary (src/main.rs): the user-facing vox-audit executable.
  • Single planning anchor (contracts/ci/vox-audit-contract.v1.yaml) declares: CLI flag set, exit-code convention, telemetry namespace, per-subcommand gate / corpus / block_ga / cost_metered fields.
FeatureDefault / Enables
ci-gates—
default—
DependencyKind
vox-code-auditNormal
vox-compilerNormal
vox-configNormal
vox-containerNormal
vox-deploy-codegenNormal
vox-http-clientNormal
vox-packageNormal
vox-project-scaffoldNormal
vox-telemetryNormal
ModuleDescription
aggregator—
core_gates—
ga—
recorder—
report—
subcommands—
StructDescription
CommonArgsCommon arguments shared by every subcommand.
RunOutcomeOne run outcome: the report and the exit code the binary should return.
EnumDescription
TierRelease-criteria tier. Declaration order IS the GA evaluation order: foundation gates are evaluated and reported before any downstream gate (see CR-F0 in docs/src/architecture/v1-release-criteria.md and the --gate all --strict-block-ga roll-up).
CrlGateCR-L gate identifier — one variant per row in contracts/ci/vox-audit-contract.v1.yaml §subcommands.
TraitDescription
SubcommandTrait every vox audit <thing> subcommand implements. The umbrella runner (vox audit all) iterates over registered subcommands in CrlGate::all() order and aggregates their outcomes into a combined report at contracts/reports/audit-all/<date>.json.
FunctionDescription
as_strStable lowercase tier name used in the GA snapshot rows.
thing_nameStable name as used by vox audit <thing> and the report thing field.
block_gaPer-contract: does failure of this gate block GA? Tooling gates (non-CR-L) always return false — they exist to keep the corpus healthy during development, not to gate release.
cost_meteredPer-contract: does this gate meter LLM cost during measurement?
tierWhich release-criteria tier this gate belongs to. The CR-L gates are §3.5 Product; the stdlib-coverage gate is Tooling. Foundation / Distribution / GUI variants enter as their gates land (Phase 0+).
allIterator over every registered gate, in display order.
workspace_rootWorkspace-root locator: walks up from CARGO_MANIFEST_DIR looking for the top-level Cargo.toml that contains [workspace]. Used by subcommands to resolve contract paths.
registryBuild the canonical registry of subcommands (2 CR-F foundation gates + 9 CR-L gates + 1 tooling gate). Order matches CrlGate::all() and contracts/ci/vox-audit-contract.v1.yaml §subcommands. Tooling gates appear after the CR-L block.
gate_from_nameResolve a [CrlGate] from a stable thing-name string.
run_gateRun a single subcommand by gate, returning its outcome. Emits a vox.audit.run telemetry event for every invocation per contracts/ci/vox-audit-contract.v1.yaml §telemetry (A11, ratified 2026-05-15). record_event! is a no-op when no recorder is registered, so the emission adds zero cost to non-instrumented runs.
run_allRun every registered subcommand and aggregate their outcomes into a combined report at contracts/reports/audit-all/<date>.json. Worst-case exit code semantics per contract §umbrella: - 0 if all sub-runs return 0 - 1 if any sub returns 1 and none return 2 or 3 - 2 if any sub returns 2 and none return 3 - 3 if any sub returns 3 Emits one vox.audit.run telemetry event per sub-gate (with umbrella_run = true) per A11 contract compliance.
run_ga_snapshotRun every registered gate (foundation first per CR-F0) plus the standalone product binaries, fold them into a [ga::GaSnapshot] with blocked_by_foundation semantics, and (when args.write_canonical_report) write contracts/reports/_snapshot/<UTC>.json. This is the spine behind vox audit --gate all --strict-block-ga.
aggregate_exit_codeAggregate-exit-code per contract §umbrella.
Dependency Topology, diagram 112 nodes, 11 edges: vox-audit → vox-code-audit; vox-audit → vox-compiler; vox-audit → vox-config; vox-audit → vox-container; vox-audit → vox-deploy-codegen; vox-audit → vox-http-client; vox-audit → vox-package; vox-audit → vox-project-scaffold; vox-audit → vox-telemetry; vox-cli → vox-audit; vox-cl…vox-auditvox-code-auditvox-compilervox-configvox-containervox-deploy-codegenvox-http-clientvox-packagevox-project-scaffoldvox-telemetryvox-clivox-cli-research
Diagram source
graph {
direction: right
node vox_audit: "vox-audit"
node vox_code_audit: "vox-code-audit"
vox_audit -> vox_code_audit
node vox_compiler: "vox-compiler"
vox_audit -> vox_compiler
node vox_config: "vox-config"
vox_audit -> vox_config
node vox_container: "vox-container"
vox_audit -> vox_container
node vox_deploy_codegen: "vox-deploy-codegen"
vox_audit -> vox_deploy_codegen
node vox_http_client: "vox-http-client"
vox_audit -> vox_http_client
node vox_package: "vox-package"
vox_audit -> vox_package
node vox_project_scaffold: "vox-project-scaffold"
vox_audit -> vox_project_scaffold
node vox_telemetry: "vox-telemetry"
vox_audit -> vox_telemetry
node vox_cli: "vox-cli"
vox_cli -> vox_audit
node vox_cli_research: "vox-cli-research"
vox_cli_research -> vox_audit
}
Consumer CrateRole
vox-cliDirect workspace dependent
vox-cli-researchDirect workspace dependent
KindSymbolSignatureSourceDescription
enumTierpub enum Tiercrates/vox-audit/src/lib.rs#L38-L44Release-criteria tier. Declaration order IS the GA evaluation order: foundation gates are evaluated and reported before any downstream gate (see CR-F0 in docs/src/architecture/v1-release-criteria.md and the --gate all --strict-block-ga roll-up).
fnas_strpub fn as_str(self) -> &'static strcrates/vox-audit/src/lib.rs#L48-L56Stable lowercase tier name used in the GA snapshot rows.
enumCrlGatepub enum CrlGatecrates/vox-audit/src/lib.rs#L62-L85CR-L gate identifier — one variant per row in contracts/ci/vox-audit-contract.v1.yaml §subcommands.
fnthing_namepub fn thing_name(self) -> &'static strcrates/vox-audit/src/lib.rs#L89-L104Stable name as used by vox audit <thing> and the report thing field.
fnblock_gapub fn block_ga(self) -> boolcrates/vox-audit/src/lib.rs#L110-L121Per-contract: does failure of this gate block GA? Tooling gates (non-CR-L) always return false — they exist to keep the corpus healthy during development, not to gate release.
fncost_meteredpub fn cost_metered(self) -> boolcrates/vox-audit/src/lib.rs#L124-L133Per-contract: does this gate meter LLM cost during measurement?
fntierpub fn tier(self) -> Tiercrates/vox-audit/src/lib.rs#L138-L152Which release-criteria tier this gate belongs to. The CR-L gates are §3.5 Product; the stdlib-coverage gate is Tooling. Foundation / Distribution / GUI variants enter as their gates land (Phase 0+).
fnallpub fn all() -> impl Iterator<Item = CrlGate>crates/vox-audit/src/lib.rs#L155-L171Iterator over every registered gate, in display order.
fnworkspace_rootpub fn workspace_root() -> std::path::PathBufcrates/vox-audit/src/lib.rs#L177-L196Workspace-root locator: walks up from CARGO_MANIFEST_DIR looking for the top-level Cargo.toml that contains [workspace]. Used by subcommands to resolve contract paths.
structCommonArgspub struct CommonArgscrates/vox-audit/src/lib.rs#L200-L214Common arguments shared by every subcommand.
structRunOutcomepub struct RunOutcomecrates/vox-audit/src/lib.rs#L232-L235One run outcome: the report and the exit code the binary should return.
traitSubcommandpub trait Subcommand: Send + Synccrates/vox-audit/src/lib.rs#L242-L253Trait every vox audit <thing> subcommand implements. The umbrella runner (vox audit all) iterates over registered subcommands in CrlGate::all() order and aggregates their outcomes into a combined report at contracts/reports/audit-all/<date>.json.
fnregistrypub fn registry() -> Vec<Box<dyn Subcommand>>crates/vox-audit/src/lib.rs#L259-L279Build the canonical registry of subcommands (2 CR-F foundation gates + 9 CR-L gates + 1 tooling gate). Order matches CrlGate::all() and contracts/ci/vox-audit-contract.v1.yaml §subcommands. Tooling gates appear after the CR-L block.
fngate_from_namepub fn gate_from_name(name: &str) -> Option<CrlGate>crates/vox-audit/src/lib.rs#L282-L284Resolve a [CrlGate] from a stable thing-name string.
fnrun_gatepub fn run_gate(gate: CrlGate, args: &CommonArgs) -> RunOutcomecrates/vox-audit/src/lib.rs#L292-L302Run a single subcommand by gate, returning its outcome. Emits a vox.audit.run telemetry event for every invocation per contracts/ci/vox-audit-contract.v1.yaml §telemetry (A11, ratified 2026-05-15). record_event! is a no-op when no recorder is registered, so the emission adds zero cost to non-instrumented runs.
fnrun_allpub fn run_all(args: &CommonArgs) -> Vec<RunOutcome>crates/vox-audit/src/lib.rs#L315-L325Run every registered subcommand and aggregate their outcomes into a combined report at contracts/reports/audit-all/<date>.json. Worst-case exit code semantics per contract §umbrella: - 0 if all sub-runs return 0 - 1 if any sub returns 1 and none return 2 or 3 - 2 if any sub returns 2 and none return 3 - 3 if any sub returns 3 Emits one vox.audit.run telemetry event per sub-gate (with umbrella_run = true) per A11 contract compliance.
fnrun_ga_snapshotpub fn run_ga_snapshot(args: &CommonArgs, strict_block_ga: bool) -> ga::GaSnapshotcrates/vox-audit/src/lib.rs#L332-L360Run every registered gate (foundation first per CR-F0) plus the standalone product binaries, fold them into a [ga::GaSnapshot] with blocked_by_foundation semantics, and (when args.write_canonical_report) write contracts/reports/_snapshot/<UTC>.json. This is the spine behind vox audit --gate all --strict-block-ga.
fnaggregate_exit_codepub fn aggregate_exit_code(outcomes: &[RunOutcome]) -> report::ExitCodecrates/vox-audit/src/lib.rs#L413-L428Aggregate-exit-code per contract §umbrella.
structaggregator::CorpusFeedbackReportpub struct CorpusFeedbackReportcrates/vox-audit/src/aggregator.rs#L28-L49Top-level CR-L8 report shape persisted to contracts/reports/corpus-feedback/<quarter>.json.
structaggregator::RepoRolluppub struct RepoRollupcrates/vox-audit/src/aggregator.rs#L54-L62Per-repository slice of [CorpusFeedbackReport]. Carries the same shape as the top-level totals but scoped to one repository_id bucket.
structaggregator::DiagnosticRolluppub struct DiagnosticRollupcrates/vox-audit/src/aggregator.rs#L66-L81One row of the top-50 firing diagnostics table.
structaggregator::RepairOutcomeHistogrampub struct RepairOutcomeHistogramcrates/vox-audit/src/aggregator.rs#L85-L97Repair-outcome histogram per CR-L8 spec.
fnaggregator::aggregatepub fn aggregate(events: &[TelemetryEvent], measured_at: &str) -> CorpusFeedbackReportcrates/vox-audit/src/aggregator.rs#L229-L280Aggregate a slice of events into a [CorpusFeedbackReport]. Pure function: deterministic given the same event slice and the same measured_at timestamp. measured_at is supplied by the caller (so tests can pin it) rather than computed internally. Produces both the workspace-wide rollup and per-repository_id buckets (A8, ratified 2026-05-15). Events with no repository_id are bucketed under [UNATTRIBUTED_REPO_KEY].
structcore_gates::CoreGateResultpub struct CoreGateResultcrates/vox-audit/src/core_gates.rs#L20-L26Outcome for one core umbrella gate.
structcore_gates::CoreGatesSummarypub struct CoreGatesSummarycrates/vox-audit/src/core_gates.rs#L30-L34Summary JSON envelope for vox audit core / --gate core.
fncore_gates::run_arch_gatepub fn run_arch_gate(root: &Path) -> CoreGateResultcrates/vox-audit/src/core_gates.rs#L37-L59Run vox-arch-check via cargo (same command as CI arch-check target).
fncore_gates::run_code_gatepub fn run_code_gate(root: &Path) -> CoreGateResultcrates/vox-audit/src/core_gates.rs#L62-L84Run vox-code-audit / TOESTUB over the workspace (legacy exit policy).
fncore_gates::run_silent_drop_gatepub fn run_silent_drop_gate(root: &Path, baseline: Option<PathBuf>) -> CoreGateResultcrates/vox-audit/src/core_gates.rs#L94-L121Run ONLY the silent-drop detectors (catch-all-swallow + cross-crate-dup) over the workspace and fail if ANY of their findings survive the optional grandfather baseline. Severity stays Info (the human vox audit code report is unchanged); the gate is count-based (no severity bump). Pass a committed contracts/toestub/silent-drop-baseline.v1.json as baseline to grandfather pre-existing sites so only NEW silent-drops trip the gate. Findings are filtered to the two rule ids explicitly, so unrelated batch detectors cannot pollute the count. (Task 2.6 / R9.)
fncore_gates::run_weak_test_gatepub fn run_weak_test_gate(root: &Path, baseline: Option<PathBuf>) -> CoreGateResultcrates/vox-audit/src/core_gates.rs#L128-L153Run ONLY the weak_test detector (touch-test anti-patterns) over the workspace, including test trees, and fail if any finding survives the optional grandfather baseline. Like the silent-drop gate this is count-based and severity-neutral: it guards against NEW touch-tests (e.g. in Phase-3 coverage waves) without forcing a rewrite of the grandfathered existing suite. (Task 2.6 sibling / weak_test gate.)
fncore_gates::run_retirement_gatepub fn run_retirement_gate() -> CoreGateResultcrates/vox-audit/src/core_gates.rs#L156-L174Run CR-L6 retirement parity via the existing registry subcommand.
fncore_gates::run_core_allpub fn run_core_all(root: &Path) -> CoreGatesSummarycrates/vox-audit/src/core_gates.rs#L177-L190Run arch → code → retirement and return an aggregate summary.
structga::GateRowpub struct GateRowcrates/vox-audit/src/ga.rs#L11-L19—
structga::GaSnapshotpub struct GaSnapshotcrates/vox-audit/src/ga.rs#L22-L30—
fnga::from_rowspub fn from_rows(mut gates: Vec<GateRow>, strict_block_ga: bool) -> Selfcrates/vox-audit/src/ga.rs#L35-L58Build the snapshot from already-evaluated rows, applying CR-F0 foundation-blocking and computing the GA verdict + exit code.
fnga::write_canonicalpub fn write_canonical(&self, root: &std::path::Path) -> std::io::Result<()>crates/vox-audit/src/ga.rs#L61-L68Write to contracts/reports/_snapshot/<YYYY-MM-DD>.json under the root.
structga::ProductBinpub struct ProductBincrates/vox-audit/src/ga.rs#L72-L76Descriptor for a standalone bin/cr-*.rs product gate.
fnga::product_binary_descriptorspub fn product_binary_descriptors() -> Vec<ProductBin>crates/vox-audit/src/ga.rs#L81-L124Descriptors for the standalone bin/cr-*.rs product gates. CR-P* are external_infra (live deploy / soak). cr-p3/cr-e3 are not yet bins — they land in Phase 6.
fnga::product_binary_gatespub fn product_binary_gates(_args: &crate::CommonArgs) -> Vec<GateRow>crates/vox-audit/src/ga.rs#L129-L163Run each product binary by resolving its sibling path next to the current executable; record a [GateRow]. A missing binary is recorded as a non-met row with exit_code -1 (“not measured”) rather than a panic.
structga::GaRatchetpub struct GaRatchetcrates/vox-audit/src/ga.rs#L167-L172Outcome of comparing a GA snapshot with the committed known-unmet baseline.
fnga::ratchetpub fn ratchet(snap: &GaSnapshot, known_unmet: &[String]) -> GaRatchetcrates/vox-audit/src/ga.rs#L177-L188Compare a GA snapshot with the committed known-unmet baseline. Only GA-relevant gates count (not tooling, matching ga_met). This never changes the honest GA verdict (ga_met); it lets CI fail on regressions instead of on “v1.0 is not done yet”.
fnga::parse_ga_baselinepub fn parse_ga_baseline(text: &str) -> Result<Vec<String>, String>crates/vox-audit/src/ga.rs#L191-L204Parse contracts/reports/cr-l-ga-baseline.v1.json: {"known_unmet": ["gate", ...]}.
structrecorder::BufferedRecorderpub struct BufferedRecordercrates/vox-audit/src/recorder.rs#L27-L29In-memory recorder used by tests and short-lived processes.
fnrecorder::newpub fn new() -> Selfcrates/vox-audit/src/recorder.rs#L32-L34—
fnrecorder::snapshotpub fn snapshot(&self) -> Vec<TelemetryEvent>crates/vox-audit/src/recorder.rs#L37-L39Snapshot the current event buffer (clones the vector).
fnrecorder::drainpub fn drain(&self) -> Vec<TelemetryEvent>crates/vox-audit/src/recorder.rs#L42-L44Drain the buffer, returning all captured events and emptying internal storage.