Architecture

The repository is organized around the measurement and attestation path. Each subpackage has a single, narrow job, and the boundaries between them are deliberately strict (in particular: nothing upstream of ldtc.attest is allowed to read raw 𝓛 out of ldtc.guardrails.lreg).

Module map

Subpackage	Job	Headline symbols
runtime	Fixed-Δt scheduler and sliding-window buffer.	FixedScheduler, SlidingWindow
plant	Software plant (E, T, R, demand, io, H) plus a UDP / serial hardware adapter.	Plant, PlantAdapter, HardwarePlantAdapter
lmeas	"L" measurement: estimators, partitioning, diagnostics, metrics.	estimate_L, PartitionManager, greedy_suggest_C, m_db, sc1_evaluate
guardrails	Enclave-like LREG, hash-chained audit, smell tests, Δt governance.	LREG, AuditLog, DeltaTGuard, smelltests
arbiter	Refusal semantics and the homeostasis controller policy.	RefusalArbiter, ControllerPolicy
omega	Labeled Ω perturbations.	omega.power_sag, omega.ingress_flood, omega.command_conflict
attest	Device-signed indicators and exporter.	build_and_sign, IndicatorExporter
reporting	Paper-quality timeline plots, SC1 tables, and verification bundle.	render_paper_timeline, write_sc1_table, bundle
cli	Glue: subcommands run, omega-power-sag, etc.	run_baseline, omega_power_sag

Data flow per tick

                ┌──────────────────────────────────────────────────────┐
                │                  FixedScheduler  (Δt)                │
                └──────────────────────────────────────────────────────┘
                                          │
                                          ▼
            ┌─────────────────┐    state    ┌────────────────────┐
            │  PlantAdapter   │────────────▶│  ControllerPolicy  │
            │  (sw / hw)      │◀────────────│     + Refusal      │
            └─────────────────┘   action    └────────────────────┘
                     │
                     │ state'
                     ▼
            ┌─────────────────┐
            │  SlidingWindow  │
            └─────────────────┘
                     │ when full
                     ▼
            ┌─────────────────┐
            │   estimate_L    │──── LResult, CIs ──┐
            │ + diagnostics   │                    │
            └─────────────────┘                    │
                     │                             │
                     ▼                             ▼
            ┌─────────────────┐         ┌──────────────────┐
            │  PartitionMgr   │         │   smell tests    │
            │  greedy_regrow  │         │  ci_inflation,   │
            └─────────────────┘         │  partition flap, │
                     │                  │  Δt edits, etc.  │
                     │                  └──────────────────┘
                     │                              │
                     ▼                              ▼
            ┌──────────────────────────────────────────────┐
            │   LREG (write-only)   +   AuditLog (chain)   │
            └──────────────────────────────────────────────┘
                                          │
                                          ▼
                          ┌─────────────────────────────┐
                          │  IndicatorExporter (CBOR)   │
                          │   build_and_sign  (Ed25519) │
                          └─────────────────────────────┘
                                          │
                                          ▼
                          ┌─────────────────────────────┐
                          │   reporting.artifacts       │
                          │   timeline / table / mfst   │
                          └─────────────────────────────┘

The arrow from LREG to the exporter is intentionally narrow: only LREG.derive crosses that boundary, and what it returns is what build_and_sign turns into a CBOR payload. Raw 𝓛 never leaves.

Per-tick sequence

1. scheduler ticks at fixed Δt.
2. Controller reads state from plant.adapter, predicts risk via LREG.latest(), computes an action, writes actuators.
3. The window buffer ingests the next state vector.
4. When the window is full, estimate_L computes (𝓛_loop, 𝓛_ex) with bootstrapped CIs and m_db turns them into M (dB).
5. Smell tests run; raw 𝓛 is appended to LREG (write-only).
6. Audit events are appended (window_measured, optionally window_diagnostics, partition_flip, etc.).
7. Periodically (rate-limited), IndicatorExporter emits a device-signed payload (nc1, sc1, mq, counter, profile_id, audit_prev_hash, invalidated).
8. reporting reads the audit log to render figures, tables, and the manifest.

All raw 𝓛 stays inside the process-local LREG boundary; exported data is derived indicators only.

Paper crosswalk

The full per-section mapping lives in paper-to-code. A condensed summary:

• lmeas/estimators.py and lmeas/metrics.py: definitions of 𝓛, the dual estimators (linear / VAR-Granger-like and Kraskov k-NN MI), and M (dB). NC1 / SC1 evaluation maps to paper §4.1 (estimators, sampling window) and §4.2 / §4.3 (NC1 / SC1).
• lmeas/diagnostics.py: per-window stationarity (ADF / KPSS) and VAR N / T ratio diagnostics surfaced into the audit.
• lmeas/partition.py: deterministic C/Ex partitioning, hysteresis, anti-flap, and the freeze during Ω per §4.1 ("Deterministic C/Ex partitioning") and §4.6 Box 1a ("Partition stability").
• runtime/scheduler.py, runtime/windows.py, and guardrails/dt_guard.py: Δt enforcement and audited privileged edits per §4.1 and §4.5.
• guardrails/lreg.py, guardrails/audit.py, and guardrails/smelltests.py: the enclave-like LREG, hash-chained audit, and the smell-test battery per §4.5 and Box 1a.
• arbiter/refusal.py: the threat model, survival-bit / NMI refusal path, and T_refuse measurement per §6.2.1 and §7.6 Signature A.
• omega/power_sag.py, omega/ingress_flood.py, and omega/command_conflict.py: the Ω battery per §4.3 / §6.5 and §7.6.
• attest/indicators.py, attest/exporter.py, and attest/keys.py: device-signed derived indicators (NC1 bit, SC1 bit, Mq) and keying per §4.5 and Appendix A.
• reporting/timeline.py and reporting/tables.py: figure-style timelines and summary tables per Figure 1 and §6.5.
• cli/main.py: orchestrates baseline → Ω battery → attestation / export per Box 2 ("Engineer's recipe") and the Phase-III Verify flow.

Next steps

• Lifecycle: the same picture, but in time order for one CLI invocation.
• Mental model: the one-paragraph story of what NC1 / SC1 measure and how the harness keeps them honest.
• Indicators: exactly what leaves the box.
• Guardrails: how invalidation works.