Hardware-Abstraction Interface Contracts

Every physical interface is declared as a typed contract so the control stack targets a stable abstraction, not a specific vendor part.

Why contracts, not wiring

The AI-native stack must not be rewritten every time a sensor or supply changes vendor. The hardware-abstraction layer (HAL) declares each physical interface as a typed contract: its signals, units, ranges, latency class, owning layer, and failure behavior. Software targets the contract; the driver behind it can change.

What a contract declares

# HAL interface contract (schema)
contract = {
  'id': 'pf_coil_supply.k',
  'direction': 'actuate',
  'signals': {'I_target':'A', 'dIdt_max':'A/s'},
  'range':   {'I_target':(0, I_max), 'dIdt_max':(0, slew_max)},
  'latency_class': 'ms',
  'owner': 'L1',
  'fail_mode': 'hold_last_safe',
  'calibration_ref': 'cal://pf_coil/k' }

The contract encodes the fields the rest of this category depends on: the owning layer, the latency class, the range checks the L1 edge enforces, and the calibration reference. A command that violates the declared range is rejected against the contract, independent of the driver.

Fail modes are part of the contract

Declaring the fail mode in the contract makes fail-safe behavior a testable property rather than driver folklore: a valve fails closed, a dump switch fails active, an accountancy read fails to a flag with no control action. Conformance tests check each driver against its contract before it is trusted in the loop.

Owner: L1/L2 jointly — L1 enforces the real-time contract, L2 the data contract. This is the abstraction that lets one AI-native stack drive two very different machines — breeder and burner — from the same code. Design-and-simulation specification; contracts are validated in hardware-in-the-loop commissioning after construction start.