dsfb-dscd 0.1.0

# dsfb-dscd

Deterministic Structural Causal Dynamics (DSCD) on top of `dsfb` + `dsfb-add`.

This crate builds trust-gated causal DAGs from deterministic observer traces, sweeps trust thresholds, and exports finite-size scaling artifacts for certifiable analysis in safety-critical autonomy workflows.

## What This Crate Does

`dsfb-dscd` provides:

- A CLI binary (`dsfb-dscd`) for deterministic end-to-end DSCD runs.
- A library API for custom pipelines (`DscdConfig`, `DscdParams`, `run_dscd_simulation`).
- Deterministic threshold sweeps `rho(tau)` and finite-size scaling outputs.
- Provenance-rich edge/event exports for auditability and replay.

At a high level:

1. Generate deterministic event/observer traces from `dsfb`.
2. Compute structural descriptors from `dsfb-add` (AET/IWLT-derived quantities).
3. Construct local candidate edges with strict temporal/structural locality.
4. Apply trust gating across a `tau` grid to produce threshold curves.
5. Compute scaling summaries (`tau*`, transition width, max derivative).
6. Export CSVs used by the DSCD notebooks and paper figures.

## Why Use DSCD

DSCD is designed for settings where reproducibility and traceability matter:

- Deterministic outputs for a fixed config and toolchain.
- Explicit local-causal constraints (temporal lag + structural radius).
- Bounded out-degree for certification-friendly graph complexity.
- Full edge provenance exports to support post-run audits.
- Ready-to-plot CSV artifacts for finite-size threshold analysis.

## Quick Start

Demo mode (free Colab / laptop):

```bash
cargo run -p dsfb-dscd --release -- --mode demo
```

Performance mode (workstation):

```bash
cargo run -p dsfb-dscd --release -- --mode performance
```

Custom run (override locality and scaling knobs):

```bash
cargo run -p dsfb-dscd --release -- --mode performance \
  --num-events 100000 \
  --tau-min 0.0 \
  --tau-max 1.0 \
  --tau-steps 256 \
  --max-temporal-lag 64 \
  --max-structural-radius 0.1 \
  --temporal-decay-gamma 0.0 \
  --structural-decay-beta 2.0 \
  --max-out-edges 8 \
  --scaling-ns 5000,10000,20000,50000,100000 \
  --root-event-id 0 \
  --output-root output-dsfb-dscd
```

## CLI Parameters

- `--mode {demo|performance}`: select preset scale and tau-grid density.
- `--num-events <usize>`: override event count used for the representative run.
- `--scaling-ns <csv>`: comma-separated `N` values for scaling curves.
- `--tau-min <f64>`: lower threshold bound.
- `--tau-max <f64>`: upper threshold bound.
- `--tau-steps <usize>`: number of thresholds in the sweep grid.
- `--max-temporal-lag <usize>`: max forward edge span in event index.
- `--max-structural-radius <f64>`: max structural distance for local edges.
- `--temporal-decay-gamma <f64>`: exponential temporal trust decay rate.
- `--structural-decay-beta <f64>`: exponential structural trust decay rate.
- `--max-out-edges <usize>`: per-source out-degree cap.
- `--output-root <path>`: output root containing timestamped run dirs.
- `--root-event-id <u64>`: reachability root used in expansion metrics.

## Library API Usage

```rust
use dsfb_dscd::{DscdConfig, DscdParams, run_dscd_simulation};
use std::path::PathBuf;

fn main() -> anyhow::Result<()> {
    let cfg = DscdConfig {
        params: DscdParams::demo(),
        root_event_id: 0,
        output_dir: PathBuf::from("output-dsfb-dscd/standalone-run"),
        scaling_ns: vec![5_000, 10_000, 20_000],
    };
    run_dscd_simulation(&cfg)?;
    Ok(())
}
```

## Significant Code Components

- `src/main.rs`: CLI surface, presets (`demo`/`performance`), argument parsing, run orchestration.
- `src/paper.rs`: canonical DSCD pipeline used for paper-grade outputs.
  - `DscdParams`: core locality/decay/sweep parameters.
  - `DscdConfig`: runtime configuration including output directory and scaling Ns.
  - `run_dscd_simulation`: deterministic end-to-end simulation + export.
  - `build_graph_for_tau`, `effective_trust`, `expansion_ratio`: threshold gating and reachability metrics.
- `src/integrations.rs`: DSFB + ADD integration, observer trust profiles, residual state, rewrite-rule labeling.
- `src/graph.rs`: legacy graph primitives and trust-gated edge insertion utilities.
- `src/sweep.rs`: legacy sweep/scaling workflows and provenance export helpers.
- `src/config.rs`: reusable config validation and timestamped output directory creation.
- `src/bin/dscd_threshold_scaling.rs`: standalone finite-size scaling binary entrypoint.

## Output Layout

Each run writes to a new timestamped folder:

`output-dsfb-dscd/<YYYYMMDD_HHMMSS>/`

Primary CSV artifacts:

- `threshold_curve_N_<N>.csv`: threshold curve samples (`tau`, `expansion_ratio`).
- `threshold_scaling_summary.csv`: per-`N` scaling summary (`num_events`, `tau_star`, `transition_width`, `max_derivative`).
- `finite_size_scaling.csv`: finite-size scaling table (includes transition width series).
- `graph_events.csv`: event nodes with trust and structural descriptors.
- `graph_edges.csv`: thresholded edge set at representative `tau*`.
- `edge_provenance_0.csv` and `edge_provenance.csv`: provenance-focused edge exports.
- `degree_distribution.csv`, `interval_sizes.csv`, `path_lengths.csv`: graph shape diagnostics.

## Determinism and Validation

- All DSCD pipelines in this crate are deterministic.
- Config validation rejects non-finite or invalid parameter ranges.
- Unit/integration tests in `src/paper.rs` and `src/graph.rs` exercise output generation and DAG invariants.

## Notebook Reproduction

Use:

- `crates/dsfb-dscd/dscd_sweep.ipynb`
- `crates/dsfb-dscd/dsfb_dscd_results_replay.ipynb`
- `crates/dsfb-dscd/notebooks/dscd_plots.ipynb`

All main paper/replay figures are regenerated from DSCD CSV outputs.

## Citation

- de Beer, R. (2026). Deterministic Structural Causal Dynamics (DSCD): Trust-Gated Emergence of Certifiable Causal Graphs for Safety-Critical Aerospace Autonomy (v1.0). Zenodo. https://doi.org/10.5281/zenodo.18867217