dsfb-gray 0.1.0

DSFB-Gray: Deterministic Rust Crate Auditing and Assurance Engine

DSFB-Gray is a deterministic Rust crate auditing system that performs structural code-quality interpretation, emits assurance scores, and produces machine-verifiable attestation artifacts.

The crate operates as a read-only audit layer over Rust source trees, generating reproducible outputs intended for code review, CI integration, and supply-chain traceability. It does not claim certification or compliance.**

The crate exposes a unified surface with a clearly defined primary interface:

• Static scanner (primary): deterministic Rust crate auditing, assurance scoring, and artifact generation
• Attestation layer: SARIF / in-toto / DSSE export for portable audit artifacts
• Runtime observer (secondary): retained DSFB structural interpretation components
• Evaluation harness: deterministic artifact regeneration and paper support

The project scope is broad by design, but the evidence model is intentionally narrow: only claims that can be regenerated from code and artifacts in this repository should be treated as authoritative. Everything else is descriptive context, not empirical evidence.

Evaluation Guidance. This repository should be evaluated primarily as a deterministic Rust crate auditing system. The static scanner defines the primary interface. Other DSFB components present in the codebase are retained framework elements and are not required to use or evaluate the audit pipeline.

What This Does NOT Do

• Does not modify the observed system (read-only, immutable references only)
• Does not replace Prometheus, Grafana, tracing, or any monitoring stack
• Does not require ML training or probabilistic models
• Does not use unsafe (enforced: #![deny(unsafe_code)])
• Does not certify crates or systems by itself
• Does not infer live gray failures from static source code alone

What This Does

DSFB treats a Rust crate as a structured audit surface:

source structure -> static findings -> assurance signals -> audit trace -> attestation

The crate also retains a broader DSFB runtime observer framework, which can consume telemetry streams and produce structural interpretations. In this repository, that runtime path is secondary and is not required to use or evaluate the static audit pipeline.

Claims and Evidence Discipline

• Public metrics in this repository are regenerated from code, not maintained by hand.
• Static scanner findings are source-visible structural proxies, not operational proof.
• Runtime results are deterministic harness results, not production-validation claims.
• The paper and README should track the same evidence base as data/evaluation_results.txt.

Quick Start

Single command:

cargo run --bin dsfb-scan-crate tokio

Other Commands:

cargo test
cargo run --bin dsfb-demo
cargo run --bin dsfb-regenerate-public-artifacts
cargo check --no-default-features

Crate audits produced by dsfb-scan-crate are written into timestamped run folders under output-dsfb-gray/, for example:

output-dsfb-gray/dsfb-gray-2026-04-14T01-23-45Z/
  tokio_scan.txt
  tokio_scan.sarif.json
  tokio_scan.intoto.json
  tokio_scan.dsse.json

The scanner still prints the human-readable report to stdout, and also writes the same .txt report plus the structured artifacts into the run directory. DSFB now emits one canonical broad audit. Domain and standards interpretations appear as conclusion lenses at the end of the report rather than as primary scan profiles.

Why Run This

DSFB-Gray is useful when you need a deterministic, inspectable audit of a Rust crate that can be:

• stored as a reproducible artifact
• compared across versions
• integrated into CI without introducing non-deterministic signals
• exported into standard formats (SARIF, in-toto, DSSE)

It is not intended to replace existing tools, but to provide a coherent, reproducible audit surface across them.

DSFB-Gray is designed to operate alongside existing tools such as Clippy, cargo-audit, and external static analyzers, aggregating and structuring their signals into a deterministic audit surface rather than replacing them.

Reproducibility: Auditing a Real Rust Crate

This section provides a concrete procedure for reproducing a DSFB audit on a real Rust crate. The example uses the widely adopted asynchronous runtime tokio.

Environment Requirements

• Rust toolchain (stable) installed via rustup
• Network access for initial crate retrieval
• Local filesystem access for artifact generation

Direct Scan from crates.io (Recommended)

After installing or cloning dsfb-gray, a crate can be scanned directly by name:

cargo run --bin dsfb-scan-crate tokio

Alternative: Manual Local Path Scan

For full control over the exact source version:

cargo fetch

Locate the crate under:

$HOME/.cargo/registry/src/

Then run:

cargo run --bin dsfb-scan-crate -- \
    --path /path/to/tokio-1.x.x/

Outputs

The audit produces:

• Deterministic assurance score and subscores
• Structured findings with reason codes
• Machine-readable artifacts (SARIF, in-toto, DSSE)
• Human-readable reports (text/CSV)

Artifacts are written to:

output-dsfb-gray/<timestamp>/

Colab Notebook Execution

A companion Colab notebook:

• installs the crate from scratch
• accepts a crates.io crate name
• runs the audit
• displays results inline
• exports a ZIP of all artifacts

Determinism Note

Repeated execution on the same crate version and configuration produces identical outputs.

This holds under:

• identical crate version
• identical DSFB configuration
• identical Rust toolchain

No claim is made for invariance across toolchain or crate changes.

Integrated Stack

• Static scanner (primary interface): deterministic crate auditing and assurance scoring
• Attestation layer: portable audit artifact export (SARIF, in-toto, DSSE)
• Public-artifact generator: reproducible audit and paper outputs
• Runtime observer (secondary, retained): DSFB structural interpretation pipeline

Runtime Evaluation (Supporting, Non-Primary)

These results correspond to the retained DSFB runtime observer evaluation harness and are included as supporting evidence of the broader framework. They are not the primary evaluation surface of the crate’s static auditing functionality.

Current metrics are generated by cargo run --bin dsfb-regenerate-public-artifacts. The current recommended configuration detects 4/4 primary scenarios, and 1 primary scenario(s) show a pre-injection anomaly.

Generated outputs are written to data/evaluation_results.txt, data/demo-output.txt, the scenario CSV files in data/, and the generated snippets in docs/generated/ and paper/generated/.

Evidence Ledger

Every public-facing numeric claim in this repository should map to one command, one artifact, or one generated section.

Assurance Scoring

The crate scanner now emits a locked percentage-based assurance score using the method identifier dsfb-assurance-score-v1.

The score is a broad improvement and review-readiness target. It is not a compliance certification.

The scoring specification is fixed in docs/AUDIT_SCORING_LOCKED.md. Any future change to weights, thresholds, checkpoint sets, or score bands must create a new method identifier and a new locked specification.

The next-phase implementation plan for hazard interpretation lenses, runtime attestation binding, formal property bridges, and refactor guidance is in docs/IMPLEMENTATION_ROADMAP.md.

Legacy root-level *_scan.* artifacts are automatically migrated into output-dsfb-gray/ the next time the scanner runs.

Public Artifact Regeneration

cargo run --bin dsfb-regenerate-public-artifacts is the canonical regeneration path for:

• data/evaluation_results.txt
• data/demo-output.txt
• scenario CSVs under data/
• docs/generated/*
• paper/generated/*
• the generated README and paper claim/result sections

Project Structure

dsfb-gray/
├── CHANGELOG.md
├── data/                  # Deterministic evaluation artifacts (regenerated)
│   ├── evaluation_results.txt
│   ├── demo-output.txt
│   ├── sensitivity_sweep.csv
│   └── <scenario>.csv
├── docs/
│   ├── AUDIT_SCORING_LOCKED.md # Locked scoring specification
│   ├── IMPLEMENTATION_ROADMAP.md # Next-phase feature roadmap
│   ├── INTEGRATION_GUIDE.md # Runtime / scanner / attestation integration
│   ├── CAPABILITY_LADDER.md # Broad-scope capability framing
│   └── SCAN_TRIAGE.md # How to read noisy vs useful scan findings
├── examples/
│   ├── telemetry_adapter_integration.rs
│   └── scan_to_runtime_prior.rs
├── paper/
│   ├── paper.md           # Markdown paper with generated sections
│   ├── paper.tex          # TeX paper with generated tables
│   └── generated/         # Generated paper fragments
├── scripts/
│   └── regenerate_public_surface.sh
├── src/
│   ├── lib.rs             # Unified public API + feature layout
│   ├── adapter.rs         # TelemetryAdapter and integration bridge
│   ├── residual.rs        # ResidualSign estimator (r, ω, α)
│   ├── envelope.rs        # Admissibility envelopes
│   ├── grammar.rs         # Grammar state machine with hysteresis
│   ├── heuristics.rs      # Heuristics bank + bounded static priors
│   ├── episode.rs         # Operator-facing episode objects
│   ├── observer.rs        # Runtime observer + reason evidence
│   ├── regime.rs          # Workload phase classifier
│   ├── audit.rs           # Deterministic audit trace
│   ├── inject.rs          # Fault injection scenarios
│   ├── report.rs          # Plain-text and CSV report generation
│   ├── evaluation.rs      # Canonical public-evidence generator
│   ├── scan.rs            # Static scanner + attestation export
│   └── bin/
│       ├── dsfb-demo.rs
│       ├── dsfb-regenerate-public-artifacts.rs
│       └── dsfb-scan-crate.rs
└── output-dsfb-gray/     # Timestamped scan runs

The Heuristics Bank

12 typed entries encoding patterns that experienced Rust engineers recognize implicitly:

Non-Interference Contract (v1.0)

All inputs accepted as &ResidualSample (immutable references). No mutable reference to any upstream system component is created. If the observer layer is removed from the dependency tree, the observed system compiles and behaves identically.

API Direction

The library surface is being hardened around four public concepts:

• TelemetryAdapter<T> for translating application telemetry into ResidualSample
• StaticPriorSet for bounded scan-to-runtime structural biasing
• ReasonEvidence for explaining why a reason code fired
• one canonical broad audit plus attestation exports for CI and supply-chain workflows

The goal is not to narrow the project. It is to make the broad stack legible and reusable as one coherent library.

Release-note discipline lives in CHANGELOG.md.

Related Work

This is a domain instantiation of the DSFB framework. Other instantiations:

• Gas Turbine Health Monitoring — C-MAPSS evaluation
• Semiconductor Process Control — SECOM dataset
• Battery Health Monitoring — NASA PCoE

Citation

@software{debeer2026dsfbgray,
  author    = {de Beer, Riaan},
  title     = {{DSFB Structural Semiotics Engine for Deterministic Rust Crate
               Auditing: A Non-Intrusive Deterministic Augmentation Layer for
               Structural Code Quality Interpretation and Certification
               Compliance Estimation}},
  year      = {2026},
  version   = {1.0},
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.19600872},
  url       = {https://doi.org/10.5281/zenodo.19600872}
}

License

The theoretical framework, formal constructions, and supervisory methods described herein constitute proprietary Background IP of Invariant Forge LLC (Delaware LLC No.\ 10529072), with prior art established by this publication and earlier Zenodo DOI publications by the same author. Commercial deployment requires a separate written license. Reference implementations are released under Apache~2.0.

Licensing: licensing@invariantforge.net

LICENSE

Author

Riaan de Beer — Chief Research Advisor, Invariant Forge LLC ORCID: 0009-0006-1155-027X