Crate dsfb_gray 

DSFB Structural Semiotics Engine

Deterministic, non-intrusive interpretation of telemetry trajectories for distributed Rust systems.

The core observer converts runtime telemetry streams into typed structural objects defined by residuals, drift, slew, admissibility envelopes, grammar states, and reason codes. With the default std feature enabled, this crate also includes the deterministic fault-injection harness and plain-text/CSV report generation used by the demo binary.

What This Crate Does

• Observes telemetry through immutable references only
• Classifies trajectories as Admissible, Boundary, or Violation
• Emits deterministic reason codes from a finite heuristics bank
• Records an audit trace for replay and verification

Feature Layout

• Core observer modules are available in no_std mode
• Scenario injection and report generation require the default std feature
• Static crate scanning and attestation export require the default std feature

Example

use dsfb_gray::{DsfbObserver, ObserverConfig, ResidualSample, ResidualSource};

let config = ObserverConfig::fast_response();
let mut observer = DsfbObserver::new(ResidualSource::Latency, &config);
let sample = ResidualSample {
    value: 12.0,
    baseline: 10.0,
    timestamp_ns: 1_000,
    source: ResidualSource::Latency,
};
let result = observer.observe(&sample);
assert_eq!(result.sign.residual, 2.0);

Non-Interference Contract

Contract Version 1.0: The observer accepts telemetry through immutable references only (&ResidualSample). No mutable reference to any upstream system component is created, stored, or transmitted.

Structs

AdmissibilityEnvelope

Admissibility envelope for a single residual source under a specific workload phase.

AppliedStaticPrior

Static prior actually applied during one heuristic match.

AsyncStarvationScenario

Async runtime starvation scenario.

AuditEvent

A single audit event recording one observation-classification cycle.

AuditTrace

Fixed-capacity audit trace buffer (stack-allocated, no_alloc compatible).

ChannelBackpressureScenario

Channel backpressure scenario.

ClockDriftScenario

Clock drift injection scenario.

CrateSourceScanReport

Result of scanning a source tree for DSFB heuristic provenance motifs.

DsfbObserver

The DSFB observer for a single residual source channel.

Episode

A structural episode: a contiguous period of a specific grammar state.

EpisodeBuilder

Builder for constructing episodes incrementally as observations arrive.

GrammarTransition

A grammar state transition event.

HeuristicEntry

A single entry in the heuristics bank.

HeuristicId

Unique identifier for a heuristic entry.

HeuristicSourceMatch

Aggregated source-motif match for one heuristic entry.

HeuristicsBank

The heuristics bank: a fixed-size collection of typed degradation motifs.

IdentityTelemetryAdapter

Identity adapter for callers that already hold ResidualSample values.

MatchResult

Result of matching a residual sign against the heuristics bank.

MultiChannelObserver

Multi-channel observer that tracks multiple residual sources simultaneously.

NegativeControlRow

One clean-window negative-control result.

ObservationResult

Observation result from a single observe() call.

ObserverConfig

Configuration for the DSFB observer.

PartialPartitionScenario

Partial network partition scenario.

PrimaryEvaluationRow

Structured result for one primary evaluation scenario.

PublicArtifactPaths

Paths written by the public-artifact regeneration workflow.

PublicEvaluationBundle

Fully structured public evaluation bundle.

ReasonEvidence

Human-readable explanation of the structural reason selected by DSFB.

RegimeClassifier

Classifier that determines the current workload phase from throughput and latency signals.

ResidualSample

A single residual measurement sample from the observed system.

ResidualSign

The residual sign: DSFB’s primary inferential object.

SampleRecord

ScanArtifactPaths

Paths of JSON scan artifacts written to disk.

ScanEvidence

One line of source evidence supporting a heuristic motif match.

ScanRunPaths

Paths describing one timestamped scan-output run.

ScanSigningKey

Ed25519 signing material for DSSE export.

ScenarioResult

SensitivitySweepRow

One row of the 2D sensitivity sweep.

StaticPrior

Static prior for one heuristic, typically sourced from the crate scanner.

StaticPriorSet

Fixed-capacity collection of static heuristic priors.

Enums

EnvelopePosition

Classification of a residual sign against an envelope.

GrammarState

Grammar state: the structural classification output.

ReasonCode

Reason codes for distributed system structural interpretations.

ResidualSource

Source type for a residual measurement.

ScanProfile

Legacy interpretation hint for the DSFB static crate scan.

WorkloadPhase

Workload phase for envelope conditioning.

Constants

CONTRACT_VERSION

Non-interference contract version.

CRATE_VERSION

Crate version for audit trace embedding.

DEFAULT_SCAN_OUTPUT_ROOT

Default root directory under which timestamped scan runs are written.

Traits

FaultScenario

A deterministic fault scenario producing a time-series of residual samples.

TelemetryAdapter

Adapter from an application-specific telemetry record into a DSFB sample.

Functions

build_public_evaluation

Build the full deterministic public evaluation bundle.

derive_static_priors_from_scan

Derive bounded runtime structural priors from a static crate scan.

export_scan_artifacts

Write SARIF, in-toto, and DSSE artifacts for a completed scan.

generate_csv

Generate CSV output from scenario results.

generate_report

Generate a plain-text report from scenario results.

migrate_legacy_scan_artifacts

Move legacy root-level scan artifacts into one timestamped migration folder.

prepare_scan_output_run

Create a timestamped output directory for one scan invocation.

render_public_evaluation_report

Render the full human-readable evaluation report.

render_scan_attestation_statement

Render the scan as an in-toto statement whose predicate summarizes the scan.

render_scan_dsse_envelope

Render the scan as a DSSE envelope around the in-toto statement.

render_scan_report

Render a source scan report as plain text.

render_scan_sarif

Render the scan as SARIF 2.1.0 JSON.

reproducibility_verified

Whether every reproducibility run matched the first baseline run.

run_scenario

Run a scenario through a DSFB observer and collect results.

scan_crate_source

Scan a crate source tree and return a static motif report.

scan_crate_source_with_profile

Scan a crate source tree using a legacy interpretation hint.

write_public_artifacts

Write the canonical public evaluation artifacts and generated snippets.