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.

Invariant Forge LLC — Riaan de Beer — ORCID: 0009-0006-1155-027X

Citation

If you use DSFB-Debug, cite the Zenodo software record:

de Beer, R. (2026). DSFB-Debug Structural Detector-Field Residual Semiotics Engine for Software Debugging: A Deterministic Augmentation Layer for Typed Residual Interpretation of Execution Traces, Log Streams, and Observability Telemetry in Production Software Systems (v1.0). Zenodo. https://doi.org/10.5281/zenodo.20088863

Zenodo record: https://zenodo.org/records/20088863

Paper Version 1.0 and internal Phase labels are research-publication identifiers; crate semver remains 0.1.0 until crates.io release stabilization.

What It Does

• Reads residuals from existing observability tools (OpenTelemetry, Jaeger, Datadog, ELK, Prometheus, Sentry) and from code-defect catalogs (Defects4J, BugsInPy, PROMISE).
• Computes typed structural interpretation: drift, slew, grammar state, motif, episode.
• Performs Trace Event Collapse: raw alerts → few typed episodes (RSCR ranges from 3.67× on the F-11 production-trace fixture to 62× on the Defects4J bug-catalog fixture; verbatim test stdout, bounded to those fixtures).
• Fuses 205 deterministic detectors organised across 27 mathematical axes (Tiers A–U + EXTRA + V/X/Y/Z/AA) into a consensus-validated typed output via the heuristics bank.
• Operates the 9-axis bank-aware fusion with a 4-rung Anti-Hallucination Ladder — Phase 0 (raw) / Phase 5.6 (confuser- boundary) / Phase 7 (tier-witness) / Phase 8 (per-detector witness) — each rung a single config flag, each rung tested deterministically.
• Produces deterministic, reproducible, auditable outputs (Theorem 9 — empirically verified on every real-bytes fixture).

What It Does NOT Do

• Does NOT replace any existing observability tool.
• Does NOT claim faster detection or higher accuracy than existing methods. The framing is augmentation, not competition.
• Does NOT modify upstream data (compile-time enforced via &[T]-only public surface).
• The no_std operational core is zero-runtime-dependency, #![forbid(unsafe_code)], and avoids unwrap/panic paths in public core evaluation APIs. std/demo/test/audit paths are separated from the no_std core.

Crate Properties

Mathematical Summary

The engine is a deterministic function from a residual matrix to a list of typed episodes. The core construction at each (window w, signal s) cell:

Fusion consensus at each (w, s) cell:

consensus(w, s) = Σ_{cell-level detectors d}     I(d fires at (w, s))
                + Σ_{window-level detectors d}   I(d fires at w)
fire(w, s)      = consensus(w, s) ≥ min_consensus

A DSFB structural episode is consensus-confirmed when at least one of its windows fires. The bank's match_episode_with_consensus then scores the typed motif with consensus boost:

score(motif, ep) = w_drift   · drift_score(ep)
                 + w_slew    · slew_score(ep)
                 + w_bound   · boundary_score(ep)
                 + w_corr    · correlation_score(ep)
                 + w_dur     · duration_score(ep)
                 + α · (consensus_max(ep) / max_detectors)

The bank's per-motif weights w_* and consensus-factor α are documented inline at src/heuristics_bank.rs.

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; empirically verified on F-11 (35 604 Jaeger spans).

Code Tour

use dsfb_debug::DsfbDebugEngine;

// Engine creation under paper-lock parameters.
let engine = DsfbDebugEngine::<32, 64>::paper_lock().unwrap();

// Per-signal evaluation (single signal).
let eval = engine.evaluate_signal(&residual_slice, num_windows);

// Full residual-matrix evaluation.
let mut evals    = vec![Default::default(); num_signals * num_windows];
let mut episodes = vec![Default::default(); 256];
let (count, metrics) = engine.run_evaluation(
    &data, num_signals, num_windows, &fault_labels,
    healthy_window_end, &mut evals, &mut episodes, "fixture_name",
).unwrap();

// Causality (graph attribution): augments episodes with root_cause_signal_index.
let (count, _) = engine.run_evaluation_with_graph(
    &data, num_signals, num_windows, &fault_labels,
    healthy_window_end, &service_graph, &mut evals, &mut episodes, "fixture",
).unwrap();

Multi-detector fusion

use dsfb_debug::fusion::{run_fusion_evaluation, FusionConfig};

let cfg = FusionConfig {
    min_consensus: 3,
    ..FusionConfig::ALL_DEFAULT  // enables all 205 detectors + 9-axis bank-aware fusion
};
let metrics = run_fusion_evaluation(
    &engine, &data, num_signals, num_windows, healthy_window_end,
    &fault_labels, &cfg, "fixture",
).unwrap();

Operator-side helpers

use dsfb_debug::{render_episode_summary, EpisodeCatalog};
use dsfb_debug::calibration::recommend_config_from_healthy;

// Render an episode for an operator dashboard.
let summary = render_episode_summary(&episode, &signal_names);

// Episode catalog: similarity matching against past closed episodes.
let mut catalog = EpisodeCatalog::<256>::new();
catalog.record(episode);
let nearest = catalog.find_similar(&query);

// Site calibration on a healthy slice.
let report = recommend_config_from_healthy(
    &healthy_data, num_signals, healthy_windows, /* percentile = */ 0.90);

Heuristics Bank Coverage

The bank ships 32 hand-curated motifs across six tiers, each with provenance (FrameworkDesign / DatasetObserved / FieldValidated), the upstream dataset name + DOI it was observed in, a dashboard hint for production debug engineers, and an IEEE 24765 / Avizienis-Laprie- Randell taxonomy anchor — no ad-hoc names.

MAX_MOTIFS = 64 leaves 32 free slots for v0.3 / v0.4 expansion. The bank exposes two lookup paths: per-signal lookup and per-episode match_episode_with_consensus (multi-feature weighted scoring with topology / duration / consensus gates). LO2 endoductive anomalies are deliberately NOT in the bank — they validate the SemanticDisposition::Unknown branch.

See docs/heuristics_bank.md for the per-motif reference.

Detector Orthogonality

The fusion harness wires 205 deterministic detectors organised across 27 mathematical axes (Tiers A–U + EXTRA + V/X/Y/Z/AA). Each axis contributes a distinct mathematical foundation; orthogonal combinations form the consensus arithmetic and route through per-motif tier-affinity masks per the Routed Evidence Principle (paper §6.5).

Each detector is implemented as a deterministic pub fn in src/incumbent_baselines.rs, citation in the doc-comment. Where literature requires FFT/DFT, MCMC, or non- deterministic randomization, the implementation uses a documented deterministic-seed reduction or time-domain proxy — the simplification is named honestly in each detector's doc-comment. See docs/fusion_design.md for the per-tier notes and consensus contribution rules.

Real-World Dataset Coverage — 12 Real-Bytes Fixtures Across 9 Datasets

All Phase F + Phase G fixtures are vendored as real upstream byte slices (no synthetic data, ever; paper-lock hard-errors on missing real data with MissingRealData). Every fixture is DOI-pinned, SHA-256- gated, and replayable under Theorem 9.

Verbatim metrics from the latest cargo test --features "std paper-lock" -- --nocapture run:

See data/MANIFEST.toml for per-dataset DOI, license, and SHA-256 gates; docs/dataset_provenance.md for the full provenance ledger; data/upstream/project_*.py for each fixture's deterministic projection script.

9-Axis Bank-Aware Fusion + Anti-Hallucination Ladder

The fusion harness is governed by a nine-axis configuration that progressively tightens the typed-disposition decision. Each axis is a single FusionConfig flag; each axis was introduced in a specific phase to close a specific failure mode (paper §11.x).

The Anti-Hallucination Ladder uses axes 6/8/9 as four progressive strictness rungs (Phase 0 / 5.6 / 7 / 8). Operators choose the rung appropriate for their fault profile; recall trades against typing precision.

Fusion Sweep Results — F-11

Captured from the fusion_sweep_on_f11_fixture test (35 604 real Jaeger spans, 16 services, 431 windows). Per-window FP rate computed against the healthy slice. Run cargo test --features "std paper-lock" --test fusion_compare -- --nocapture for the verbatim matrix.

Single-detector minima for reference (tests/incumbent_compare.rs): scalar-3σ 0.0139, CUSUM 0.0116, EWMA 0.0812, DSFB-structural 0.0070. At N≥7, fusion FP rate (0.0023) is ~3× lower than DSFB-structural alone, ~5× lower than CUSUM, ~6× lower than scalar-3σ, ~35× lower than EWMA.

Honest claim: F-11 + F-11b numbers are bounded to those fixtures. Generalisation requires Phase II partner-data engagement.

Standards Alignment

NIST SP 800-53 (AU-2/3/6/12), NIST SP 800-92, NIST SP 800-171, DO-178C §6.3 (pathway-eligible foresight, not certification), IEEE 1012-2016, ISO/IEC 25010, OpenTelemetry, W3C Trace Context, SOC 2 Type II.

See docs/standards_alignment.md for control-level mapping.

Quick Verification

cargo build --no-default-features
cargo test  --no-default-features
cargo test  --features "std paper-lock" -- --nocapture
cargo clippy --features "std paper-lock" --all-targets -- -D warnings

License

Apache 2.0 (reference implementation). Background IP: Invariant Forge LLC. Commercial deployment requires separate written license. Contact: licensing@invariantforge.net