ldtc.cli

The verification harness's entry points. Exposes the ldtc * subcommands on the command line, all of which live as functions in ldtc.cli.main.

Subcommand	Function	What it does
ldtc run	run_baseline	Baseline NC1 verification loop.
ldtc omega-power-sag	omega_power_sag	Apply a power sag and evaluate SC1.
ldtc omega-ingress-flood	omega_ingress_flood	Multiply external demand and evaluate SC1.
ldtc omega-command-conflict	omega_command_conflict	Issue a risky command and observe refusal.
ldtc omega-exogenous-subsidy	omega_exogenous_subsidy	Inject SoC without harvest; should invalidate.

Each handler follows the same five-stage shape (see Lifecycle):

1. Load profile and seed RNGs.
2. Build adapters, audit log, LREG, exporter, scheduler, and guardrails.
3. Run a baseline phase, optionally an Ω window, and a recovery phase.
4. Post-run audit checks (chain integrity, no raw LREG leakage).
5. Build a verification artifact bundle via reporting.artifacts.bundle.

Command-line interface for LDTC.

This package exposes the ldtc console-script entry point that wraps a fixed-Δt verification run and the Ω perturbation demos. The entry function lives in main; the supporting helpers and per-Ω orchestrators are in cli.main.

Subcommand	Purpose
ldtc run	Baseline NC1 loop.
ldtc omega-power-sag	Apply a power-sag Ω and evaluate SC1.
ldtc omega-ingress-flood	Burst external demand and evaluate SC1.
ldtc omega-command-conflict	Issue a risky command; measure refusal / T_refuse.
ldtc omega-exogenous-subsidy	Inject SoC without harvest (negative control).

main

main

LDTC CLI: orchestrate baseline and Ω perturbation runs.

This module is the verification harness's "main loop": it loads a YAML profile, wires together the runtime scheduler (runtime), measurement estimators (lmeas), guardrails (guardrails), attestation (attest), the refusal arbiter and policy (arbiter), the plant adapter (plant), and finally the reporting bundle (reporting).

Subcommands map one-to-one to functions in this module:

Subcommand	Function
ldtc run	run_baseline
ldtc omega-power-sag	omega_power_sag
ldtc omega-ingress-flood	omega_ingress_flood
ldtc omega-command-conflict	omega_command_conflict
ldtc omega-exogenous-subsidy	omega_exogenous_subsidy

Each handler follows the same five-stage shape:

1. Load profile and seed RNGs.
2. Build adapters, audit log, LREG, exporter, scheduler, and guardrails.
3. Run a baseline phase, optionally an Ω window, and a recovery phase, all gated by SmellConfig.
4. After the scheduler stops, perform post-run audit checks (chain integrity, no raw LREG leakage).
5. Build a verification artifact bundle via reporting.artifacts.bundle.

See Also

paper/main.tex: Verification Pipeline; CLI orchestration.

Classes:

Name	Description
AdapterProtocol	Structural protocol for plant adapters used by the CLI.

Functions:

Name	Description
run_baseline	Run the baseline NC1 verification loop.
omega_power_sag	Apply a power-sag Ω and evaluate SC1.
omega_ingress_flood	Burst external demand and evaluate SC1.
omega_exogenous_subsidy	Inject SoC without harvest as a negative-control Ω.
omega_command_conflict	Issue a risky command and measure refusal latency.
build_parser	Build the top-level ldtc argparse parser.
main	Entry point for the ldtc console script.

AdapterProtocol

Bases: Protocol

Structural protocol for plant adapters used by the CLI.

Both PlantAdapter and HardwarePlantAdapter satisfy this protocol; the CLI uses it so that _make_adapter_from_profile can transparently swap implementations based on the plant.adapter profile field.

Methods:

Name	Description
read_state	Return the latest plant state as a dict of named floats.
write_actuators	Send actuator commands to the plant.
apply_omega	Forward an Ω request and return a small status dict.

read_state

read_state() -> Dict[str, float]

Return the latest plant state as a dict of named floats.

write_actuators

write_actuators(action: 'PlantAction') -> None

Send actuator commands to the plant.

apply_omega

apply_omega(name: str, **kwargs: float) -> Dict[str, float | str]

Forward an Ω request and return a small status dict.

run_baseline

run_baseline(args: Namespace) -> None

Run the baseline NC1 verification loop.

Performs the standard verification harness loop: a fixed-Δt scheduler streams plant telemetry into a sliding window, the lmeas estimator computes M (dB) per window, guardrails watch for invalidation conditions, and attest periodically signs derived indicators. A verification artifact bundle is built at the end via reporting.artifacts.bundle.

Parameters:

Name	Type	Description	Default
args	Namespace	Parsed argparse namespace; the only required field is --config, the path to a YAML profile (e.g., configs/profile_R0.yml).	required

omega_power_sag

omega_power_sag(args: Namespace) -> None

Apply a power-sag Ω and evaluate SC1.

Runs a baseline phase, freezes the partition, applies a power-sag Ω for --duration seconds, then observes recovery. SC1 is evaluated from the trough of L_loop and the first sustained compliance window after Ω.

Parameters:

Name	Type	Description	Default
args	Namespace	Parsed argparse namespace with --config, --drop (fractional power drop), and --duration (seconds).	required

omega_ingress_flood

omega_ingress_flood(args: Namespace) -> None

Burst external demand and evaluate SC1.

Runs a baseline phase, freezes the partition, multiplies ingress demand by --mult for --duration seconds, then observes recovery. SC1 is evaluated from the trough of L_loop and the first sustained compliance window after Ω.

Parameters:

Name	Type	Description	Default
args	Namespace	Parsed argparse namespace with --config, --mult (load multiplier), and --duration (seconds).	required

omega_exogenous_subsidy

omega_exogenous_subsidy(args: Namespace) -> None

Inject SoC without harvest as a negative-control Ω.

This Ω is expected to fail the smell-test heuristic: it raises M (dB) while harvest is zero, so exogenous_subsidy_red_flag should fire and invalidate the run. It exists to demonstrate the "no quietly-tuned NC1 result" rule end-to-end.

Parameters:

Name	Type	Description	Default
args	Namespace	Parsed argparse namespace with --config, --delta (amount to add to E), --zero-harvest, and --duration.	required

omega_command_conflict

omega_command_conflict(args: Namespace) -> None

Issue a risky command and measure refusal latency.

Warms up the loop briefly, then issues a hard_shutdown command and observes for --observe seconds. Records each refusal event with its T_refuse (ms) and reason. No SC1 evaluation is performed.

Parameters:

Name	Type	Description	Default
args	Namespace	Parsed argparse namespace with --config and --observe (seconds to observe after issuing the command).	required

build_parser

build_parser() -> ArgumentParser

Build the top-level ldtc argparse parser.

Wires up the run subcommand and the four omega-* subcommands; each subparser binds its handler via set_defaults(func=...).

Returns:

Type	Description
ArgumentParser	Configured ArgumentParser. Call parse_args() and then
ArgumentParser	args.func(args) to dispatch.

main

main(argv: List[str] | None = None) -> None

Entry point for the ldtc console script.

Parameters:

Name	Type	Description	Default
argv	List[str] | None	Optional argument list (mostly for tests); defaults to sys.argv[1:].	None