Add dsfb-debug crate

Author: infinityabundance

crates/dsfb-debug/.cargo-mutants.toml

@@ -0,0 +1,41 @@
+# DSFB-Debug — cargo-mutants configuration.
+#
+# Mutation testing focuses on the modules whose correctness the paper
+# makes load-bearing claims about: grammar evaluation (§5.5),
+# policy mapping (§5), and episode aggregation (§7 — Trace Event
+# Collapse). A mutation in any of these that is NOT killed by the test
+# suite is a signal that the test suite under-specifies the module.
+#
+# Run:
+#   cargo mutants --manifest-path crates/dsfb-debug/Cargo.toml --in-place
+#
+# Tier-1 modules (must have ≥ 80% mutation kill-rate before paper goes
+# out): grammar.rs, policy.rs, episode.rs.
+# Tier-2 (target ≥ 60%): sign.rs, dsa.rs, baseline.rs.
+# Tier-3 (best-effort): heuristics_bank.rs, residual.rs, envelope.rs.
+
+# Examine only the load-bearing modules first; the const constructors in
+# adapters/ and lib.rs internal scaffolding produce noisy mutants.
+examine_globs = [
+    "src/grammar.rs",
+    "src/policy.rs",
+    "src/episode.rs",
+    "src/sign.rs",
+    "src/dsa.rs",
+    "src/baseline.rs",
+    "src/heuristics_bank.rs",
+    "src/residual.rs",
+    "src/envelope.rs",
+]
+
+# The test command must fire both the no_std unit tests and the std-side
+# fixture-aware tests so paper-lock invariants are exercised.
+test_tool = "cargo"
+additional_cargo_test_args = ["--features", "std paper-lock"]
+
+# Timeout safety: the no_std core is tiny, but mutation runs are slow.
+timeout_multiplier = 2.0
+
+# Skip mutants that target trivial scaffolding the paper does not
+# claim correctness for.
+skip_calls = ["dbg!"]

crates/dsfb-debug/.dockerignore

@@ -0,0 +1,12 @@
+target/
+target-local/
+artifacts/
+data/upstream/
+*.zip
+*.tar.gz
+*.log
+*.aux
+*.out
+*.toc
+build/
+.cargo/

crates/dsfb-debug/.gitignore

@@ -0,0 +1,21 @@
+# Build artefacts (also covered by parent .gitignore but listed for
+# standalone-workspace clarity).
+target/
+Cargo.lock.bak
+
+# Upstream archives — these are large and DOI-pinned externally; we
+# store SHA-256 manifests in `data/MANIFEST.toml` and the projected
+# slices in `data/fixtures/`. The raw upstream archives stay local.
+data/upstream/
+
+# Paper source and build artefacts stay local unless explicitly requested.
+paper/
+
+# Generated demo/report bundles.
+output-dsfb-debug/
+
+# Misc local-only.
+*.swp
+.DS_Store
+*.zip
+*.tar.gz

crates/dsfb-debug/Cargo.toml

@@ -0,0 +1,55 @@
+[package]
+name = "dsfb-debug"
+version = "0.1.0"
+edition = "2021"
+authors = ["Riaan de Beer <riaan@invariantforge.net>"]
+license = "Apache-2.0"
+description = """
+DSFB-Debug — Structural Semiotics Engine for Software Debugging.
+A deterministic, read-only, observer-only augmentation layer for
+execution-trace residual interpretation. Does NOT replace existing
+observability tools — augments them with typed structural interpretation.
+"""
+repository = "https://github.com/infinityabundance/dsfb"
+keywords = ["debugging", "observability", "deterministic", "semiotics", "tracing"]
+categories = ["no-std", "science", "algorithms"]
+rust-version = "1.75.0"
+
+[features]
+default = []
+# paper-lock: gates the real-dataset evaluation API (`evaluate_real_dataset`).
+# Without this feature the std-only real-data path is physically absent from
+# the compiled artefact, preserving the no_std/no_alloc default build.
+paper-lock = ["std"]
+# std: enables the std-only adapter, hash-verification, and real-dataset entry
+# points. The no_std core (residual/sign/grammar/policy/episode pipeline)
+# remains identical regardless of this feature.
+std = []
+# demo: opt-in feature for the `dsfb-debug-demo` binary. Pulls in plotters /
+# printpdf / zip / chrono crates ONLY when this feature is requested. The
+# zero-dep no_std core is unaffected; default `cargo install` pulls nothing.
+# Reviewers reproducing the published figures use:
+#   cargo install --path . --features demo
+#   dsfb-debug-demo
+demo = ["std", "paper-lock", "dep:plotters", "dep:zip"]
+
+[dependencies]
+# Core crate has zero runtime dependencies — pure no_std, no_alloc.
+# SHA-256 and TSV parsing are hand-rolled in `src/adapters/`.
+# The optional dependencies below are gated behind the `demo` feature
+# and never enter the no_std/no_alloc core build.
+plotters = { version = "0.3", optional = true, default-features = false, features = ["bitmap_backend", "bitmap_encoder", "ttf", "all_series", "all_elements", "full_palette"] }
+zip = { version = "0.6", optional = true, default-features = false, features = ["deflate"] }
+
+[[bin]]
+name = "dsfb-debug-demo"
+path = "src/bin/dsfb_debug_demo.rs"
+required-features = ["demo"]
+
+[dev-dependencies]
+
+# Detached from the parent workspace at /home/one/dsfb/Cargo.toml so the
+# crate can be built / tested standalone after the folder rename. Remove
+# this block once the parent manifest's `workspace.members` is updated
+# to point at `crates/dsfb-debug`.
+[workspace]

crates/dsfb-debug/Dockerfile

@@ -0,0 +1,40 @@
+# DSFB-Debug — reviewer reproducibility container (Phase η.8, Session 18).
+#
+# One-command boot of the entire DSFB-Debug verification chain on a
+# clean machine. From a fresh checkout:
+#
+#     docker build -t dsfb-debug:reviewer .
+#     docker run --rm dsfb-debug:reviewer
+#
+# Default CMD runs `cargo test --features "std paper-lock" -- --nocapture`
+# which fires every per-fixture eval test, the LO-CV harness, the
+# sensitivity sweep, the axis ablation, the detector subset opt, the
+# timing benchmark, and the property-test suite end-to-end.
+#
+# Pinned to rust:1.75-bookworm to match the rust-toolchain.toml MSRV.
+# No Cargo runtime dependencies in the no_std core; the demo feature
+# adds plotters + zip; both vendored via cargo's own resolution.
+#
+# Theorem 9 deterministic replay verified inside every test invoked
+# by the default CMD; reproducibility is byte-identical across
+# reviewer machines that match the rust:1.75-bookworm digest.
+
+FROM rust:1.75-bookworm
+
+WORKDIR /work/dsfb-debug
+
+# Bring source tree in. .dockerignore should exclude target/ +
+# build artefacts; reviewers running `docker build` get a clean
+# build from source.
+COPY . .
+
+# Pre-fetch dependencies + build the crate so first `docker run`
+# is snappy. Build with full features so the LO-CV harness +
+# audit modules are wired.
+RUN cargo build --features "std paper-lock"
+
+# Default verification chain. Re-runs every fixture eval + LO-CV
+# + sensitivity + ablation + subset opt + timing + property tests.
+# Output is the verbatim test stdout reviewers should match against
+# the published audit ledgers in docs/audit/.
+CMD ["cargo", "test", "--features", "std paper-lock", "--", "--nocapture"]