Crate dsfb_debug 

dsfb-debug — Structural Semiotics Engine for Software Debugging

A deterministic, read-only, observer-only augmentation layer that turns the residuals every observability stack already discards into typed, human-readable debugging episodes with full evidence trails.

Augmentation, not replacement

DSFB-Debug does NOT compete with existing observability tools (Datadog, OpenTelemetry, Jaeger, Sentry, Prometheus, ELK). It sits on top of them as a passive observer that ingests their residuals and produces typed structural interpretation. The intended deployment is: existing tools detect anomalies; DSFB-Debug structures them into typed episodes; operators receive the union as actionable insight rather than alert noise.

Non-Intrusion Contract (type-enforced)

Every public function accepts only shared immutable references (&[T]). There is NO mutable write path into any upstream data structure. The Rust type system enforces this at compile time. See docs/non_intrusion_contract.md for the formal contract.

Crate Properties (compile-time enforced)

• #![no_std] — no standard library dependency in the core
• #![forbid(unsafe_code)] — zero unsafe blocks anywhere
• #![deny(clippy::unwrap_used)] — no panic paths
• Zero runtime Cargo dependencies — SHA-256, DFT, matrix algebra are hand-rolled in src/adapters/ and src/incumbent_baselines.rs
• Deterministic — identical inputs always produce byte-identical outputs (Theorem 9, formally proven in paper §6.4)

Feature Gates

• std — enables Vec-based variable-size buffers and the adapter layer. The no_std core is unchanged.
• paper-lock — enables evaluate_real_dataset, the RealDatasetManifest struct, and SHA-256 integrity gating. Implies std. Without paper-lock, the real-data entry point is physically absent from the compiled artefact.

Pipeline Architecture

Residual → SignTuple → Grammar → Hysteresis → ReasonCode → Bank lookup → Episode

The engine is a pipeline of deterministic stages. Each stage has its own module:

Stage	Module	Output type
Residual extraction	adapters/residual_projection.rs	OwnedResidualMatrix
Sign tuple	sign.rs	SignTuple
Grammar	grammar.rs	GrammarState
Hysteresis	policy.rs	confirmed GrammarState
Reason code	policy.rs	ReasonCode
Heuristics bank lookup	heuristics_bank.rs	SemanticDisposition
Episode aggregation	episode.rs	DebugEpisode
Multi-detector fusion	fusion.rs	FusionMetrics (std-only)
Causality attribution	causality.rs	root_cause_signal_index
Operator rendering	render.rs	String (std-only)

Standards Alignment

• NIST SP 800-53 Rev. 5: AU-2 (auditable events: named primary witness detectors), AU-3 (record content: per-motif provenance + DOI + taxonomy), AU-6 (review/analysis: episode catalog), AU-12 (audit generation: deterministic replay)
• NIST SP 800-92: §4.2 (log analysis), §5 (log management)
• NIST SP 800-171 Rev. 2: §3.3 (Audit & Accountability)
• DO-178C §6.3: certification-pathway-eligible architectural foresight (NOT a certification claim)
• IEEE 1012-2016 §7: V&V verification tool classification
• ISO/IEC 25010:2023: Analysability, Testability
• OpenTelemetry Semantic Conventions: OTLP-compatible residual ingestion
• W3C Trace Context Level 1: §3 (traceparent), §4 (tracestate)
• SOC 2 Type II: CC7.2, CC7.3 (Monitoring Activities)

Theorem 9 (Deterministic Replay)

For any byte-stable residual matrix input, two consecutive engine.run_evaluation(...) calls produce byte-identical episode output. Mechanically proven by composition of deterministic stages (paper §6.4); empirically verified on every real-bytes vendored fixture by verify_deterministic_replay. Failure of this assertion on real bytes surfaces as a hard test failure, not a silent metric drift.

Modules

baseline

DSFB-Debug: baseline computation — healthy-window statistics.

causality

DSFB-Debug: causality / graph attribution — root-cause stamping over the service-call graph (no_std).

config

DSFB-Debug: engine configuration — paper §F.4 + Appendix F.

dsa

DSFB-Debug: Deterministic Structural Accumulator (DSA) — paper §5 and Appendix D.

envelope

DSFB-Debug: admissibility envelope — paper §5.4 Equation (3).

episode

DSFB-Debug: episode aggregation — Trace Event Collapse implementation.

episode_catalog

DSFB-Debug: episode catalog — institutional memory for debugging episodes.

error

DSFB-Debug: error types — additive, Copy, no-panic.

grammar

DSFB-Debug: grammar evaluation — paper §5.5.

graph_inference

DSFB-Debug: service-call graph auto-inference (no_std).

heuristics_bank

DSFB-Debug: Heuristics Bank — 32 hand-curated motifs with full Phase 0–8 fusion-axis decision parameters.

policy

DSFB-Debug: policy engine — paper §5.

residual

DSFB-Debug: residual computation — paper §5.2 Equation (1).

sign

DSFB-Debug: sign-tuple computation — paper §5.3 Equation (2).

types

DSFB-Debug: core domain types — public API contract.

Structs

DsfbDebugEngine

Main DSFB debugging engine — stateless, deterministic, read-only.