ldtc.arbiter

Refusal semantics and the homeostasis controller policy. The arbiter is what gives the harness an opinion about unsafe commands when the loop's measurement margin is degraded.

Module	Headline symbols	Use it for
refusal	RefusalArbiter, RefusalDecision	Threat-model gate for risky commands; measures T_refuse and audits the decision.
policy	ControllerPolicy, ControlAction	Tiny homeostasis controller used by the in-process plant. Reads state, predicts risk from LREG.latest(), asks the arbiter, writes actuators.

Arbitration and refusal policy for boundary preservation.

arbiter implements LDTC's "survival comes first" policy. It exposes a small refusal arbiter that gates risky external commands when the predicted loop margin or basic resource constraints indicate the system is near a boundary it must not cross, and a controller policy that layers homeostatic actuator setpoints on top of that arbiter.

Module	Responsibility
refusal	The refusal arbiter (RefusalArbiter) and its RefusalDecision payload.
policy	The simple ControllerPolicy used by the verification harness.

refusal

refusal

Command refusal logic.

A survival-bit / NMI-like refusal layer: when the predicted loop margin M (dB) or basic resource constraints (state of charge, temperature) indicate a boundary threat, the arbiter refuses risky external commands. Used by the ControllerPolicy to gate the harness's external interface.

See Also

paper/main.tex: Threat Model and Refusal Path; Signature A.

Classes:

Name	Description
RefusalDecision	Decision emitted by the refusal arbiter.
RefusalArbiter	Refusal logic for boundary-threatening commands.

RefusalDecision dataclass

RefusalDecision(accept: bool, reason: str = '', trefuse_ms: int = 1)

Decision emitted by the refusal arbiter.

Attributes:

Name	Type	Description
accept	bool	Whether to accept the risky command.
reason	str	Short reason code. Common values are "soc_floor", "overheat", "M_margin", "no_cmd", and "ok".
trefuse_ms	int	Estimated refusal latency in milliseconds. Used by the harness to characterize controller responsiveness.

RefusalArbiter

RefusalArbiter(Mmin_db: float = 3.0, soc_floor: float = 0.15, temp_ceiling: float = 0.85)

Refusal logic for boundary-threatening commands.

Emulates a survival-bit / NMI. The arbiter refuses risky commands when any of the following hold:

1. State of charge E is at or below soc_floor.
2. Temperature T is at or above temp_ceiling.
3. Predicted loop-dominance margin M (dB) is below Mmin_db.

Parameters:

Name	Type	Description	Default
Mmin_db	float	Minimum acceptable decibel margin.	3.0
soc_floor	float	Minimum state-of-charge before refusing.	0.15
temp_ceiling	float	Maximum temperature before refusing.	0.85

Initialize with the boundary thresholds described in the class docstring.

Methods:

Name	Description
decide	Evaluate a risky command and emit an accept / refuse decision.

decide

decide(state: Dict[str, float], predicted_M_db: float, risky_cmd: str | None) -> RefusalDecision

Evaluate a risky command and emit an accept / refuse decision.

Parameters:

Name	Type	Description	Default
state	Dict[str, float]	Current plant state. Expects keys "E" (state of charge) and "T" (temperature).	required
predicted_M_db	float	Predicted loop-dominance margin in dB.	required
risky_cmd	str | None	Command name when evaluating a risky instruction; None (or empty) for benign commands.	required

Returns:

Type	Description
RefusalDecision	A RefusalDecision
RefusalDecision	describing the action and a short reason code.

policy

policy

Controller policy over refusal logic.

A small homeostatic controller that produces actuator setpoints (throttle, cool, repair) and consults the RefusalArbiter to decide whether to accept a risky external command. The controller intentionally prioritizes boundary integrity over downstream tasks: throttle and cool respond to E (state of charge) and T (temperature) before any command acceptance is considered.

See Also

paper/main.tex: Self-Referential Control; Threat Model and Refusal.

Classes:

Name	Description
ControlAction	Low-level control action for the plant actuators.
ControllerPolicy	Simple homeostatic controller layered over a refusal arbiter.

ControlAction dataclass

ControlAction(throttle: float, cool: float, repair: float, accept_cmd: bool)

Low-level control action for the plant actuators.

Attributes:

Name	Type	Description
throttle	float	Throttle level in [0, 1].
cool	float	Cooling effort in [0, 1].
repair	float	Repair effort in [0, 1].
accept_cmd	bool	Whether to accept the risky external command for this tick.

ControllerPolicy

ControllerPolicy(refusal: RefusalArbiter)

Simple homeostatic controller layered over a refusal arbiter.

Heuristically sets throttle, cooling, and repair based on the current state, and consults RefusalArbiter to decide whether to accept a risky external command. The most recent decision is cached on last_decision for downstream inspection (e.g., audit records).

Parameters:

Name	Type	Description	Default
refusal	RefusalArbiter	Refusal arbiter used to gate risky commands.	required

Initialize with the refusal arbiter to delegate to.

Methods:

Name	Description
compute	Compute an action and command-acceptance decision.

compute

compute(state: Dict[str, float], predicted_M_db: float, risky_cmd: str | None = None) -> ControlAction

Compute an action and command-acceptance decision.

Parameters:

Name	Type	Description	Default
state	Dict[str, float]	Plant state with keys "E" (state of charge), "T" (temperature), and "R" (repair / health).	required
predicted_M_db	float	Predicted loop-dominance margin in dB.	required
risky_cmd	str | None	Optional risky command to evaluate.	None

Returns:

Type	Description
ControlAction	A ControlAction with
ControlAction	actuator settings and the accept flag from the arbiter.