Skip to content

Canonical Interface Cleanup

The August 2026 cleanup removed repository-owned compatibility layers instead of maintaining two names or schemas for the same concept. New code should use only the contracts below.

Runtime APIs

  • Logging uses src.core.logging.log and configure_logging directly.
  • The learned shield wrapper is TransitionShield, constructed with the required init_safety_bound keyword.
  • Labelled environments require an explicit SafetyAbstraction; overriding a wrapper-only safe(...) implementation is not a substitute.
  • Environment episode-cap metadata is named max_steps.
  • DPGGMatrix uses pot_step; the ignored pot_bins constructor argument was removed.
  • Soft opponent-model rollouts accept a graph-indexed OMBuffer and the three-argument graph sampler. SoftRolloutPIConfig.rollout_steps is the sole rollout-length field.
  • World-model inference uses predict_probs_bits_rewards; random collection uses collect_rollouts_random.
  • Experiment notebooks pass n_agents explicitly to create_base_config. Omitting it is a launch error even for environments that currently support exactly two agents.

Artifacts and caches

  • Joint graphs are serialized as src.joint_graph.common.Graph directly; wrapper objects containing a .graph field are rejected.
  • True-shield graph caches require the graph pickle plus its canonical metadata sidecar. Embedded cache-wrapper objects are rejected.
  • Timing data is read only from the export root's timings.json, with hardware records in timings_hardware.json. Suffixed files and pickle timing payloads are not migrated.
  • Diagram state widths must match the live environment schema. Extra stored suffix bits are rejected instead of displayed as auxiliary metadata.
  • Environment set_state() methods accept only the tuple emitted by the current get_state(). Counter-bearing snapshot tuples are rejected.

Existing exports that violate these contracts must be rebuilt with the current notebooks. The repository deliberately has no import shims or conversion notebooks for those formats.