ldtc.guardrails¶

Measurement and attestation guardrails. The pieces here are what make the harness's NC1 / SC1 results hard to silently misconfigure.

Module	Headline symbols	Use it for
`audit`	`AuditLog`	Append-only, hash-chained event journal. Every event in a run; every record carries `prev_hash = SHA256(prev_record)`.
`dt_guard`	`DeltaTGuard`, `DtGuardConfig`	Rate-limited, audited `Δt` changes.
`lreg`	`LREG`, `LEntry`	Write-only enclave that holds raw `𝓛`. Only `derive()` and `latest()` exit.
`smelltests`	`SmellConfig`, `invalid_by_ci`, `audit_chain_broken`, `audit_contains_raw_lreg_values`, `exogenous_subsidy_red_flag`	Per-window invalidation heuristics and post-run integrity checks.

Guardrails and governance for LDTC runs.

Components in this subpackage protect the integrity of an LDTC run by limiting how the harness can be reconfigured at runtime, what can leave the measurement enclave, and which conditions silently invalidate a result:

audit is the append-only, hash-chained JSONL audit log.
dt_guard provides privileged Δt governance with rate limits and audit.
lreg is the enclave-like register for raw 𝓛 and CIs; only derived indicators are exported.
smelltests runs measurement-fragility and anti-gaming checks (CI inflation, partition flips, jitter, exogenous subsidy, audit-chain integrity).

Together these enforce LDTC's "no quietly-tuned NC1/SC1 result" rule: any change to Δt, any partition flip during Ω, any CI blow-up, or any leakage of raw 𝓛 either gets rejected or records a run_invalidated event in the audit log.

audit¶

audit ¶

Append-only audit log.

Hash-chained JSONL records with monotonic counters used to attest measurement and policy events. The audit chain provides tamper-evident provenance for an LDTC run: every record links to the previous record's SHA-256, so any post-hoc edit invalidates the chain from that point forward.

See Also

paper/main.tex: Methods: Measurement and Attestation; Audit chain.

Classes:

Name	Description
`AuditRecord`	Serialized audit record structure.
`AuditLog`	Append-only, hash-chained audit log in JSONL format.

AuditRecord `dataclass` ¶

AuditRecord(counter: int, ts: float, event: str, details: Dict[str, Any], prev_hash: str, hash: str)

Serialized audit record structure.

Attributes:

Name	Type	Description
`counter`	`int`	Monotonic counter for this record. Starts at 1 and strictly increases.
`ts`	`float`	UNIX timestamp (float seconds, from `time.time()`).
`event`	`str`	Event name (free-form string used for filtering and replay).
`details`	`Dict[str, Any]`	Arbitrary JSON-serializable details. Policy filters block raw LREG keys (`L_loop`, `L_ex`, `ci_loop`, `ci_ex`) from leaking through this channel.
`prev_hash`	`str`	Hash of the previous record (`"GENESIS"` for the first).
`hash`	`str`	SHA-256 hash of this record's canonical JSON.

AuditLog ¶

AuditLog(path: str)

Append-only, hash-chained audit log in JSONL format.

Ensures monotonic counters and a verifiable hash chain across records. Used throughout the CLI to record measurement, governance, and policy events. Writers are serialized through an internal lock so multiple threads can append safely.

Parameters:

Name	Type	Description	Default
`path`	`str`	Filesystem path to the JSONL audit file. The parent directory is created if it does not exist.	required

Initialize an audit log rooted at path.

Parameters:

Name	Type	Description	Default
`path`	`str`	Filesystem path to the JSONL audit file. The parent directory is created if it does not exist.	required

Methods:

Name	Description
`append`	Append an event to the audit log.

Attributes:

Name	Type	Description
`last_hash`	`str`	Hex-encoded SHA-256 of the most recently written record.
`counter`	`int`	Monotonic counter of the last record written (0 before any writes).

last_hash `property` ¶

last_hash: str

Hex-encoded SHA-256 of the most recently written record.

Equals "GENESIS" until the first record is written. Use this to anchor downstream artifacts (e.g., signed indicator manifests) to a specific run.

counter `property` ¶

counter: int

Monotonic counter of the last record written (0 before any writes).

append ¶

append(event: str, details: Optional[Dict[str, Any]] = None) -> AuditRecord

Append an event to the audit log.

Parameters:

Name	Type	Description	Default
`event`	`str`	Event name (free-form, but conventionally `snake_case`, e.g., `"scheduler_started"`).	required
`details`	`Optional[Dict[str, Any]]`	Optional dict of additional fields. Raw LREG keys (`L_loop`, `L_ex`, `ci_loop`, `ci_ex`) are blocked by policy and will raise `ValueError`.	`None`

Returns:

Type	Description
`AuditRecord`	The `AuditRecord` that
`AuditRecord`	was written.

Raises:

Type	Description
`ValueError`	If `details` contains any raw LREG key.

dt_guard¶

dt_guard ¶

Δt governance.

A privileged, rate-limited interface for mutating the scheduler's Δt. Records every accepted change in the audit log and invalidates the run when policy limits are exceeded. The intent is to prevent operators from "tuning" away an SC1 violation by changing the sample rate mid-run.

See Also

paper/main.tex: Smell-tests and invalidation; Δt governance.

Classes:

Name	Description
`DtGuardConfig`	Configuration for `Δt` governance constraints.
`DeltaTGuard`	Privileged `Δt` governance wrapper.

DtGuardConfig `dataclass` ¶

DtGuardConfig(max_changes_per_hour: int = 3, min_seconds_between_changes: float = 1.0)

Configuration for Δt governance constraints.

Attributes:

Name	Type	Description
`max_changes_per_hour`	`int`	Maximum permitted changes in any rolling one-hour window.
`min_seconds_between_changes`	`float`	Minimum wall-clock spacing between consecutive edits, in seconds.

DeltaTGuard ¶

DeltaTGuard(audit: AuditLog, cfg: Optional[DtGuardConfig] = None)

Privileged Δt governance wrapper.

The single, rate-limited pathway to update the scheduler's Δt. Every accepted change is recorded in the audit log; every refused change invalidates the run by appending a run_invalidated event with the human-readable reason.

Parameters:

Name	Type	Description	Default
`audit`	`AuditLog`	`AuditLog` instance used for recording events.	required
`cfg`	`Optional[DtGuardConfig]`	Optional configuration for rate limits. Defaults to a sensible policy of 3 changes / hour with at least 1 s between changes.	`None`

Initialize the guard. See class docstring for argument details.

Methods:

Name	Description
`can_change`	Check whether a `Δt` change is currently permissible.
`change_dt`	Attempt to change `Δt`; audit and invalidate on violations.

Attributes:

Name	Type	Description
`invalidated`	`bool`	`True` once a `Δt` governance violation has invalidated the run.

invalidated `property` ¶

invalidated: bool

True once a Δt governance violation has invalidated the run.

can_change ¶

can_change(now: Optional[float] = None) -> bool

Check whether a Δt change is currently permissible.

Parameters:

Name	Type	Description	Default
`now`	`Optional[float]`	Optional timestamp override (unix seconds) for rate-limit accounting. Tests use this to simulate the passage of time.	`None`

Returns:

Type	Description
`bool`	`True` if within both hourly and spacing limits; otherwise
`bool`	`False`.

change_dt ¶

change_dt(scheduler: Any, new_dt: float, policy_digest: Optional[str] = None) -> bool

Attempt to change Δt; audit and invalidate on violations.

Parameters:

Name	Type	Description	Default
`scheduler`	`Any`	Object exposing `set_dt(new_dt) -> old_dt`, typically a `FixedScheduler`.	required
`new_dt`	`float`	Desired new `Δt` in seconds.	required
`policy_digest`	`Optional[str]`	Optional identifier of the policy that authorized the change. Recorded in the audit details.	`None`

Returns:

Type	Description
`bool`	`True` if the change was committed; `False` if it was
`bool`	refused (the run is invalidated in that case).

lreg¶

lreg ¶

LREG: enclave-like register for raw 𝓛 and CI bounds.

LREG ("loop register") holds the per-window raw loop / exchange influence values and their CIs in memory. By design, raw entries are write-only from outside the package: external callers go through derive, which returns only indicator-grade summaries (nc1, M_db, counters, invalidation flag). This honors LDTC's no-raw-LREG export policy: the only thing that ever leaves the enclave is the derived, device-signed indicator.

See Also

paper/main.tex: Methods: Measurement and Attestation; Export policy.

Classes:

Name	Description
`LEntry`	Raw LREG entry for a single window.
`LREG`	Enclave-like store for raw `𝓛` and CI bounds with derived indicators.

LEntry `dataclass` ¶

LEntry(L_loop: float, L_ex: float, ci_loop: Tuple[float, float], ci_ex: Tuple[float, float], M_db: float, nc1_pass: bool)

Raw LREG entry for a single window.

Attributes:

Name	Type	Description
`L_loop`	`float`	Loop influence.
`L_ex`	`float`	Exchange influence.
`ci_loop`	`Tuple[float, float]`	95% confidence interval for `L_loop` as `(lo, hi)`.
`ci_ex`	`Tuple[float, float]`	95% confidence interval for `L_ex` as `(lo, hi)`.
`M_db`	`float`	Decibel loop-dominance for this window.
`nc1_pass`	`bool`	Whether NC1 was met in this window.

LREG ¶

LREG()

Enclave-like store for raw 𝓛 and CI bounds with derived indicators.

Raw entries are write-only from outside the package; external callers should go through derive to access only the indicator-grade summary. Maintaining this boundary is what gives LDTC's exported indicators their integrity story.

Initialize an empty LREG with a fresh counter and lock.

Methods:

Name	Description
`write`	Append a raw entry and return its sequence index.
`invalidate`	Mark the run invalidated with a short reason code.
`latest`	Return the most recently written entry, or `None` if empty.
`derive`	Return derived indicators suitable for export.

Attributes:

Name	Type	Description
`invalidated`	`bool`	`True` once any guardrail has invalidated this run.
`reason`	`Optional[str]`	Reason code for the most recent invalidation, or `None`.

invalidated `property` ¶

invalidated: bool

True once any guardrail has invalidated this run.

reason `property` ¶

reason: Optional[str]

Reason code for the most recent invalidation, or None.

write ¶

write(entry: LEntry) -> int

Append a raw entry and return its sequence index.

Parameters:

Name	Type	Description	Default
`entry`	`LEntry`	Raw `LEntry` for the current window.	required

Returns:

Type	Description
`int`	Zero-based sequence index assigned to the entry.

invalidate ¶

invalidate(reason: str) -> None

Mark the run invalidated with a short reason code.

Subsequent calls to derive will report invalidated=True and force nc1=False.

Parameters:

Name	Type	Description	Default
`reason`	`str`	Short, machine-readable reason (e.g., `"ci_inflation"`).	required

latest ¶

latest() -> Optional[LEntry]

Return the most recently written entry, or None if empty.

derive ¶

derive() -> Dict[str, float | int | bool]

Return derived indicators suitable for export.

This is the only read API intended for external callers. The returned dict never contains raw L_loop / L_ex / CI fields, and nc1 is forced False when the run has been invalidated.

Returns:

Type	Description
`Dict[str, float \| int \| bool]`	Dict with at minimum:
`Dict[str, float \| int \| bool]`	`nc1`: Boolean NC1 status after invalidation check.
`Dict[str, float \| int \| bool]`	`M_db`: Decibel loop-dominance of the latest window.
`Dict[str, float \| int \| bool]`	`counter`: Number of windows written so far.
`Dict[str, float \| int \| bool]`	`invalidated`: Whether the run has been invalidated.

smelltests¶

smelltests ¶

Smell-tests and invalidation heuristics.

A small library of "is this run still trustworthy?" checks that the CLI runs on every window. Includes:

CI width guards (absolute and inflation-vs-baseline).
Partition flip-rate checks (and forbidding flips during Ω).
Δt jitter thresholds.
Exogenous-subsidy red flags (M rising while I/O is high; SoC rising with no harvest).
Audit-chain integrity checks (counter / hash / timestamp continuity).

If any guard returns True, the CLI invalidates the run by appending a run_invalidated audit event. This is the mechanism that protects NC1 / SC1 results from being silently undermined by misconfigured measurement.

See Also

paper/main.tex: Smell-tests and invalidation.

Classes:

Name	Description
`SmellConfig`	Configuration thresholds for smell-tests and guards.

Functions:

Name	Description
`ci_halfwidth`	Compute the half-width of a confidence interval.
`invalid_by_ci`	Check absolute CI half-width limits.
`flips_per_hour`	Compute flip rate per hour.
`invalid_by_partition_flips`	Check whether the partition flip rate exceeds the configured limit.
`invalid_flip_during_omega`	Check for partition changes during a frozen `Ω` window.
`invalid_by_ci_history`	Evaluate CI health over a look-back window.
`audit_contains_raw_lreg_values`	Detect raw LREG fields in audit records.
`exogenous_subsidy_red_flag`	Heuristics for detecting exogenous-subsidy conditions.
`audit_chain_broken`	Validate audit chain counters, hashes, and timestamps.

SmellConfig `dataclass` ¶

SmellConfig(max_dt_changes_per_hour: int = 3, max_partition_flips_per_hour: int = 2, max_ci_halfwidth: float = 0.3, forbid_partition_flip_during_omega: bool = True, ci_lookback_windows: int = 5, ci_inflate_factor: float = 2.0, jitter_p95_rel_max: float = 0.25, io_suspicious_threshold: float = 0.8, min_M_rise_db: float = 0.5, M_rise_lookback: int = 3, min_harvest_for_soc_gain: float = 0.001)

Configuration thresholds for smell-tests and guards.

Attributes:

Name	Type	Description
`max_dt_changes_per_hour`	`int`	`Δt` edits allowed per rolling hour.
`max_partition_flips_per_hour`	`int`	Partition flips allowed per rolling hour.
`max_ci_halfwidth`	`float`	Absolute CI half-width limit on `L_loop` and `L_ex` (NaN bounds always exceed this).
`forbid_partition_flip_during_omega`	`bool`	When `True`, freeze the partition during `Ω` windows so SC1 sees a fixed `(C, Ex)`.
`ci_lookback_windows`	`int`	Number of windows used for CI history checks.
`ci_inflate_factor`	`float`	Maximum allowed inflation in median CI half-width vs the baseline median.
`jitter_p95_rel_max`	`float`	Maximum allowed `p95(\|jitter\|) / dt` before invalidation.
`io_suspicious_threshold`	`float`	I/O fraction at which the exogenous-subsidy heuristic considers the channel suspicious.
`min_M_rise_db`	`float`	Minimum `ΔM` (dB) to flag as a subsidy.
`M_rise_lookback`	`int`	Look-back windows for the subsidy check.
`min_harvest_for_soc_gain`	`float`	Minimum harvest considered non-zero for SoC-gain detection.

ci_halfwidth ¶

ci_halfwidth(ci: Tuple[float, float]) -> float

Compute the half-width of a confidence interval.

Parameters:

Name	Type	Description	Default
`ci`	`Tuple[float, float]`	Tuple of `(lo, hi)` bounds.	required

Returns:

Type	Description
`float`	Half-width value; returns a very large sentinel (`1e9`) if any
`float`	input is `NaN` or `None` so downstream guards trip predictably.

invalid_by_ci ¶

invalid_by_ci(ci_loop: Tuple[float, float], ci_ex: Tuple[float, float], cfg: SmellConfig) -> bool

Check absolute CI half-width limits.

Parameters:

Name	Type	Description	Default
`ci_loop`	`Tuple[float, float]`	CI for loop influence.	required
`ci_ex`	`Tuple[float, float]`	CI for exchange influence.	required
`cfg`	`SmellConfig`	Threshold configuration.	required

Returns:

Type	Description
`bool`	`True` if either half-width exceeds `cfg.max_ci_halfwidth`.

flips_per_hour ¶

flips_per_hour(flips: int, elapsed_sec: float) -> float

Compute flip rate per hour.

Parameters:

Name	Type	Description	Default
`flips`	`int`	Number of flips observed.	required
`elapsed_sec`	`float`	Elapsed time in seconds.	required

Returns:

Type	Description
`float`	Flip rate in events per hour. Returns `inf` when `elapsed_sec`
`float`	is non-positive but `flips > 0` (a degenerate but conservative
`float`	signal).

invalid_by_partition_flips ¶

invalid_by_partition_flips(flips: int, elapsed_sec: float, cfg: SmellConfig) -> bool

Check whether the partition flip rate exceeds the configured limit.

Parameters:

Name	Type	Description	Default
`flips`	`int`	Number of flips observed.	required
`elapsed_sec`	`float`	Elapsed time in seconds.	required
`cfg`	`SmellConfig`	Threshold configuration.	required

Returns:

Type	Description
`bool`	`True` if flips per hour exceeds
`bool`	`cfg.max_partition_flips_per_hour`.

invalid_flip_during_omega ¶

invalid_flip_during_omega(flips_before: int, flips_after: int, cfg: SmellConfig) -> bool

Check for partition changes during a frozen Ω window.

Parameters:

Name	Type	Description	Default
`flips_before`	`int`	Flip count before `Ω`.	required
`flips_after`	`int`	Flip count after `Ω`.	required
`cfg`	`SmellConfig`	Threshold configuration.	required

Returns:

Type	Description
`bool`	`True` if any flip occurred during `Ω` and flips are forbidden
`bool`	by `cfg.forbid_partition_flip_during_omega`.

invalid_by_ci_history ¶

invalid_by_ci_history(ci_loop_hist: Sequence[Tuple[float, float]], ci_ex_hist: Sequence[Tuple[float, float]], cfg: SmellConfig, baseline_medians: Optional[Tuple[float, float]] = None) -> bool

Evaluate CI health over a look-back window.

Considered invalid when either:

The median half-width over the last cfg.ci_lookback_windows windows exceeds cfg.max_ci_halfwidth, or
baseline_medians are provided and either median is inflated by at least cfg.ci_inflate_factor relative to baseline.

Returns False (defensively) on any internal error so the harness keeps running rather than spuriously invalidating a run on a bug.

Parameters:

Name	Type	Description	Default
`ci_loop_hist`	`Sequence[Tuple[float, float]]`	Sequence of `(lo, hi)` CI tuples for `L_loop`.	required
`ci_ex_hist`	`Sequence[Tuple[float, float]]`	Sequence of `(lo, hi)` CI tuples for `L_ex`.	required
`cfg`	`SmellConfig`	Threshold configuration.	required
`baseline_medians`	`Optional[Tuple[float, float]]`	Optional `(median_loop, median_ex)` baseline half-widths used for inflation comparison.	`None`

Returns:

Type	Description
`bool`	`True` if the CI history fails either check.

audit_contains_raw_lreg_values ¶

audit_contains_raw_lreg_values(audit_path: str) -> bool

Detect raw LREG fields in audit records.

A defense-in-depth scan for L_loop, L_ex, ci_loop, ci_ex in any audit record's details. The audit log writer already blocks these keys; this function exists so post-hoc verification can catch a regression.

Parameters:

Name	Type	Description	Default
`audit_path`	`str`	Path to the audit JSONL file.	required

Returns:

Type	Description
`bool`	`True` if any record's `details` contains raw LREG keys.
`bool`	Returns `False` if the file is clean, missing, or fails to
`bool`	parse (the function is intentionally lenient to avoid false
`bool`	positives from unrelated bugs).

exogenous_subsidy_red_flag ¶

exogenous_subsidy_red_flag(Ms_db: Sequence[float], ios: Sequence[float], Es: Sequence[float], Hs: Sequence[float], cfg: SmellConfig) -> bool

Heuristics for detecting exogenous-subsidy conditions.

Flags when M is rising while I/O is both high and increasing, or when SoC is rising while harvest is approximately zero over a look-back window. Both situations suggest the apparent loop dominance comes from outside the system rather than from a real closed-loop dynamic.

Parameters:

Name	Type	Description	Default
`Ms_db`	`Sequence[float]`	Recent `M (dB)` values.	required
`ios`	`Sequence[float]`	Recent I/O fraction values.	required
`Es`	`Sequence[float]`	Recent state-of-charge values.	required
`Hs`	`Sequence[float]`	Recent harvest values.	required
`cfg`	`SmellConfig`	Threshold configuration.	required

Returns:

Type	Description
`bool`	`True` if either heuristic fires. Returns `False` defensively on
`bool`	any internal error.

audit_chain_broken ¶

audit_chain_broken(audit_path: str) -> bool

Validate audit chain counters, hashes, and timestamps.

Walks the JSONL file and verifies that:

counter strictly increases by 1 per record.
Each prev_hash matches the previous record's hash (with "GENESIS" as the seed).
ts is non-decreasing.

Parameters:

Name	Type	Description	Default
`audit_path`	`str`	Path to the audit JSONL file.	required

Returns:

Type	Description
`bool`	`True` if the chain is broken (or the file cannot be opened or
`bool`	parsed). `False` only when the chain is fully verified.

ldtc.guardrails¶

audit¶

audit ¶

AuditRecord dataclass ¶

AuditLog ¶

last_hash property ¶

counter property ¶

append ¶

dt_guard¶

dt_guard ¶

DtGuardConfig dataclass ¶

DeltaTGuard ¶

invalidated property ¶

can_change ¶

change_dt ¶

lreg¶

lreg ¶

LEntry dataclass ¶

LREG ¶

invalidated property ¶

reason property ¶

write ¶

invalidate ¶

latest ¶

derive ¶

smelltests¶

smelltests ¶

SmellConfig dataclass ¶

ci_halfwidth ¶

invalid_by_ci ¶

flips_per_hour ¶

invalid_by_partition_flips ¶

invalid_flip_during_omega ¶

invalid_by_ci_history ¶

audit_contains_raw_lreg_values ¶

exogenous_subsidy_red_flag ¶

audit_chain_broken ¶

AuditRecord `dataclass` ¶

last_hash `property` ¶

counter `property` ¶

DtGuardConfig `dataclass` ¶

invalidated `property` ¶

LEntry `dataclass` ¶

invalidated `property` ¶

reason `property` ¶

SmellConfig `dataclass` ¶