ldtc.guardrails¶
Guardrails: Append-only audit log.
Hash-chained JSONL records with monotonic counters used to attest measurement and policy events, providing tamper-evident provenance for runs.
See Also
paper/main.tex — Methods: Measurement & Attestation; Audit chain.
AuditLog
¶
Append-only, hash-chained audit log (JSONL).
Ensures monotonic counters and a verifiable hash chain across records. Used throughout the CLI to record measurement and governance events.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
path
|
str
|
Filesystem path to the JSONL audit file. |
required |
counter
property
¶
Return the last written counter value.
Returns:
| Type | Description |
|---|---|
int
|
Monotonic counter for the last record written. |
last_hash
property
¶
Return the current hash head of the audit chain.
Returns:
| Type | Description |
|---|---|
str
|
Hex-encoded hash string. |
append(event, details=None)
¶
Append an event to the audit log.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
event
|
str
|
Event name. |
required |
details
|
Optional[Dict[str, Any]]
|
Optional dict of additional fields; raw LREG keys are blocked by policy and will raise an error. |
None
|
Returns:
| Name | Type | Description |
|---|---|---|
The |
AuditRecord
|
class: |
AuditRecord
dataclass
¶
Serialized audit record structure.
Attributes:
| Name | Type | Description |
|---|---|---|
counter |
int
|
Monotonic counter for this record. |
ts |
float
|
UNIX timestamp (float seconds). |
event |
str
|
Event name. |
details |
Dict[str, Any]
|
Arbitrary JSON-serializable details (policy filters applied). |
prev_hash |
str
|
Hash of the previous record ("GENESIS" for the first). |
hash |
str
|
SHA-256 hash of this record's canonical JSON. |
Guardrails: Δt governance.
Privileged, rate-limited interface to mutate scheduler Δt with audit logging and run invalidation on policy violations.
See Also
paper/main.tex — Smell-tests & invalidation; Δt governance.
DeltaTGuard
¶
Privileged Δt governance wrapper.
Single, rate-limited pathway to update scheduler Δt with audit records and invalidation signaling when limits are exceeded.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
audit
|
AuditLog
|
AuditLog instance used for recording events. |
required |
cfg
|
Optional[DtGuardConfig]
|
Optional configuration for rate limits. |
None
|
invalidated
property
¶
Whether a Δt governance violation invalidated the run.
Returns:
| Type | Description |
|---|---|
bool
|
True if invalidated; otherwise False. |
can_change(now=None)
¶
Check whether a Δt change is permissible.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
now
|
Optional[float]
|
Optional timestamp override for rate-limit accounting. |
None
|
Returns:
| Type | Description |
|---|---|
bool
|
True if within hourly and spacing limits; otherwise False. |
change_dt(scheduler, new_dt, policy_digest=None)
¶
Attempt to change Δt; audit and invalidate on violations.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
scheduler
|
Any
|
Object exposing |
required |
new_dt
|
float
|
Desired new Δt in seconds. |
required |
policy_digest
|
Optional[str]
|
Optional identifier of the policy authorizing the change. |
None
|
Returns:
| Type | Description |
|---|---|
bool
|
True if the change was committed; False if refused and the run was |
bool
|
invalidated by audit. |
DtGuardConfig
dataclass
¶
Configuration for Δt governance constraints.
Attributes:
| Name | Type | Description |
|---|---|---|
max_changes_per_hour |
int
|
Maximum permitted changes in any rolling hour. |
min_seconds_between_changes |
float
|
Minimum spacing between edits. |
Guardrails: LREG enclave.
In-memory enclave-like register for raw loop/exchange values and CIs, exposing only derived indicators externally to honor the no-raw-LREG policy.
See Also
paper/main.tex — Methods: Measurement & Attestation; Export policy.
LEntry
dataclass
¶
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]
|
Confidence interval for |
ci_ex |
Tuple[float, float]
|
Confidence interval for |
M_db |
float
|
Decibel loop-dominance. |
nc1_pass |
bool
|
Whether NC1 was met in this window. |
LREG
¶
Enclave-like store for raw L and CI with derived indicators.
Raw entries are write-only; external callers should use :meth:derive to
access device-signed-style indicators only.
invalidated
property
¶
Whether the run has been invalidated by a guardrail.
Returns:
| Type | Description |
|---|---|
bool
|
True if invalidated; otherwise False. |
reason
property
¶
Reason code for invalidation, if any.
Returns:
| Type | Description |
|---|---|
Optional[str]
|
Reason string or None. |
derive()
¶
Return derived indicators suitable for export.
Returns:
| Type | Description |
|---|---|
Dict[str, float | int | bool]
|
Dict containing at minimum: |
Dict[str, float | int | bool]
|
|
Dict[str, float | int | bool]
|
|
Dict[str, float | int | bool]
|
|
Dict[str, float | int | bool]
|
|
Guardrails: Smell-tests and invalidation heuristics.
Includes CI width guards, partition flip-rate checks, Δt jitter thresholds, exogenous subsidy red flags, and audit-chain integrity checks. Used by the CLI to determine when to invalidate a run by assay.
See Also
paper/main.tex — Smell-tests & invalidation.
SmellConfig
dataclass
¶
Configuration thresholds for smell-tests and guards.
Attributes:
| Name | Type | Description |
|---|---|---|
max_dt_changes_per_hour |
int
|
Δt edits allowed per hour. |
max_partition_flips_per_hour |
int
|
Partition flips allowed per hour. |
max_ci_halfwidth |
float
|
Absolute CI half-width limit. |
forbid_partition_flip_during_omega |
bool
|
Freeze partition during Ω. |
ci_lookback_windows |
int
|
Number of windows used for CI history checks. |
ci_inflate_factor |
float
|
Relative inflation vs baseline median allowed. |
jitter_p95_rel_max |
float
|
Max p95(|jitter|)/dt before invalidation. |
io_suspicious_threshold |
float
|
I/O threshold considered suspicious. |
min_M_rise_db |
float
|
Minimum M rise to flag subsidy. |
M_rise_lookback |
int
|
Look-back windows for subsidy check. |
min_harvest_for_soc_gain |
float
|
Minimum H considered non-zero for SoC gains. |
audit_chain_broken(audit_path)
¶
Validate audit chain counters, hashes, and timestamps.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
audit_path
|
str
|
Path to audit JSONL file. |
required |
Returns:
| Type | Description |
|---|---|
bool
|
True if the chain is broken; otherwise False. |
audit_contains_raw_lreg_values(audit_path)
¶
Detect raw LREG fields in audit records.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
audit_path
|
str
|
Path to audit JSONL file. |
required |
Returns:
| Type | Description |
|---|---|
bool
|
True if any record details contain raw LREG keys. |
ci_halfwidth(ci)
¶
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; very large if inputs are NaN/None. |
exogenous_subsidy_red_flag(Ms_db, ios, Es, Hs, cfg)
¶
Heuristics for detecting exogenous subsidy conditions.
Flags when M is rising while I/O is high and increasing, or when SoC is rising while harvest is ~0 over a look-back window.
flips_per_hour(flips, elapsed_sec)
¶
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. |
invalid_by_ci(ci_loop, ci_ex, cfg)
¶
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 the configured maximum. |
invalid_by_ci_history(ci_loop_hist, ci_ex_hist, cfg, baseline_medians=None)
¶
Evaluate CI health over a look-back window.
Invalid if either median half-width over the last N windows exceeds the absolute limit, or if baseline medians are provided and inflated by the configured factor.
invalid_by_partition_flips(flips, elapsed_sec, cfg)
¶
Check whether 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/hour exceeds |
invalid_flip_during_omega(flips_before, flips_after, cfg)
¶
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. |