API Reference

Generated from docstrings via mkdocstrings.

CONCERTO — the method

concerto.api

Public Protocols for CONCERTO — the method-level contracts.

All concrete implementations (in chamber.* or concerto.safety, concerto.training) depend on these Protocols, not on each other. See ADR-INDEX.md for the full decision record; individual modules in this package cite the specific ADR they implement.

concerto.safety

CONCERTO safety stack — exp CBF-QP + conformal overlay + OSCBF + braking.

Implements the three-layer safety filter decided in ADR-004 (Wang-Ames-Egerstedt 2017 + Huriot & Sibai 2025 + Morton & Pavone 2025), the per-task numeric bounds plumbing from ADR-006 §Decision, and the three-table reporting format from ADR-014 §Decision.

Public surface (see :mod:concerto.safety.api for full docstrings):

• :class:Bounds — per-task numeric envelope (ADR-006).
• :class:SafetyState — mutable conformal-CBF state (ADR-004).
• :class:FilterInfo — telemetry payload (ADR-014).
• :class:EgoOnlySafetyFilter, :class:JointSafetyFilter — typed Protocols for the two filter shapes (ADR-004 §Public API; spike_004A §Three-mode taxonomy). The legacy single :data:SafetyFilter alias remains importable but emits a :class:DeprecationWarning on first use; removal target 0.3.0.
• :class:ConcertoSafetyInfeasible — QP-infeasibility error (ADR-004).
• :class:EmergencyController — per-uid embodiment hook for the hard braking fallback (ADR-004 risk-mitigation #1).
• :class:CartesianAccelEmergencyController — default Cartesian sum-and-saturate override for double-integrator agents (ADR-004 risk-mitigation #1).
• :data:DEFAULT_EPSILON, :data:DEFAULT_ETA, :data:DEFAULT_WARMUP_STEPS — conformal defaults (ADR-004 §Decision).
• :func:solve_qp_stub — small Clarabel QP benchmark used by the M2 saturation guard test (T3.10 replaced the no-op M2 stub with a real solve at a name-preserved entry point).

FilterInfo module-attribute

FilterInfo = TypedDict(
    "FilterInfo",
    {
        "lambda": LambdaDict,
        "constraint_violation": FloatArray,
        "prediction_gap_loss": LambdaDict | None,
        "fallback_fired": bool,
        "qp_solve_ms": float,
    },
)

Telemetry payload returned by the filter Protocols (ADR-014 §Decision).

Returned by :meth:EgoOnlySafetyFilter.filter and :meth:JointSafetyFilter.filter.

The fields populate the three-table renderer's row data:

• lambda — current conformal slack as a :data:LambdaDict (per-pair UID-tuple keys → float); feeds Table 3 (conservativeness gap λ mean/var vs. oracle gt/noLearn). Issue #144 promoted this field from a canonical-pair-order ndarray to the dict form so the per-pair indexing is part of the type system; see :func:lambda_to_jsonable / :func:lambda_from_jsonable for the ADR-014 v3 wire encoding.
• constraint_violation — per-pair non-negative violation signal max(0, -h_ij) from the CBF backbone. Zero when the constraint is satisfied; positive when the barrier is in the violated half-space. Counted into Table 2's per-condition violation rates. Stays as a :class:numpy.ndarray indexed by the canonical pair-iteration order produced by :func:make_pair_keys over the filter's UID set — issue #144's structural fix targets lambda only.
• prediction_gap_loss — per-pair Huriot & Sibai 2025 §IV.A loss max(0, predicted_h - actual_h) against a partner-trajectory predictor as a :data:LambdaDict (same keying as lambda). This is the signal that drives the conformal update (update_lambda); :data:None when no predictor is wired (the CBF backbone alone cannot compute it — see concerto.safety.conformal.update_lambda_from_predictor).
• fallback_fired — feeds Table 2's "fallback fired" column.
• qp_solve_ms — feeds the OSCBF 1 kHz target check (ADR-004 §"OSCBF target").

The constraint-violation and prediction-gap loss are reported as separate cells of the ADR-014 three-table report because they answer different questions: constraint_violation is a per-step CBF gap (did the QP keep us in the safe set this step?), and prediction_gap_loss is the conformal calibration signal (was the predictor's forecast of the safe set wrong?).

AgentControlModel

Bases: Protocol

Per-agent action ↔ Cartesian-acceleration map (ADR-004 §Decision; spike_004A).

The CBF row generator builds pairwise constraints in Cartesian / safety space, then projects to per-agent action-space coefficients via this Protocol. The Protocol mediates between each agent's action space (joint torques for a 7-DOF arm, wheel velocities for a 2-DOF base, Cartesian accelerations for a point mass) and the shared safety space (Cartesian acceleration of the agent's safety body).

Implementations MUST be deterministic on identical (state, action) inputs (P6; seeding contract) and MUST be consistent with each other: for any state and any Cartesian acceleration a in the image of :meth:action_to_cartesian_accel, action_to_cartesian_accel(state, cartesian_accel_to_action(state, a)) == a to within floating- point tolerance. The right-inverse exists by construction for over-actuated agents (Jacobian has more columns than rows); for exactly-actuated agents the right-inverse is the unique inverse.

Attributes:

• uid (str) –

  Unique identifier of the agent whose model this is.

• action_dim (int) –

  Dimensionality of the agent's action vector (e.g. 7 for a 7-DOF arm; 2 for a planar double integrator).

• position_dim (int) –

  Cartesian dimension of the agent's safety body (typically 2 for the §V toy crossing, 3 for manipulation).

Source code in src/concerto/safety/api.py

@runtime_checkable
class AgentControlModel(Protocol):
    """Per-agent action ↔ Cartesian-acceleration map (ADR-004 §Decision; spike_004A).

    The CBF row generator builds pairwise constraints in Cartesian /
    safety space, then projects to per-agent action-space coefficients
    via this Protocol. The Protocol mediates between each agent's
    *action space* (joint torques for a 7-DOF arm, wheel velocities
    for a 2-DOF base, Cartesian accelerations for a point mass) and
    the shared *safety space* (Cartesian acceleration of the agent's
    safety body).

    Implementations MUST be deterministic on identical ``(state,
    action)`` inputs (P6; seeding contract) and MUST be consistent
    with each other: for any ``state`` and any Cartesian acceleration
    ``a`` in the image of :meth:`action_to_cartesian_accel`,
    ``action_to_cartesian_accel(state,
    cartesian_accel_to_action(state, a)) == a`` to within floating-
    point tolerance. The right-inverse exists by construction for
    over-actuated agents (Jacobian has more columns than rows); for
    exactly-actuated agents the right-inverse is the unique inverse.

    Attributes:
        uid: Unique identifier of the agent whose model this is.
        action_dim: Dimensionality of the agent's action vector
            (e.g. 7 for a 7-DOF arm; 2 for a planar double integrator).
        position_dim: Cartesian dimension of the agent's safety body
            (typically 2 for the §V toy crossing, 3 for manipulation).
    """

    @property
    def uid(self) -> str:
        """Unique identifier of the agent (ADR-004 §Decision)."""
        ...

    @property
    def action_dim(self) -> int:
        """Dimensionality of the action vector (ADR-004 §Decision)."""
        ...

    @property
    def position_dim(self) -> int:
        """Cartesian dimension of the safety body (ADR-004 §Decision)."""
        ...

    def action_to_cartesian_accel(self, state: AgentSnapshot, action: FloatArray) -> FloatArray:
        """Map a control-space action to a Cartesian acceleration (ADR-004 §Decision).

        Args:
            state: Current :class:`concerto.safety.cbf_qp.AgentSnapshot`.
                The mapping is state-dependent for any embodiment whose
                Jacobian depends on configuration (e.g. a 7-DOF arm).
            action: Action vector of shape ``(action_dim,)``, dtype
                ``float64``.

        Returns:
            Cartesian acceleration of shape ``(position_dim,)``, dtype
            ``float64``.
        """
        ...

    def cartesian_accel_to_action(
        self, state: AgentSnapshot, cartesian_accel: FloatArray
    ) -> FloatArray:
        """Right-inverse for QP projection back into action space (ADR-004 §Decision).

        Used by the CBF-QP to express the per-agent action-space slot
        coefficients of a Cartesian constraint row, and (via
        :class:`~concerto.safety.emergency.JacobianEmergencyController`)
        by the braking fallback to translate the Cartesian repulsion
        target into joint-space torques. For an over-actuated agent the
        right-inverse selects one of the many actions that realise the
        same Cartesian acceleration; the damped-least-squares
        pseudo-inverse is the canonical choice (see
        :class:`JacobianControlModel`) and is the single source of
        truth for the Cartesian-to-joint map across the CBF row
        projection and the emergency fallback (ADR-004 §Decision; P1.02).

        Args:
            state: Current :class:`concerto.safety.cbf_qp.AgentSnapshot`.
            cartesian_accel: Cartesian acceleration of shape
                ``(position_dim,)``, dtype ``float64``.

        Returns:
            Action vector of shape ``(action_dim,)``, dtype ``float64``.
        """
        ...

    def max_cartesian_accel(self, bounds: Bounds) -> float:
        """Per-agent Cartesian acceleration capacity (ADR-004 §Decision; spike_004A).

        Used by the QP-row generator to size the per-pair
        ``alpha_pair = alpha_i_cart + alpha_j_cart`` and to drive the
        proportional Wang-Ames-Egerstedt 2017 §IV budget split for
        heterogeneous embodiments. For a double-integrator agent
        whose action space *is* Cartesian acceleration this is
        ``bounds.cartesian_accel_capacity`` (the L2 magnitude cap).

        Args:
            bounds: Per-task :class:`Bounds` envelope.

        Returns:
            Strictly positive scalar acceleration capacity.
        """
        ...

action_dim property

action_dim: int

Dimensionality of the action vector (ADR-004 §Decision).

position_dim property

position_dim: int

Cartesian dimension of the safety body (ADR-004 §Decision).

uid property

uid: str

Unique identifier of the agent (ADR-004 §Decision).

action_to_cartesian_accel

action_to_cartesian_accel(
    state: AgentSnapshot, action: FloatArray
) -> FloatArray

Map a control-space action to a Cartesian acceleration (ADR-004 §Decision).

Parameters:

• state (AgentSnapshot) –

  Current :class:concerto.safety.cbf_qp.AgentSnapshot. The mapping is state-dependent for any embodiment whose Jacobian depends on configuration (e.g. a 7-DOF arm).

• action (FloatArray) –

  Action vector of shape (action_dim,), dtype float64.

Returns:

• FloatArray –

  Cartesian acceleration of shape (position_dim,), dtype

• FloatArray –

  float64.

Source code in src/concerto/safety/api.py

def action_to_cartesian_accel(self, state: AgentSnapshot, action: FloatArray) -> FloatArray:
    """Map a control-space action to a Cartesian acceleration (ADR-004 §Decision).

    Args:
        state: Current :class:`concerto.safety.cbf_qp.AgentSnapshot`.
            The mapping is state-dependent for any embodiment whose
            Jacobian depends on configuration (e.g. a 7-DOF arm).
        action: Action vector of shape ``(action_dim,)``, dtype
            ``float64``.

    Returns:
        Cartesian acceleration of shape ``(position_dim,)``, dtype
        ``float64``.
    """
    ...

cartesian_accel_to_action

cartesian_accel_to_action(
    state: AgentSnapshot, cartesian_accel: FloatArray
) -> FloatArray

Right-inverse for QP projection back into action space (ADR-004 §Decision).

Used by the CBF-QP to express the per-agent action-space slot coefficients of a Cartesian constraint row, and (via :class:~concerto.safety.emergency.JacobianEmergencyController) by the braking fallback to translate the Cartesian repulsion target into joint-space torques. For an over-actuated agent the right-inverse selects one of the many actions that realise the same Cartesian acceleration; the damped-least-squares pseudo-inverse is the canonical choice (see :class:JacobianControlModel) and is the single source of truth for the Cartesian-to-joint map across the CBF row projection and the emergency fallback (ADR-004 §Decision; P1.02).

Parameters:

• state (AgentSnapshot) –

  Current :class:concerto.safety.cbf_qp.AgentSnapshot.

• cartesian_accel (FloatArray) –

  Cartesian acceleration of shape (position_dim,), dtype float64.

Returns:

• FloatArray –

  Action vector of shape (action_dim,), dtype float64.

Source code in src/concerto/safety/api.py

def cartesian_accel_to_action(
    self, state: AgentSnapshot, cartesian_accel: FloatArray
) -> FloatArray:
    """Right-inverse for QP projection back into action space (ADR-004 §Decision).

    Used by the CBF-QP to express the per-agent action-space slot
    coefficients of a Cartesian constraint row, and (via
    :class:`~concerto.safety.emergency.JacobianEmergencyController`)
    by the braking fallback to translate the Cartesian repulsion
    target into joint-space torques. For an over-actuated agent the
    right-inverse selects one of the many actions that realise the
    same Cartesian acceleration; the damped-least-squares
    pseudo-inverse is the canonical choice (see
    :class:`JacobianControlModel`) and is the single source of
    truth for the Cartesian-to-joint map across the CBF row
    projection and the emergency fallback (ADR-004 §Decision; P1.02).

    Args:
        state: Current :class:`concerto.safety.cbf_qp.AgentSnapshot`.
        cartesian_accel: Cartesian acceleration of shape
            ``(position_dim,)``, dtype ``float64``.

    Returns:
        Action vector of shape ``(action_dim,)``, dtype ``float64``.
    """
    ...

max_cartesian_accel

max_cartesian_accel(bounds: Bounds) -> float

Per-agent Cartesian acceleration capacity (ADR-004 §Decision; spike_004A).

Used by the QP-row generator to size the per-pair alpha_pair = alpha_i_cart + alpha_j_cart and to drive the proportional Wang-Ames-Egerstedt 2017 §IV budget split for heterogeneous embodiments. For a double-integrator agent whose action space is Cartesian acceleration this is bounds.cartesian_accel_capacity (the L2 magnitude cap).

Parameters:

• bounds (Bounds) –

  Per-task :class:Bounds envelope.

Returns:

• float –

  Strictly positive scalar acceleration capacity.

Source code in src/concerto/safety/api.py

def max_cartesian_accel(self, bounds: Bounds) -> float:
    """Per-agent Cartesian acceleration capacity (ADR-004 §Decision; spike_004A).

    Used by the QP-row generator to size the per-pair
    ``alpha_pair = alpha_i_cart + alpha_j_cart`` and to drive the
    proportional Wang-Ames-Egerstedt 2017 §IV budget split for
    heterogeneous embodiments. For a double-integrator agent
    whose action space *is* Cartesian acceleration this is
    ``bounds.cartesian_accel_capacity`` (the L2 magnitude cap).

    Args:
        bounds: Per-task :class:`Bounds` envelope.

    Returns:
        Strictly positive scalar acceleration capacity.
    """
    ...

Bounds dataclass

Per-task numeric bounds for the safety stack (ADR-006 §Decision Option C).

The Bounds envelope is the explicit-numeric half of ADR-006's hybrid decision: bounds gate QP feasibility and reportability while the conformal slack (:class:SafetyState) governs online adaptation. The enumerated values track ADR-006 §Consequences — the comm-latency bound is anchored to the URLLC-3GPP-R17 sweep table from M2; action_linf_component, cartesian_accel_capacity, and action_rate are task-specific (Phase-1 fills them; Phase-0 ships sane defaults). The force_limit field is a Phase-0 stub for ADR-007 Open Question #4 (per-vendor decomposition, ADR-004 Open Question #5) — a strategy-interfaced per-vendor handler slots in once Stage-3 SA resolves the open question.

Field split (issue #146, closed by P1.02; 2026-05-17). The prior single action_norm field was consumed by two safety layers with mismatched semantics (L-infinity per-component in the CBF-QP outer filter; L2 magnitude cap in the Cartesian emergency controller). The field is now split into two explicit fields, each named for its semantics:

• action_linf_component — per-component L-infinity bound on the action vector (|u[k]| <= action_linf_component for every component k). Enforced by :class:concerto.safety.cbf_qp.ExpCBFQP's action-space bound rows and (post-Jacobian) by :class:~concerto.safety.emergency.JacobianEmergencyController's per-joint clip.
• cartesian_accel_capacity — L2 magnitude cap on the Cartesian acceleration. The semantic source of the per-agent alpha in the Wang-Ames-Egerstedt 2017 §III barrier value (alpha_pair = 2 * cartesian_accel_capacity for symmetric agents) and of the :class:~concerto.safety.emergency.CartesianAccelEmergencyController's saturation step.

For a d-dimensional action the two are related but not equal: an action drawn from the L-infinity envelope has worst-case L2 magnitude sqrt(d) * action_linf_component. The conservative operator pattern is cartesian_accel_capacity = action_linf_component (matches the pre-split semantics under the safe-operator workaround the 2026-05-16 docstring named); a less conservative deployment sets cartesian_accel_capacity = sqrt(d) * action_linf_component to use the full envelope. Either pin is the operator's call; the safety stack treats the two fields as independent inputs.

Attributes:

• action_linf_component (float) –

  Per-component L-infinity bound enforced by the CBF-QP outer filter (:class:concerto.safety.cbf_qp.ExpCBFQP) and as the post-Jacobian per-joint clip in :class:~concerto.safety.emergency.JacobianEmergencyController.

• cartesian_accel_capacity (float) –

  L2 magnitude cap on Cartesian acceleration. Source of the per-agent alpha consumed by the conformal-barrier alpha_pair and the saturation step in :class:~concerto.safety.emergency.CartesianAccelEmergencyController.

• action_rate (float) –

  Maximum :math:\lVert u_k - u_{k-1} \rVert_2 per agent, per task. Bounds the actuator-rate slack the conformal CBF must remain feasible under (ADR-006 §Decision).

• comm_latency_ms (float) –

  Default mean comm latency, in milliseconds. Set from the URLLC profile selected for the run (ADR-006 §Consequences; chamber.comm.URLLC_3GPP_R17).

• force_limit (float) –

  Global force threshold for the per-pair contact-force constraint (ADR-004 Open Question #5; per-vendor handler slots in once Stage-3 SA resolves the decomposition).

Source code in src/concerto/safety/api.py

@dataclass(frozen=True)
class Bounds:
    r"""Per-task numeric bounds for the safety stack (ADR-006 §Decision Option C).

    The ``Bounds`` envelope is the explicit-numeric half of ADR-006's hybrid
    decision: bounds gate QP feasibility and reportability while the
    conformal slack (:class:`SafetyState`) governs online adaptation. The
    enumerated values track ADR-006 §Consequences — the comm-latency bound
    is anchored to the URLLC-3GPP-R17 sweep table from M2;
    ``action_linf_component``, ``cartesian_accel_capacity``, and
    ``action_rate`` are task-specific (Phase-1 fills them; Phase-0 ships
    sane defaults). The ``force_limit`` field is a Phase-0 stub for
    ADR-007 Open Question #4 (per-vendor decomposition, ADR-004 Open
    Question #5) — a strategy-interfaced per-vendor handler slots in once
    Stage-3 SA resolves the open question.

    **Field split (issue #146, closed by P1.02; 2026-05-17).** The prior
    single ``action_norm`` field was consumed by two safety layers with
    mismatched semantics (L-infinity per-component in the CBF-QP outer
    filter; L2 magnitude cap in the Cartesian emergency controller). The
    field is now split into two explicit fields, each named for its
    semantics:

    - ``action_linf_component`` — per-component L-infinity bound on the
      action vector (``|u[k]| <= action_linf_component`` for every
      component ``k``). Enforced by
      :class:`concerto.safety.cbf_qp.ExpCBFQP`'s action-space bound rows
      and (post-Jacobian) by :class:`~concerto.safety.emergency.JacobianEmergencyController`'s
      per-joint clip.
    - ``cartesian_accel_capacity`` — L2 magnitude cap on the Cartesian
      acceleration. The semantic source of the per-agent ``alpha`` in
      the Wang-Ames-Egerstedt 2017 §III barrier value (``alpha_pair =
      2 * cartesian_accel_capacity`` for symmetric agents) and of the
      :class:`~concerto.safety.emergency.CartesianAccelEmergencyController`'s
      saturation step.

    For a ``d``-dimensional action the two are related but not equal:
    an action drawn from the L-infinity envelope has worst-case L2
    magnitude ``sqrt(d) * action_linf_component``. The conservative
    operator pattern is ``cartesian_accel_capacity =
    action_linf_component`` (matches the pre-split semantics under the
    safe-operator workaround the 2026-05-16 docstring named); a less
    conservative deployment sets ``cartesian_accel_capacity =
    sqrt(d) * action_linf_component`` to use the full envelope. Either
    pin is the operator's call; the safety stack treats the two fields
    as independent inputs.

    Attributes:
        action_linf_component: Per-component L-infinity bound enforced
            by the CBF-QP outer filter
            (:class:`concerto.safety.cbf_qp.ExpCBFQP`) and as the
            post-Jacobian per-joint clip in
            :class:`~concerto.safety.emergency.JacobianEmergencyController`.
        cartesian_accel_capacity: L2 magnitude cap on Cartesian
            acceleration. Source of the per-agent ``alpha`` consumed
            by the conformal-barrier ``alpha_pair`` and the saturation
            step in
            :class:`~concerto.safety.emergency.CartesianAccelEmergencyController`.
        action_rate: Maximum :math:`\lVert u_k - u_{k-1} \rVert_2` per
            agent, per task. Bounds the actuator-rate slack the conformal
            CBF must remain feasible under (ADR-006 §Decision).
        comm_latency_ms: Default mean comm latency, in milliseconds. Set
            from the URLLC profile selected for the run (ADR-006
            §Consequences; ``chamber.comm.URLLC_3GPP_R17``).
        force_limit: Global force threshold for the per-pair contact-force
            constraint (ADR-004 Open Question #5; per-vendor handler slots
            in once Stage-3 SA resolves the decomposition).
    """

    action_linf_component: float
    cartesian_accel_capacity: float
    action_rate: float
    comm_latency_ms: float
    force_limit: float

CartesianAccelEmergencyController

Cartesian-acceleration emergency override (ADR-004 risk-mitigation #1).

Default :class:EmergencyController for double-integrator agents whose control dimension equals the Cartesian dimension (2D and 3D point masses; the toy crossing example in Wang-Ames-Egerstedt 2017 §V). The aggregation rule is:

1. Sum the per-pair Cartesian repulsion unit vectors.
2. Saturate the result to bounds.cartesian_accel_capacity in the net push-apart direction: when the sum has non-trivial magnitude, rescale it to bounds.cartesian_accel_capacity (max emergency push); when it cancels out, return zero.
3. Return the saturated vector — its shape matches agent_state.position.shape by construction.

Single-pair case (one dangerous partner): the sum is a single unit vector with norm 1; the output magnitude is bounds.cartesian_accel_capacity, matching the original toy-crossing contract. Two opposing pairs (uid squeezed in the middle): the sum cancels to ~zero and the output is a zero action — there is no preferred direction to push in, and a spurious push would be worse than a no-op. Two non-opposing pairs: the sum points in the net escape direction and the output is bounds.cartesian_accel_capacity along that direction.

Not correct for 7-DOF manipulators: see :class:JacobianEmergencyController and the ADR-007 Stage-1 AS spike scope.

Source code in src/concerto/safety/emergency.py

class CartesianAccelEmergencyController:
    """Cartesian-acceleration emergency override (ADR-004 risk-mitigation #1).

    Default :class:`EmergencyController` for double-integrator agents
    whose control dimension equals the Cartesian dimension (2D and 3D
    point masses; the toy crossing example in Wang-Ames-Egerstedt 2017
    §V). The aggregation rule is:

    1. Sum the per-pair Cartesian repulsion unit vectors.
    2. Saturate the result to ``bounds.cartesian_accel_capacity`` in
       the *net* push-apart direction: when the sum has non-trivial
       magnitude, rescale it to ``bounds.cartesian_accel_capacity``
       (max emergency push); when it cancels out, return zero.
    3. Return the saturated vector — its shape matches
       ``agent_state.position.shape`` by construction.

    Single-pair case (one dangerous partner): the sum is a single unit
    vector with norm 1; the output magnitude is
    ``bounds.cartesian_accel_capacity``, matching the original
    toy-crossing contract. Two opposing pairs (uid squeezed in the
    middle): the sum cancels to ~zero and the output is a zero action
    — there is no preferred direction to push in, and a spurious push
    would be worse than a no-op. Two non-opposing pairs: the sum
    points in the net escape direction and the output is
    ``bounds.cartesian_accel_capacity`` along that direction.

    Not correct for 7-DOF manipulators: see
    :class:`JacobianEmergencyController` and the ADR-007 Stage-1 AS
    spike scope.
    """

    def compute_override(
        self,
        agent_state: AgentSnapshot,
        pairwise_repulsion_vectors: list[FloatArray],
        bounds: Bounds,
    ) -> FloatArray:
        """Sum-and-saturate Cartesian repulsion vectors (ADR-004 risk-mitigation #1).

        Args:
            agent_state: This uid's snapshot; only its ``position.shape``
                is used (the override's output shape).
            pairwise_repulsion_vectors: At least one Cartesian unit
                vector pointing away from each dangerous partner.
            bounds: Per-task :class:`Bounds`; the saturation magnitude
                is ``bounds.cartesian_accel_capacity`` (the L2 magnitude
                cap on Cartesian acceleration). Post-P1.02 the field
                split closes the prior L-infinity / L2 ambiguity that
                lived on the unified ``action_norm`` field — the
                per-component L-infinity envelope now lives on
                ``bounds.action_linf_component`` and is consumed only
                by the CBF-QP outer filter and (post-Jacobian) by
                :class:`JacobianEmergencyController`.

        Returns:
            Saturated Cartesian acceleration along the net push-apart
            direction with magnitude ``bounds.cartesian_accel_capacity``;
            or zero when the pairwise vectors cancel out. Shape matches
            ``agent_state.position.shape``, dtype ``float64``.
        """
        if not pairwise_repulsion_vectors:
            return np.zeros_like(agent_state.position, dtype=np.float64)

        aggregate = np.sum(
            np.stack(pairwise_repulsion_vectors, axis=0).astype(np.float64, copy=False),
            axis=0,
        )
        norm = float(np.linalg.norm(aggregate))
        if norm < _AGGREGATE_NORM_FLOOR:
            return np.zeros_like(agent_state.position, dtype=np.float64)
        return ((aggregate / norm) * bounds.cartesian_accel_capacity).astype(np.float64, copy=False)

compute_override

compute_override(
    agent_state: AgentSnapshot,
    pairwise_repulsion_vectors: list[FloatArray],
    bounds: Bounds,
) -> FloatArray

Sum-and-saturate Cartesian repulsion vectors (ADR-004 risk-mitigation #1).

Parameters:

• agent_state (AgentSnapshot) –

  This uid's snapshot; only its position.shape is used (the override's output shape).

• pairwise_repulsion_vectors (list[FloatArray]) –

  At least one Cartesian unit vector pointing away from each dangerous partner.

• bounds (Bounds) –

  Per-task :class:Bounds; the saturation magnitude is bounds.cartesian_accel_capacity (the L2 magnitude cap on Cartesian acceleration). Post-P1.02 the field split closes the prior L-infinity / L2 ambiguity that lived on the unified action_norm field — the per-component L-infinity envelope now lives on bounds.action_linf_component and is consumed only by the CBF-QP outer filter and (post-Jacobian) by :class:JacobianEmergencyController.

Returns:

• FloatArray –

  Saturated Cartesian acceleration along the net push-apart

• FloatArray –

  direction with magnitude bounds.cartesian_accel_capacity;

• FloatArray –

  or zero when the pairwise vectors cancel out. Shape matches

• FloatArray –

  agent_state.position.shape, dtype float64.

Source code in src/concerto/safety/emergency.py

def compute_override(
    self,
    agent_state: AgentSnapshot,
    pairwise_repulsion_vectors: list[FloatArray],
    bounds: Bounds,
) -> FloatArray:
    """Sum-and-saturate Cartesian repulsion vectors (ADR-004 risk-mitigation #1).

    Args:
        agent_state: This uid's snapshot; only its ``position.shape``
            is used (the override's output shape).
        pairwise_repulsion_vectors: At least one Cartesian unit
            vector pointing away from each dangerous partner.
        bounds: Per-task :class:`Bounds`; the saturation magnitude
            is ``bounds.cartesian_accel_capacity`` (the L2 magnitude
            cap on Cartesian acceleration). Post-P1.02 the field
            split closes the prior L-infinity / L2 ambiguity that
            lived on the unified ``action_norm`` field — the
            per-component L-infinity envelope now lives on
            ``bounds.action_linf_component`` and is consumed only
            by the CBF-QP outer filter and (post-Jacobian) by
            :class:`JacobianEmergencyController`.

    Returns:
        Saturated Cartesian acceleration along the net push-apart
        direction with magnitude ``bounds.cartesian_accel_capacity``;
        or zero when the pairwise vectors cancel out. Shape matches
        ``agent_state.position.shape``, dtype ``float64``.
    """
    if not pairwise_repulsion_vectors:
        return np.zeros_like(agent_state.position, dtype=np.float64)

    aggregate = np.sum(
        np.stack(pairwise_repulsion_vectors, axis=0).astype(np.float64, copy=False),
        axis=0,
    )
    norm = float(np.linalg.norm(aggregate))
    if norm < _AGGREGATE_NORM_FLOOR:
        return np.zeros_like(agent_state.position, dtype=np.float64)
    return ((aggregate / norm) * bounds.cartesian_accel_capacity).astype(np.float64, copy=False)

ConcertoSafetyInfeasible

Bases: RuntimeError

Raised when the safety QP is infeasible (ADR-004 §Decision; ADR-006 §Risks).

The conformal CBF-QP can become infeasible when partner-induced constraints conflict with within-robot OSCBF constraints under aggressive actuator limits — exactly the open problem named in Garg et al. 2024 §7.3 and tracked as ADR-006 R5. Callers MUST route to the braking fallback (ADR-004 risk-mitigation #1) on this error; the conformal QP is not a valid recovery path because Theorem 3 (Huriot & Sibai 2025) only bounds the average loss.

Source code in src/concerto/safety/errors.py

class ConcertoSafetyInfeasible(RuntimeError):  # noqa: N818
    """Raised when the safety QP is infeasible (ADR-004 §Decision; ADR-006 §Risks).

    The conformal CBF-QP can become infeasible when partner-induced
    constraints conflict with within-robot OSCBF constraints under
    aggressive actuator limits — exactly the open problem named in
    Garg et al. 2024 §7.3 and tracked as ADR-006 R5. Callers MUST route
    to the braking fallback (ADR-004 risk-mitigation #1) on this error;
    the conformal QP is not a valid recovery path because Theorem 3
    (Huriot & Sibai 2025) only bounds the *average* loss.
    """

DoubleIntegratorControlModel dataclass

Identity action ↔ Cartesian-acceleration map (ADR-004 §Decision; spike_004A §Reduction).

Default :class:AgentControlModel for double-integrator agents whose action space coincides with Cartesian acceleration (the Wang-Ames-Egerstedt 2017 §V toy crossing and every Phase-0 homogeneous test). The Jacobian J_i = d cartesian_accel / d action is the identity, so the CBF row coefficients projected through this model are element-wise identical to the rows the pre-refactor _pair_constraint_row emitted. This is the migration shim: tests that construct homogeneous 2-D pairs pass a :class:DoubleIntegratorControlModel per uid and run unchanged through :class:ExpCBFQP in :attr:SafetyMode.CENTRALIZED mode.

Attributes:

• uid (str) –

  Unique identifier of the agent.

• action_dim (int) –

  Dimensionality of the agent's action vector (equal to position_dim by construction).

Source code in src/concerto/safety/api.py

@dataclass(frozen=True)
class DoubleIntegratorControlModel:
    """Identity action ↔ Cartesian-acceleration map (ADR-004 §Decision; spike_004A §Reduction).

    Default :class:`AgentControlModel` for double-integrator agents
    whose action space coincides with Cartesian acceleration (the
    Wang-Ames-Egerstedt 2017 §V toy crossing and every Phase-0
    homogeneous test). The Jacobian ``J_i = d cartesian_accel /
    d action`` is the identity, so the CBF row coefficients projected
    through this model are element-wise identical to the rows the
    pre-refactor ``_pair_constraint_row`` emitted. This is the
    migration shim: tests that construct homogeneous 2-D pairs pass
    a :class:`DoubleIntegratorControlModel` per uid and run unchanged
    through :class:`ExpCBFQP` in :attr:`SafetyMode.CENTRALIZED` mode.

    Attributes:
        uid: Unique identifier of the agent.
        action_dim: Dimensionality of the agent's action vector
            (equal to ``position_dim`` by construction).
    """

    uid: str
    action_dim: int

    @property
    def position_dim(self) -> int:
        """Cartesian dimension of the safety body (ADR-004 §Decision).

        For a double integrator the action and position spaces have
        the same dimension by definition.
        """
        return self.action_dim

    def action_to_cartesian_accel(self, state: AgentSnapshot, action: FloatArray) -> FloatArray:
        """Return ``action`` unchanged (ADR-004 §Decision; spike_004A §Reduction).

        The double-integrator identity map.
        """
        del state
        if action.shape != (self.action_dim,):
            msg = (
                f"action shape {action.shape} mismatches "
                f"DoubleIntegratorControlModel(uid={self.uid!r}).action_dim={self.action_dim}"
            )
            raise ValueError(msg)
        return action.astype(np.float64, copy=False)

    def cartesian_accel_to_action(
        self, state: AgentSnapshot, cartesian_accel: FloatArray
    ) -> FloatArray:
        """Return ``cartesian_accel`` unchanged (ADR-004 §Decision; spike_004A §Reduction).

        The double-integrator identity right-inverse.
        """
        del state
        if cartesian_accel.shape != (self.action_dim,):
            msg = (
                f"cartesian_accel shape {cartesian_accel.shape} mismatches "
                f"DoubleIntegratorControlModel(uid={self.uid!r}).position_dim={self.action_dim}"
            )
            raise ValueError(msg)
        return cartesian_accel.astype(np.float64, copy=False)

    def max_cartesian_accel(self, bounds: Bounds) -> float:
        """Return ``bounds.cartesian_accel_capacity`` (ADR-004 §Decision; spike_004A).

        For a double integrator the L2 magnitude cap *is* the Cartesian
        acceleration capacity by definition of the embodiment. The
        Wang-Ames-Egerstedt 2017 §III barrier formula's ``alpha`` is a
        Cartesian acceleration capacity (it appears inside
        ``sqrt(2 * alpha * ...)``); pre-split this read
        ``bounds.action_norm`` under the operator pattern
        ``action_norm = capacity / sqrt(d)``, but the post-split field
        names this semantic explicitly (ADR-004 §Revision history
        2026-05-17 + ADR-INDEX footnote (a)).
        """
        return float(bounds.cartesian_accel_capacity)

position_dim property

position_dim: int

Cartesian dimension of the safety body (ADR-004 §Decision).

For a double integrator the action and position spaces have the same dimension by definition.

action_to_cartesian_accel

action_to_cartesian_accel(
    state: AgentSnapshot, action: FloatArray
) -> FloatArray

Return action unchanged (ADR-004 §Decision; spike_004A §Reduction).

The double-integrator identity map.

Source code in src/concerto/safety/api.py

def action_to_cartesian_accel(self, state: AgentSnapshot, action: FloatArray) -> FloatArray:
    """Return ``action`` unchanged (ADR-004 §Decision; spike_004A §Reduction).

    The double-integrator identity map.
    """
    del state
    if action.shape != (self.action_dim,):
        msg = (
            f"action shape {action.shape} mismatches "
            f"DoubleIntegratorControlModel(uid={self.uid!r}).action_dim={self.action_dim}"
        )
        raise ValueError(msg)
    return action.astype(np.float64, copy=False)

cartesian_accel_to_action

cartesian_accel_to_action(
    state: AgentSnapshot, cartesian_accel: FloatArray
) -> FloatArray

Return cartesian_accel unchanged (ADR-004 §Decision; spike_004A §Reduction).

The double-integrator identity right-inverse.

Source code in src/concerto/safety/api.py

def cartesian_accel_to_action(
    self, state: AgentSnapshot, cartesian_accel: FloatArray
) -> FloatArray:
    """Return ``cartesian_accel`` unchanged (ADR-004 §Decision; spike_004A §Reduction).

    The double-integrator identity right-inverse.
    """
    del state
    if cartesian_accel.shape != (self.action_dim,):
        msg = (
            f"cartesian_accel shape {cartesian_accel.shape} mismatches "
            f"DoubleIntegratorControlModel(uid={self.uid!r}).position_dim={self.action_dim}"
        )
        raise ValueError(msg)
    return cartesian_accel.astype(np.float64, copy=False)

max_cartesian_accel

max_cartesian_accel(bounds: Bounds) -> float

Return bounds.cartesian_accel_capacity (ADR-004 §Decision; spike_004A).

For a double integrator the L2 magnitude cap is the Cartesian acceleration capacity by definition of the embodiment. The Wang-Ames-Egerstedt 2017 §III barrier formula's alpha is a Cartesian acceleration capacity (it appears inside sqrt(2 * alpha * ...)); pre-split this read bounds.action_norm under the operator pattern action_norm = capacity / sqrt(d), but the post-split field names this semantic explicitly (ADR-004 §Revision history 2026-05-17 + ADR-INDEX footnote (a)).

Source code in src/concerto/safety/api.py

def max_cartesian_accel(self, bounds: Bounds) -> float:
    """Return ``bounds.cartesian_accel_capacity`` (ADR-004 §Decision; spike_004A).

    For a double integrator the L2 magnitude cap *is* the Cartesian
    acceleration capacity by definition of the embodiment. The
    Wang-Ames-Egerstedt 2017 §III barrier formula's ``alpha`` is a
    Cartesian acceleration capacity (it appears inside
    ``sqrt(2 * alpha * ...)``); pre-split this read
    ``bounds.action_norm`` under the operator pattern
    ``action_norm = capacity / sqrt(d)``, but the post-split field
    names this semantic explicitly (ADR-004 §Revision history
    2026-05-17 + ADR-INDEX footnote (a)).
    """
    return float(bounds.cartesian_accel_capacity)

EgoOnlySafetyFilter

Bases: Protocol

Contract for an :attr:SafetyMode.EGO_ONLY safety-filter pipeline (ADR-004 §Public API).

The deployment / ad-hoc / black-box-partner mode (ADR-006 §Decision; reviewer P0-3). The QP decides only the ego agent's action; the partner's motion enters as a predicted disturbance on the constraint right-hand side. The structural difference from :class:JointSafetyFilter is wire-visible: proposed_action is a single :class:FloatArray (the ego's nominal control), and the return value's first element is likewise an array — never a dict.

Implementations compose the three layers from ADR-004 — exp CBF-QP backbone (Wang-Ames-Egerstedt 2017), conformal slack overlay (Huriot & Sibai 2025), OSCBF inner filter (Morton & Pavone 2025) — plus the hard braking fallback (ADR-004 risk-mitigation #1) into a single propose-check-replan boundary that wraps any nominal controller without accessing its internals (the property the black-box-partner setting requires per ADR-006 §Decision).

The canonical implementation is :meth:concerto.safety.cbf_qp.ExpCBFQP.ego_only; third-party plugin filters that target ego-only deployment SHOULD subclass / structurally-conform to this Protocol so static checkers can catch shape mismatches at construction time (spike_004A §Three-mode taxonomy; reviewer P0-2).

Source code in src/concerto/safety/api.py

@runtime_checkable
class EgoOnlySafetyFilter(Protocol):
    """Contract for an :attr:`SafetyMode.EGO_ONLY` safety-filter pipeline (ADR-004 §Public API).

    The deployment / ad-hoc / black-box-partner mode (ADR-006 §Decision;
    reviewer P0-3). The QP decides only the ego agent's action; the
    partner's motion enters as a predicted disturbance on the
    constraint right-hand side. The structural difference from
    :class:`JointSafetyFilter` is wire-visible: ``proposed_action`` is a
    single :class:`FloatArray` (the ego's nominal control), and the
    return value's first element is likewise an array — never a dict.

    Implementations compose the three layers from ADR-004 — exp CBF-QP
    backbone (Wang-Ames-Egerstedt 2017), conformal slack overlay
    (Huriot & Sibai 2025), OSCBF inner filter (Morton & Pavone 2025) —
    plus the hard braking fallback (ADR-004 risk-mitigation #1) into a
    single propose-check-replan boundary that wraps any nominal
    controller without accessing its internals (the property the
    black-box-partner setting requires per ADR-006 §Decision).

    The canonical implementation is
    :meth:`concerto.safety.cbf_qp.ExpCBFQP.ego_only`; third-party
    plugin filters that target ego-only deployment SHOULD subclass /
    structurally-conform to this Protocol so static checkers can
    catch shape mismatches at construction time (spike_004A
    §Three-mode taxonomy; reviewer P0-2).
    """

    def reset(self, *, seed: int | None = None) -> None:
        """Reset filter state at episode start (ADR-004 §Decision).

        Args:
            seed: Optional root seed for the filter's deterministic RNG
                substream (P6). Implementations route this through
                ``concerto.training.seeding.derive_substream`` so two
                CPU runs with the same seed produce byte-identical
                outputs.
        """
        ...

    def filter(
        self,
        proposed_action: FloatArray,
        obs: dict[str, object],
        state: SafetyState,
        bounds: Bounds,
        *,
        ego_uid: str,
        partner_predicted_states: dict[str, AgentSnapshot],
        dt: float,
    ) -> tuple[FloatArray, FilterInfo]:
        """Project the nominal ego action onto the safe set (ADR-004 §Public API).

        Args:
            proposed_action: Ego nominal control input of shape
                ``(control_models[ego_uid].action_dim,)``. The QP
                minimises ``||u - u_hat||^2`` with this as the reference
                (Wang-Ames-Egerstedt 2017 eq. 9).
            obs: Observation dict; the filter reads ``obs["comm"]`` (M2
                contract — see ``chamber.comm.api.CommPacket``) and
                ``obs["meta"]["partner_id"]`` (M4 contract; ``None`` ⇒
                single-partner mode, no hard fail; identity change ⇒
                reset ``lambda`` to ``lambda_safe`` and enter warmup
                per ADR-004 risk-mitigation #2).
            state: Mutable :class:`SafetyState`; updated in place by the
                conformal layer each control step.
            bounds: Per-task :class:`Bounds` envelope (ADR-006 §Decision).
            ego_uid: Identifies which uid in ``obs["agent_states"]`` is
                the ego.
            partner_predicted_states: Per-partner-uid predicted
                :class:`concerto.safety.cbf_qp.AgentSnapshot` at the
                *next* control step, used to evaluate the partner's
                predicted Cartesian acceleration; this enters the
                constraint RHS as a known drift term.
            dt: Predictor lookahead horizon in seconds (typically the
                env's control-step duration). Used to convert the
                predicted velocity delta into a Cartesian acceleration
                ``(v_pred - v_now) / dt`` on the constraint RHS
                (ADR-004 §Decisions, "Predicted-acceleration units";
                external-review P0-1, 2026-05-16). Must be strictly
                positive and consistent with the value passed to the
                partner-trajectory predictor (e.g.
                :func:`concerto.safety.conformal.constant_velocity_predict`).

        Returns:
            A pair ``(safe_action, info)`` where ``safe_action`` is the
            QP-projected ego action and ``info`` is a
            :class:`FilterInfo` telemetry payload feeding the ADR-014
            three-table renderer.

        Raises:
            ConcertoSafetyInfeasible: When the QP is infeasible even after
                slack relaxation (ADR-004 §Decision; ADR-006 §Risks). The
                caller MUST route to the braking fallback in this case.
        """
        ...

filter

filter(
    proposed_action: FloatArray,
    obs: dict[str, object],
    state: SafetyState,
    bounds: Bounds,
    *,
    ego_uid: str,
    partner_predicted_states: dict[str, AgentSnapshot],
    dt: float,
) -> tuple[FloatArray, FilterInfo]

Project the nominal ego action onto the safe set (ADR-004 §Public API).

Parameters:

• proposed_action (FloatArray) –

  Ego nominal control input of shape (control_models[ego_uid].action_dim,). The QP minimises ||u - u_hat||^2 with this as the reference (Wang-Ames-Egerstedt 2017 eq. 9).

• obs (dict[str, object]) –

  Observation dict; the filter reads obs["comm"] (M2 contract — see chamber.comm.api.CommPacket) and obs["meta"]["partner_id"] (M4 contract; None ⇒ single-partner mode, no hard fail; identity change ⇒ reset lambda to lambda_safe and enter warmup per ADR-004 risk-mitigation #2).

• state (SafetyState) –

  Mutable :class:SafetyState; updated in place by the conformal layer each control step.

• bounds (Bounds) –

  Per-task :class:Bounds envelope (ADR-006 §Decision).

• ego_uid (str) –

  Identifies which uid in obs["agent_states"] is the ego.

• partner_predicted_states (dict[str, AgentSnapshot]) –

  Per-partner-uid predicted :class:concerto.safety.cbf_qp.AgentSnapshot at the next control step, used to evaluate the partner's predicted Cartesian acceleration; this enters the constraint RHS as a known drift term.

• dt (float) –

  Predictor lookahead horizon in seconds (typically the env's control-step duration). Used to convert the predicted velocity delta into a Cartesian acceleration (v_pred - v_now) / dt on the constraint RHS (ADR-004 §Decisions, "Predicted-acceleration units"; external-review P0-1, 2026-05-16). Must be strictly positive and consistent with the value passed to the partner-trajectory predictor (e.g. :func:concerto.safety.conformal.constant_velocity_predict).

Returns:

• FloatArray –

  A pair (safe_action, info) where safe_action is the

• FilterInfo –

  QP-projected ego action and info is a

• tuple[FloatArray, FilterInfo] –

  class:FilterInfo telemetry payload feeding the ADR-014

• tuple[FloatArray, FilterInfo] –

  three-table renderer.

Raises:

• ConcertoSafetyInfeasible –

  When the QP is infeasible even after slack relaxation (ADR-004 §Decision; ADR-006 §Risks). The caller MUST route to the braking fallback in this case.

Source code in src/concerto/safety/api.py

def filter(
    self,
    proposed_action: FloatArray,
    obs: dict[str, object],
    state: SafetyState,
    bounds: Bounds,
    *,
    ego_uid: str,
    partner_predicted_states: dict[str, AgentSnapshot],
    dt: float,
) -> tuple[FloatArray, FilterInfo]:
    """Project the nominal ego action onto the safe set (ADR-004 §Public API).

    Args:
        proposed_action: Ego nominal control input of shape
            ``(control_models[ego_uid].action_dim,)``. The QP
            minimises ``||u - u_hat||^2`` with this as the reference
            (Wang-Ames-Egerstedt 2017 eq. 9).
        obs: Observation dict; the filter reads ``obs["comm"]`` (M2
            contract — see ``chamber.comm.api.CommPacket``) and
            ``obs["meta"]["partner_id"]`` (M4 contract; ``None`` ⇒
            single-partner mode, no hard fail; identity change ⇒
            reset ``lambda`` to ``lambda_safe`` and enter warmup
            per ADR-004 risk-mitigation #2).
        state: Mutable :class:`SafetyState`; updated in place by the
            conformal layer each control step.
        bounds: Per-task :class:`Bounds` envelope (ADR-006 §Decision).
        ego_uid: Identifies which uid in ``obs["agent_states"]`` is
            the ego.
        partner_predicted_states: Per-partner-uid predicted
            :class:`concerto.safety.cbf_qp.AgentSnapshot` at the
            *next* control step, used to evaluate the partner's
            predicted Cartesian acceleration; this enters the
            constraint RHS as a known drift term.
        dt: Predictor lookahead horizon in seconds (typically the
            env's control-step duration). Used to convert the
            predicted velocity delta into a Cartesian acceleration
            ``(v_pred - v_now) / dt`` on the constraint RHS
            (ADR-004 §Decisions, "Predicted-acceleration units";
            external-review P0-1, 2026-05-16). Must be strictly
            positive and consistent with the value passed to the
            partner-trajectory predictor (e.g.
            :func:`concerto.safety.conformal.constant_velocity_predict`).

    Returns:
        A pair ``(safe_action, info)`` where ``safe_action`` is the
        QP-projected ego action and ``info`` is a
        :class:`FilterInfo` telemetry payload feeding the ADR-014
        three-table renderer.

    Raises:
        ConcertoSafetyInfeasible: When the QP is infeasible even after
            slack relaxation (ADR-004 §Decision; ADR-006 §Risks). The
            caller MUST route to the braking fallback in this case.
    """
    ...

reset

reset(*, seed: int | None = None) -> None

Reset filter state at episode start (ADR-004 §Decision).

Parameters:

• seed (int | None, default: None ) –

  Optional root seed for the filter's deterministic RNG substream (P6). Implementations route this through concerto.training.seeding.derive_substream so two CPU runs with the same seed produce byte-identical outputs.

Source code in src/concerto/safety/api.py

def reset(self, *, seed: int | None = None) -> None:
    """Reset filter state at episode start (ADR-004 §Decision).

    Args:
        seed: Optional root seed for the filter's deterministic RNG
            substream (P6). Implementations route this through
            ``concerto.training.seeding.derive_substream`` so two
            CPU runs with the same seed produce byte-identical
            outputs.
    """
    ...

EmergencyController

Bases: Protocol

Per-uid emergency-override hook (ADR-004 risk-mitigation #1).

Translates the aggregate per-uid repulsion (summed across every dangerous pair the uid is involved in) into a control-space override action. The braking fallback consults one controller per uid so heterogeneous embodiments (double-integrator base, 7-DOF arm, manipulator end-effector) can supply their own Cartesian-to-control mapping without :func:concerto.safety.braking.maybe_brake needing to know the embodiment class.

Implementations MUST be deterministic on identical inputs (P6; seeding contract) and MUST return an array whose shape matches the control-action shape the env expects for this uid — not necessarily the Cartesian shape. A 7-DOF arm controller returns a 7-vector; a 2D double-integrator controller returns a 2-vector.

Source code in src/concerto/safety/emergency.py

@runtime_checkable
class EmergencyController(Protocol):
    """Per-uid emergency-override hook (ADR-004 risk-mitigation #1).

    Translates the aggregate per-uid repulsion (summed across every
    dangerous pair the uid is involved in) into a control-space override
    action. The braking fallback consults one controller per uid so
    heterogeneous embodiments (double-integrator base, 7-DOF arm,
    manipulator end-effector) can supply their own Cartesian-to-control
    mapping without :func:`concerto.safety.braking.maybe_brake` needing
    to know the embodiment class.

    Implementations MUST be deterministic on identical inputs (P6;
    seeding contract) and MUST return an array whose shape matches the
    control-action shape the env expects for this uid — *not*
    necessarily the Cartesian shape. A 7-DOF arm controller returns a
    7-vector; a 2D double-integrator controller returns a 2-vector.
    """

    def compute_override(
        self,
        agent_state: AgentSnapshot,
        pairwise_repulsion_vectors: list[FloatArray],
        bounds: Bounds,
    ) -> FloatArray:
        """Return the embodiment-specific emergency override (ADR-004 risk-mitigation #1).

        Args:
            agent_state: This uid's :class:`AgentSnapshot` at the current
                control step. Implementations may read position and
                velocity to build a Jacobian or any embodiment-specific
                mapping. The Cartesian default ignores it (the repulsion
                vectors already carry the direction information).
            pairwise_repulsion_vectors: List of unit-magnitude Cartesian
                repulsion vectors, one per dangerous pair this uid is
                involved in (sign convention: each vector points *away*
                from the partner in that pair). The list has at least
                one element — uids with zero dangerous pairs are not
                routed through this hook.
            bounds: Per-task :class:`Bounds`; how each field caps the
                override is up to the implementation. The Cartesian
                controller uses ``bounds.cartesian_accel_capacity`` to
                L2-cap the saturated direction; the Jacobian controller
                additionally uses ``bounds.action_linf_component`` for
                a post-transform per-joint clip.

        Returns:
            Override action in this uid's control space, ``float64``.
        """
        ...

compute_override

compute_override(
    agent_state: AgentSnapshot,
    pairwise_repulsion_vectors: list[FloatArray],
    bounds: Bounds,
) -> FloatArray

Return the embodiment-specific emergency override (ADR-004 risk-mitigation #1).

Parameters:

• agent_state (AgentSnapshot) –

  This uid's :class:AgentSnapshot at the current control step. Implementations may read position and velocity to build a Jacobian or any embodiment-specific mapping. The Cartesian default ignores it (the repulsion vectors already carry the direction information).

• pairwise_repulsion_vectors (list[FloatArray]) –

  List of unit-magnitude Cartesian repulsion vectors, one per dangerous pair this uid is involved in (sign convention: each vector points away from the partner in that pair). The list has at least one element — uids with zero dangerous pairs are not routed through this hook.

• bounds (Bounds) –

  Per-task :class:Bounds; how each field caps the override is up to the implementation. The Cartesian controller uses bounds.cartesian_accel_capacity to L2-cap the saturated direction; the Jacobian controller additionally uses bounds.action_linf_component for a post-transform per-joint clip.

Returns:

• FloatArray –

  Override action in this uid's control space, float64.

Source code in src/concerto/safety/emergency.py

def compute_override(
    self,
    agent_state: AgentSnapshot,
    pairwise_repulsion_vectors: list[FloatArray],
    bounds: Bounds,
) -> FloatArray:
    """Return the embodiment-specific emergency override (ADR-004 risk-mitigation #1).

    Args:
        agent_state: This uid's :class:`AgentSnapshot` at the current
            control step. Implementations may read position and
            velocity to build a Jacobian or any embodiment-specific
            mapping. The Cartesian default ignores it (the repulsion
            vectors already carry the direction information).
        pairwise_repulsion_vectors: List of unit-magnitude Cartesian
            repulsion vectors, one per dangerous pair this uid is
            involved in (sign convention: each vector points *away*
            from the partner in that pair). The list has at least
            one element — uids with zero dangerous pairs are not
            routed through this hook.
        bounds: Per-task :class:`Bounds`; how each field caps the
            override is up to the implementation. The Cartesian
            controller uses ``bounds.cartesian_accel_capacity`` to
            L2-cap the saturated direction; the Jacobian controller
            additionally uses ``bounds.action_linf_component`` for
            a post-transform per-joint clip.

    Returns:
        Override action in this uid's control space, ``float64``.
    """
    ...

JacobianControlModel dataclass

Jacobian-aware action ↔ Cartesian map skeleton (ADR-004 §Decision; ADR-007 Stage 1 AS).

The 7-DOF arm case for the AS axis. Takes a Jacobian callable jacobian_fn(state) -> J (Cartesian-to-action shape (position_dim, action_dim)) and a damped-least-squares pseudo-inverse for the right-inverse (Nakamura & Hanafusa 1986; the singularity-robust variant the OSCBF inner filter already relies on per Morton & Pavone 2025 §IV).

Stage-1 AS spike will exercise this on the 7-DOF arm; the skeleton raises :class:NotImplementedError on :meth:action_to_cartesian_accel unless a Jacobian callable is supplied via jacobian_fn. The same loud-fail discipline ADR-004 §Risks established for :class:concerto.safety.emergency.JacobianEmergencyController applies here: 7-DOF uids must not silently receive a Cartesian- shaped action by accident.

Attributes:

• uid (str) –

  Unique identifier of the agent.

• action_dim (int) –

  Dimensionality of the action vector (e.g. 7 for a Franka arm).

• position_dim (int) –

  Cartesian dimension of the safety body (typically 3 for manipulation).

• jacobian_fn (Callable[[AgentSnapshot], FloatArray] | None) –

  Optional callable mapping :class:AgentSnapshot to the Jacobian matrix of shape (position_dim, action_dim). When :data:None, both mapping methods raise :class:NotImplementedError.

• damping (float) –

  Damped-least-squares parameter; default :data:DEFAULT_DLS_DAMPING.

• max_cartesian_accel_value (float) –

  Pre-computed scalar capacity (kg-free acceleration units). Defaults to :data:numpy.nan so the placeholder fails loudly on attempted use; supply the embodiment-specific value at construction time.

Source code in src/concerto/safety/api.py

@dataclass
class JacobianControlModel:
    """Jacobian-aware action ↔ Cartesian map skeleton (ADR-004 §Decision; ADR-007 Stage 1 AS).

    The 7-DOF arm case for the AS axis. Takes a Jacobian callable
    ``jacobian_fn(state) -> J`` (Cartesian-to-action shape
    ``(position_dim, action_dim)``) and a damped-least-squares
    pseudo-inverse for the right-inverse (Nakamura & Hanafusa 1986;
    the singularity-robust variant the OSCBF inner filter already
    relies on per Morton & Pavone 2025 §IV).

    Stage-1 AS spike will exercise this on the 7-DOF arm; the
    skeleton raises :class:`NotImplementedError` on
    :meth:`action_to_cartesian_accel` unless a Jacobian callable is
    supplied via ``jacobian_fn``. The same loud-fail discipline
    ADR-004 §Risks established for
    :class:`concerto.safety.emergency.JacobianEmergencyController`
    applies here: 7-DOF uids must not silently receive a Cartesian-
    shaped action by accident.

    Attributes:
        uid: Unique identifier of the agent.
        action_dim: Dimensionality of the action vector (e.g. 7 for
            a Franka arm).
        position_dim: Cartesian dimension of the safety body
            (typically 3 for manipulation).
        jacobian_fn: Optional callable mapping
            :class:`AgentSnapshot` to the Jacobian matrix of shape
            ``(position_dim, action_dim)``. When :data:`None`, both
            mapping methods raise :class:`NotImplementedError`.
        damping: Damped-least-squares parameter; default
            :data:`DEFAULT_DLS_DAMPING`.
        max_cartesian_accel_value: Pre-computed scalar capacity
            (kg-free acceleration units). Defaults to
            :data:`numpy.nan` so the placeholder fails loudly on
            attempted use; supply the embodiment-specific value at
            construction time.
    """

    uid: str
    action_dim: int
    position_dim: int
    jacobian_fn: Callable[[AgentSnapshot], FloatArray] | None = None
    damping: float = DEFAULT_DLS_DAMPING
    max_cartesian_accel_value: float = float("nan")

    def action_to_cartesian_accel(self, state: AgentSnapshot, action: FloatArray) -> FloatArray:
        """Apply ``J(state) @ action`` (ADR-004 §Decision; ADR-007 Stage 1 AS).

        Raises:
            NotImplementedError: When ``jacobian_fn`` was not supplied
                at construction time. Stage-1 AS spike delivers the
                concrete kinematic model; until then 7-DOF uids fail
                loudly per ADR-004 §Risks.
        """
        if self.jacobian_fn is None:
            msg = (
                f"JacobianControlModel(uid={self.uid!r}) has no jacobian_fn; "
                "Stage-1 AS spike (ADR-007 §Stage 1) supplies the kinematic "
                "model. Until then 7-DOF uids must not be routed through the "
                "CBF-QP."
            )
            raise NotImplementedError(msg)
        jac = np.asarray(self.jacobian_fn(state), dtype=np.float64)
        return (jac @ action.astype(np.float64, copy=False)).astype(np.float64, copy=False)

    def cartesian_accel_to_action(
        self, state: AgentSnapshot, cartesian_accel: FloatArray
    ) -> FloatArray:
        """Apply the damped-least-squares pseudo-inverse (ADR-004 §Decision; ADR-007 Stage 1 AS).

        ``J^T (J J^T + damping^2 I)^{-1} a`` — Nakamura & Hanafusa
        1986 singularity-robust right-inverse, identical in form to
        the OSCBF inner filter's Jacobian handling.

        Raises:
            NotImplementedError: When ``jacobian_fn`` was not supplied
                at construction time.
        """
        if self.jacobian_fn is None:
            msg = (
                f"JacobianControlModel(uid={self.uid!r}) has no jacobian_fn; "
                "Stage-1 AS spike (ADR-007 §Stage 1) supplies the kinematic "
                "model. Until then 7-DOF uids must not be routed through the "
                "CBF-QP."
            )
            raise NotImplementedError(msg)
        jac = np.asarray(self.jacobian_fn(state), dtype=np.float64)
        gram = jac @ jac.T + (self.damping * self.damping) * np.eye(
            self.position_dim, dtype=np.float64
        )
        rhs = cartesian_accel.astype(np.float64, copy=False)
        return (jac.T @ np.linalg.solve(gram, rhs)).astype(np.float64, copy=False)

    def max_cartesian_accel(self, bounds: Bounds) -> float:
        """Return the pre-computed Cartesian acceleration capacity (ADR-004 §Decision).

        Raises:
            ValueError: When ``max_cartesian_accel_value`` was left at
                its placeholder :data:`numpy.nan`. Stage-1 AS spike
                supplies the embodiment-specific value.
        """
        del bounds
        if not np.isfinite(self.max_cartesian_accel_value):
            msg = (
                f"JacobianControlModel(uid={self.uid!r}).max_cartesian_accel_value "
                "was not configured. Stage-1 AS spike (ADR-007 §Stage 1) supplies "
                "the embodiment-specific value."
            )
            raise ValueError(msg)
        return float(self.max_cartesian_accel_value)

action_to_cartesian_accel

action_to_cartesian_accel(
    state: AgentSnapshot, action: FloatArray
) -> FloatArray

Apply J(state) @ action (ADR-004 §Decision; ADR-007 Stage 1 AS).

Raises:

• NotImplementedError –

  When jacobian_fn was not supplied at construction time. Stage-1 AS spike delivers the concrete kinematic model; until then 7-DOF uids fail loudly per ADR-004 §Risks.

Source code in src/concerto/safety/api.py

def action_to_cartesian_accel(self, state: AgentSnapshot, action: FloatArray) -> FloatArray:
    """Apply ``J(state) @ action`` (ADR-004 §Decision; ADR-007 Stage 1 AS).

    Raises:
        NotImplementedError: When ``jacobian_fn`` was not supplied
            at construction time. Stage-1 AS spike delivers the
            concrete kinematic model; until then 7-DOF uids fail
            loudly per ADR-004 §Risks.
    """
    if self.jacobian_fn is None:
        msg = (
            f"JacobianControlModel(uid={self.uid!r}) has no jacobian_fn; "
            "Stage-1 AS spike (ADR-007 §Stage 1) supplies the kinematic "
            "model. Until then 7-DOF uids must not be routed through the "
            "CBF-QP."
        )
        raise NotImplementedError(msg)
    jac = np.asarray(self.jacobian_fn(state), dtype=np.float64)
    return (jac @ action.astype(np.float64, copy=False)).astype(np.float64, copy=False)

cartesian_accel_to_action

cartesian_accel_to_action(
    state: AgentSnapshot, cartesian_accel: FloatArray
) -> FloatArray

Apply the damped-least-squares pseudo-inverse (ADR-004 §Decision; ADR-007 Stage 1 AS).

J^T (J J^T + damping^2 I)^{-1} a — Nakamura & Hanafusa 1986 singularity-robust right-inverse, identical in form to the OSCBF inner filter's Jacobian handling.

Raises:

• NotImplementedError –

  When jacobian_fn was not supplied at construction time.

Source code in src/concerto/safety/api.py

def cartesian_accel_to_action(
    self, state: AgentSnapshot, cartesian_accel: FloatArray
) -> FloatArray:
    """Apply the damped-least-squares pseudo-inverse (ADR-004 §Decision; ADR-007 Stage 1 AS).

    ``J^T (J J^T + damping^2 I)^{-1} a`` — Nakamura & Hanafusa
    1986 singularity-robust right-inverse, identical in form to
    the OSCBF inner filter's Jacobian handling.

    Raises:
        NotImplementedError: When ``jacobian_fn`` was not supplied
            at construction time.
    """
    if self.jacobian_fn is None:
        msg = (
            f"JacobianControlModel(uid={self.uid!r}) has no jacobian_fn; "
            "Stage-1 AS spike (ADR-007 §Stage 1) supplies the kinematic "
            "model. Until then 7-DOF uids must not be routed through the "
            "CBF-QP."
        )
        raise NotImplementedError(msg)
    jac = np.asarray(self.jacobian_fn(state), dtype=np.float64)
    gram = jac @ jac.T + (self.damping * self.damping) * np.eye(
        self.position_dim, dtype=np.float64
    )
    rhs = cartesian_accel.astype(np.float64, copy=False)
    return (jac.T @ np.linalg.solve(gram, rhs)).astype(np.float64, copy=False)

max_cartesian_accel

max_cartesian_accel(bounds: Bounds) -> float

Return the pre-computed Cartesian acceleration capacity (ADR-004 §Decision).

Raises:

• ValueError –

  When max_cartesian_accel_value was left at its placeholder :data:numpy.nan. Stage-1 AS spike supplies the embodiment-specific value.

Source code in src/concerto/safety/api.py

def max_cartesian_accel(self, bounds: Bounds) -> float:
    """Return the pre-computed Cartesian acceleration capacity (ADR-004 §Decision).

    Raises:
        ValueError: When ``max_cartesian_accel_value`` was left at
            its placeholder :data:`numpy.nan`. Stage-1 AS spike
            supplies the embodiment-specific value.
    """
    del bounds
    if not np.isfinite(self.max_cartesian_accel_value):
        msg = (
            f"JacobianControlModel(uid={self.uid!r}).max_cartesian_accel_value "
            "was not configured. Stage-1 AS spike (ADR-007 §Stage 1) supplies "
            "the embodiment-specific value."
        )
        raise ValueError(msg)
    return float(self.max_cartesian_accel_value)

JointSafetyFilter

Bases: Protocol

Joint-action filter contract for CENTRALIZED / SHARED_CONTROL (ADR-004 §Public API).

The oracle / ablation baseline mode plus the lab-only co-control mode (ADR-014 three-table report upper-bound row; reviewer P0-3 mode 3). The QP decides every uid's action; per-uid slot widths come from control_models[uid].action_dim (no implicit "first uid's shape" fallback per reviewer P0-2). The structural difference from :class:EgoOnlySafetyFilter is wire-visible: proposed_action is a dict[uid, FloatArray], and the return value's first element is likewise a dict.

The canonical implementations are :meth:concerto.safety.cbf_qp.ExpCBFQP.centralized and :meth:concerto.safety.cbf_qp.ExpCBFQP.shared_control.

Source code in src/concerto/safety/api.py

@runtime_checkable
class JointSafetyFilter(Protocol):
    """Joint-action filter contract for CENTRALIZED / SHARED_CONTROL (ADR-004 §Public API).

    The oracle / ablation baseline mode plus the lab-only co-control
    mode (ADR-014 three-table report upper-bound row; reviewer P0-3
    mode 3). The QP decides every uid's action; per-uid slot widths
    come from ``control_models[uid].action_dim`` (no implicit "first
    uid's shape" fallback per reviewer P0-2). The structural
    difference from :class:`EgoOnlySafetyFilter` is wire-visible:
    ``proposed_action`` is a ``dict[uid, FloatArray]``, and the
    return value's first element is likewise a dict.

    The canonical implementations are
    :meth:`concerto.safety.cbf_qp.ExpCBFQP.centralized` and
    :meth:`concerto.safety.cbf_qp.ExpCBFQP.shared_control`.
    """

    def reset(self, *, seed: int | None = None) -> None:
        """Reset filter state at episode start (ADR-004 §Decision).

        See :meth:`EgoOnlySafetyFilter.reset` for the determinism
        contract (P6 seeding).
        """
        ...

    def filter(
        self,
        proposed_action: dict[str, FloatArray],
        obs: dict[str, object],
        state: SafetyState,
        bounds: Bounds,
        *,
        ego_uid: str | None = None,
        partner_action_bound: float | None = None,
    ) -> tuple[dict[str, FloatArray], FilterInfo]:
        """Project the per-uid nominal actions onto the safe set (ADR-004 §Public API).

        Args:
            proposed_action: Per-agent nominal control inputs, keyed by
                uid. The QP minimises ``||u - u_hat||^2`` with this as
                the reference (Wang-Ames-Egerstedt 2017 eq. 9).
            obs: Observation dict; same contract as
                :meth:`EgoOnlySafetyFilter.filter`.
            state: Mutable :class:`SafetyState`; updated in place by the
                conformal layer each control step.
            bounds: Per-task :class:`Bounds` envelope (ADR-006 §Decision).
            ego_uid: Required for :attr:`SafetyMode.SHARED_CONTROL`,
                ignored for :attr:`SafetyMode.CENTRALIZED`. Identifies
                which uid in ``proposed_action`` is the ego whose
                action is unconstrained by ``partner_action_bound``.
            partner_action_bound: Required for
                :attr:`SafetyMode.SHARED_CONTROL`, ignored for
                :attr:`SafetyMode.CENTRALIZED`. Strictly positive
                L-infinity ball radius around each non-ego uid's
                proposed action.

        Returns:
            A pair ``(safe_action, info)`` matching the input shape
            (one entry per uid in ``proposed_action``).

        Raises:
            ConcertoSafetyInfeasible: When the QP is infeasible even after
                slack relaxation (ADR-004 §Decision; ADR-006 §Risks).
        """
        ...

filter

filter(
    proposed_action: dict[str, FloatArray],
    obs: dict[str, object],
    state: SafetyState,
    bounds: Bounds,
    *,
    ego_uid: str | None = None,
    partner_action_bound: float | None = None,
) -> tuple[dict[str, FloatArray], FilterInfo]

Project the per-uid nominal actions onto the safe set (ADR-004 §Public API).

Parameters:

• proposed_action (dict[str, FloatArray]) –

  Per-agent nominal control inputs, keyed by uid. The QP minimises ||u - u_hat||^2 with this as the reference (Wang-Ames-Egerstedt 2017 eq. 9).

• obs (dict[str, object]) –

  Observation dict; same contract as :meth:EgoOnlySafetyFilter.filter.

• state (SafetyState) –

  Mutable :class:SafetyState; updated in place by the conformal layer each control step.

• bounds (Bounds) –

  Per-task :class:Bounds envelope (ADR-006 §Decision).

• ego_uid (str | None, default: None ) –

  Required for :attr:SafetyMode.SHARED_CONTROL, ignored for :attr:SafetyMode.CENTRALIZED. Identifies which uid in proposed_action is the ego whose action is unconstrained by partner_action_bound.

• partner_action_bound (float | None, default: None ) –

  Required for :attr:SafetyMode.SHARED_CONTROL, ignored for :attr:SafetyMode.CENTRALIZED. Strictly positive L-infinity ball radius around each non-ego uid's proposed action.

Returns:

• dict[str, FloatArray] –

  A pair (safe_action, info) matching the input shape

• FilterInfo –

  (one entry per uid in proposed_action).

Raises:

• ConcertoSafetyInfeasible –

  When the QP is infeasible even after slack relaxation (ADR-004 §Decision; ADR-006 §Risks).

Source code in src/concerto/safety/api.py

def filter(
    self,
    proposed_action: dict[str, FloatArray],
    obs: dict[str, object],
    state: SafetyState,
    bounds: Bounds,
    *,
    ego_uid: str | None = None,
    partner_action_bound: float | None = None,
) -> tuple[dict[str, FloatArray], FilterInfo]:
    """Project the per-uid nominal actions onto the safe set (ADR-004 §Public API).

    Args:
        proposed_action: Per-agent nominal control inputs, keyed by
            uid. The QP minimises ``||u - u_hat||^2`` with this as
            the reference (Wang-Ames-Egerstedt 2017 eq. 9).
        obs: Observation dict; same contract as
            :meth:`EgoOnlySafetyFilter.filter`.
        state: Mutable :class:`SafetyState`; updated in place by the
            conformal layer each control step.
        bounds: Per-task :class:`Bounds` envelope (ADR-006 §Decision).
        ego_uid: Required for :attr:`SafetyMode.SHARED_CONTROL`,
            ignored for :attr:`SafetyMode.CENTRALIZED`. Identifies
            which uid in ``proposed_action`` is the ego whose
            action is unconstrained by ``partner_action_bound``.
        partner_action_bound: Required for
            :attr:`SafetyMode.SHARED_CONTROL`, ignored for
            :attr:`SafetyMode.CENTRALIZED`. Strictly positive
            L-infinity ball radius around each non-ego uid's
            proposed action.

    Returns:
        A pair ``(safe_action, info)`` matching the input shape
        (one entry per uid in ``proposed_action``).

    Raises:
        ConcertoSafetyInfeasible: When the QP is infeasible even after
            slack relaxation (ADR-004 §Decision; ADR-006 §Risks).
    """
    ...

reset

reset(*, seed: int | None = None) -> None

Reset filter state at episode start (ADR-004 §Decision).

See :meth:EgoOnlySafetyFilter.reset for the determinism contract (P6 seeding).

Source code in src/concerto/safety/api.py

def reset(self, *, seed: int | None = None) -> None:
    """Reset filter state at episode start (ADR-004 §Decision).

    See :meth:`EgoOnlySafetyFilter.reset` for the determinism
    contract (P6 seeding).
    """
    ...

SafetyMode

Bases: Enum

Safety-filter operating mode (ADR-004 §Decision; spike_004A §Three-mode taxonomy).

Three modes make the filter's who is being optimised contract explicit at the constructor site, so callsites cannot accidentally request the oracle solve at deployment (reviewer P0-3):

• :attr:EGO_ONLY — deployment default. QP decision variable is the ego agent's action only; the partner's motion enters as a predicted disturbance on the constraint RHS. This is the ad-hoc / black-box-partner setting ADR-006 §Decision pins.
• :attr:CENTRALIZED — oracle / ablation only. QP decision variable is the concatenation of every uid's action, with per-uid slot widths set by control_models[uid].action_dim (no implicit "first uid's shape" fallback). Used as the upper-bound baseline in ADR-014's three-table report. Never used at evaluation against ad-hoc partners.
• :attr:SHARED_CONTROL — lab-only baseline (reviewer P0-3 mode 3). Same shape as :attr:CENTRALIZED with an additional partner_action_bound parameter that restricts the partner's adjustment magnitude. Measures how much of the centralised headroom comes from co-control budget vs from partner co-operation.

Mode is a constructor argument, not a per-call flag: the conformal slack vector SafetyState.lambda_ is sized per pair, and the pair set differs between :attr:EGO_ONLY (one row per partner) and :attr:CENTRALIZED (full pairwise table). Flipping mode mid-episode would silently invalidate the conformal state. A mode change requires constructing a new filter with a fresh :class:SafetyState.

Source code in src/concerto/safety/api.py

class SafetyMode(Enum):
    """Safety-filter operating mode (ADR-004 §Decision; spike_004A §Three-mode taxonomy).

    Three modes make the filter's *who is being optimised* contract
    explicit at the constructor site, so callsites cannot accidentally
    request the oracle solve at deployment (reviewer P0-3):

    - :attr:`EGO_ONLY` — **deployment default.** QP decision variable is
      the ego agent's action only; the partner's motion enters as a
      predicted disturbance on the constraint RHS. This is the
      ad-hoc / black-box-partner setting ADR-006 §Decision pins.
    - :attr:`CENTRALIZED` — oracle / ablation only. QP decision variable
      is the concatenation of every uid's action, with per-uid slot
      widths set by ``control_models[uid].action_dim`` (no implicit
      "first uid's shape" fallback). Used as the upper-bound baseline
      in ADR-014's three-table report. Never used at evaluation
      against ad-hoc partners.
    - :attr:`SHARED_CONTROL` — lab-only baseline (reviewer P0-3 mode 3).
      Same shape as :attr:`CENTRALIZED` with an additional
      ``partner_action_bound`` parameter that restricts the partner's
      adjustment magnitude. Measures how much of the centralised
      headroom comes from co-control budget vs from partner
      co-operation.

    Mode is a **constructor argument**, not a per-call flag: the
    conformal slack vector ``SafetyState.lambda_`` is sized per pair,
    and the pair set differs between :attr:`EGO_ONLY` (one row per
    partner) and :attr:`CENTRALIZED` (full pairwise table). Flipping
    mode mid-episode would silently invalidate the conformal state.
    A mode change requires constructing a new filter with a fresh
    :class:`SafetyState`.
    """

    EGO_ONLY = "ego_only"
    CENTRALIZED = "centralized"
    SHARED_CONTROL = "shared_control"

SafetyState dataclass

Mutable conformal CBF state (Huriot & Sibai 2025 §IV; ADR-004 §Decision).

The conformal slack dict lambda_ carries one entry per agent pair, keyed by a lexicographically-ordered UID tuple (uid_a, uid_b) with uid_a < uid_b. Each entry is updated each control step by :func:concerto.safety.conformal.update_lambda according to Theorem 3's rule lambda_{k+1} = lambda_k + eta * (eps - l_k). ADR-004 risk-mitigation #2 motivates the partner-swap warmup window: on partner identity change (detected via obs["meta"]["partner_id"]) the state is reset to lambda_safe (the value guaranteeing QP feasibility under the worst-case bounded prediction error per ADR-006 Assumption A2) and the next warmup_steps_remaining steps run with a tighter eps.

Issue #144 / ADR-014 v3 (2026-05-19) promoted lambda_ from a canonical-pair-order-indexed :class:numpy.ndarray to a :data:LambdaDict keyed by canonical UID-pair tuples. The structural fix subsumes the implicit pair-index alignment invariant the prior Phase-0 amendment (canonical_pair_order) enforced via runtime asserts: a caller that rebuilds the snapshot dict in a different insertion order still keys into the same canonical tuple, so per-pair slack cannot silently misalign with the pairwise CBF constraint.

Attributes:

• lambda_ (LambdaDict) –

  Per-pair slack as a :data:LambdaDict. Construct via :func:make_lambda_dict (or directly when the canonical pair set is already in hand). Mutated in place by :func:concerto.safety.conformal.update_lambda.

• epsilon (float) –

  Target average loss. ADR-004 §Decision pins the default to -0.05 (conservative manipulation regime).

• eta (float) –

  Conformal learning rate (default 0.01).

• warmup_steps_remaining (int) –

  Decremented each step while in warmup; zero outside the warmup window (ADR-004 risk-mitigation #2).

Source code in src/concerto/safety/api.py

@dataclass
class SafetyState:
    """Mutable conformal CBF state (Huriot & Sibai 2025 §IV; ADR-004 §Decision).

    The conformal slack dict ``lambda_`` carries one entry per agent
    pair, keyed by a lexicographically-ordered UID tuple
    ``(uid_a, uid_b)`` with ``uid_a < uid_b``. Each entry is updated
    each control step by
    :func:`concerto.safety.conformal.update_lambda` according to
    Theorem 3's rule
    ``lambda_{k+1} = lambda_k + eta * (eps - l_k)``. ADR-004
    risk-mitigation #2 motivates the partner-swap warmup window: on
    partner identity change (detected via ``obs["meta"]["partner_id"]``)
    the state is reset to ``lambda_safe`` (the value guaranteeing QP
    feasibility under the worst-case bounded prediction error per ADR-006
    Assumption A2) and the next ``warmup_steps_remaining`` steps run with
    a tighter eps.

    Issue #144 / ADR-014 v3 (2026-05-19) promoted ``lambda_`` from a
    canonical-pair-order-indexed :class:`numpy.ndarray` to a
    :data:`LambdaDict` keyed by canonical UID-pair tuples. The
    structural fix subsumes the implicit pair-index alignment
    invariant the prior Phase-0 amendment (canonical_pair_order)
    enforced via runtime asserts: a caller that rebuilds the snapshot
    dict in a different insertion order still keys into the same
    canonical tuple, so per-pair slack cannot silently misalign with
    the pairwise CBF constraint.

    Attributes:
        lambda_: Per-pair slack as a :data:`LambdaDict`. Construct
            via :func:`make_lambda_dict` (or directly when the canonical
            pair set is already in hand). Mutated in place by
            :func:`concerto.safety.conformal.update_lambda`.
        epsilon: Target average loss. ADR-004 §Decision pins the default
            to ``-0.05`` (conservative manipulation regime).
        eta: Conformal learning rate (default ``0.01``).
        warmup_steps_remaining: Decremented each step while in warmup;
            zero outside the warmup window (ADR-004 risk-mitigation #2).
    """

    lambda_: LambdaDict
    epsilon: float = DEFAULT_EPSILON
    eta: float = DEFAULT_ETA
    warmup_steps_remaining: int = 0

__getattr__

__getattr__(name: str) -> object

Re-export the deprecated :data:SafetyFilter alias from the api submodule.

Forwards the lookup so from concerto.safety import SafetyFilter surfaces the same :class:DeprecationWarning as from concerto.safety.api import SafetyFilter. ADR-004 §Public API; spike_004A §Three-mode taxonomy.

Source code in src/concerto/safety/__init__.py

def __getattr__(name: str) -> object:
    """Re-export the deprecated :data:`SafetyFilter` alias from the api submodule.

    Forwards the lookup so ``from concerto.safety import SafetyFilter``
    surfaces the same :class:`DeprecationWarning` as ``from
    concerto.safety.api import SafetyFilter``. ADR-004 §Public API;
    spike_004A §Three-mode taxonomy.
    """
    if name in _DEPRECATED_NAMES:
        return getattr(_api, name)
    msg = f"module {__name__!r} has no attribute {name!r}"
    raise AttributeError(msg)

canonical_pair_key

canonical_pair_key(a: str, b: str) -> tuple[str, str]

Return the lexicographically-ordered pair key for (a, b) (ADR-004 §Decision; issue #144).

The canonical key for any agent pair is the unique 2-tuple of UIDs sorted lexicographically. Callers that already know the canonical order (e.g. a nested loop with the outer uid lex-smaller than the inner) can build the tuple directly; this helper is for sites that take an unordered (uid_a, uid_b) pair (e.g. EGO_ONLY mode's (ego_uid, partner_uid) rows, where neither side is guaranteed to be lex-smaller) and need the canonical lookup key for :data:LambdaDict indexing.

Parameters:

• a (str) –

  First UID.

• b (str) –

  Second UID (must differ from a).

Returns:

• tuple[str, str] –

  (a, b) if a < b lexicographically, otherwise (b, a).

Raises:

• ValueError –

  If a == b (an agent pair always has two distinct UIDs).

Source code in src/concerto/safety/api.py

def canonical_pair_key(a: str, b: str) -> tuple[str, str]:
    """Return the lexicographically-ordered pair key for ``(a, b)`` (ADR-004 §Decision; issue #144).

    The canonical key for any agent pair is the unique 2-tuple of UIDs
    sorted lexicographically. Callers that already know the canonical
    order (e.g. a nested loop with the outer uid lex-smaller than the
    inner) can build the tuple directly; this helper is for sites that
    take an unordered ``(uid_a, uid_b)`` pair (e.g. EGO_ONLY mode's
    ``(ego_uid, partner_uid)`` rows, where neither side is guaranteed
    to be lex-smaller) and need the canonical lookup key for
    :data:`LambdaDict` indexing.

    Args:
        a: First UID.
        b: Second UID (must differ from ``a``).

    Returns:
        ``(a, b)`` if ``a < b`` lexicographically, otherwise ``(b, a)``.

    Raises:
        ValueError: If ``a == b`` (an agent pair always has two
            distinct UIDs).
    """
    if a == b:
        msg = f"canonical_pair_key requires distinct UIDs; got {a!r} == {b!r}"
        raise ValueError(msg)
    return (a, b) if a < b else (b, a)

canonical_pair_order

canonical_pair_order(uids: Iterable[str]) -> list[str]

Canonical lexicographic UID order for pair iteration (ADR-004 §Decision).

Public utility used by the three pair-iteration entry points (:func:concerto.safety.conformal.compute_prediction_gap_for_pairs, :meth:concerto.safety.cbf_qp.ExpCBFQP._filter_ego_only, and :meth:concerto.safety.cbf_qp.ExpCBFQP._filter_joint); third-party consumers building their own pair-iteration code over the safety stack should call this helper to stay aligned with the same canonical ordering :class:SafetyState lambda_ is indexed against. Returns a list of the UIDs sorted lexicographically; downstream code iterates upper-triangular pairs (uids[i], uids[j]) for i < j so the pair index for any (uid_a, uid_b) (with uid_a < uid_b lexicographically) is stable across callers and across dict reconstruction (external-review P1, 2026-05-16).

Post-issue-#144 the structural fix (lambda_: LambdaDict) makes the pair-keying part of the type system: lookups go via the lexicographic tuple key produced by :func:canonical_pair_key, and callers no longer rely on the canonical ordering to index a flat array. The helper is retained as a primitive because the upper-triangular pair iteration in :func:make_pair_keys and the cbf_qp call-sites still needs a deterministic uid ordering to build the canonical set of pair tuples.

Parameters:

• uids (Iterable[str]) –

  An iterable of agent UIDs.

Returns:

• list[str] –

  A new list containing the UIDs sorted lexicographically.

Raises:

• ValueError –

  If the iterable contains duplicates (a partner-set invariant the upstream filter already enforces, surfaced here as a defensive check).

Source code in src/concerto/safety/api.py

def canonical_pair_order(uids: Iterable[str]) -> list[str]:
    """Canonical lexicographic UID order for pair iteration (ADR-004 §Decision).

    Public utility used by the three pair-iteration entry points
    (:func:`concerto.safety.conformal.compute_prediction_gap_for_pairs`,
    :meth:`concerto.safety.cbf_qp.ExpCBFQP._filter_ego_only`, and
    :meth:`concerto.safety.cbf_qp.ExpCBFQP._filter_joint`); third-party
    consumers building their own pair-iteration code over the safety
    stack should call this helper to stay aligned with the same
    canonical ordering :class:`SafetyState` ``lambda_`` is indexed
    against. Returns
    a list of the UIDs sorted lexicographically; downstream code
    iterates upper-triangular pairs ``(uids[i], uids[j]) for i < j``
    so the pair index for any ``(uid_a, uid_b)`` (with
    ``uid_a < uid_b`` lexicographically) is stable across callers and
    across dict reconstruction (external-review P1, 2026-05-16).

    Post-issue-#144 the structural fix (``lambda_: LambdaDict``) makes
    the pair-keying part of the type system: lookups go via the
    lexicographic tuple key produced by :func:`canonical_pair_key`, and
    callers no longer rely on the canonical ordering to index a flat
    array. The helper is retained as a primitive because the
    upper-triangular pair iteration in
    :func:`make_pair_keys` and the cbf_qp call-sites still needs a
    deterministic uid ordering to build the canonical set of pair
    tuples.

    Args:
        uids: An iterable of agent UIDs.

    Returns:
        A new list containing the UIDs sorted lexicographically.

    Raises:
        ValueError: If the iterable contains duplicates (a partner-set
            invariant the upstream filter already enforces, surfaced
            here as a defensive check).
    """
    out = sorted(uids)
    if len(set(out)) != len(out):
        msg = f"duplicate uids in pair iteration: {out!r}"
        raise ValueError(msg)
    return out

lambda_from_jsonable

lambda_from_jsonable(
    payload: object, *, uids: Iterable[str] | None = None
) -> LambdaDict

Deserialise a :data:LambdaDict from a JSON-decoded payload (ADR-014 §Decision; issue #144).

Accepts either:

• v3 (current) — a list of structured entries [{"a": uid_a, "b": uid_b, "value": λ}, ...] as produced by :func:lambda_to_jsonable. Each entry's pair is canonicalised via :func:canonical_pair_key so a misordered (b, a) entry on the wire is rebuilt under the canonical (a, b) key.
• v2 (legacy) — a flat list / sequence of floats of length n*(n-1)/2 plus an explicit uids keyword. The values are assumed to be indexed in the canonical pair-iteration order (the implicit invariant that issue #144 closed by promoting to a dict). Reading this form emits a :class:DeprecationWarning and the legacy reader is targeted for removal in v0.6.0.

Parameters:

• payload (object) –

  The JSON-decoded structure (list of dicts for v3, or a list of floats for v2).

• uids (Iterable[str] | None, default: None ) –

  Required for v2; ignored for v3. The UID set whose canonical pair order indexed the legacy ndarray.

Returns:

• LambdaDict –

  A fresh :data:LambdaDict.

Raises:

• TypeError –

  When payload is neither a v3 structured list nor a v2 flat float list, or v2 was passed without uids.

• ValueError –

  When a v3 entry lists a == b (canonical pair keys always have distinct UIDs), or the v2 length does not match the canonical pair count for uids.

Source code in src/concerto/safety/api.py

def lambda_from_jsonable(
    payload: object,
    *,
    uids: Iterable[str] | None = None,
) -> LambdaDict:
    """Deserialise a :data:`LambdaDict` from a JSON-decoded payload (ADR-014 §Decision; issue #144).

    Accepts either:

    - **v3 (current)** — a list of structured entries
      ``[{"a": uid_a, "b": uid_b, "value": λ}, ...]`` as produced by
      :func:`lambda_to_jsonable`. Each entry's pair is canonicalised
      via :func:`canonical_pair_key` so a misordered ``(b, a)`` entry
      on the wire is rebuilt under the canonical ``(a, b)`` key.
    - **v2 (legacy)** — a flat list / sequence of floats of length
      ``n*(n-1)/2`` plus an explicit ``uids`` keyword. The values are
      assumed to be indexed in the canonical pair-iteration order
      (the implicit invariant that issue #144 closed by promoting to
      a dict). Reading this form emits a :class:`DeprecationWarning`
      and the legacy reader is targeted for removal in v0.6.0.

    Args:
        payload: The JSON-decoded structure (list of dicts for v3, or
            a list of floats for v2).
        uids: Required for v2; ignored for v3. The UID set whose
            canonical pair order indexed the legacy ndarray.

    Returns:
        A fresh :data:`LambdaDict`.

    Raises:
        TypeError: When ``payload`` is neither a v3 structured list
            nor a v2 flat float list, or v2 was passed without
            ``uids``.
        ValueError: When a v3 entry lists ``a == b`` (canonical pair
            keys always have distinct UIDs), or the v2 length does
            not match the canonical pair count for ``uids``.
    """
    if not isinstance(payload, list):
        msg = f"lambda_from_jsonable: expected list payload, got {type(payload).__name__}"
        raise TypeError(msg)
    payload_list: list[Any] = payload  # type: ignore[assignment]
    if payload_list and isinstance(payload_list[0], dict):
        # v3 structured-entry form.
        out: LambdaDict = {}
        for entry in payload_list:
            if not isinstance(entry, dict):
                msg = f"lambda_from_jsonable: v3 entries must be dicts; got {type(entry).__name__}"
                raise TypeError(msg)
            entry_dict: dict[str, Any] = entry  # type: ignore[assignment]
            a = str(entry_dict["a"])
            b = str(entry_dict["b"])
            key = canonical_pair_key(a, b)
            out[key] = float(entry_dict["value"])
        return out
    # v2 legacy ndarray / flat-float-list form.
    if uids is None:
        msg = (
            "lambda_from_jsonable: legacy v2 ndarray payload requires the "
            "explicit ``uids`` keyword (the canonical pair order that "
            "indexed the array). Issue #144 closed the implicit-order "
            "invariant; the v2 reader is deprecated and targeted for "
            "removal in v0.6.0."
        )
        raise TypeError(msg)
    warnings.warn(
        "lambda_from_jsonable: legacy v2 (ndarray) payload — pair-keying "
        "via implicit canonical-pair-order is deprecated in favour of the "
        "v3 structured-list form. Targeted for removal in v0.6.0; see "
        "issue #144 + ADR-014 §Revision history.",
        DeprecationWarning,
        stacklevel=2,
    )
    keys = make_pair_keys(uids)
    if len(payload_list) != len(keys):
        msg = (
            f"lambda_from_jsonable: v2 payload length {len(payload_list)} does "
            f"not match the canonical pair count {len(keys)} for the given "
            f"UID set."
        )
        raise ValueError(msg)
    return {key: float(value) for key, value in zip(keys, payload_list, strict=True)}

lambda_to_jsonable

lambda_to_jsonable(d: LambdaDict) -> list[dict[str, Any]]

Serialise a :data:LambdaDict for JSON round-trip (ADR-014 §Decision; issue #144).

JSON does not have tuple keys natively. The structured list form [{"a": uid_a, "b": uid_b, "value": λ}, ...] is the canonical wire encoding for v3 :data:LambdaDict payloads — pair-keys are explicit named fields rather than stringified tuples, so a reader cannot accidentally split or rejoin the pair on the wrong delimiter.

Parameters:

• d (LambdaDict) –

  A :data:LambdaDict.

Returns:

• list[dict[str, Any]] –

  A list of plain-dict entries with "a", "b", and

• list[dict[str, Any]] –

  "value" fields, ordered by the canonical pair-key order

• from ( list[dict[str, Any]] ) –

  func:make_pair_keys over the dict's UID set so the

• list[dict[str, Any]] –

  wire encoding is determinstic.

Source code in src/concerto/safety/api.py

def lambda_to_jsonable(d: LambdaDict) -> list[dict[str, Any]]:
    """Serialise a :data:`LambdaDict` for JSON round-trip (ADR-014 §Decision; issue #144).

    JSON does not have tuple keys natively. The structured list form
    ``[{"a": uid_a, "b": uid_b, "value": λ}, ...]`` is the canonical
    wire encoding for v3 :data:`LambdaDict` payloads — pair-keys are
    explicit named fields rather than stringified tuples, so a reader
    cannot accidentally split or rejoin the pair on the wrong
    delimiter.

    Args:
        d: A :data:`LambdaDict`.

    Returns:
        A list of plain-dict entries with ``"a"``, ``"b"``, and
        ``"value"`` fields, ordered by the canonical pair-key order
        from :func:`make_pair_keys` over the dict's UID set so the
        wire encoding is determinstic.
    """
    uids: set[str] = set()
    for a, b in d:
        uids.add(a)
        uids.add(b)
    payload: list[dict[str, Any]] = []
    for a, b in make_pair_keys(uids):
        if (a, b) not in d:
            continue
        payload.append({"a": a, "b": b, "value": float(d[(a, b)])})
    return payload

make_lambda_dict

make_lambda_dict(
    uids: Iterable[str], *, fill: float = 0.0
) -> LambdaDict

Construct a :data:LambdaDict over the canonical pair set (ADR-004 §Decision; issue #144).

The convenience constructor for :class:SafetyState's lambda_ field. Each canonical pair-key produced by :func:make_pair_keys maps to fill; callers seed every pair to the same scalar (typically the warm-start lambda_safe from :func:concerto.safety.conformal.reset_on_partner_swap) and the conformal layer updates entries in place per step.

Parameters:

• uids (Iterable[str]) –

  Iterable of agent UIDs.

• fill (float, default: 0.0 ) –

  Initial per-pair value (default 0.0).

Returns:

• LambdaDict –

  A fresh :data:LambdaDict with one entry per canonical pair.

Source code in src/concerto/safety/api.py

def make_lambda_dict(uids: Iterable[str], *, fill: float = 0.0) -> LambdaDict:
    """Construct a :data:`LambdaDict` over the canonical pair set (ADR-004 §Decision; issue #144).

    The convenience constructor for :class:`SafetyState`'s ``lambda_``
    field. Each canonical pair-key produced by :func:`make_pair_keys`
    maps to ``fill``; callers seed every pair to the same scalar
    (typically the warm-start ``lambda_safe`` from
    :func:`concerto.safety.conformal.reset_on_partner_swap`) and the
    conformal layer updates entries in place per step.

    Args:
        uids: Iterable of agent UIDs.
        fill: Initial per-pair value (default ``0.0``).

    Returns:
        A fresh :data:`LambdaDict` with one entry per canonical pair.
    """
    return {key: float(fill) for key in make_pair_keys(uids)}

make_pair_keys

make_pair_keys(
    uids: Iterable[str],
) -> list[tuple[str, str]]

Build the canonical upper-triangular pair-key list (ADR-004 §Decision; issue #144).

Returns the list of (uid_i, uid_j) tuples with i < j over the lexicographically-sorted UID order produced by :func:canonical_pair_order. Used by :func:make_lambda_dict, the cbf_qp call-sites, and any other consumer that needs to enumerate the canonical pair set for a uid collection.

Parameters:

• uids (Iterable[str]) –

  Iterable of agent UIDs (must not contain duplicates).

Returns:

• list[tuple[str, str]] –

  A new list of pair-key tuples in canonical iteration order

• list[tuple[str, str]] –

  (outer loop over lex-sorted uids, inner loop over the

• list[tuple[str, str]] –

  suffix). The list length is n*(n-1)/2 for n distinct

• list[tuple[str, str]] –

  uids.

Source code in src/concerto/safety/api.py

def make_pair_keys(uids: Iterable[str]) -> list[tuple[str, str]]:
    """Build the canonical upper-triangular pair-key list (ADR-004 §Decision; issue #144).

    Returns the list of ``(uid_i, uid_j)`` tuples with ``i < j`` over
    the lexicographically-sorted UID order produced by
    :func:`canonical_pair_order`. Used by :func:`make_lambda_dict`,
    the cbf_qp call-sites, and any other consumer that needs to
    enumerate the canonical pair set for a uid collection.

    Args:
        uids: Iterable of agent UIDs (must not contain duplicates).

    Returns:
        A new list of pair-key tuples in canonical iteration order
        (outer loop over lex-sorted uids, inner loop over the
        suffix). The list length is ``n*(n-1)/2`` for ``n`` distinct
        uids.
    """
    sorted_uids = canonical_pair_order(uids)
    pairs: list[tuple[str, str]] = []
    for i, a in enumerate(sorted_uids):
        pairs.extend((a, b) for b in sorted_uids[i + 1 :])
    return pairs

solve_qp_stub

solve_qp_stub(
    *args: object, **kwargs: object
) -> tuple[float, float]

Real CBF-QP benchmark solve (T3.10; ADR-004 §"OSCBF target").

T3.10 replaces M2's no-op stub with an actual Clarabel solve on a small representative QP. The function name is preserved for backward compatibility with tests/property/test_qp_saturation.py (the M2 acceptance gate) per plan/03 §8 + the M3 brief Hard Rule

4: the saturation guard's regime check (drop_rate >= 10 % or

latency >= 100 ms; ADR-006 §Risks R5) is independent of the QP body, so after replacement it still fires only at the URLLC saturation profile, not at lossy.

The QP is pre-built at module load and the solver instance is module-level so the per-call hot path is just the Clarabel solve — no allocation or instantiation overhead. The *args / **kwargs signature is preserved for the saturation_guard contract (callers pass no args; the placeholder forwarding kept the signature open for future per-call inputs).

Parameters:

• *args (object, default: () ) –

  Ignored (M2 backward-compat surface).

• **kwargs (object, default: {} ) –

  Ignored.

Returns:

• float –

  (decision_norm, elapsed_seconds) matching the M2 stub

• float –

  contract; the M2 saturation guard reads only the timing

• tuple[float, float] –

  envelope so the decision value is informational.

Source code in src/concerto/safety/__init__.py

def solve_qp_stub(*args: object, **kwargs: object) -> tuple[float, float]:
    """Real CBF-QP benchmark solve (T3.10; ADR-004 §"OSCBF target").

    T3.10 replaces M2's no-op stub with an actual Clarabel solve on a
    small representative QP. The function name is preserved for
    backward compatibility with ``tests/property/test_qp_saturation.py``
    (the M2 acceptance gate) per plan/03 §8 + the M3 brief Hard Rule
    #4: the saturation guard's regime check (drop_rate >= 10 % or
    latency >= 100 ms; ADR-006 §Risks R5) is independent of the QP
    body, so after replacement it still fires only at the URLLC
    ``saturation`` profile, not at ``lossy``.

    The QP is pre-built at module load and the solver instance is
    module-level so the per-call hot path is just the Clarabel solve
    — no allocation or instantiation overhead. The ``*args`` /
    ``**kwargs`` signature is preserved for the ``saturation_guard``
    contract (callers pass no args; the placeholder forwarding kept
    the signature open for future per-call inputs).

    Args:
        *args: Ignored (M2 backward-compat surface).
        **kwargs: Ignored.

    Returns:
        ``(decision_norm, elapsed_seconds)`` matching the M2 stub
        contract; the M2 saturation guard reads only the timing
        envelope so the decision value is informational.
    """
    del args, kwargs
    x, ms = _BENCH_SOLVER.solve(_BENCH_P, _BENCH_Q, _BENCH_A, _BENCH_B)
    return float(np.linalg.norm(x)), ms / 1000.0

concerto.training

CONCERTO training stack — ego-AHT HAPPO wrapper + seeding + logging.

Implements the frozen-partner ego-AHT training algorithm from ADR-002 using the HARL fork (ADR-002 §"HARL dependency"). The seeding module provides the determinism harness required by project principle P6.

CheckStatus

Bases: Enum

Outcome taxonomy for :class:SlopeReport (ADR-002 §Risks #1; review P1-2).

Replaces the pre-amendment binary passed: bool shape so callers can distinguish "trip-wire cleared" from "data too short" from "curve contained NaN / inf". The legacy passed boolean is preserved for v0.5.x backwards-compat but is derived from status; passed = status is CheckStatus.PASSED.

Values

PASSED: slope > 0 and p_value < alpha. FAILED: Slope non-positive (flat or regressing) OR p-value above alpha. INSUFFICIENT_DATA: Curve has fewer than min_episodes entries. The pre-amendment code returned passed=True here (vacuous-pass-on-short-curves bug, external-review P1-2); the new branch returns this status with passed=False so consumers do not silently consume a too-short curve as a passing trip-wire. INVALID: Curve contains NaN or +/- inf. The pre-amendment code would crash inside scipy.stats.linregress (on NaN) or silently propagate inf through the slope; the new branch detects them up front and returns this status with passed=False.

Source code in src/concerto/training/learning_signal_check.py

class CheckStatus(Enum):
    """Outcome taxonomy for :class:`SlopeReport` (ADR-002 §Risks #1; review P1-2).

    Replaces the pre-amendment binary ``passed: bool`` shape so callers
    can distinguish "trip-wire cleared" from "data too short" from
    "curve contained NaN / inf". The legacy ``passed`` boolean is
    preserved for v0.5.x backwards-compat but is derived from
    ``status``; ``passed = status is CheckStatus.PASSED``.

    Values:
        PASSED: ``slope > 0`` and ``p_value < alpha``.
        FAILED: Slope non-positive (flat or regressing) OR p-value
            above ``alpha``.
        INSUFFICIENT_DATA: Curve has fewer than ``min_episodes``
            entries. The pre-amendment code returned ``passed=True``
            here (vacuous-pass-on-short-curves bug, external-review
            P1-2); the new branch returns this status with
            ``passed=False`` so consumers do not silently consume a
            too-short curve as a passing trip-wire.
        INVALID: Curve contains NaN or +/- inf. The pre-amendment code
            would crash inside ``scipy.stats.linregress`` (on NaN) or
            silently propagate inf through the slope; the new branch
            detects them up front and returns this status with
            ``passed=False``.
    """

    PASSED = "passed"
    FAILED = "failed"
    INSUFFICIENT_DATA = "insufficient_data"
    INVALID = "invalid"

GuaranteeReport dataclass

Result of one moving-window non-decreasing-fraction check (T4b.13; ADR-002 §Risks #1).

The dataclass is frozen so a returned report cannot be mutated after the fact (the project's reproducibility contract: provenance bundles are immutable). Serialise to JSON via :func:dataclasses.asdict (used by :func:plot_reward_curve).

The "Guarantee" in the name is a legacy label held over from the pre-rename empirical_guarantee module — the value is a trip-wire, not a formal guarantee; see the module docstring + :class:CheckStatus for the renamed canonical taxonomy. The dataclass name is preserved for v0.5.x backwards-compat with consumers that import it directly.

Attributes:

• window (int) –

  Moving-average window length the report was computed against (default :data:DEFAULT_WINDOW).

• threshold (float) –

  Pass threshold the report was checked against (default :data:DEFAULT_THRESHOLD).

• n_intervals (int) –

  Number of consecutive-window-pair intervals examined. Equals max(len(curve) - window, 0) for a non-degenerate run; zero when the curve is empty or shorter than window.

• n_nondecreasing (int) –

  Count of intervals whose later-window mean is >= the earlier-window mean.

• fraction (float) –

  n_nondecreasing / n_intervals when n_intervals > 0; 1.0 (vacuously) when n_intervals == 0 so callers can treat the degenerate case uniformly.

• passed (bool) –

  fraction >= threshold. Vacuously True when n_intervals == 0 (the curve was too short to assert anything; the assertion is documented as vacuous in that regime).

Source code in src/concerto/training/learning_signal_check.py

@dataclass(frozen=True)
class GuaranteeReport:
    """Result of one moving-window non-decreasing-fraction check (T4b.13; ADR-002 §Risks #1).

    The dataclass is frozen so a returned report cannot be mutated after
    the fact (the project's reproducibility contract: provenance bundles
    are immutable). Serialise to JSON via :func:`dataclasses.asdict`
    (used by :func:`plot_reward_curve`).

    The "Guarantee" in the name is a legacy label held over from the
    pre-rename ``empirical_guarantee`` module — the value is a
    trip-wire, not a formal guarantee; see the module docstring +
    :class:`CheckStatus` for the renamed canonical taxonomy. The
    dataclass name is preserved for v0.5.x backwards-compat with
    consumers that import it directly.

    Attributes:
        window: Moving-average window length the report was computed
            against (default :data:`DEFAULT_WINDOW`).
        threshold: Pass threshold the report was checked against (default
            :data:`DEFAULT_THRESHOLD`).
        n_intervals: Number of consecutive-window-pair intervals examined.
            Equals ``max(len(curve) - window, 0)`` for a non-degenerate
            run; zero when the curve is empty or shorter than ``window``.
        n_nondecreasing: Count of intervals whose later-window mean is
            ``>=`` the earlier-window mean.
        fraction: ``n_nondecreasing / n_intervals`` when ``n_intervals > 0``;
            ``1.0`` (vacuously) when ``n_intervals == 0`` so callers can
            treat the degenerate case uniformly.
        passed: ``fraction >= threshold``. Vacuously ``True`` when
            ``n_intervals == 0`` (the curve was too short to assert
            anything; the assertion is documented as vacuous in that
            regime).
    """

    window: int
    threshold: float
    n_intervals: int
    n_nondecreasing: int
    fraction: float
    passed: bool

SlopeReport dataclass

Result of one slope-test learning-signal check (T4b.13; ADR-002 §Risks #1).

Captures everything an external reader needs to interpret the trip-wire outcome without re-running the experiment: the least-squares slope itself, the coefficient of determination, the one-sided p-value, the alpha threshold the run was checked against, the number of episodes the regression saw, the :class:CheckStatus taxon, and the deprecated passed boolean (kept for v0.5.x backwards-compat).

The dataclass is frozen so a returned report cannot be mutated after the fact (the project's reproducibility contract: provenance bundles are immutable). Serialise to JSON via :func:dataclasses.asdict (used by :func:plot_slope_curve).

Attributes:

• slope (float) –

  Least-squares slope of per-episode reward versus episode index, in reward-units-per-episode. Positive ⇒ learning; zero or negative ⇒ no learning or regressing.

• intercept (float) –

  Least-squares intercept. Useful for the regression overlay in :func:plot_slope_curve and as a sanity check on the early-rollout reward scale.

• r_squared (float) –

  Coefficient of determination R². Low R² plus status=PASSED is acceptable on noisy tasks (the slope is still statistically significant); the project does not gate on R² directly.

• p_value (float) –

  One-sided p-value for the null "slope <= 0", computed as two_sided_p / 2 when the observed slope is positive and 1 - two_sided_p / 2 when non-positive. The two-sided p-value comes from :func:scipy.stats.linregress.

• alpha (float) –

  Significance threshold the check was run against (default :data:DEFAULT_ALPHA).

• n_episodes (int) –

  Number of episodes in the regressed curve. Below :data:DEFAULT_MIN_EPISODES the report carries :attr:CheckStatus.INSUFFICIENT_DATA.

• status (CheckStatus) –

  Outcome taxon (:class:CheckStatus). Canonical signal; new code should branch on this, not on passed.

• passed (bool) –

  Deprecated — derived from status (passed == status is CheckStatus.PASSED). Kept for v0.5.x consumers; removal target v0.6.0. Construction emits a :class:DeprecationWarning in __post_init__.

Source code in src/concerto/training/learning_signal_check.py

@dataclass(frozen=True)
class SlopeReport:
    """Result of one slope-test learning-signal check (T4b.13; ADR-002 §Risks #1).

    Captures everything an external reader needs to interpret the
    trip-wire outcome without re-running the experiment: the
    least-squares slope itself, the coefficient of determination, the
    one-sided p-value, the alpha threshold the run was checked against,
    the number of episodes the regression saw, the :class:`CheckStatus`
    taxon, and the deprecated ``passed`` boolean (kept for v0.5.x
    backwards-compat).

    The dataclass is frozen so a returned report cannot be mutated after
    the fact (the project's reproducibility contract: provenance bundles
    are immutable). Serialise to JSON via :func:`dataclasses.asdict`
    (used by :func:`plot_slope_curve`).

    Attributes:
        slope: Least-squares slope of per-episode reward versus episode
            index, in reward-units-per-episode. Positive ⇒ learning;
            zero or negative ⇒ no learning or regressing.
        intercept: Least-squares intercept. Useful for the regression
            overlay in :func:`plot_slope_curve` and as a sanity check
            on the early-rollout reward scale.
        r_squared: Coefficient of determination ``R²``. Low ``R²`` plus
            ``status=PASSED`` is acceptable on noisy tasks (the slope is
            still statistically significant); the project does not gate
            on ``R²`` directly.
        p_value: One-sided p-value for the null "slope <= 0", computed
            as ``two_sided_p / 2`` when the observed slope is positive
            and ``1 - two_sided_p / 2`` when non-positive. The
            two-sided p-value comes from
            :func:`scipy.stats.linregress`.
        alpha: Significance threshold the check was run against
            (default :data:`DEFAULT_ALPHA`).
        n_episodes: Number of episodes in the regressed curve. Below
            :data:`DEFAULT_MIN_EPISODES` the report carries
            :attr:`CheckStatus.INSUFFICIENT_DATA`.
        status: Outcome taxon (:class:`CheckStatus`). Canonical signal;
            new code should branch on this, not on ``passed``.
        passed: **Deprecated** — derived from ``status`` (``passed ==
            status is CheckStatus.PASSED``). Kept for v0.5.x consumers;
            removal target v0.6.0. Construction emits a
            :class:`DeprecationWarning` in ``__post_init__``.
    """

    slope: float
    intercept: float
    r_squared: float
    p_value: float
    alpha: float
    n_episodes: int
    status: CheckStatus
    passed: bool = False

    def __post_init__(self) -> None:
        """Derive ``passed`` from ``status`` + emit the field-deprecation warning.

        Two side effects, in order:

        1. ``passed`` is recomputed from ``status`` so the two cannot
           drift even when a caller supplies an inconsistent value
           (e.g. while round-tripping a legacy v1 JSON payload that
           has ``passed`` but no ``status``); the (rare) override uses
           ``object.__setattr__`` because the dataclass is frozen.
        2. A :class:`DeprecationWarning` is emitted **unconditionally,
           on every construction**, signalling that the ``passed`` field
           itself is deprecated. The warning fires whether or not the
           caller supplied ``passed`` explicitly — the goal is to flag
           the *field* to consumers, not just inconsistent inputs. New
           code should branch on ``report.status is CheckStatus.PASSED``
           and ignore ``passed`` entirely; ``passed`` is removed in
           v0.6.0 along with this ``__post_init__`` warning.
        """
        derived = self.status is CheckStatus.PASSED
        if self.passed != derived:
            object.__setattr__(self, "passed", derived)
        warnings.warn(
            "SlopeReport.passed is deprecated; use "
            "`report.status is CheckStatus.PASSED` instead "
            "(removal target: v0.6.0; external-review P1-1/P1-2, "
            "2026-05-16).",
            DeprecationWarning,
            stacklevel=3,
        )

__post_init__

__post_init__() -> None

Derive passed from status + emit the field-deprecation warning.

Two side effects, in order:

1. passed is recomputed from status so the two cannot drift even when a caller supplies an inconsistent value (e.g. while round-tripping a legacy v1 JSON payload that has passed but no status); the (rare) override uses object.__setattr__ because the dataclass is frozen.
2. A :class:DeprecationWarning is emitted unconditionally, on every construction, signalling that the passed field itself is deprecated. The warning fires whether or not the caller supplied passed explicitly — the goal is to flag the field to consumers, not just inconsistent inputs. New code should branch on report.status is CheckStatus.PASSED and ignore passed entirely; passed is removed in v0.6.0 along with this __post_init__ warning.

Source code in src/concerto/training/learning_signal_check.py

def __post_init__(self) -> None:
    """Derive ``passed`` from ``status`` + emit the field-deprecation warning.

    Two side effects, in order:

    1. ``passed`` is recomputed from ``status`` so the two cannot
       drift even when a caller supplies an inconsistent value
       (e.g. while round-tripping a legacy v1 JSON payload that
       has ``passed`` but no ``status``); the (rare) override uses
       ``object.__setattr__`` because the dataclass is frozen.
    2. A :class:`DeprecationWarning` is emitted **unconditionally,
       on every construction**, signalling that the ``passed`` field
       itself is deprecated. The warning fires whether or not the
       caller supplied ``passed`` explicitly — the goal is to flag
       the *field* to consumers, not just inconsistent inputs. New
       code should branch on ``report.status is CheckStatus.PASSED``
       and ignore ``passed`` entirely; ``passed`` is removed in
       v0.6.0 along with this ``__post_init__`` warning.
    """
    derived = self.status is CheckStatus.PASSED
    if self.passed != derived:
        object.__setattr__(self, "passed", derived)
    warnings.warn(
        "SlopeReport.passed is deprecated; use "
        "`report.status is CheckStatus.PASSED` instead "
        "(removal target: v0.6.0; external-review P1-1/P1-2, "
        "2026-05-16).",
        DeprecationWarning,
        stacklevel=3,
    )

assert_non_decreasing_window

assert_non_decreasing_window(
    curve: RewardCurve,
    *,
    window: int = DEFAULT_WINDOW,
    threshold: float = DEFAULT_THRESHOLD,
) -> GuaranteeReport

Check the moving-window-of-K mean for non-decreasing intervals (ADR-002 §Risks #1).

Slides a window of length window over curve.per_episode_ego_rewards and counts the fraction of consecutive interval pairs whose later-window mean is >= the earlier-window mean. A run is considered to have cleared the trip-wire when that fraction is >= threshold.

Plan/05 §6 criterion 4 names the canonical setting: window=10, threshold=0.8. Callers MUST NOT silently widen the window or lower the threshold to coerce a passing report — if the assertion fires under the production config, hand control back to the maintainer and open a #scope-revision issue (ADR-002 §Risks

1 mitigation policy).

Degenerate inputs (empty curve, len(curve) < window) return a report with n_intervals=0 and passed=True. The pass is vacuous — there is not enough signal to assert anything — and is only useful as a sentinel for unit tests of the helper itself; do not rely on it to mask a too-short production run. The canonical slope test :func:check_positive_learning_slope resolves this vacuous-pass class of failure (external-review P1-2) by returning CheckStatus.INSUFFICIENT_DATA with passed=False on too-short curves.

Parameters:

• curve (RewardCurve) –

  The reward curve produced by :func:concerto.training.ego_aht.train. Only the per_episode_ego_rewards field is read; the per-step series is deliberately ignored because the assertion is episode-aggregated (Huriot-Sibai 2025 Theorem 7 is stated over the policy-improvement step, which lives at episode granularity).

• window (int, default: DEFAULT_WINDOW ) –

  Window size (default :data:DEFAULT_WINDOW).

• threshold (float, default: DEFAULT_THRESHOLD ) –

  Pass threshold on the non-decreasing fraction (default :data:DEFAULT_THRESHOLD).

Returns:

• Frozen ( GuaranteeReport ) –

  class:GuaranteeReport. Does NOT raise on failure — the

• GuaranteeReport –

  caller decides whether to fail the test, exit the CLI non-zero,

• GuaranteeReport –

  or just log the report.

Source code in src/concerto/training/learning_signal_check.py

def assert_non_decreasing_window(
    curve: RewardCurve,
    *,
    window: int = DEFAULT_WINDOW,
    threshold: float = DEFAULT_THRESHOLD,
) -> GuaranteeReport:
    """Check the moving-window-of-K mean for non-decreasing intervals (ADR-002 §Risks #1).

    Slides a window of length ``window`` over ``curve.per_episode_ego_rewards``
    and counts the fraction of consecutive interval pairs whose later-window
    mean is ``>=`` the earlier-window mean. A run is considered to have
    cleared the trip-wire when that fraction is ``>= threshold``.

    Plan/05 §6 criterion 4 names the canonical setting:
    ``window=10, threshold=0.8``. Callers MUST NOT silently widen the
    window or lower the threshold to coerce a passing report — if the
    assertion fires under the production config, hand control back to
    the maintainer and open a ``#scope-revision`` issue (ADR-002 §Risks
    #1 mitigation policy).

    Degenerate inputs (empty curve, ``len(curve) < window``) return a
    report with ``n_intervals=0`` and ``passed=True``. The pass is
    *vacuous* — there is not enough signal to assert anything — and is
    only useful as a sentinel for unit tests of the helper itself; do
    not rely on it to mask a too-short production run. The canonical
    slope test :func:`check_positive_learning_slope` resolves this
    vacuous-pass class of failure (external-review P1-2) by returning
    ``CheckStatus.INSUFFICIENT_DATA`` with ``passed=False`` on
    too-short curves.

    Args:
        curve: The reward curve produced by
            :func:`concerto.training.ego_aht.train`. Only the
            ``per_episode_ego_rewards`` field is read; the per-step
            series is deliberately ignored because the assertion is
            episode-aggregated (Huriot-Sibai 2025 Theorem 7 is stated
            over the policy-improvement step, which lives at episode
            granularity).
        window: Window size (default :data:`DEFAULT_WINDOW`).
        threshold: Pass threshold on the non-decreasing fraction
            (default :data:`DEFAULT_THRESHOLD`).

    Returns:
        Frozen :class:`GuaranteeReport`. Does NOT raise on failure — the
        caller decides whether to fail the test, exit the CLI non-zero,
        or just log the report.
    """
    rewards = list(curve.per_episode_ego_rewards)
    if len(rewards) < window or window <= 0:
        return GuaranteeReport(
            window=window,
            threshold=threshold,
            n_intervals=0,
            n_nondecreasing=0,
            fraction=1.0,
            passed=True,
        )
    means: list[float] = []
    running_sum = sum(rewards[:window])
    means.append(running_sum / window)
    for i in range(window, len(rewards)):
        running_sum += rewards[i] - rewards[i - window]
        means.append(running_sum / window)
    n_intervals = len(means) - 1
    n_nondecreasing = sum(1 for prev, nxt in pairwise(means) if nxt >= prev)
    fraction = n_nondecreasing / n_intervals if n_intervals > 0 else 1.0
    return GuaranteeReport(
        window=window,
        threshold=threshold,
        n_intervals=n_intervals,
        n_nondecreasing=n_nondecreasing,
        fraction=fraction,
        passed=fraction >= threshold,
    )

check_positive_learning_slope

check_positive_learning_slope(
    curve: RewardCurve,
    *,
    alpha: float = DEFAULT_ALPHA,
    min_episodes: int = DEFAULT_MIN_EPISODES,
) -> SlopeReport

Least-squares slope check on per-episode reward (ADR-002 §Risks #1; canonical).

Renames the pre-amendment assert_positive_learning_slope (the "assert" verb overclaimed — the function returns a report rather than raising, and the slope check is a trip-wire for ADR-002 §Risks #1, not a formal monotonic-improvement guarantee). The old name remains available via a deprecation shim at concerto.training.empirical_guarantee.assert_positive_learning_slope; removal target v0.6.0.

Issue #62 root-cause writeup: the legacy :func:assert_non_decreasing_window statistic has poor signal-to- noise on per-episode rewards at the Phase-0 100k-frame budget — the moving-window-of-10 mean stdev (~6.3) is comparable to the total drift (~10-20 reward units) the trainer can produce, and the non-decreasing-fraction sits near 0.5 (a random walk) even when the policy is materially improving. The slope check integrates over the whole curve and rejects the null "slope <= 0" with p-values astronomically below any reasonable alpha when learning is real.

The check:

1. Validate the curve. NaN / +/- inf ⇒ :attr:CheckStatus.INVALID immediately.
2. If n < min_episodes ⇒ :attr:CheckStatus.INSUFFICIENT_DATA with passed=False. (Pre-amendment code returned passed=True here; external-review P1-2 flagged this as silently masking too-short curves.)
3. Fit rewards ~ slope * episode_index + intercept via least squares (:func:scipy.stats.linregress).
4. Take the one-sided p-value: two_sided / 2 when the observed slope is positive, otherwise 1 - two_sided / 2. (scipy reports two-sided by default; the one-sided form is the natural gate for "positive learning".)
5. Pass when slope > 0 AND p_value < alpha ⇒ :attr:CheckStatus.PASSED. Else :attr:CheckStatus.FAILED.

Plan/05 §6 criterion 4 uses alpha=0.05 as the canonical threshold; the project's production config gives p_value < 1e-14 across seeds, so the gate has very wide margin.

Parameters:

• curve (RewardCurve) –

  The reward curve produced by :func:concerto.training.ego_aht.train. Only per_episode_ego_rewards is read.

• alpha (float, default: DEFAULT_ALPHA ) –

  One-sided significance threshold. Default :data:DEFAULT_ALPHA.

• min_episodes (int, default: DEFAULT_MIN_EPISODES ) –

  Minimum episode count for a non-vacuous report. Below this the report carries :attr:CheckStatus.INSUFFICIENT_DATA. Default :data:DEFAULT_MIN_EPISODES.

Returns:

• Frozen ( SlopeReport ) –

  class:SlopeReport. Does NOT raise on failure — the

• SlopeReport –

  caller decides whether to fail the test, exit the CLI non-zero,

• SlopeReport –

  or just log the report.

Source code in src/concerto/training/learning_signal_check.py

def check_positive_learning_slope(
    curve: RewardCurve,
    *,
    alpha: float = DEFAULT_ALPHA,
    min_episodes: int = DEFAULT_MIN_EPISODES,
) -> SlopeReport:
    """Least-squares slope check on per-episode reward (ADR-002 §Risks #1; canonical).

    Renames the pre-amendment ``assert_positive_learning_slope`` (the
    "assert" verb overclaimed — the function returns a report rather
    than raising, and the slope check is a *trip-wire* for ADR-002
    §Risks #1, not a formal monotonic-improvement guarantee). The old
    name remains available via a deprecation shim at
    ``concerto.training.empirical_guarantee.assert_positive_learning_slope``;
    removal target v0.6.0.

    Issue #62 root-cause writeup: the legacy
    :func:`assert_non_decreasing_window` statistic has poor signal-to-
    noise on per-episode rewards at the Phase-0 100k-frame budget — the
    moving-window-of-10 mean stdev (~6.3) is comparable to the total
    drift (~10-20 reward units) the trainer can produce, and the
    non-decreasing-fraction sits near 0.5 (a random walk) even when the
    policy is materially improving. The slope check integrates over the
    whole curve and rejects the null "slope <= 0" with p-values
    astronomically below any reasonable alpha when learning is real.

    The check:

    1. Validate the curve. NaN / +/- inf ⇒
       :attr:`CheckStatus.INVALID` immediately.
    2. If ``n < min_episodes`` ⇒ :attr:`CheckStatus.INSUFFICIENT_DATA`
       with ``passed=False``. (Pre-amendment code returned
       ``passed=True`` here; external-review P1-2 flagged this as
       silently masking too-short curves.)
    3. Fit ``rewards ~ slope * episode_index + intercept`` via least
       squares (:func:`scipy.stats.linregress`).
    4. Take the one-sided p-value: ``two_sided / 2`` when the observed
       slope is positive, otherwise ``1 - two_sided / 2``. (scipy
       reports two-sided by default; the one-sided form is the natural
       gate for "positive learning".)
    5. Pass when ``slope > 0`` AND ``p_value < alpha`` ⇒
       :attr:`CheckStatus.PASSED`. Else :attr:`CheckStatus.FAILED`.

    Plan/05 §6 criterion 4 uses ``alpha=0.05`` as the canonical
    threshold; the project's production config gives ``p_value < 1e-14``
    across seeds, so the gate has very wide margin.

    Args:
        curve: The reward curve produced by
            :func:`concerto.training.ego_aht.train`. Only
            ``per_episode_ego_rewards`` is read.
        alpha: One-sided significance threshold. Default
            :data:`DEFAULT_ALPHA`.
        min_episodes: Minimum episode count for a non-vacuous report.
            Below this the report carries
            :attr:`CheckStatus.INSUFFICIENT_DATA`. Default
            :data:`DEFAULT_MIN_EPISODES`.

    Returns:
        Frozen :class:`SlopeReport`. Does NOT raise on failure — the
        caller decides whether to fail the test, exit the CLI non-zero,
        or just log the report.
    """
    rewards = np.asarray(list(curve.per_episode_ego_rewards), dtype=np.float64)
    n = int(rewards.shape[0])

    # 1. Validate. NaN / +/- inf surface as INVALID before any solver
    # path touches the array.
    if n > 0 and not np.all(np.isfinite(rewards)):
        return SlopeReport(
            slope=0.0,
            intercept=0.0,
            r_squared=0.0,
            p_value=1.0,
            alpha=alpha,
            n_episodes=n,
            status=CheckStatus.INVALID,
        )

    # 2. Insufficient data. Replaces the pre-amendment vacuous-pass
    # branch (external-review P1-2) that returned passed=True.
    if n < min_episodes:
        return SlopeReport(
            slope=0.0,
            intercept=0.0,
            r_squared=0.0,
            p_value=1.0,
            alpha=alpha,
            n_episodes=n,
            status=CheckStatus.INSUFFICIENT_DATA,
        )

    # 3-5. Slope regression. Zero-variance y is a degenerate case that
    # scipy.stats.linregress rejects, so handle it ahead of the call
    # and emit FAILED (the slope is not strictly positive).
    if float(rewards.std()) == 0.0:
        return SlopeReport(
            slope=0.0,
            intercept=float(rewards[0]) if n > 0 else 0.0,
            r_squared=0.0,
            p_value=1.0,
            alpha=alpha,
            n_episodes=n,
            status=CheckStatus.FAILED,
        )
    x = np.arange(n, dtype=np.float64)
    result = stats.linregress(x, rewards)
    slope = float(result.slope)
    intercept = float(result.intercept)
    r_squared = float(result.rvalue) ** 2
    two_sided_p = float(result.pvalue)
    p_value = two_sided_p / 2.0 if slope > 0.0 else 1.0 - two_sided_p / 2.0
    status = CheckStatus.PASSED if slope > 0.0 and p_value < alpha else CheckStatus.FAILED
    return SlopeReport(
        slope=slope,
        intercept=intercept,
        r_squared=r_squared,
        p_value=p_value,
        alpha=alpha,
        n_episodes=n,
        status=status,
    )

plot_reward_curve

plot_reward_curve(
    curve: RewardCurve,
    *,
    report: GuaranteeReport,
    out_dir: Path,
) -> tuple[Path, Path]

Emit <run_id>.png + <run_id>.json for the assertion plot (T4b.13; ADR-002 §Risks #1).

Writes two files under out_dir:

• <run_id>.png: matplotlib line plot of the per-episode reward with the moving-window-of-report.window mean overlaid. The report's fraction / passed are stamped into the title so docs/explanation/why-aht.md can embed the figure unchanged.
• <run_id>.json: machine-replayable sidecar carrying the raw per-episode curve + the report. A future reader regenerates the figure by replaying the JSON through this function.

matplotlib is imported lazily inside the function so the surrounding module stays importable in environments without the viz extra (Phase-0 CI, headless containers). Callers that need the plot must install the viz extra (uv sync --extra viz).

Parameters:

• curve (RewardCurve) –

  The reward curve produced by :func:concerto.training.ego_aht.train. curve.run_id is used as the filename stem.

• report (GuaranteeReport) –

  The :class:GuaranteeReport produced by :func:assert_non_decreasing_window. Stamped into the figure title and copied into the JSON sidecar.

• out_dir (Path) –

  Output directory. Created if missing.

Returns:

• Path –

  (png_path, json_path) tuple — the absolute paths of the two

• Path –

  emitted files.

Source code in src/concerto/training/learning_signal_check.py

def plot_reward_curve(
    curve: RewardCurve,
    *,
    report: GuaranteeReport,
    out_dir: Path,
) -> tuple[Path, Path]:
    """Emit ``<run_id>.png`` + ``<run_id>.json`` for the assertion plot (T4b.13; ADR-002 §Risks #1).

    Writes two files under ``out_dir``:

    - ``<run_id>.png``: matplotlib line plot of the per-episode reward
      with the moving-window-of-``report.window`` mean overlaid. The
      report's ``fraction`` / ``passed`` are stamped into the title so
      ``docs/explanation/why-aht.md`` can embed the figure unchanged.
    - ``<run_id>.json``: machine-replayable sidecar carrying the raw
      per-episode curve + the report. A future reader regenerates the
      figure by replaying the JSON through this function.

    ``matplotlib`` is imported lazily inside the function so the
    surrounding module stays importable in environments without the
    ``viz`` extra (Phase-0 CI, headless containers). Callers that need
    the plot must install the ``viz`` extra (``uv sync --extra viz``).

    Args:
        curve: The reward curve produced by
            :func:`concerto.training.ego_aht.train`. ``curve.run_id``
            is used as the filename stem.
        report: The :class:`GuaranteeReport` produced by
            :func:`assert_non_decreasing_window`. Stamped into the figure
            title and copied into the JSON sidecar.
        out_dir: Output directory. Created if missing.

    Returns:
        ``(png_path, json_path)`` tuple — the absolute paths of the two
        emitted files.
    """
    import matplotlib  # noqa: PLC0415

    matplotlib.use("Agg", force=True)
    import matplotlib.pyplot as plt  # noqa: PLC0415

    out_dir.mkdir(parents=True, exist_ok=True)
    rewards = list(curve.per_episode_ego_rewards)

    fig, ax = plt.subplots(figsize=(8, 4.5))
    if rewards:
        ax.plot(range(len(rewards)), rewards, label="per-episode ego reward", alpha=0.4)
        if len(rewards) >= report.window > 0:
            running_sum = sum(rewards[: report.window])
            means: list[float] = [running_sum / report.window]
            for i in range(report.window, len(rewards)):
                running_sum += rewards[i] - rewards[i - report.window]
                means.append(running_sum / report.window)
            ax.plot(
                range(report.window - 1, len(rewards)),
                means,
                label=f"moving mean (window={report.window})",
                linewidth=2,
            )
    ax.set_xlabel("episode index")
    ax.set_ylabel("ego reward (sum over episode)")
    status = "PASS" if report.passed else "FAIL"
    ax.set_title(
        f"Learning-signal check (moving window) — run {curve.run_id} — {status} "
        f"({report.n_nondecreasing}/{report.n_intervals} "
        f"non-decreasing, threshold={report.threshold:.2f})"
    )
    if rewards:
        ax.legend(loc="lower right")
    ax.grid(visible=True, alpha=0.3)
    fig.tight_layout()
    png_path = out_dir / f"{curve.run_id}.png"
    fig.savefig(png_path, dpi=120)
    plt.close(fig)

    json_path = out_dir / f"{curve.run_id}.json"
    json_path.write_text(
        json.dumps(
            {
                "run_id": curve.run_id,
                "per_episode_ego_rewards": rewards,
                "report": asdict(report),
            },
            sort_keys=True,
            indent=2,
        ),
        encoding="utf-8",
    )
    return png_path, json_path

plot_slope_curve

plot_slope_curve(
    curve: RewardCurve,
    *,
    report: SlopeReport,
    out_dir: Path,
) -> tuple[Path, Path]

Emit <run_id>.png + <run_id>.json for the slope plot (T4b.13; ADR-002 §Risks #1).

Mirrors :func:plot_reward_curve's contract but overlays the least-squares regression line instead of the moving-window mean. The status line in the title carries the slope, p-value, status, and pass/fail flag so docs/explanation/why-aht.md can embed the figure unchanged.

Parameters:

• curve (RewardCurve) –

  The reward curve produced by :func:concerto.training.ego_aht.train. curve.run_id is the filename stem.

• report (SlopeReport) –

  The :class:SlopeReport produced by :func:check_positive_learning_slope. Stamped into the figure title and copied into the JSON sidecar.

• out_dir (Path) –

  Output directory. Created if missing.

Returns:

• Path –

  (png_path, json_path) tuple — the absolute paths of the two

• Path –

  emitted files.

Source code in src/concerto/training/learning_signal_check.py

def plot_slope_curve(
    curve: RewardCurve,
    *,
    report: SlopeReport,
    out_dir: Path,
) -> tuple[Path, Path]:
    """Emit ``<run_id>.png`` + ``<run_id>.json`` for the slope plot (T4b.13; ADR-002 §Risks #1).

    Mirrors :func:`plot_reward_curve`'s contract but overlays the
    least-squares regression line instead of the moving-window mean.
    The status line in the title carries the slope, p-value, status,
    and pass/fail flag so ``docs/explanation/why-aht.md`` can embed
    the figure unchanged.

    Args:
        curve: The reward curve produced by
            :func:`concerto.training.ego_aht.train`. ``curve.run_id``
            is the filename stem.
        report: The :class:`SlopeReport` produced by
            :func:`check_positive_learning_slope`. Stamped into the
            figure title and copied into the JSON sidecar.
        out_dir: Output directory. Created if missing.

    Returns:
        ``(png_path, json_path)`` tuple — the absolute paths of the two
        emitted files.
    """
    import matplotlib  # noqa: PLC0415

    matplotlib.use("Agg", force=True)
    import matplotlib.pyplot as plt  # noqa: PLC0415

    out_dir.mkdir(parents=True, exist_ok=True)
    rewards = list(curve.per_episode_ego_rewards)

    fig, ax = plt.subplots(figsize=(8, 4.5))
    if rewards:
        x = list(range(len(rewards)))
        ax.plot(x, rewards, label="per-episode ego reward", alpha=0.35)
        ax.plot(
            x,
            [report.slope * xi + report.intercept for xi in x],
            label=(
                f"least-squares slope = {report.slope:+.4f}/episode (R²={report.r_squared:.3f})"
            ),
            linewidth=2,
        )
    ax.set_xlabel("episode index")
    ax.set_ylabel("ego reward (sum over episode)")
    status_label = report.status.name
    ax.set_title(
        f"Learning-signal check (slope) — run {curve.run_id} — {status_label} "
        f"(p={report.p_value:.2e}, alpha={report.alpha:.2g}, "
        f"n={report.n_episodes})"
    )
    if rewards:
        ax.legend(loc="lower right")
    ax.grid(visible=True, alpha=0.3)
    fig.tight_layout()
    png_path = out_dir / f"{curve.run_id}.png"
    fig.savefig(png_path, dpi=120)
    plt.close(fig)

    json_path = out_dir / f"{curve.run_id}.json"
    json_path.write_text(
        json.dumps(
            {
                "run_id": curve.run_id,
                "per_episode_ego_rewards": rewards,
                "report": asdict(report),
            },
            sort_keys=True,
            indent=2,
            default=lambda o: o.value if isinstance(o, Enum) else str(o),
        ),
        encoding="utf-8",
    )
    return png_path, json_path

Deterministic seeding harness for CONCERTO (P6 reproducibility).

Every randomised piece of CONCERTO and CHAMBER (env wrappers, comm channel, partner zoo, training loop) draws from a numpy Generator seeded via :func:derive_substream. The function maps a (name, root_seed) pair to a fresh Substream whose RNG is independent of every other named substream under the same root seed; reusing the same pair always returns byte-identical draws.

Cited as ADR-002 §"deterministic seeding harness" (training stack) and ADR-003 §Decision (the comm channel uses derive_substream("comm.fixed", ...) to seed its substream).

Substream dataclass

Wraps a numpy SeedSequence with convenience constructors (P6).

ADR-002 §"deterministic seeding harness". The frozen dataclass makes the substream identity hashable; equality is structural over the underlying seed-sequence's entropy + spawn key, which is enough for caching.

Source code in src/concerto/training/seeding.py

@dataclass(frozen=True)
class Substream:
    """Wraps a numpy ``SeedSequence`` with convenience constructors (P6).

    ADR-002 §"deterministic seeding harness". The frozen dataclass makes the
    substream identity hashable; equality is structural over the underlying
    seed-sequence's entropy + spawn key, which is enough for caching.
    """

    seed_sequence: np.random.SeedSequence

    def default_rng(self) -> np.random.Generator:
        """Construct a fresh numpy ``Generator`` from this substream (P6).

        ADR-002 §"deterministic seeding harness". Two calls return independent
        generators that produce identical sequences when freshly built — i.e.,
        the substream is a *seed factory*, not an iterator.
        """
        return np.random.default_rng(self.seed_sequence)

    def spawn(self, n: int) -> list[Substream]:
        """Spawn ``n`` independent child substreams (P6).

        ADR-002 §"deterministic seeding harness". Use when a producer needs
        per-worker / per-episode RNG without colliding with sibling streams.
        """
        return [Substream(seed_sequence=child) for child in self.seed_sequence.spawn(n)]

default_rng

default_rng() -> np.random.Generator

Construct a fresh numpy Generator from this substream (P6).

ADR-002 §"deterministic seeding harness". Two calls return independent generators that produce identical sequences when freshly built — i.e., the substream is a seed factory, not an iterator.

Source code in src/concerto/training/seeding.py

def default_rng(self) -> np.random.Generator:
    """Construct a fresh numpy ``Generator`` from this substream (P6).

    ADR-002 §"deterministic seeding harness". Two calls return independent
    generators that produce identical sequences when freshly built — i.e.,
    the substream is a *seed factory*, not an iterator.
    """
    return np.random.default_rng(self.seed_sequence)

spawn

spawn(n: int) -> list[Substream]

Spawn n independent child substreams (P6).

ADR-002 §"deterministic seeding harness". Use when a producer needs per-worker / per-episode RNG without colliding with sibling streams.

Source code in src/concerto/training/seeding.py

def spawn(self, n: int) -> list[Substream]:
    """Spawn ``n`` independent child substreams (P6).

    ADR-002 §"deterministic seeding harness". Use when a producer needs
    per-worker / per-episode RNG without colliding with sibling streams.
    """
    return [Substream(seed_sequence=child) for child in self.seed_sequence.spawn(n)]

derive_substream

derive_substream(
    name: str, *, root_seed: int = 0
) -> Substream

Derive a deterministic named substream from a root seed (P6).

ADR-002 §"deterministic seeding harness"; ADR-003 §Decision (the comm channel uses derive_substream("comm.fixed", root_seed=...)).

Parameters:

• name (str) –

  Stable label for the substream. Distinct names yield independent RNG streams under the same root_seed; reusing the pair (name, root_seed) always returns byte-identical draws.

• root_seed (int, default: 0 ) –

  Project-wide root seed. Defaults to 0 so call sites can ship working defaults; production runs override per-experiment.

Returns:

• A ( Substream ) –

  class:Substream whose :meth:Substream.default_rng is the

• Substream –

  canonical entry-point for downstream randomness.

Source code in src/concerto/training/seeding.py

def derive_substream(name: str, *, root_seed: int = 0) -> Substream:
    """Derive a deterministic named substream from a root seed (P6).

    ADR-002 §"deterministic seeding harness"; ADR-003 §Decision (the comm
    channel uses ``derive_substream("comm.fixed", root_seed=...)``).

    Args:
        name: Stable label for the substream. Distinct names yield independent
            RNG streams under the same ``root_seed``; reusing the pair
            ``(name, root_seed)`` always returns byte-identical draws.
        root_seed: Project-wide root seed. Defaults to 0 so call sites can
            ship working defaults; production runs override per-experiment.

    Returns:
        A :class:`Substream` whose :meth:`Substream.default_rng` is the
        canonical entry-point for downstream randomness.
    """
    seed_seq = np.random.SeedSequence(
        entropy=root_seed,
        spawn_key=_name_to_spawn_key(name),
    )
    return Substream(seed_sequence=seed_seq)

Structured logging for ego-AHT training runs (ADR-002 §Decisions; plan/05 §2).

Every line emitted during a training run carries the RunContext fields (run_id, seed, git_sha, pyproject_hash) plus a per-event step so any line in any artefact can be traced back to the exact code + config + RNG state that produced it. Phase-0 ships two sinks:

• A local JSONL file (logs/<run_id>.jsonl) — the offline-replayable fallback that does not depend on W&B being reachable. Every JSONL line is a self-contained valid JSON object.
• An opt-in :class:wandb.sdk.wandb_run.Run sink — the caller passes a pre-constructed run object as the wandb_sink kwarg of :func:bind_run_logger. Phase-0 uses W&B's offline mode in tests so the sink can be exercised without a network round-trip. The four :class:RunContext provenance fields are written to W&B's config once at bind time (via :meth:WandbSink.set_config) rather than to every metric event, so they appear as run-level metadata rather than scalar metrics.

Determinism: :func:compute_run_metadata derives run_id from (seed, git_sha, pyproject_hash, run_kind) so two reruns with identical code + config + seed produce the same run_id (P6 reproducibility). The pyproject_hash is the SHA-256 of the project's pyproject.toml so a silent dependency drift produces a different run_id.

RunContext dataclass

Per-run provenance bundle bound to every log line (ADR-002 §Decisions; plan/05 §2; P6).

Attributes:

• run_id (str) –

  Stable 16-hex-char hash derived from the other four fields via :func:compute_run_metadata. Used as the JSONL filename and as the W&B run name so artefacts collated by run_id from different sinks describe the same run.

• seed (int) –

  Project-wide root seed; ego-AHT runs derive every RNG substream from this via :func:concerto.training.seeding.derive_substream.

• git_sha (str) –

  Full SHA of the commit checked out at the first resolution in this process (the launch SHA; resolved once per process per repo root — issue #227, ADR-002 §Revision history 2026-06-12), or :data:GIT_SHA_UNKNOWN when the working tree is not a git repository or the git binary is missing.

• pyproject_hash (str) –

  SHA-256 of pyproject.toml (full hex digest). A silent dependency drift produces a different hash and therefore a different run_id.

• run_kind (str) –

  Free-form label describing what this run is for (e.g. "empirical_guarantee", "zoo_seed"). Folded into the run_id hash so two distinct kinds at the same seed do not collide.

• extra (dict[str, str]) –

  Optional free-form string-string metadata attached to every log line (e.g. task name, partner class). Read-only by convention; defaults to empty dict.

Source code in src/concerto/training/logging.py

@dataclass(frozen=True)
class RunContext:
    """Per-run provenance bundle bound to every log line (ADR-002 §Decisions; plan/05 §2; P6).

    Attributes:
        run_id: Stable 16-hex-char hash derived from the other four fields
            via :func:`compute_run_metadata`. Used as the JSONL filename
            and as the W&B run name so artefacts collated by ``run_id``
            from different sinks describe the same run.
        seed: Project-wide root seed; ego-AHT runs derive every RNG
            substream from this via :func:`concerto.training.seeding.derive_substream`.
        git_sha: Full SHA of the commit checked out at the *first*
            resolution in this process (the launch SHA; resolved once
            per process per repo root — issue #227, ADR-002 §Revision
            history 2026-06-12), or :data:`GIT_SHA_UNKNOWN` when the
            working tree is not a git repository or the ``git`` binary
            is missing.
        pyproject_hash: SHA-256 of ``pyproject.toml`` (full hex digest).
            A silent dependency drift produces a different hash and
            therefore a different ``run_id``.
        run_kind: Free-form label describing what this run is for (e.g.
            ``"empirical_guarantee"``, ``"zoo_seed"``). Folded into the
            ``run_id`` hash so two distinct kinds at the same seed do not
            collide.
        extra: Optional free-form string-string metadata attached to every
            log line (e.g. task name, partner class). Read-only by
            convention; defaults to empty dict.
    """

    run_id: str
    seed: int
    git_sha: str
    pyproject_hash: str
    run_kind: str
    extra: dict[str, str] = field(default_factory=dict)
    #: Optional safety-stack telemetry summary (P1.04.5; ADR-007 §Stage 1b).
    #:
    #: ``None`` for pre-P1.04.5 callers; populated by
    #: :func:`concerto.training.ego_aht.train` at end-of-cell when
    #: ``safety_filter`` was wired (the
    #: :class:`concerto.training.safety_telemetry.SafetyAggregator`'s
    #: ``finalise()`` output). Forward-additive widening — existing
    #: JSONL parsers ignore the field; the new audit-gate hook reads
    #: the ``safety_telemetry_final`` JSONL event directly (more
    #: discoverable than reading the in-memory ``RunContext`` post-
    #: training). The ``RunContext`` carrying the field is the
    #: source-of-truth for in-process callers (e.g.
    #: :class:`chamber.benchmarks.stage1_common.TrainedPolicyFactory`)
    #: that need the summary without re-parsing the JSONL.
    safety_telemetry: dict[str, object] | None = None

WandbSink

Bases: Protocol

Minimal :class:wandb.sdk.wandb_run.Run surface we depend on (ADR-002, ADR-017 §Decisions).

Plan/05 §2: W&B is opt-in. The Protocol lets tests inject an in-memory fake without requiring the real wandb package to be importable. P1.05.11 widened the surface from two methods (log / set_config) to four; the new methods (add_tags and close) are part of ADR-017's W&B-run-lifecycle contract.

Source code in src/concerto/training/logging.py

class WandbSink(Protocol):
    """Minimal :class:`wandb.sdk.wandb_run.Run` surface we depend on (ADR-002, ADR-017 §Decisions).

    Plan/05 §2: W&B is opt-in. The Protocol lets tests inject an in-memory
    fake without requiring the real ``wandb`` package to be importable.
    P1.05.11 widened the surface from two methods (``log`` /
    ``set_config``) to four; the new methods (``add_tags`` and
    ``close``) are part of ADR-017's W&B-run-lifecycle contract.
    """

    def log(self, data: Mapping[str, object], *, step: int | None = None) -> None:
        """Emit one structured event (W&B-side surface; ADR-002 §Decisions)."""
        ...  # pragma: no cover

    def set_config(self, config: Mapping[str, object]) -> None:
        """Store run-level metadata once at bind time (ADR-002 §Decisions; plan/05 §2).

        Called by :func:`bind_run_logger` to pin the four
        :class:`RunContext` provenance fields (``run_id``, ``seed``,
        ``git_sha``, ``pyproject_hash``) on the W&B run as metadata rather
        than as per-step metrics.
        """
        ...  # pragma: no cover

    def add_tags(self, tags: Iterable[str]) -> None:
        """Append tags to the W&B run (P1.05.11; ADR-017 §Decisions).

        ADR-017 §Decisions: ``stage:<n>``, ``sub_stage:<x>``,
        ``condition:<id>``, ``prereg:<sha8>``, ``backfill:<bool>``
        appear here. Implementations must be idempotent: re-adding an
        existing tag is a no-op.
        """
        ...  # pragma: no cover

    def close(self) -> None:
        """Finalise the W&B run (P1.05.11; ADR-017 §Decisions).

        Called by the training driver once the cell completes. The
        :class:`_WandbRunSink` impl calls ``wandb.finish()``; in-memory
        test fakes typically no-op.
        """
        ...  # pragma: no cover

add_tags

add_tags(tags: Iterable[str]) -> None

Append tags to the W&B run (P1.05.11; ADR-017 §Decisions).

ADR-017 §Decisions: stage:<n>, sub_stage:<x>, condition:<id>, prereg:<sha8>, backfill:<bool> appear here. Implementations must be idempotent: re-adding an existing tag is a no-op.

Source code in src/concerto/training/logging.py

def add_tags(self, tags: Iterable[str]) -> None:
    """Append tags to the W&B run (P1.05.11; ADR-017 §Decisions).

    ADR-017 §Decisions: ``stage:<n>``, ``sub_stage:<x>``,
    ``condition:<id>``, ``prereg:<sha8>``, ``backfill:<bool>``
    appear here. Implementations must be idempotent: re-adding an
    existing tag is a no-op.
    """
    ...  # pragma: no cover

close

close() -> None

Finalise the W&B run (P1.05.11; ADR-017 §Decisions).

Called by the training driver once the cell completes. The :class:_WandbRunSink impl calls wandb.finish(); in-memory test fakes typically no-op.

Source code in src/concerto/training/logging.py

def close(self) -> None:
    """Finalise the W&B run (P1.05.11; ADR-017 §Decisions).

    Called by the training driver once the cell completes. The
    :class:`_WandbRunSink` impl calls ``wandb.finish()``; in-memory
    test fakes typically no-op.
    """
    ...  # pragma: no cover

log

log(
    data: Mapping[str, object], *, step: int | None = None
) -> None

Emit one structured event (W&B-side surface; ADR-002 §Decisions).

Source code in src/concerto/training/logging.py

def log(self, data: Mapping[str, object], *, step: int | None = None) -> None:
    """Emit one structured event (W&B-side surface; ADR-002 §Decisions)."""
    ...  # pragma: no cover

set_config

set_config(config: Mapping[str, object]) -> None

Store run-level metadata once at bind time (ADR-002 §Decisions; plan/05 §2).

Called by :func:bind_run_logger to pin the four :class:RunContext provenance fields (run_id, seed, git_sha, pyproject_hash) on the W&B run as metadata rather than as per-step metrics.

Source code in src/concerto/training/logging.py

def set_config(self, config: Mapping[str, object]) -> None:
    """Store run-level metadata once at bind time (ADR-002 §Decisions; plan/05 §2).

    Called by :func:`bind_run_logger` to pin the four
    :class:`RunContext` provenance fields (``run_id``, ``seed``,
    ``git_sha``, ``pyproject_hash``) on the W&B run as metadata rather
    than as per-step metrics.
    """
    ...  # pragma: no cover

bind_run_logger

bind_run_logger(
    ctx: RunContext,
    *,
    jsonl_path: Path,
    wandb_sink: WandbSink | None = None,
) -> structlog.BoundLogger

Build a structlog logger that emits JSONL + optionally W&B (ADR-002 §Decisions; plan/05 §2).

The returned logger has every :class:RunContext field bound to it so every emitted line carries them automatically. Callers add per-event fields (e.g. step, ego_reward) via logger.info(...).

The function does NOT close the JSONL file; the caller owns its lifecycle (typically a with open(...) as fh: block held open for the duration of the run).

Parameters:

• ctx (RunContext) –

  Run-level provenance bundle.

• jsonl_path (Path) –

  Filesystem path where the JSONL fallback is written. Parent directory is created if missing.

• wandb_sink (WandbSink | None, default: None ) –

  Optional :class:WandbSink (production: a wandb.run; tests: an in-memory fake). When None, only JSONL is emitted.

Returns:

• A ( BoundLogger ) –

  class:structlog.BoundLogger wrapping the JSONL (and optionally

• BoundLogger –

  W&B) sinks. The logger is not module-global; callers explicitly

• BoundLogger –

  pass it through their training loop so unit tests can substitute

• BoundLogger –

  in-memory sinks freely.

Source code in src/concerto/training/logging.py

def bind_run_logger(
    ctx: RunContext,
    *,
    jsonl_path: Path,
    wandb_sink: WandbSink | None = None,
) -> structlog.BoundLogger:
    """Build a structlog logger that emits JSONL + optionally W&B (ADR-002 §Decisions; plan/05 §2).

    The returned logger has every :class:`RunContext` field bound to it so
    every emitted line carries them automatically. Callers add per-event
    fields (e.g. ``step``, ``ego_reward``) via ``logger.info(...)``.

    The function does NOT close the JSONL file; the caller owns its
    lifecycle (typically a ``with open(...) as fh:`` block held open for
    the duration of the run).

    Args:
        ctx: Run-level provenance bundle.
        jsonl_path: Filesystem path where the JSONL fallback is written.
            Parent directory is created if missing.
        wandb_sink: Optional :class:`WandbSink` (production: a ``wandb.run``;
            tests: an in-memory fake). When ``None``, only JSONL is emitted.

    Returns:
        A :class:`structlog.BoundLogger` wrapping the JSONL (and optionally
        W&B) sinks. The logger is not module-global; callers explicitly
        pass it through their training loop so unit tests can substitute
        in-memory sinks freely.
    """
    jsonl_path.parent.mkdir(parents=True, exist_ok=True)
    fh = jsonl_path.open("w", encoding="utf-8")
    if wandb_sink is not None:
        # Pin run-level provenance once on the W&B run's config so the four
        # context fields don't appear as per-step metrics in charts.
        wandb_sink.set_config(
            {
                "run_id": ctx.run_id,
                "seed": ctx.seed,
                "git_sha": ctx.git_sha,
                "pyproject_hash": ctx.pyproject_hash,
                "run_kind": ctx.run_kind,
                **ctx.extra,
            }
        )
    processors: list[Any] = [structlog.processors.add_log_level]
    if wandb_sink is not None:
        processors.append(_WandbProcessor(wandb_sink))
    processors.append(_JSONLSink(fh))
    base = structlog.wrap_logger(
        logger=None,  # type: ignore[arg-type]  # structlog uses a no-op base when None.
        processors=processors,
    )
    return base.bind(
        run_id=ctx.run_id,
        seed=ctx.seed,
        git_sha=ctx.git_sha,
        pyproject_hash=ctx.pyproject_hash,
        run_kind=ctx.run_kind,
        **ctx.extra,
    )

compute_run_metadata

compute_run_metadata(
    *,
    seed: int,
    run_kind: str,
    repo_root: Path,
    extra: Mapping[str, str] | None = None,
    config_fingerprint: str | None = None,
) -> RunContext

Build :class:RunContext with auto-detected git/pyproject hashes (ADR-002; plan/05 §2).

The run_id is the first 16 hex chars of the SHA-256 of (seed, git_sha, pyproject_hash, run_kind) — plus config_fingerprint when supplied — matching the 16-hex-char convention used for PartnerSpec.partner_id (plan/04 §3.1) so artefact filenames are uniform across the project.

RUNID-COLLISION fix (issue #214; ADR-002 §Revision history 2026-06-10): without the config in the hash material, same-seed runs at the same commit collide — observed in the 2026-06-10 regime-alignment chain, where cells differing only in regime knobs (gamma, num_envs, frames) reproduced each other's run_ids and their plain {run_id}.jsonl archive copies overwrote. Callers that own a run config (the training loop) pass its fingerprint; None preserves the legacy hash material byte-for-byte so config-less callers' historical run_ids remain reproducible.

Parameters:

• seed (int) –

  Root seed; passed to :func:concerto.training.seeding.derive_substream upstream.

• run_kind (str) –

  Free-form label (e.g. "empirical_guarantee").

• repo_root (Path) –

  Working-tree directory to query for git_sha and pyproject.toml.

• extra (Mapping[str, str] | None, default: None ) –

  Optional string-string metadata attached to every line.

• config_fingerprint (str | None, default: None ) –

  Optional stable hash of the run's config (the training loop passes the SHA-256 of the Pydantic model_dump_json() excluding the operator-side sink fields artifacts_root / log_dir / wandb — output destinations are not run semantics, and the P6 byte-identity test pins that two same-seed runs in different scratch dirs share one identity; see :func:concerto.training.ego_aht.train). Folded into the run_id material when not None.

Returns:

• RunContext –

  A frozen :class:RunContext ready to bind via :func:bind_run_logger.

Source code in src/concerto/training/logging.py

def compute_run_metadata(
    *,
    seed: int,
    run_kind: str,
    repo_root: Path,
    extra: Mapping[str, str] | None = None,
    config_fingerprint: str | None = None,
) -> RunContext:
    """Build :class:`RunContext` with auto-detected git/pyproject hashes (ADR-002; plan/05 §2).

    The ``run_id`` is the first 16 hex chars of the SHA-256 of
    ``(seed, git_sha, pyproject_hash, run_kind)`` — plus
    ``config_fingerprint`` when supplied — matching the 16-hex-char
    convention used for ``PartnerSpec.partner_id`` (plan/04 §3.1) so
    artefact filenames are uniform across the project.

    RUNID-COLLISION fix (issue #214; ADR-002 §Revision history
    2026-06-10): without the config in the hash material, same-seed
    runs at the same commit collide — observed in the 2026-06-10
    regime-alignment chain, where cells differing only in regime knobs
    (gamma, num_envs, frames) reproduced each other's run_ids and their
    plain ``{run_id}.jsonl`` archive copies overwrote. Callers that own
    a run config (the training loop) pass its fingerprint; ``None``
    preserves the legacy hash material byte-for-byte so config-less
    callers' historical run_ids remain reproducible.

    Args:
        seed: Root seed; passed to
            :func:`concerto.training.seeding.derive_substream` upstream.
        run_kind: Free-form label (e.g. ``"empirical_guarantee"``).
        repo_root: Working-tree directory to query for ``git_sha`` and
            ``pyproject.toml``.
        extra: Optional string-string metadata attached to every line.
        config_fingerprint: Optional stable hash of the run's config
            (the training loop passes the SHA-256 of the Pydantic
            ``model_dump_json()`` excluding the operator-side sink
            fields ``artifacts_root`` / ``log_dir`` / ``wandb`` —
            output destinations are not run semantics, and the P6
            byte-identity test pins that two same-seed runs in
            different scratch dirs share one identity; see
            :func:`concerto.training.ego_aht.train`). Folded into the
            run_id material when not ``None``.

    Returns:
        A frozen :class:`RunContext` ready to bind via :func:`bind_run_logger`.
    """
    git_sha = _detect_git_sha(repo_root)
    pyproject_hash = _compute_pyproject_hash(repo_root / "pyproject.toml")
    if config_fingerprint is None:
        material = repr((seed, git_sha, pyproject_hash, run_kind))
    else:
        material = repr((seed, git_sha, pyproject_hash, run_kind, config_fingerprint))
    run_id = hashlib.sha256(material.encode("utf-8")).hexdigest()[:16]
    return RunContext(
        run_id=run_id,
        seed=seed,
        git_sha=git_sha,
        pyproject_hash=pyproject_hash,
        run_kind=run_kind,
        extra=dict(extra or {}),
    )

log_eval

log_eval(
    logger: BoundLogger,
    *,
    step: int,
    condition: str,
    **results: float | int,
) -> None

Emit one event="eval" line for an eval-cell completion (P1.05.11; ADR-017 §Schema).

Eval events differ from training scalars: they carry the condition identifier (one of the four Stage-1 condition_id strings) and aggregate terminal statistics (success_rate, mean_episode_length, mean_episode_reward, n_terminated, n_truncated). The chamber-analyze summary subcommand surfaces these as the run's terminal metrics.

Parameters:

• logger (BoundLogger) –

  A bound logger from :func:bind_run_logger.

• step (int) –

  Global training step (frames) at which the eval was triggered.

• condition (str) –

  Stage-1 condition_id (e.g. "stage1_pickplace_panda_plus_fetch_ego_aht_happo_per_agent") or a short slug like "as-hetero".

• **results (float | int, default: {} ) –

  Terminal metric key → value pairs. int-shaped counts (n_terminated, n_truncated) are accepted alongside float rates.

Source code in src/concerto/training/logging.py

def log_eval(
    logger: structlog.BoundLogger,
    *,
    step: int,
    condition: str,
    **results: float | int,
) -> None:
    """Emit one ``event="eval"`` line for an eval-cell completion (P1.05.11; ADR-017 §Schema).

    Eval events differ from training scalars: they carry the
    ``condition`` identifier (one of the four Stage-1 ``condition_id``
    strings) and aggregate terminal statistics (``success_rate``,
    ``mean_episode_length``, ``mean_episode_reward``,
    ``n_terminated``, ``n_truncated``). The ``chamber-analyze
    summary`` subcommand surfaces these as the run's terminal metrics.

    Args:
        logger: A bound logger from :func:`bind_run_logger`.
        step: Global training step (frames) at which the eval was
            triggered.
        condition: Stage-1 ``condition_id`` (e.g.
            ``"stage1_pickplace_panda_plus_fetch_ego_aht_happo_per_agent"``)
            or a short slug like ``"as-hetero"``.
        **results: Terminal metric key → value pairs. ``int``-shaped
            counts (``n_terminated``, ``n_truncated``) are accepted
            alongside ``float`` rates.
    """
    logger.info(
        "eval",
        step=step,
        condition=condition,
        metric_namespace="eval",
        wall_time=_iso_utc_now(),
        **results,
    )

log_scalars

log_scalars(
    logger: BoundLogger,
    *,
    step: int,
    namespace: LogNamespace,
    **scalars: float,
) -> None

Emit one event="scalar" line with a namespace tag (P1.05.11; ADR-017 §Schema).

Thin wrapper that pins the event, metric_namespace, and wall_time fields so the chamber-analyze CLI's namespace- based filtering has a stable contract. Other fields flow through as scalar metric values.

The wrapper does not validate the metric values — the caller is responsible for passing float-shaped data. None / NaN is accepted (downstream readers must handle them).

Parameters:

• logger (BoundLogger) –

  A bound logger from :func:bind_run_logger. Its bound RunContext fields propagate to the emitted line.

• step (int) –

  Global training step (frames). Routed to W&B's step= kwarg via :class:_WandbProcessor and appears as a top- level step field in the JSONL line.

• namespace (LogNamespace) –

  One of "train", "eval", "safety", "hardware", "rollout". The chamber-analyze metrics --namespace flag filters on this value.

• **scalars (float, default: {} ) –

  Metric key → value pairs. Each pair appears as a top-level field on the emitted JSONL line.

Raises:

• ValueError –

  If namespace is not in the allow-list (defensive backstop against typos that would silently make a metric un-findable by chamber-analyze).

Source code in src/concerto/training/logging.py

def log_scalars(
    logger: structlog.BoundLogger,
    *,
    step: int,
    namespace: LogNamespace,
    **scalars: float,
) -> None:
    """Emit one ``event="scalar"`` line with a namespace tag (P1.05.11; ADR-017 §Schema).

    Thin wrapper that pins the ``event``, ``metric_namespace``, and
    ``wall_time`` fields so the ``chamber-analyze`` CLI's namespace-
    based filtering has a stable contract. Other fields flow through
    as scalar metric values.

    The wrapper does not validate the metric *values* — the caller is
    responsible for passing ``float``-shaped data. ``None`` / NaN is
    accepted (downstream readers must handle them).

    Args:
        logger: A bound logger from :func:`bind_run_logger`. Its bound
            ``RunContext`` fields propagate to the emitted line.
        step: Global training step (frames). Routed to W&B's ``step=``
            kwarg via :class:`_WandbProcessor` and appears as a top-
            level ``step`` field in the JSONL line.
        namespace: One of ``"train"``, ``"eval"``, ``"safety"``,
            ``"hardware"``, ``"rollout"``. The ``chamber-analyze
            metrics --namespace`` flag filters on this value.
        **scalars: Metric key → value pairs. Each pair appears as a
            top-level field on the emitted JSONL line.

    Raises:
        ValueError: If ``namespace`` is not in the allow-list (defensive
            backstop against typos that would silently make a
            metric un-findable by ``chamber-analyze``).
    """
    if namespace not in _LOG_NAMESPACES:
        msg = (
            f"log_scalars: namespace={namespace!r} not in allow-list "
            f"{sorted(_LOG_NAMESPACES)!r}. Extending the allow-list requires "
            "editing concerto.training.logging._LOG_NAMESPACES + ADR-017 §Schema."
        )
        raise ValueError(msg)
    logger.info(
        "scalar",
        step=step,
        metric_namespace=namespace,
        wall_time=_iso_utc_now(),
        **scalars,
    )

make_wandb_run_sink

make_wandb_run_sink(
    cfg: WandbConfig,
    ctx: RunContext,
    *,
    tags: Sequence[str] = (),
    config_extras: Mapping[str, object] | None = None,
) -> WandbSink | None

Build a W&B sink, or return None to degrade to JSONL-only (P1.05.11; ADR-017).

The factory implements the optional-sink discipline: every failure path returns None (with a single warning), never raises. The training driver passes the returned value as wandb_sink= to :func:bind_run_logger; None keeps the existing JSONL-only behaviour intact.

Failure paths (each emits a single :class:UserWarning and returns None):

• cfg.enabled is False (the most common path; not really a "failure" — the operator opted out).
• WANDB_API_KEY is missing AND cfg.mode != "offline" (online uploads require auth; offline mode writes to disk).
• import wandb raises (defensive — wandb is a runtime dep today, but the no-import path stays here for the future where the founder may demote it to extras).
• wandb.init(...) raises (network, auth, quota, ...).

On success, the W&B run is created with:

• id = ctx.run_id — reuses the 16-hex per-cell run id so the W&B run name matches the JSONL filename one-to-one.
• project = cfg.project — default "concerto-chamber" per ADR-017 §Decisions.
• tags = (*tags, "stage:<x>", "run_kind:<x>", ...) — the caller supplies stage/sub_stage/condition/prereg tags; the factory does not invent them. ADR-017 §Decisions pins that prereg_sha is also written to wandb.config so the W&B UI can filter both on a tag (cheap match) AND on a config field (auditable).
• config carries the four :class:RunContext provenance fields plus any config_extras (e.g. prereg_sha, git_sha, command_line). These appear in the run's "Overview" panel — searchable via the W&B UI's filter panel.

Parameters:

• cfg (WandbConfig) –

  The :class:concerto.training.config.WandbConfig block from the composed Hydra config.

• ctx (RunContext) –

  Per-cell :class:RunContext (binds run_id, seed, git_sha, pyproject_hash, run_kind).

• tags (Sequence[str], default: () ) –

  Optional iterable of pre-built tag strings. ADR-017 §Decisions: include stage:<n>, sub_stage:<x>, condition:<id>, prereg:<sha8>, backfill:true|false at minimum.

• config_extras (Mapping[str, object] | None, default: None ) –

  Optional mapping merged into wandb.config on top of the four :class:RunContext provenance fields. Use for prereg_sha (full SHA, alongside the short-form in tags), command_line, and other non-provenance audit metadata.

Returns:

• A ( WandbSink | None ) –

  class:_WandbRunSink wrapping the live W&B run, or

• WandbSink | None –

  None if any failure path above fired. The training driver

• WandbSink | None –

  passes the returned value (or None) to

• WandbSink | None –

  func:bind_run_logger.

Source code in src/concerto/training/logging.py

def make_wandb_run_sink(
    cfg: WandbConfig,
    ctx: RunContext,
    *,
    tags: Sequence[str] = (),
    config_extras: Mapping[str, object] | None = None,
) -> WandbSink | None:
    """Build a W&B sink, or return ``None`` to degrade to JSONL-only (P1.05.11; ADR-017).

    The factory implements the optional-sink discipline: every failure
    path returns ``None`` (with a single warning), never raises. The
    training driver passes the returned value as ``wandb_sink=`` to
    :func:`bind_run_logger`; ``None`` keeps the existing JSONL-only
    behaviour intact.

    Failure paths (each emits a single :class:`UserWarning` and returns
    ``None``):

    - ``cfg.enabled is False`` (the most common path; not really a
      "failure" — the operator opted out).
    - ``WANDB_API_KEY`` is missing AND ``cfg.mode != "offline"``
      (online uploads require auth; offline mode writes to disk).
    - ``import wandb`` raises (defensive — wandb is a runtime dep
      today, but the no-import path stays here for the future where
      the founder may demote it to extras).
    - ``wandb.init(...)`` raises (network, auth, quota, ...).

    On success, the W&B run is created with:

    - ``id = ctx.run_id`` — reuses the 16-hex per-cell run id so the
      W&B run name matches the JSONL filename one-to-one.
    - ``project = cfg.project`` — default ``"concerto-chamber"`` per
      ADR-017 §Decisions.
    - ``tags = (*tags, "stage:<x>", "run_kind:<x>", ...)`` — the
      caller supplies stage/sub_stage/condition/prereg tags; the
      factory does not invent them. ADR-017 §Decisions pins that
      ``prereg_sha`` is also written to ``wandb.config`` so the W&B UI
      can filter both on a tag (cheap match) AND on a config field
      (auditable).
    - ``config`` carries the four :class:`RunContext` provenance
      fields plus any ``config_extras`` (e.g. ``prereg_sha``,
      ``git_sha``, ``command_line``). These appear in the run's
      "Overview" panel — searchable via the W&B UI's filter panel.

    Args:
        cfg: The :class:`concerto.training.config.WandbConfig` block
            from the composed Hydra config.
        ctx: Per-cell :class:`RunContext` (binds ``run_id``, ``seed``,
            ``git_sha``, ``pyproject_hash``, ``run_kind``).
        tags: Optional iterable of pre-built tag strings. ADR-017
            §Decisions: include ``stage:<n>``, ``sub_stage:<x>``,
            ``condition:<id>``, ``prereg:<sha8>``, ``backfill:true|false``
            at minimum.
        config_extras: Optional mapping merged into ``wandb.config``
            on top of the four :class:`RunContext` provenance fields.
            Use for ``prereg_sha`` (full SHA, alongside the
            short-form in ``tags``), ``command_line``, and other
            non-provenance audit metadata.

    Returns:
        A :class:`_WandbRunSink` wrapping the live W&B run, or
        ``None`` if any failure path above fired. The training driver
        passes the returned value (or ``None``) to
        :func:`bind_run_logger`.
    """
    if not cfg.enabled:
        # Operator opt-out; not a failure — silent (no warning).
        return None

    # Auth check before the (expensive) wandb import. ``WANDB_API_KEY`` is
    # required for online mode. Offline mode (``WANDB_MODE=offline``) writes
    # to disk and does not need a key; the offline path is what the
    # deterministic-seed equivalence smoke uses.
    wandb_mode = os.environ.get("WANDB_MODE", "online")
    if wandb_mode != "offline" and not os.environ.get("WANDB_API_KEY"):
        warnings.warn(
            "WANDB_API_KEY missing and WANDB_MODE != 'offline'; W&B sink degrades "
            "to no-op (run continues with JSONL only). Set WANDB_API_KEY or "
            "export WANDB_MODE=offline to silence. (ADR-017 §Decisions)",
            UserWarning,
            stacklevel=2,
        )
        return None

    try:
        import wandb  # noqa: PLC0415 - import inside try is the degrade-gracefully contract
    except ImportError as exc:
        warnings.warn(
            f"`import wandb` failed ({type(exc).__name__}: {exc!s:.200}); "
            "W&B sink degrades to no-op (run continues with JSONL only). "
            "Install with `uv sync` or `pip install wandb`. (ADR-017 §Decisions)",
            UserWarning,
            stacklevel=2,
        )
        return None

    # Build the wandb.config payload — RunContext provenance + caller extras.
    cfg_payload: dict[str, object] = {
        "run_id": ctx.run_id,
        "seed": ctx.seed,
        "git_sha": ctx.git_sha,
        "pyproject_hash": ctx.pyproject_hash,
        "run_kind": ctx.run_kind,
    }
    cfg_payload.update(ctx.extra)
    if config_extras:
        cfg_payload.update(dict(config_extras))

    try:
        run = wandb.init(
            id=ctx.run_id,
            name=ctx.run_id,
            project=cfg.project,
            tags=tuple(tags) if tags else None,
            config=cfg_payload,
            resume="never",
            reinit=True,  # allow multiple per-cell runs in one process
        )
    except Exception as exc:  # top-level catch by design — degrade gracefully
        warnings.warn(
            f"wandb.init(...) raised ({type(exc).__name__}: {exc!s:.200}); "
            "W&B sink degrades to no-op (run continues with JSONL only). "
            "(ADR-017 §Decisions)",
            UserWarning,
            stacklevel=2,
        )
        return None

    return _WandbRunSink(run)

Checkpoint save/load with SHA-256 integrity (T4b.12; ADR-002 §Decisions).

The training stack writes torch state-dicts as .pt files referenced from M4a's :class:~chamber.partners.api.PartnerSpec weights_uri field (plan/04 §3.8). This module owns the wire format:

• A local://artifacts/<name>.pt URI resolves to <artifacts_root>/<name>.pt.
• Each .pt payload is paired with a <name>.pt.json metadata sidecar carrying :class:CheckpointMetadata (run_id, seed, step, git_sha, pyproject_hash, sha256). The sidecar is the authoritative provenance record; the .pt file is the opaque tensor payload.
• :func:load_checkpoint re-hashes the loaded .pt payload and refuses to return tensors when the digest disagrees with the sidecar (ADR-002 §Decisions; P6 reproducibility).

Deploy order: payload first, sidecar second. A half-finished deploy (payload landed but sidecar not yet) hits the "missing sidecar" failure path and refuses to load tensors. The reverse order (sidecar first, stale payload) would silently load tensors with the wrong provenance — do not invert.

ADR-009 §Consequences "draft-zoo scoping": the M4a Phase-0 draft-zoo specs reference local://artifacts/mappo_seed42_step100k.pt and local://artifacts/happo_seed7_step50k.pt but the concrete frozen-RL adapters (T4.5 / T4.6) load them only in M4 Phase 3. Until then the SHA- verified loader fails loudly when the sidecar is missing — by design.

CheckpointError

Bases: RuntimeError

Loud-fail signal for checkpoint I/O failures (ADR-002 §Decisions).

Raised on: - URI scheme mismatch (only local:// is supported in Phase 0). - Missing .pt payload or missing sidecar JSON. - SHA-256 mismatch between the stored sidecar digest and the re-computed payload digest on load.

Subclasses :class:RuntimeError so a careless caller catching Exception still sees the failure but can disambiguate via isinstance(exc, CheckpointError).

Source code in src/concerto/training/checkpoints.py

class CheckpointError(RuntimeError):
    """Loud-fail signal for checkpoint I/O failures (ADR-002 §Decisions).

    Raised on:
    - URI scheme mismatch (only ``local://`` is supported in Phase 0).
    - Missing ``.pt`` payload or missing sidecar JSON.
    - SHA-256 mismatch between the stored sidecar digest and the
      re-computed payload digest on load.

    Subclasses :class:`RuntimeError` so a careless caller catching
    ``Exception`` still sees the failure but can disambiguate via
    ``isinstance(exc, CheckpointError)``.
    """

CheckpointMetadata dataclass

Provenance + integrity sidecar for one checkpoint (T4b.12; plan/05 §5).

Mirrors the :class:~concerto.training.logging.RunContext provenance bundle (run_id / seed / git_sha / pyproject_hash) plus the per- checkpoint step and the integrity-protecting sha256 of the .pt payload. All fields are required so a sidecar with missing keys raises :class:CheckpointError on load (loud-fail per ADR-002).

Attributes:

• run_id (str) –

  16-hex hash of the run that produced this checkpoint. Cross-references the run's JSONL log file via :class:concerto.training.logging.RunContext.

• seed (int) –

  Root seed of the producing run; same value passed to :func:concerto.training.seeding.derive_substream.

• step (int) –

  Training step at which this checkpoint was taken (e.g. 50_000 for the canonical "50%-reward" tier in ADR-009 §Decision).

• git_sha (str) –

  Full SHA of the commit the producing run was launched from. "unknown" is permitted (sentinel from :class:concerto.training.logging.GIT_SHA_UNKNOWN).

• pyproject_hash (str) –

  SHA-256 of pyproject.toml at run launch. Detects silent dependency drift between save and load.

• sha256 (str) –

  SHA-256 of the raw .pt payload bytes, computed at save time and verified on every load. Mismatch → :class:CheckpointError.

Source code in src/concerto/training/checkpoints.py

@dataclass(frozen=True)
class CheckpointMetadata:
    """Provenance + integrity sidecar for one checkpoint (T4b.12; plan/05 §5).

    Mirrors the :class:`~concerto.training.logging.RunContext` provenance
    bundle (run_id / seed / git_sha / pyproject_hash) plus the per-
    checkpoint ``step`` and the integrity-protecting ``sha256`` of the
    ``.pt`` payload. All fields are required so a sidecar with missing
    keys raises :class:`CheckpointError` on load (loud-fail per ADR-002).

    Attributes:
        run_id: 16-hex hash of the run that produced this checkpoint.
            Cross-references the run's JSONL log file via
            :class:`concerto.training.logging.RunContext`.
        seed: Root seed of the producing run; same value passed to
            :func:`concerto.training.seeding.derive_substream`.
        step: Training step at which this checkpoint was taken (e.g.
            50_000 for the canonical "50%-reward" tier in
            ADR-009 §Decision).
        git_sha: Full SHA of the commit the producing run was launched
            from. ``"unknown"`` is permitted (sentinel from
            :class:`concerto.training.logging.GIT_SHA_UNKNOWN`).
        pyproject_hash: SHA-256 of ``pyproject.toml`` at run launch.
            Detects silent dependency drift between save and load.
        sha256: SHA-256 of the raw ``.pt`` payload bytes, computed at
            save time and verified on every load. Mismatch →
            :class:`CheckpointError`.
    """

    run_id: str
    seed: int
    step: int
    git_sha: str
    pyproject_hash: str
    sha256: str

    @classmethod
    def from_dict(cls, raw: Mapping[str, object]) -> CheckpointMetadata:
        """Build a :class:`CheckpointMetadata` from a JSON-decoded mapping (ADR-002 §Decisions).

        Refuses partial sidecars: every field declared on the dataclass
        must be present, and types are coerced (``int``/``str``) without
        loss. Missing fields raise :class:`CheckpointError` so a half-
        written sidecar is caught at load time, not at first inference.

        Args:
            raw: A ``json.load(open(sidecar))``-style dict.

        Returns:
            A frozen :class:`CheckpointMetadata` instance.

        Raises:
            CheckpointError: If any required field is missing.
        """
        required = ("run_id", "seed", "step", "git_sha", "pyproject_hash", "sha256")
        missing = [k for k in required if k not in raw]
        if missing:
            raise CheckpointError(
                f"Checkpoint sidecar is missing required field(s): {missing}; "
                "expected the full provenance bundle (ADR-002 §Decisions)."
            )
        try:
            return cls(
                run_id=str(raw["run_id"]),
                seed=int(raw["seed"]),  # type: ignore[arg-type]
                step=int(raw["step"]),  # type: ignore[arg-type]
                git_sha=str(raw["git_sha"]),
                pyproject_hash=str(raw["pyproject_hash"]),
                sha256=str(raw["sha256"]),
            )
        except (TypeError, ValueError) as exc:
            # Hand-edited sidecar with malformed seed/step (e.g. "50000.0",
            # "abc") would otherwise raise an unwrapped ValueError; wrap so
            # callers catching CheckpointError see all sidecar-failure modes
            # uniformly (ADR-002 §Decisions).
            raise CheckpointError(
                f"Checkpoint sidecar contains malformed integer field(s): {exc}; "
                "expected ``seed`` and ``step`` to coerce to int (ADR-002 §Decisions)."
            ) from exc

from_dict classmethod

from_dict(raw: Mapping[str, object]) -> CheckpointMetadata

Build a :class:CheckpointMetadata from a JSON-decoded mapping (ADR-002 §Decisions).

Refuses partial sidecars: every field declared on the dataclass must be present, and types are coerced (int/str) without loss. Missing fields raise :class:CheckpointError so a half- written sidecar is caught at load time, not at first inference.

Parameters:

• raw (Mapping[str, object]) –

  A json.load(open(sidecar))-style dict.

Returns:

• CheckpointMetadata –

  A frozen :class:CheckpointMetadata instance.

Raises:

• CheckpointError –

  If any required field is missing.

Source code in src/concerto/training/checkpoints.py

@classmethod
def from_dict(cls, raw: Mapping[str, object]) -> CheckpointMetadata:
    """Build a :class:`CheckpointMetadata` from a JSON-decoded mapping (ADR-002 §Decisions).

    Refuses partial sidecars: every field declared on the dataclass
    must be present, and types are coerced (``int``/``str``) without
    loss. Missing fields raise :class:`CheckpointError` so a half-
    written sidecar is caught at load time, not at first inference.

    Args:
        raw: A ``json.load(open(sidecar))``-style dict.

    Returns:
        A frozen :class:`CheckpointMetadata` instance.

    Raises:
        CheckpointError: If any required field is missing.
    """
    required = ("run_id", "seed", "step", "git_sha", "pyproject_hash", "sha256")
    missing = [k for k in required if k not in raw]
    if missing:
        raise CheckpointError(
            f"Checkpoint sidecar is missing required field(s): {missing}; "
            "expected the full provenance bundle (ADR-002 §Decisions)."
        )
    try:
        return cls(
            run_id=str(raw["run_id"]),
            seed=int(raw["seed"]),  # type: ignore[arg-type]
            step=int(raw["step"]),  # type: ignore[arg-type]
            git_sha=str(raw["git_sha"]),
            pyproject_hash=str(raw["pyproject_hash"]),
            sha256=str(raw["sha256"]),
        )
    except (TypeError, ValueError) as exc:
        # Hand-edited sidecar with malformed seed/step (e.g. "50000.0",
        # "abc") would otherwise raise an unwrapped ValueError; wrap so
        # callers catching CheckpointError see all sidecar-failure modes
        # uniformly (ADR-002 §Decisions).
        raise CheckpointError(
            f"Checkpoint sidecar contains malformed integer field(s): {exc}; "
            "expected ``seed`` and ``step`` to coerce to int (ADR-002 §Decisions)."
        ) from exc

load_checkpoint

load_checkpoint(
    *, uri: str, artifacts_root: Path
) -> tuple[dict[str, torch.Tensor], CheckpointMetadata]

Load a torch state-dict + verify SHA-256 (T4b.12; ADR-002 §Decisions; P6).

Refuses to return tensors when: - The .pt payload is missing. - The sidecar JSON is missing. - The sidecar is missing required fields (per :meth:CheckpointMetadata.from_dict). - The sidecar's stored sha256 disagrees with the recomputed digest of the on-disk payload.

All four failure modes raise :class:CheckpointError so a partial deployment (e.g. payload deployed but sidecar not yet) cannot silently load tensors that the project has no provenance for.

Parameters:

• uri (str) –

  Source URI (e.g. "local://artifacts/happo_seed7_step50k.pt").

• artifacts_root (Path) –

  Filesystem directory the URI resolves against.

Returns:

• dict[str, Tensor] –

  A tuple (state_dict, metadata) where state_dict is the

• CheckpointMetadata –

  verbatim mapping loaded from the .pt payload and

• tuple[dict[str, Tensor], CheckpointMetadata] –

  metadata is the verified :class:CheckpointMetadata.

Raises:

• CheckpointError –

  On any of the four loud-fail conditions above.

Source code in src/concerto/training/checkpoints.py

def load_checkpoint(
    *,
    uri: str,
    artifacts_root: Path,
) -> tuple[dict[str, torch.Tensor], CheckpointMetadata]:
    """Load a torch state-dict + verify SHA-256 (T4b.12; ADR-002 §Decisions; P6).

    Refuses to return tensors when:
    - The ``.pt`` payload is missing.
    - The sidecar JSON is missing.
    - The sidecar is missing required fields (per
      :meth:`CheckpointMetadata.from_dict`).
    - The sidecar's stored ``sha256`` disagrees with the recomputed
      digest of the on-disk payload.

    All four failure modes raise :class:`CheckpointError` so a partial
    deployment (e.g. payload deployed but sidecar not yet) cannot
    silently load tensors that the project has no provenance for.

    Args:
        uri: Source URI (e.g.
            ``"local://artifacts/happo_seed7_step50k.pt"``).
        artifacts_root: Filesystem directory the URI resolves against.

    Returns:
        A tuple ``(state_dict, metadata)`` where ``state_dict`` is the
        verbatim mapping loaded from the ``.pt`` payload and
        ``metadata`` is the verified :class:`CheckpointMetadata`.

    Raises:
        CheckpointError: On any of the four loud-fail conditions above.
    """
    payload_path = resolve_uri(uri, artifacts_root=artifacts_root)
    if not payload_path.exists():
        raise CheckpointError(
            f"Checkpoint payload not found at {payload_path} (resolved from {uri!r})."
        )
    sidecar = _sidecar_path(payload_path)
    if not sidecar.exists():
        raise CheckpointError(
            f"Checkpoint sidecar not found at {sidecar}; refusing to load tensors "
            "without a provenance record (ADR-002 §Decisions)."
        )
    metadata = CheckpointMetadata.from_dict(json.loads(sidecar.read_text(encoding="utf-8")))
    actual_digest = _sha256_of(payload_path)
    if actual_digest != metadata.sha256:
        raise CheckpointError(
            f"Checkpoint integrity check failed for {payload_path}: "
            f"sidecar sha256={metadata.sha256!r} but on-disk sha256={actual_digest!r}. "
            "The payload may have been corrupted, partially overwritten, or "
            "swapped without updating the sidecar (ADR-002 §Decisions; P6)."
        )
    # weights_only=True restricts the unpickler to safe tensor primitives,
    # so we do not execute arbitrary code from a tampered .pt file. Pinned
    # explicitly (rather than relying on the default) because the project
    # supports torch>=2.3, and the default flipped to True only at 2.4.
    state_dict = torch.load(
        payload_path,
        weights_only=True,
        map_location="cpu",
    )
    return state_dict, metadata

resolve_uri

resolve_uri(uri: str, *, artifacts_root: Path) -> Path

Resolve local://artifacts/<name>.pt URI to filesystem path (ADR-002; plan/04 §3.8).

Phase-0 supports the local:// scheme only. Non-local:// URIs raise :class:CheckpointError so Phase-1 distribution schemes (hf://, s3://) cannot silently fall through to the local filesystem before an ADR amendment is in place.

The path immediately under local:// is appended to artifacts_root; e.g. local://artifacts/foo.pt against artifacts_root=/data resolves to /data/artifacts/foo.pt. The leading artifacts/ segment in the URI is preserved by design — it makes the URI self-describing in logs and keeps the on-disk layout grep-able.

Parameters:

• uri (str) –

  The weights_uri from a :class:~chamber.partners.api.PartnerSpec (plan/04 §3.8).

• artifacts_root (Path) –

  Filesystem directory the URI is resolved against.

Returns:

• Path –

  Absolute filesystem path to the .pt payload (the file may

• Path –

  not exist yet — :func:save_checkpoint creates it).

Raises:

• CheckpointError –

  If uri does not start with :data:LOCAL_URI_SCHEME.

Source code in src/concerto/training/checkpoints.py

def resolve_uri(uri: str, *, artifacts_root: Path) -> Path:
    """Resolve ``local://artifacts/<name>.pt`` URI to filesystem path (ADR-002; plan/04 §3.8).

    Phase-0 supports the ``local://`` scheme only. Non-``local://`` URIs
    raise :class:`CheckpointError` so Phase-1 distribution schemes
    (``hf://``, ``s3://``) cannot silently fall through to the local
    filesystem before an ADR amendment is in place.

    The path immediately under ``local://`` is appended to ``artifacts_root``;
    e.g. ``local://artifacts/foo.pt`` against ``artifacts_root=/data`` resolves
    to ``/data/artifacts/foo.pt``. The leading ``artifacts/`` segment in the
    URI is preserved by design — it makes the URI self-describing in logs
    and keeps the on-disk layout grep-able.

    Args:
        uri: The ``weights_uri`` from a
            :class:`~chamber.partners.api.PartnerSpec` (plan/04 §3.8).
        artifacts_root: Filesystem directory the URI is resolved against.

    Returns:
        Absolute filesystem path to the ``.pt`` payload (the file may
        not exist yet — :func:`save_checkpoint` creates it).

    Raises:
        CheckpointError: If ``uri`` does not start with
            :data:`LOCAL_URI_SCHEME`.
    """
    if not uri.startswith(LOCAL_URI_SCHEME):
        raise CheckpointError(
            f"Unsupported URI scheme: {uri!r}. Phase-0 supports only "
            f"{LOCAL_URI_SCHEME!r} (plan/04 §3.8)."
        )
    relative = uri[len(LOCAL_URI_SCHEME) :]
    return artifacts_root / relative

save_checkpoint

save_checkpoint(
    *,
    state_dict: Mapping[str, Tensor],
    uri: str,
    metadata: CheckpointMetadata,
    artifacts_root: Path,
) -> Path

Save a torch state-dict + sidecar (T4b.12; ADR-002 §Decisions).

The save is two-phase: write the .pt payload first, then compute its SHA-256, write the sidecar JSON with the digest stitched in. The sha256 field on the input metadata is overwritten with the digest computed at save time so callers cannot accidentally ship a stale digest that would crash :func:load_checkpoint.

Parameters:

• state_dict (Mapping[str, Tensor]) –

  A Mapping[str, torch.Tensor] exactly as produced by model.state_dict(). Saved verbatim via :func:torch.save.

• uri (str) –

  Destination URI (e.g. "local://artifacts/happo_seed7_step50k.pt").

• metadata (CheckpointMetadata) –

  Provenance bundle. The sha256 field is recomputed at save time and overrides whatever the caller passed.

• artifacts_root (Path) –

  Filesystem directory the URI resolves against.

Returns:

• Path –

  Absolute filesystem path to the written .pt payload.

Raises:

• CheckpointError –

  If uri is not a local:// URI.

Source code in src/concerto/training/checkpoints.py

def save_checkpoint(
    *,
    state_dict: Mapping[str, torch.Tensor],
    uri: str,
    metadata: CheckpointMetadata,
    artifacts_root: Path,
) -> Path:
    """Save a torch state-dict + sidecar (T4b.12; ADR-002 §Decisions).

    The save is two-phase: write the ``.pt`` payload first, then compute
    its SHA-256, write the sidecar JSON with the digest stitched in. The
    ``sha256`` field on the input ``metadata`` is overwritten with the
    digest computed at save time so callers cannot accidentally ship a
    stale digest that would crash :func:`load_checkpoint`.

    Args:
        state_dict: A ``Mapping[str, torch.Tensor]`` exactly as produced
            by ``model.state_dict()``. Saved verbatim via :func:`torch.save`.
        uri: Destination URI (e.g.
            ``"local://artifacts/happo_seed7_step50k.pt"``).
        metadata: Provenance bundle. The ``sha256`` field is recomputed
            at save time and overrides whatever the caller passed.
        artifacts_root: Filesystem directory the URI resolves against.

    Returns:
        Absolute filesystem path to the written ``.pt`` payload.

    Raises:
        CheckpointError: If ``uri`` is not a ``local://`` URI.
    """
    payload_path = resolve_uri(uri, artifacts_root=artifacts_root)
    payload_path.parent.mkdir(parents=True, exist_ok=True)
    torch.save(dict(state_dict), payload_path)
    digest = _sha256_of(payload_path)
    pinned = CheckpointMetadata(
        run_id=metadata.run_id,
        seed=metadata.seed,
        step=metadata.step,
        git_sha=metadata.git_sha,
        pyproject_hash=metadata.pyproject_hash,
        sha256=digest,
    )
    _sidecar_path(payload_path).write_text(
        json.dumps(asdict(pinned), sort_keys=True, indent=2),
        encoding="utf-8",
    )
    return payload_path

Hydra-driven config for ego-AHT training runs (T4b.11; ADR-002 §Decisions; plan/05 §2).

The training stack is configured via Hydra YAML files under configs/training/<algo>/<task>.yaml. This module ships the type-safe Pydantic v2 models that those YAMLs validate against: EgoAHTConfig is the root, with sub-models for the env / partner / W&B / hyperparameter blocks.

Why two layers (Hydra + Pydantic)?

• Hydra owns the composition + CLI override surface (defaults, group selection, +key=value overrides).
• Pydantic owns the validation + Python-side type-safety (Path coercion, range checks, frozen-by-default to keep call sites from mutating config mid-run).

:func:load_config is the canonical entry point: it locates the project's configs/ directory by walking up from the caller's CWD, composes the named config via Hydra, and validates it through :class:EgoAHTConfig.

ADR-002 §Decisions ("Hydra config root"): the YAML schema is part of the public reproducibility contract. Adding a required field is a breaking change to the config; deprecate-then-remove via a Pydantic :class:Field default and a DeprecationWarning rather than removing in place.

EgoAHTConfig

Bases: _FrozenModel

Root config for an ego-AHT training run (T4b.11; ADR-002 §Decisions).

Validates the composed Hydra config and exposes a frozen Python-side handle for :func:concerto.training.ego_aht.train.

Attributes:

• algo (str) –

  Trainer-class registry key. Phase-0: "ego_aht_happo"; "ego_aht_hatd3" is the Phase-1 stub.

• seed (int) –

  Project root seed routed to :func:concerto.training.seeding.derive_substream. Two runs with the same seed produce byte-identical CPU reward curves (plan/05 §6 criterion 7).

• total_frames (int) –

  Training budget in env frames. T4b.13 = 100_000.

• checkpoint_every (int) –

  Save a .pt artefact every K frames.

• artifacts_root (Path) –

  Directory the local://artifacts/... URIs resolve against (plan/04 §3.8).

• log_dir (Path) –

  Directory where the JSONL logs are written.

• wandb (WandbConfig) –

  :class:WandbConfig.

• env (EnvConfig) –

  :class:EnvConfig.

• partner (PartnerConfig) –

  :class:PartnerConfig.

• happo (HAPPOHyperparams) –

  :class:HAPPOHyperparams.

• runtime (RuntimeConfig) –

  :class:RuntimeConfig — device + determinism knobs (ADR-002 §Decisions; plan/08 §4 GPU determinism caveat). Defaults to device="auto" + deterministic_torch=True so an unset YAML on a Mac CPU dev box just works; the production mpe_cooperative_push.yaml pins device: cpu and stage0_smoke.yaml pins device: cuda.

• rollout_recorder (RolloutRecorderConfig) –

  :class:RolloutRecorderConfig — eval-rollout video + per-step sidecar JSONL knob (P1.05.11; ADR-017 §Decisions). Defaults to enabled=False so existing YAMLs that do not declare the section keep their current behaviour (no recording, no render-mode change).

Source code in src/concerto/training/config.py

class EgoAHTConfig(_FrozenModel):
    """Root config for an ego-AHT training run (T4b.11; ADR-002 §Decisions).

    Validates the composed Hydra config and exposes a frozen
    Python-side handle for :func:`concerto.training.ego_aht.train`.

    Attributes:
        algo: Trainer-class registry key. Phase-0: ``"ego_aht_happo"``;
            ``"ego_aht_hatd3"`` is the Phase-1 stub.
        seed: Project root seed routed to
            :func:`concerto.training.seeding.derive_substream`. Two
            runs with the same ``seed`` produce byte-identical CPU
            reward curves (plan/05 §6 criterion 7).
        total_frames: Training budget in env frames. T4b.13 = 100_000.
        checkpoint_every: Save a ``.pt`` artefact every K frames.
        artifacts_root: Directory the ``local://artifacts/...`` URIs
            resolve against (plan/04 §3.8).
        log_dir: Directory where the JSONL logs are written.
        wandb: :class:`WandbConfig`.
        env: :class:`EnvConfig`.
        partner: :class:`PartnerConfig`.
        happo: :class:`HAPPOHyperparams`.
        runtime: :class:`RuntimeConfig` — device + determinism knobs
            (ADR-002 §Decisions; plan/08 §4 GPU determinism caveat).
            Defaults to ``device="auto"`` + ``deterministic_torch=True``
            so an unset YAML on a Mac CPU dev box just works; the
            production ``mpe_cooperative_push.yaml`` pins
            ``device: cpu`` and ``stage0_smoke.yaml`` pins
            ``device: cuda``.
        rollout_recorder: :class:`RolloutRecorderConfig` — eval-rollout
            video + per-step sidecar JSONL knob (P1.05.11; ADR-017
            §Decisions). Defaults to ``enabled=False`` so existing
            YAMLs that do not declare the section keep their current
            behaviour (no recording, no render-mode change).
    """

    algo: str = "ego_aht_happo"
    seed: int = Field(default=0, ge=0)
    total_frames: int = Field(default=100_000, gt=0)
    checkpoint_every: int = Field(default=10_000, gt=0)
    artifacts_root: Path = Path("./artifacts")
    log_dir: Path = Path("./logs")
    wandb: WandbConfig = Field(default_factory=WandbConfig)
    env: EnvConfig
    partner: PartnerConfig = Field(default_factory=PartnerConfig)
    happo: HAPPOHyperparams = Field(default_factory=HAPPOHyperparams)
    runtime: RuntimeConfig = Field(default_factory=RuntimeConfig)
    safety: SafetyConfig = Field(default_factory=SafetyConfig)
    rollout_recorder: RolloutRecorderConfig = Field(default_factory=RolloutRecorderConfig)
    shaping: ShapingConfig = Field(default_factory=ShapingConfig)
    exploratory: ExploratoryConfig = Field(default_factory=ExploratoryConfig)

EnvConfig

Bases: _FrozenModel

Env-side configuration (T4b.13; ADR-002 §Decisions; plan/05 §3.5).

Attributes:

• task (str) –

  Registered task name. Phase-0 supports "mpe_cooperative_push" (T4b.13's empirical-guarantee env) and "stage0_smoke" (T4b.14's zoo-seed env, deferred to user-side GPU run). P1.04 adds "stage1_pickplace" (ADR-007 §Stage 1b real-env science-evaluation target).

• episode_length (int) –

  Truncation horizon in env ticks. The empirical- guarantee experiment defaults to 50 (matches PettingZoo simple_spread).

• agent_uids (tuple[str, str]) –

  2-element list of uids the env exposes; the first is the ego, the second is the frozen partner.

• condition_id (str | None) –

  Stage-1b pre-registered condition_id string (P1.04 / ADR-007 §Stage 1b). Required when task == "stage1_pickplace" because OM-homo and OM-hetero share the ("panda_wristcam", "fetch") agent_uids tuple — the condition_id is the explicit disambiguator. The yaml carries a sensible default; :class:chamber.benchmarks.stage1_common.TrainedPolicyFactory overrides per (seed, condition) cell via model_copy. None for non-Stage-1b tasks (MPE, Stage-0) — pre-P1.04 cfgs work unchanged.

• num_envs (int) –

  Training-cell parallelisation count (P1.05.10; ADR-007 §Stage 1b regime-alignment revision). 1 (default) preserves the historical single-env loop byte-identically (ADR-002). > 1 builds the env vectorised (ManiSkill GPU sim) and switches :func:concerto.training.ego_aht.train to the batched rollout path; the per-update batch becomes num_envs x happo.rollout_length transitions. Implementation-detail-of-the-cell per the ADR-007 Rev 15 precedent — the prereg condition_ids / seed list / gate criteria are untouched. The training-time safety stack is not batched in this slice: num_envs > 1 with safety.enabled=True loud-fails in train().

• mask_partner_obs (bool) –

  B-BLIND (ADR-011 §Decision as amended 2026-07-05): when True, the env builder layers the task's partner-blind observation mask outside the ego state synthesizer, zeroing the partner-state + coupling-feedback slice (co-carry: indices [18, 43) — see :mod:chamber.envs.cocarry_blind_mask). A pure observation transform — no trainer changes; the actor keeps its input width so B-BLIND / B-AHT checkpoints stay layout-compatible. False (default) is the historical coupling-aware cell, byte-identical.

Source code in src/concerto/training/config.py

class EnvConfig(_FrozenModel):
    """Env-side configuration (T4b.13; ADR-002 §Decisions; plan/05 §3.5).

    Attributes:
        task: Registered task name. Phase-0 supports ``"mpe_cooperative_push"``
            (T4b.13's empirical-guarantee env) and ``"stage0_smoke"``
            (T4b.14's zoo-seed env, deferred to user-side GPU run).
            P1.04 adds ``"stage1_pickplace"`` (ADR-007 §Stage 1b real-env
            science-evaluation target).
        episode_length: Truncation horizon in env ticks. The empirical-
            guarantee experiment defaults to 50 (matches PettingZoo
            simple_spread).
        agent_uids: 2-element list of uids the env exposes; the first is
            the ego, the second is the frozen partner.
        condition_id: Stage-1b pre-registered condition_id string
            (P1.04 / ADR-007 §Stage 1b). Required when
            ``task == "stage1_pickplace"`` because OM-homo and
            OM-hetero share the ``("panda_wristcam", "fetch")``
            agent_uids tuple — the condition_id is the explicit
            disambiguator. The yaml carries a sensible default;
            :class:`chamber.benchmarks.stage1_common.TrainedPolicyFactory`
            overrides per ``(seed, condition)`` cell via
            ``model_copy``. ``None`` for non-Stage-1b tasks (MPE,
            Stage-0) — pre-P1.04 cfgs work unchanged.
        num_envs: Training-cell parallelisation count (P1.05.10;
            ADR-007 §Stage 1b regime-alignment revision). ``1``
            (default) preserves the historical single-env loop
            byte-identically (ADR-002). ``> 1`` builds the env
            vectorised (ManiSkill GPU sim) and switches
            :func:`concerto.training.ego_aht.train` to the batched
            rollout path; the per-update batch becomes
            ``num_envs x happo.rollout_length`` transitions.
            Implementation-detail-of-the-cell per the ADR-007 Rev 15
            precedent — the prereg condition_ids / seed list / gate
            criteria are untouched. The training-time safety stack is
            not batched in this slice: ``num_envs > 1`` with
            ``safety.enabled=True`` loud-fails in ``train()``.
        mask_partner_obs: B-BLIND (ADR-011 §Decision as amended
            2026-07-05): when ``True``, the env builder layers the
            task's partner-blind observation mask outside the ego
            ``state`` synthesizer, zeroing the partner-state +
            coupling-feedback slice (co-carry: indices ``[18, 43)`` —
            see :mod:`chamber.envs.cocarry_blind_mask`). A pure
            observation transform — no trainer changes; the actor
            keeps its input width so B-BLIND / B-AHT checkpoints stay
            layout-compatible. ``False`` (default) is the historical
            coupling-aware cell, byte-identical.
    """

    task: str
    episode_length: int = Field(default=50, gt=0)
    agent_uids: tuple[str, str] = ("ego", "partner")
    condition_id: str | None = None
    num_envs: int = Field(default=1, ge=1)
    mask_partner_obs: bool = False

    @field_validator("agent_uids", mode="before")
    @classmethod
    def _coerce_agent_uids(cls, v: object) -> object:
        # Hydra/OmegaConf parses YAML lists as ListConfig (subclass of list),
        # not tuple — coerce to keep the tuple-typed contract intact.
        if isinstance(v, list):
            return tuple(v)
        return v

    @field_validator("agent_uids")
    @classmethod
    def _check_distinct_uids(cls, v: tuple[str, str]) -> tuple[str, str]:
        if v[0] == v[1]:
            raise ValueError(f"agent_uids must be distinct; got {v!r}")
        return v

ExploratoryConfig

Bases: _FrozenModel

EXPLORATORY rig knobs — structurally barred from gate-facing runs.

Every field here is default-off (byte-identical pre-existing behaviour, ADR-002) and refused by :class:chamber.benchmarks.stage1_common.TrainedPolicyFactory at construction — the production gate dispatch cannot run with any EXPLORATORY knob active, by construction (the safety-loud-fail pattern). Activating one for a gate-facing protocol requires an ADR, not a config edit.

Attributes:

• partner_static_override (bool) –

  When True, :func:chamber.benchmarks.training_runner.run_training wraps the built partner in the zero-action :class:chamber.partners.exploratory.static_override.ExploratoryStaticPartnerOverride (the partner stands motionless at its reset pose; partner classes and registry untouched). EXPLORATORY only — the 2026-06-11 homo-static slice (spikes/results/stage1-failure-investigation/2026-06-11-homo-static-exploratory/) is its sole pre-stated use. The flag is folded into the run_id config fingerprint and stamped on every JSONL line (exploratory_partner_static) so no archive can carry a static-partner run silently.

Source code in src/concerto/training/config.py

class ExploratoryConfig(_FrozenModel):
    """EXPLORATORY rig knobs — structurally barred from gate-facing runs.

    Every field here is default-off (byte-identical pre-existing
    behaviour, ADR-002) and refused by
    :class:`chamber.benchmarks.stage1_common.TrainedPolicyFactory` at
    construction — the production gate dispatch cannot run with any
    EXPLORATORY knob active, by construction (the safety-loud-fail
    pattern). Activating one for a gate-facing protocol requires an
    ADR, not a config edit.

    Attributes:
        partner_static_override: When ``True``,
            :func:`chamber.benchmarks.training_runner.run_training`
            wraps the built partner in the zero-action
            :class:`chamber.partners.exploratory.static_override.ExploratoryStaticPartnerOverride`
            (the partner stands motionless at its reset pose; partner
            classes and registry untouched). EXPLORATORY only — the
            2026-06-11 homo-static slice
            (``spikes/results/stage1-failure-investigation/2026-06-11-homo-static-exploratory/``)
            is its sole pre-stated use. The flag is folded into the
            run_id config fingerprint and stamped on every JSONL line
            (``exploratory_partner_static``) so no archive can carry a
            static-partner run silently.
    """

    partner_static_override: bool = False

HAPPOHyperparams

Bases: _FrozenModel

On-policy ego-AHT HAPPO hyperparameters (ADR-002 §Decisions; plan/05 §3.2).

Defaults match the published HARL Bi-DexHands-style values where they translate; tuned conservatively for the small MPE task to keep the empirical-guarantee experiment within its 30-minute CPU budget (plan/05 §8).

Attributes:

• lr (float) –

  Adam learning rate for the actor + critic.

• gamma (float) –

  Discount factor.

• gae_lambda (float) –

  GAE-λ for advantage estimation.

• clip_eps (float) –

  PPO clipping epsilon.

• n_epochs (int) –

  Number of optimisation epochs per rollout.

• rollout_length (int) –

  Frames collected per epoch before the update step.

• batch_size (int) –

  SGD minibatch size; rollout_length must be a multiple.

• hidden_dim (int) –

  MLP hidden width for actor + critic.

Source code in src/concerto/training/config.py

class HAPPOHyperparams(_FrozenModel):
    """On-policy ego-AHT HAPPO hyperparameters (ADR-002 §Decisions; plan/05 §3.2).

    Defaults match the published HARL Bi-DexHands-style values where
    they translate; tuned conservatively for the small MPE task to keep
    the empirical-guarantee experiment within its 30-minute CPU budget
    (plan/05 §8).

    Attributes:
        lr: Adam learning rate for the actor + critic.
        gamma: Discount factor.
        gae_lambda: GAE-λ for advantage estimation.
        clip_eps: PPO clipping epsilon.
        n_epochs: Number of optimisation epochs per rollout.
        rollout_length: Frames collected per epoch before the update step.
        batch_size: SGD minibatch size; rollout_length must be a multiple.
        hidden_dim: MLP hidden width for actor + critic.
    """

    lr: float = Field(default=3.0e-4, gt=0.0)
    gamma: float = Field(default=0.99, ge=0.0, le=1.0)
    gae_lambda: float = Field(default=0.95, ge=0.0, le=1.0)
    clip_eps: float = Field(default=0.2, gt=0.0)
    n_epochs: int = Field(default=4, gt=0)
    rollout_length: int = Field(default=1024, gt=0)
    batch_size: int = Field(default=256, gt=0)
    hidden_dim: int = Field(default=64, gt=0)

PartnerConfig

Bases: _FrozenModel

Frozen partner spec (ADR-009 §Decision; plan/05 §3.5).

Mirrors the M4a :class:chamber.partners.api.PartnerSpec fields so the training loop can build a PartnerSpec directly from the config without re-validating.

Attributes:

• class_name (str) –

  Registry key passed to :func:chamber.partners.registry.load_partner. Phase-0 empirical-guarantee runs use "scripted_heuristic".

• seed (int) –

  Per-partner training seed; for scripted partners use 0.

• checkpoint_step (int | None) –

  Training step at which the checkpoint was taken; None for scripted partners.

• weights_uri (str | None) –

  local://... URI for frozen-RL partners; None for scripted partners.

• extra (dict[str, str]) –

  Free-form string-string metadata routed to PartnerSpec.extra.

Source code in src/concerto/training/config.py

class PartnerConfig(_FrozenModel):
    """Frozen partner spec (ADR-009 §Decision; plan/05 §3.5).

    Mirrors the M4a :class:`chamber.partners.api.PartnerSpec` fields so
    the training loop can build a ``PartnerSpec`` directly from the
    config without re-validating.

    Attributes:
        class_name: Registry key passed to
            :func:`chamber.partners.registry.load_partner`. Phase-0
            empirical-guarantee runs use ``"scripted_heuristic"``.
        seed: Per-partner training seed; for scripted partners use ``0``.
        checkpoint_step: Training step at which the checkpoint was
            taken; ``None`` for scripted partners.
        weights_uri: ``local://...`` URI for frozen-RL partners; ``None``
            for scripted partners.
        extra: Free-form string-string metadata routed to
            ``PartnerSpec.extra``.
    """

    class_name: str = "scripted_heuristic"
    seed: int = 0
    checkpoint_step: int | None = None
    weights_uri: str | None = None
    extra: dict[str, str] = Field(default_factory=dict)

RolloutRecorderConfig

Bases: _FrozenModel

Eval-rollout video + per-step sidecar JSONL knob (P1.05.11; ADR-017 §Decisions).

The rollout recorder captures one full eval episode every interval_frames training frames, emitting two paired artefacts at <archive_dir>/rollouts/<condition>/step_<NNNNNN>.{mp4,jsonl}: an MP4 the founder can watch and a per-step JSONL the agent can parse. The per-step JSONL is a small obs_summary subset (cube_pose, goal_pos, tcp_pose, ego qpos/qvel, partner qpos/qvel, plus is_grasped and gripper_width from info when exposed) — never the full 65-D flattened ego state — so agent-side reasoning stays tractable.

Records are written to sidecar files, not appended to the main <run_id>.jsonl stream — rollout data is bulky and tooling that streams the main JSONL must not be forced to parse rollout frames (ADR-017 §Schema appendix).

Attributes:

• enabled (bool) –

  Master switch. False (default) skips both the video and the sidecar JSONL — env construction does not request render_mode="rgb_array" and the per-step collection loop short-circuits. CI runs and unit tests should leave this off.

• interval_frames (int) –

  Record one eval episode every K training frames. Default 25_000 frames ≈ 4 recordings over a 100k Stage-1b cell. Smaller values produce more granular video history at proportionally higher disk + CPU cost.

• per_step_jsonl (bool) –

  When True (default), emit the paired per-step sidecar JSONL alongside the MP4. When False, emit the MP4 only. The agent-side co-analysis workflow assumes the sidecar JSONL is present.

• episodes_per_record (int) –

  How many eval episodes to record at each interval_frames trigger point. Default 1.

• fps (int) –

  Video frame rate for the MP4 encode. Default 20 — matches ManiSkill's default control_freq for the Stage-1b pick-place env.

Source code in src/concerto/training/config.py

class RolloutRecorderConfig(_FrozenModel):
    """Eval-rollout video + per-step sidecar JSONL knob (P1.05.11; ADR-017 §Decisions).

    The rollout recorder captures one full eval episode every
    ``interval_frames`` training frames, emitting two paired artefacts
    at ``<archive_dir>/rollouts/<condition>/step_<NNNNNN>.{mp4,jsonl}``:
    an MP4 the founder can watch and a per-step JSONL the agent can
    parse. The per-step JSONL is a small ``obs_summary`` subset
    (cube_pose, goal_pos, tcp_pose, ego qpos/qvel, partner qpos/qvel,
    plus ``is_grasped`` and ``gripper_width`` from ``info`` when
    exposed) — never the full 65-D flattened ego state — so agent-side
    reasoning stays tractable.

    Records are written to **sidecar files**, not appended to the main
    ``<run_id>.jsonl`` stream — rollout data is bulky and tooling that
    streams the main JSONL must not be forced to parse rollout frames
    (ADR-017 §Schema appendix).

    Attributes:
        enabled: Master switch. ``False`` (default) skips both the
            video and the sidecar JSONL — env construction does not
            request ``render_mode="rgb_array"`` and the per-step
            collection loop short-circuits. CI runs and unit tests
            should leave this off.
        interval_frames: Record one eval episode every K training
            frames. Default 25_000 frames ≈ 4 recordings over a 100k
            Stage-1b cell. Smaller values produce more granular video
            history at proportionally higher disk + CPU cost.
        per_step_jsonl: When ``True`` (default), emit the paired
            per-step sidecar JSONL alongside the MP4. When ``False``,
            emit the MP4 only. The agent-side co-analysis workflow
            assumes the sidecar JSONL is present.
        episodes_per_record: How many eval episodes to record at each
            ``interval_frames`` trigger point. Default 1.
        fps: Video frame rate for the MP4 encode. Default 20 — matches
            ManiSkill's default ``control_freq`` for the Stage-1b
            pick-place env.
    """

    enabled: bool = False
    interval_frames: int = Field(default=25_000, gt=0)
    per_step_jsonl: bool = True
    episodes_per_record: int = Field(default=1, gt=0)
    fps: int = Field(default=20, gt=0)

RuntimeConfig

Bases: _FrozenModel

Device + perf knobs (ADR-002 §Decisions; plan/08 §4 GPU determinism caveat).

Phase-0 development runs on Mac CPU (Apple M-series). Production zoo-seed runs target Linux + CUDA via scripts/repro/zoo_seed.sh (M4b-9b). The two regimes have different determinism contracts:

• CPU: byte-identical across runs at the same seed (plan/05 §6 criterion 7; pinned by tests/integration/test_cpu_determinism.py). deterministic_torch=True calls :func:torch.use_deterministic_algorithms once at trainer construction so any non-deterministic CUDA-style op falls back to a deterministic implementation if one exists, or warns loudly otherwise (warn_only=True).
• CUDA / MPS: plan/08 §4 grants the GPU determinism caveat — cuDNN / cuBLAS kernels are not bit-deterministic across hardware generations even with deterministic flags. Set deterministic_torch=False on GPU configs to disable the strict-mode flag and avoid the warning spam.

Attributes:

• device (Literal['auto', 'cpu', 'cuda', 'mps']) –

  "auto" resolves via :func:chamber.utils.device.torch_device (CUDA > MPS > CPU). Explicit "cpu" / "cuda" / "mps" pins the choice and raises if unavailable (the trainer reports the ADR cite in the error message so a confused user searching for the message lands on ADR-002 §Decisions).

• deterministic_torch (bool) –

  When True, the trainer calls :func:torch.use_deterministic_algorithms(True, warn_only=True) once at construction. Documented as a process-global side effect.

Source code in src/concerto/training/config.py

class RuntimeConfig(_FrozenModel):
    """Device + perf knobs (ADR-002 §Decisions; plan/08 §4 GPU determinism caveat).

    Phase-0 development runs on Mac CPU (Apple M-series). Production
    zoo-seed runs target Linux + CUDA via
    ``scripts/repro/zoo_seed.sh`` (M4b-9b). The two regimes have
    different determinism contracts:

    - **CPU**: byte-identical across runs at the same seed (plan/05 §6
      criterion 7; pinned by ``tests/integration/test_cpu_determinism.py``).
      ``deterministic_torch=True`` calls
      :func:`torch.use_deterministic_algorithms` once at trainer
      construction so any non-deterministic CUDA-style op falls back to
      a deterministic implementation if one exists, or warns loudly
      otherwise (``warn_only=True``).
    - **CUDA / MPS**: plan/08 §4 grants the GPU determinism caveat —
      cuDNN / cuBLAS kernels are not bit-deterministic across hardware
      generations even with deterministic flags. Set
      ``deterministic_torch=False`` on GPU configs to disable the
      strict-mode flag and avoid the warning spam.

    Attributes:
        device: ``"auto"`` resolves via
            :func:`chamber.utils.device.torch_device` (CUDA > MPS >
            CPU). Explicit ``"cpu"`` / ``"cuda"`` / ``"mps"`` pins the
            choice and raises if unavailable (the trainer reports the
            ADR cite in the error message so a confused user
            searching for the message lands on ADR-002 §Decisions).
        deterministic_torch: When ``True``, the trainer calls
            :func:`torch.use_deterministic_algorithms(True, warn_only=True)`
            once at construction. Documented as a process-global side
            effect.
    """

    device: Literal["auto", "cpu", "cuda", "mps"] = "auto"
    deterministic_torch: bool = True

SafetyConfig

Bases: _FrozenModel

Safety-stack runtime configuration for the training rollout (P1.04.5; ADR-007 §Stage 1b).

Phase-1 P1.04.5 wires the CBF-QP outer filter into :func:concerto.training.ego_aht.train per ADR-007 §Stage 1b implementation-details paragraph 2. The filter runs once per env step between the trainer's act and env.step; conformal slack state.lambda_ accumulates per cell and the :class:concerto.training.safety_telemetry.SafetyAggregator emits a safety_telemetry_final JSONL event at end-of-cell carrying the audit-gate predicate's inputs.

The block is read by :class:chamber.benchmarks.stage1_common.TrainedPolicyFactory's per-cell construction path; non-Stage-1b yaml configs default enabled=False so the filter doesn't engage outside its target use case (the Phase-0 MPE empirical-guarantee config + the Stage-0 smoke adapter both keep the un-filtered training rollout).

Kill-switch contract (D10 from the P1.04.5 Plan-subagent design): when enabled=False the training loop skips the filter entirely and emits safety_enabled=false in the JSONL summary. The audit-gate hook reads that flag and emits a non-failing "safety disabled by operator override; gate skipped" message — the operator's intent is preserved on the audit trail.

Attributes:

• enabled (bool) –

  Master switch. True (default) wires the filter + telemetry into the training loop. False skips both; the audit gate reads safety_enabled and treats the cell as non-gated.

• saturation_threshold (float) –

  Fraction of cartesian_accel_capacity above which the cell is considered saturated. Default 0.9 leaves a 10% margin — operator-tunable for the audit-gate predicate A. ADR-007 §Stage 1b implementation details paragraph 2 names the predicate verbatim (λ_steady_state < cartesian_accel_capacity); the 0.9 factor is the engineering safety margin.

• cbf_gamma (float) –

  Class-K function gain forwarded to :func:concerto.safety.conformal.update_lambda_from_predictor. Default 5.0 matches the existing :data:concerto.safety.cbf_qp.DEFAULT_CBF_GAMMA.

• lambda_safe (float) –

  Per-pair slack reset value at cell start (Phase-0 placeholder 0.0 per ADR-004 §Open questions; the derived form is a Stage-2 prerequisite).

• n_warmup_steps (int) –

  Length of the warmup window after the cell starts (matches :data:concerto.safety.api.DEFAULT_WARMUP_STEPS).

• predictor_kind (Literal['constant_velocity']) –

  Partner-trajectory predictor (Phase-0/1 default "constant_velocity" per :func:concerto.safety.conformal.constant_velocity_predict; AoI-conditioned variants are Phase-2 per ADR-004 §Open questions).

• tau_brake (float) –

  Per-step braking-fallback TTC threshold in seconds (P1.04.6; ADR-007 §Stage 1b training-vs-deployment parity). When the smallest pairwise time-to-collision drops below this, :func:concerto.safety.braking.maybe_brake overrides the ego action with the per-uid emergency-controller's push-apart response — the per-step backstop that does not depend on QP feasibility (Wang-Ames-Egerstedt 2017 eq. 17; ADR-004 risk-mitigation #1). Default matches :data:concerto.safety.braking.DEFAULT_TAU_BRAKE (100 ms).

• clamp_floor_ratio (float) –

  Per-step symmetric clamp on state.lambda_ (P1.05.7 / issue #180; ADR-004 §Decision Revision 6). Each per-pair λ is clamped to [-clamp_floor_ratio x cartesian_accel_capacity, +clamp_floor_ratio x cartesian_accel_capacity] after each :func:concerto.safety.conformal.update_lambda_from_predictor step. Must be strictly less than :attr:saturation_threshold so the audit-gate predicate A (which trips at |λ_ss| >= saturation_threshold x cap) reserves a clean margin above the clamp boundary for "the clamp itself failed" pathological cases. The buffer (saturation_threshold - clamp_floor_ratio) x cap is the engineering safety margin between in-loop clamping (operational) and audit-gate tripping (diagnostic). With production defaults (0.9 vs 0.7, cap = 10) the buffer is 2.0 m/s². Trades Huriot-Sibai 2025 §VI Theorem 3's exact long-run average-loss bound for operational robustness — the bound now holds modulo the clamped boundary, which is consistent with the engineering meaning of "conformal slack bounded by the conservative manipulation envelope". Pre-launch evidence: P1.05 100k-frame AS-hetero probe measured drift of exactly -η x |ε| = -5e-04 per step (matches analytic to 4 decimal places), projecting unclamped λ_ss ≈ -49.76 at the production budget — well past the audit-gate boundary of ±9.0.

Source code in src/concerto/training/config.py

class SafetyConfig(_FrozenModel):
    """Safety-stack runtime configuration for the training rollout (P1.04.5; ADR-007 §Stage 1b).

    Phase-1 P1.04.5 wires the CBF-QP outer filter into
    :func:`concerto.training.ego_aht.train` per ADR-007 §Stage 1b
    implementation-details paragraph 2. The filter runs once per env
    step between the trainer's ``act`` and ``env.step``; conformal
    slack ``state.lambda_`` accumulates per cell and the
    :class:`concerto.training.safety_telemetry.SafetyAggregator` emits
    a ``safety_telemetry_final`` JSONL event at end-of-cell carrying
    the audit-gate predicate's inputs.

    The block is read by
    :class:`chamber.benchmarks.stage1_common.TrainedPolicyFactory`'s
    per-cell construction path; non-Stage-1b yaml configs default
    ``enabled=False`` so the filter doesn't engage outside its target
    use case (the Phase-0 MPE empirical-guarantee config + the
    Stage-0 smoke adapter both keep the un-filtered training rollout).

    Kill-switch contract (D10 from the P1.04.5 Plan-subagent design):
    when ``enabled=False`` the training loop skips the filter entirely
    and emits ``safety_enabled=false`` in the JSONL summary. The
    audit-gate hook reads that flag and emits a non-failing
    "safety disabled by operator override; gate skipped" message — the
    operator's intent is preserved on the audit trail.

    Attributes:
        enabled: Master switch. ``True`` (default) wires the filter +
            telemetry into the training loop. ``False`` skips both;
            the audit gate reads ``safety_enabled`` and treats the
            cell as non-gated.
        saturation_threshold: Fraction of ``cartesian_accel_capacity``
            above which the cell is considered saturated. Default
            ``0.9`` leaves a 10% margin — operator-tunable for the
            audit-gate predicate A. ADR-007 §Stage 1b implementation
            details paragraph 2 names the predicate verbatim
            (``λ_steady_state < cartesian_accel_capacity``); the
            ``0.9`` factor is the engineering safety margin.
        cbf_gamma: Class-K function gain forwarded to
            :func:`concerto.safety.conformal.update_lambda_from_predictor`.
            Default ``5.0`` matches the existing
            :data:`concerto.safety.cbf_qp.DEFAULT_CBF_GAMMA`.
        lambda_safe: Per-pair slack reset value at cell start
            (Phase-0 placeholder ``0.0`` per ADR-004 §Open questions;
            the derived form is a Stage-2 prerequisite).
        n_warmup_steps: Length of the warmup window after the cell
            starts (matches
            :data:`concerto.safety.api.DEFAULT_WARMUP_STEPS`).
        predictor_kind: Partner-trajectory predictor (Phase-0/1
            default ``"constant_velocity"`` per
            :func:`concerto.safety.conformal.constant_velocity_predict`;
            AoI-conditioned variants are Phase-2 per ADR-004 §Open
            questions).
        tau_brake: Per-step braking-fallback TTC threshold in seconds
            (P1.04.6; ADR-007 §Stage 1b training-vs-deployment parity).
            When the smallest pairwise time-to-collision drops below
            this, :func:`concerto.safety.braking.maybe_brake` overrides
            the ego action with the per-uid emergency-controller's
            push-apart response — the per-step backstop that does not
            depend on QP feasibility (Wang-Ames-Egerstedt 2017 eq. 17;
            ADR-004 risk-mitigation #1). Default matches
            :data:`concerto.safety.braking.DEFAULT_TAU_BRAKE` (100 ms).
        clamp_floor_ratio: Per-step symmetric clamp on ``state.lambda_``
            (P1.05.7 / issue #180; ADR-004 §Decision Revision 6). Each
            per-pair λ is clamped to
            ``[-clamp_floor_ratio x cartesian_accel_capacity,
            +clamp_floor_ratio x cartesian_accel_capacity]`` after each
            :func:`concerto.safety.conformal.update_lambda_from_predictor`
            step. Must be strictly less than
            :attr:`saturation_threshold` so the audit-gate predicate A
            (which trips at ``|λ_ss| >= saturation_threshold x cap``)
            reserves a clean margin above the clamp boundary for "the
            clamp itself failed" pathological cases. The buffer
            ``(saturation_threshold - clamp_floor_ratio) x cap`` is the
            engineering safety margin between in-loop clamping
            (operational) and audit-gate tripping (diagnostic). With
            production defaults (0.9 vs 0.7, cap = 10) the buffer is
            2.0 m/s². Trades Huriot-Sibai 2025 §VI Theorem 3's exact
            long-run average-loss bound for operational robustness —
            the bound now holds modulo the clamped boundary, which is
            consistent with the engineering meaning of "conformal
            slack bounded by the conservative manipulation envelope".
            Pre-launch evidence: P1.05 100k-frame AS-hetero probe
            measured drift of exactly ``-η x |ε| = -5e-04`` per step
            (matches analytic to 4 decimal places), projecting
            unclamped λ_ss ≈ -49.76 at the production budget — well
            past the audit-gate boundary of ±9.0.
    """

    enabled: bool = False
    saturation_threshold: float = Field(default=0.9, gt=0.0, le=1.0)
    cbf_gamma: float = Field(default=5.0, gt=0.0)
    lambda_safe: float = 0.0
    n_warmup_steps: int = Field(default=50, ge=0)
    predictor_kind: Literal["constant_velocity"] = "constant_velocity"
    tau_brake: float = Field(default=0.100, gt=0.0)
    clamp_floor_ratio: float = Field(default=0.7, gt=0.0, le=1.0)

    @model_validator(mode="after")
    def _validate_clamp_below_saturation(self) -> SafetyConfig:
        """clamp_floor_ratio must be strictly less than saturation_threshold (P1.05.7 / #180).

        Without the strict inequality the clamp would engage at the same
        boundary the audit-gate trips, producing |λ_ss| == threshold ==
        audit-gate-trip on every clamped step. The default 0.7 < 0.9
        leaves a 0.2 x cap = 2.0 m/s² buffer at production cap. Tests
        in ``tests/unit/test_safety_config_clamp.py`` pin both this
        invariant + the boundary-buffer arithmetic.
        """
        if self.clamp_floor_ratio >= self.saturation_threshold:
            msg = (
                f"SafetyConfig.clamp_floor_ratio={self.clamp_floor_ratio} must be "
                f"strictly less than saturation_threshold={self.saturation_threshold}. "
                "The clamp engages at clamp_floor_ratio x cartesian_accel_capacity; "
                "the audit-gate predicate A trips at saturation_threshold x cap "
                "(P1.04.5 / #178). The buffer between them is the engineering "
                "safety margin — see ADR-004 §Decision Revision 6 (#180)."
            )
            raise ValueError(msg)
        return self

ShapingConfig

Bases: _FrozenModel

Training-cell reward-shaping knobs (P1.05.11; ADR-007 §Stage 1b Rev 18).

Potential-based settle term in exact Ng-Harada-Russell form, F(s, s') = gamma·Phi(s') - Phi(s) with the training MDP's own gamma and Phi(s) = -settle_alpha · min(max-arm-|qvel|, settle_qvel_cap) · 1[is_obj_placed(s)] — state-only, therefore policy-invariant (NHR 1999 Thm 1). Applied by :class:chamber.envs.stage1_shaping.Stage1SettleShapingWrapper around the training env only (:func:chamber.benchmarks.training_runner.run_training); the canonical env reward and evaluate() are byte-untouched, and every evaluation instrument measures unshaped success. See the 2026-06-11 PBRS-settle pre-statement for the alpha derivation and the frozen experiment design.

Attributes:

• settle_alpha (float) –

  Potential scale alpha. 0.0 (default) disables the wrapper entirely — byte-identical pre-existing behaviour (ADR-002). The 2026-06-11 slice pre-states 0.1 and 0.5.

• settle_qvel_cap (float) –

  Cap on the potential's qvel term, in rad/s. 0.7 covers the measured 0.40-0.66 hold band with margin (gamma-scan margins; settle-reachability pre-flight).

• transport_pbrs_coeff (float) –

  Co-carry Rung-2 remediation (COCARRY_RUNG2_REMEDIATION_2026-06-16; ADR-026 §Decision 4). Scale of the policy-invariant transport PBRS potential Phi = -coeff * dist(bar_centroid, goal) applied by :func:chamber.benchmarks.training_runner.run_training via :class:chamber.envs.cocarry_shaping.CoCarryTransportPBRSWrapper (F = gamma*Phi(s') - Phi(s); NHR-invariant, cannot change the optimum). 0.0 (default) disables the wrapper entirely — byte-identical pre-existing behaviour (ADR-002), so non-co-carry cells are unaffected. The co-carry training config sets this to :data:chamber.envs.cocarry.COCARRY_REWARD_TRANSPORT_PBRS_COEFF (a Tier-1 parity test pins the equality).

Source code in src/concerto/training/config.py

class ShapingConfig(_FrozenModel):
    """Training-cell reward-shaping knobs (P1.05.11; ADR-007 §Stage 1b Rev 18).

    Potential-based settle term in exact Ng-Harada-Russell form,
    F(s, s') = gamma·Phi(s') - Phi(s) with the training MDP's own gamma and
    Phi(s) = -settle_alpha · min(max-arm-|qvel|, settle_qvel_cap) ·
    1[is_obj_placed(s)] — state-only, therefore policy-invariant (NHR
    1999 Thm 1). Applied by
    :class:`chamber.envs.stage1_shaping.Stage1SettleShapingWrapper`
    around the *training* env only
    (:func:`chamber.benchmarks.training_runner.run_training`); the
    canonical env reward and ``evaluate()`` are byte-untouched, and
    every evaluation instrument measures unshaped success. See the
    2026-06-11 PBRS-settle pre-statement for the alpha derivation and the
    frozen experiment design.

    Attributes:
        settle_alpha: Potential scale alpha. ``0.0`` (default) disables the
            wrapper entirely — byte-identical pre-existing behaviour
            (ADR-002). The 2026-06-11 slice pre-states 0.1 and 0.5.
        settle_qvel_cap: Cap on the potential's qvel term, in rad/s.
            0.7 covers the measured 0.40-0.66 hold band with margin
            (gamma-scan margins; settle-reachability pre-flight).
        transport_pbrs_coeff: Co-carry Rung-2 remediation
            (COCARRY_RUNG2_REMEDIATION_2026-06-16; ADR-026 §Decision 4).
            Scale of the policy-invariant transport PBRS potential
            ``Phi = -coeff * dist(bar_centroid, goal)`` applied by
            :func:`chamber.benchmarks.training_runner.run_training` via
            :class:`chamber.envs.cocarry_shaping.CoCarryTransportPBRSWrapper`
            (``F = gamma*Phi(s') - Phi(s)``; NHR-invariant, cannot change
            the optimum). ``0.0`` (default) disables the wrapper entirely —
            byte-identical pre-existing behaviour (ADR-002), so non-co-carry
            cells are unaffected. The co-carry training config sets this to
            :data:`chamber.envs.cocarry.COCARRY_REWARD_TRANSPORT_PBRS_COEFF`
            (a Tier-1 parity test pins the equality).
    """

    settle_alpha: float = Field(default=0.0, ge=0.0)
    settle_qvel_cap: float = Field(default=0.7, gt=0.0)
    transport_pbrs_coeff: float = Field(default=0.0, ge=0.0)

WandbConfig

Bases: _FrozenModel

W&B sink toggle + project name (ADR-002 §Decisions; ADR-017 §Decisions; plan/05 §2).

Attributes:

• enabled (bool) –

  When False (default), :func:bind_run_logger is built without a W&B sink and only the JSONL fallback fires. CI runs and unit tests should leave this off.

• project (str) –

  W&B project name. Used only when enabled is True. Default "concerto-chamber" per ADR-017 §Decisions (single project across all stages; tag-based filtering for stage:, sub_stage:, condition:, prereg:, backfill:). Pre-ADR-017 default was "concerto-m4b" (legacy Month-4-Phase-B); migrated 2026-05-22.

Source code in src/concerto/training/config.py

class WandbConfig(_FrozenModel):
    """W&B sink toggle + project name (ADR-002 §Decisions; ADR-017 §Decisions; plan/05 §2).

    Attributes:
        enabled: When ``False`` (default), :func:`bind_run_logger` is
            built without a W&B sink and only the JSONL fallback fires.
            CI runs and unit tests should leave this off.
        project: W&B project name. Used only when ``enabled`` is ``True``.
            Default ``"concerto-chamber"`` per ADR-017 §Decisions
            (single project across all stages; tag-based filtering for
            ``stage:``, ``sub_stage:``, ``condition:``, ``prereg:``,
            ``backfill:``). Pre-ADR-017 default was ``"concerto-m4b"``
            (legacy Month-4-Phase-B); migrated 2026-05-22.
    """

    enabled: bool = False
    project: str = "concerto-chamber"

load_config

load_config(
    *, config_path: Path, overrides: list[str] | None = None
) -> EgoAHTConfig

Compose a Hydra config + validate via :class:EgoAHTConfig (T4b.11; ADR-002 §Decisions).

The function does NOT use Hydra's @hydra.main decorator (which takes over the process's CWD + argv); it uses the lower-level :class:hydra.compose API so the call is testable and re-entrant.

Parameters:

• config_path (Path) –

  Absolute path to the YAML config file (e.g. configs/training/ego_aht_happo/mpe_cooperative_push.yaml). The directory becomes Hydra's config_dir and the stem becomes the config_name it loads. Splitting via the file path keeps the YAML's root-level keys at the root of the composed config (rather than Hydra's path-folding).

• overrides (list[str] | None, default: None ) –

  Optional list of Hydra CLI-style overrides (e.g. ["seed=7", "happo.lr=1e-4"]).

Returns:

• EgoAHTConfig –

  A frozen :class:EgoAHTConfig ready for

• EgoAHTConfig –

  func:concerto.training.ego_aht.train.

Raises:

• ValidationError –

  If the composed config violates the schema (missing required field, out-of-range hyperparam, duplicate agent uids, etc.).

Source code in src/concerto/training/config.py

def load_config(
    *,
    config_path: Path,
    overrides: list[str] | None = None,
) -> EgoAHTConfig:
    """Compose a Hydra config + validate via :class:`EgoAHTConfig` (T4b.11; ADR-002 §Decisions).

    The function does NOT use Hydra's ``@hydra.main`` decorator (which
    takes over the process's CWD + argv); it uses the lower-level
    :class:`hydra.compose` API so the call is testable and re-entrant.

    Args:
        config_path: Absolute path to the YAML config file (e.g.
            ``configs/training/ego_aht_happo/mpe_cooperative_push.yaml``).
            The directory becomes Hydra's ``config_dir`` and the
            stem becomes the ``config_name`` it loads. Splitting via the
            file path keeps the YAML's root-level keys at the root of
            the composed config (rather than Hydra's path-folding).
        overrides: Optional list of Hydra CLI-style overrides
            (e.g. ``["seed=7", "happo.lr=1e-4"]``).

    Returns:
        A frozen :class:`EgoAHTConfig` ready for
        :func:`concerto.training.ego_aht.train`.

    Raises:
        pydantic.ValidationError: If the composed config violates the
            schema (missing required field, out-of-range hyperparam,
            duplicate agent uids, etc.).
    """
    config_dir = config_path.parent.resolve()
    config_name = config_path.stem
    # Re-entrancy: another caller (or a leftover pytest fixture) may have
    # left ``GlobalHydra`` initialised. Clear it so initialize_config_dir's
    # ``with`` block can re-bind to the new directory cleanly.
    if GlobalHydra.instance().is_initialized():
        GlobalHydra.instance().clear()
    with initialize_config_dir(config_dir=str(config_dir), version_base="1.3"):
        cfg = compose(config_name=config_name, overrides=overrides or [])
    raw = OmegaConf.to_container(cfg, resolve=True)
    if not isinstance(raw, dict):
        raise TypeError(
            f"Composed Hydra config must be a mapping at root; got {type(raw).__name__}"
        )
    return EgoAHTConfig.model_validate(raw)

Ego-AHT training loop entry point (T4b.11; ADR-002 §Decisions; plan/05 §3.5).

The single user-facing API for an ego-AHT training run is :func:train. It wires up logging, seeding, per-step rollout collection, checkpoint emission, and the trainer-factory seam, and returns a :class:RewardCurve for T4b.13's empirical-guarantee assertion.

Dependency-direction discipline (project plan/10 §2 dependency-direction rule): concerto.* MUST NOT import from chamber.*. The training loop therefore takes the env and partner via dependency injection — the chamber-side runner (chamber.benchmarks.training_runner) builds the concrete env (:class:chamber.envs.mpe_cooperative_push.MPECooperativePushEnv) and partner (via :func:chamber.partners.registry.load_partner) and hands them to :func:train. That keeps every concerto.* arrow pointing only at lower layers.

Trainer-factory injection: this loop lives in concerto.* and so cannot import from chamber.* (project plan/10 §2). The real ego-PPO trainer (:class:chamber.benchmarks.ego_ppo_trainer.EgoPPOTrainer) wraps HARL's HAPPO and lives on the chamber side; the chamber-side :func:chamber.benchmarks.training_runner.run_training selects it as the default. :func:train therefore continues to accept trainer_factory and falls back to :class:RandomEgoTrainer when called directly without an injected factory — which keeps the loop unit-testable inside concerto.* without violating the dependency direction.

ADR-002 risk-mitigation #1: this loop is the substrate the empirical- guarantee assertion runs against. Do not silently drop steps, mutate the rollout collection mid-loop, or change the partner-frozen contract without a new ADR.

EgoTrainer

Bases: Protocol

Minimal contract the training loop expects of an ego trainer (T4b.11; ADR-002 §Decisions).

Two concrete implementations satisfy this Protocol:

• :class:chamber.benchmarks.ego_ppo_trainer.EgoPPOTrainer — the real HARL-HAPPO-backed ego-PPO trainer (M4b-8a / plan/05 §3.5), and the default selected by :func:chamber.benchmarks.training_runner.run_training.
• :class:RandomEgoTrainer — the Phase-0 reference fallback, used by :func:train when no trainer_factory is injected.

The Protocol is intentionally tiny (:meth:act + :meth:observe + :meth:update + :meth:state_dict) so the seam stays small enough that an external user can plug in their own algorithm without changing :func:train.

Source code in src/concerto/training/ego_aht.py

class EgoTrainer(Protocol):
    """Minimal contract the training loop expects of an ego trainer (T4b.11; ADR-002 §Decisions).

    Two concrete implementations satisfy this Protocol:

    - :class:`chamber.benchmarks.ego_ppo_trainer.EgoPPOTrainer` — the
      real HARL-HAPPO-backed ego-PPO trainer (M4b-8a / plan/05 §3.5),
      and the default selected by
      :func:`chamber.benchmarks.training_runner.run_training`.
    - :class:`RandomEgoTrainer` — the Phase-0 reference fallback, used
      by :func:`train` when no ``trainer_factory`` is injected.

    The Protocol is intentionally tiny (:meth:`act` + :meth:`observe` +
    :meth:`update` + :meth:`state_dict`) so the seam stays small enough
    that an external user can plug in their own algorithm without
    changing :func:`train`.
    """

    def act(
        self,
        obs: Mapping[str, Any],
        *,
        deterministic: bool = False,
    ) -> NDArray[np.floating]:
        """Sample (or pick deterministically) the ego action (ADR-002 §Decisions)."""
        ...  # pragma: no cover

    def observe(
        self,
        obs: Mapping[str, Any],
        reward: Any,  # noqa: ANN401 - scalar float (single-env) or per-env vector (vectorised; P1.05.10)
        done: Any,  # noqa: ANN401 - scalar bool or per-env vector
        *,
        truncated: Any = False,  # noqa: ANN401 - scalar bool or per-env vector
        final_obs: Mapping[str, Any] | None = None,
    ) -> None:
        """Record a (s, a, r, s', done, truncated) tuple (ADR-002 §Decisions; Pardo 2017).

        ``done`` keeps the historical "this step ended the episode"
        meaning (terminated OR truncated). ``truncated`` is a
        keyword-only flag that distinguishes time-limit truncation from
        true termination — needed by PPO-style trainers to bootstrap the
        GAE target correctly (see :func:`chamber.benchmarks.ego_ppo_trainer.compute_gae`
        and project issue #62 for the root-cause writeup). Default
        ``truncated=False`` keeps legacy callers' behavior unchanged.

        Vectorised cells (P1.05.10; ADR-007 §Stage 1b regime-alignment
        revision): ``reward`` / ``done`` / ``truncated`` arrive as
        per-env vectors and ``final_obs`` carries the pre-reset batched
        obs from the chamber-side auto-reset wrapper whenever any env
        ended its episode this step (the Pardo bootstrap target).
        Single-env callers never pass ``final_obs``.
        """
        ...  # pragma: no cover

    def update(self) -> None:
        """Run one optimisation epoch on the buffered rollout (ADR-002 §Decisions)."""
        ...  # pragma: no cover

    def state_dict(self) -> dict[str, Any]:
        """Return the trainer's torch state-dict for checkpointing (ADR-002 §Decisions)."""
        ...  # pragma: no cover

act

act(
    obs: Mapping[str, Any], *, deterministic: bool = False
) -> NDArray[np.floating]

Sample (or pick deterministically) the ego action (ADR-002 §Decisions).

Source code in src/concerto/training/ego_aht.py

def act(
    self,
    obs: Mapping[str, Any],
    *,
    deterministic: bool = False,
) -> NDArray[np.floating]:
    """Sample (or pick deterministically) the ego action (ADR-002 §Decisions)."""
    ...  # pragma: no cover

observe

observe(
    obs: Mapping[str, Any],
    reward: Any,
    done: Any,
    *,
    truncated: Any = False,
    final_obs: Mapping[str, Any] | None = None,
) -> None

Record a (s, a, r, s', done, truncated) tuple (ADR-002 §Decisions; Pardo 2017).

done keeps the historical "this step ended the episode" meaning (terminated OR truncated). truncated is a keyword-only flag that distinguishes time-limit truncation from true termination — needed by PPO-style trainers to bootstrap the GAE target correctly (see :func:chamber.benchmarks.ego_ppo_trainer.compute_gae and project issue #62 for the root-cause writeup). Default truncated=False keeps legacy callers' behavior unchanged.

Vectorised cells (P1.05.10; ADR-007 §Stage 1b regime-alignment revision): reward / done / truncated arrive as per-env vectors and final_obs carries the pre-reset batched obs from the chamber-side auto-reset wrapper whenever any env ended its episode this step (the Pardo bootstrap target). Single-env callers never pass final_obs.

Source code in src/concerto/training/ego_aht.py

def observe(
    self,
    obs: Mapping[str, Any],
    reward: Any,  # noqa: ANN401 - scalar float (single-env) or per-env vector (vectorised; P1.05.10)
    done: Any,  # noqa: ANN401 - scalar bool or per-env vector
    *,
    truncated: Any = False,  # noqa: ANN401 - scalar bool or per-env vector
    final_obs: Mapping[str, Any] | None = None,
) -> None:
    """Record a (s, a, r, s', done, truncated) tuple (ADR-002 §Decisions; Pardo 2017).

    ``done`` keeps the historical "this step ended the episode"
    meaning (terminated OR truncated). ``truncated`` is a
    keyword-only flag that distinguishes time-limit truncation from
    true termination — needed by PPO-style trainers to bootstrap the
    GAE target correctly (see :func:`chamber.benchmarks.ego_ppo_trainer.compute_gae`
    and project issue #62 for the root-cause writeup). Default
    ``truncated=False`` keeps legacy callers' behavior unchanged.

    Vectorised cells (P1.05.10; ADR-007 §Stage 1b regime-alignment
    revision): ``reward`` / ``done`` / ``truncated`` arrive as
    per-env vectors and ``final_obs`` carries the pre-reset batched
    obs from the chamber-side auto-reset wrapper whenever any env
    ended its episode this step (the Pardo bootstrap target).
    Single-env callers never pass ``final_obs``.
    """
    ...  # pragma: no cover

state_dict

state_dict() -> dict[str, Any]

Return the trainer's torch state-dict for checkpointing (ADR-002 §Decisions).

Source code in src/concerto/training/ego_aht.py

def state_dict(self) -> dict[str, Any]:
    """Return the trainer's torch state-dict for checkpointing (ADR-002 §Decisions)."""
    ...  # pragma: no cover

update

update() -> None

Run one optimisation epoch on the buffered rollout (ADR-002 §Decisions).

Source code in src/concerto/training/ego_aht.py

def update(self) -> None:
    """Run one optimisation epoch on the buffered rollout (ADR-002 §Decisions)."""
    ...  # pragma: no cover

EnvLike

Bases: Protocol

Structural Gymnasium-multi-agent env contract the loop needs (T4b.11; ADR-002 §Decisions).

Defined locally so :func:train does not import a concrete class from chamber.* (project plan/10 §2 dependency-direction rule). The chamber-side :class:chamber.envs.mpe_cooperative_push.MPECooperativePushEnv satisfies this Protocol structurally.

Source code in src/concerto/training/ego_aht.py

@runtime_checkable
class EnvLike(Protocol):
    """Structural Gymnasium-multi-agent env contract the loop needs (T4b.11; ADR-002 §Decisions).

    Defined locally so :func:`train` does not import a concrete class
    from ``chamber.*`` (project plan/10 §2 dependency-direction rule). The
    chamber-side :class:`chamber.envs.mpe_cooperative_push.MPECooperativePushEnv`
    satisfies this Protocol structurally.
    """

    def reset(
        self,
        *,
        seed: int | None = None,
        options: dict[str, Any] | None = None,
    ) -> tuple[Mapping[str, Any], Mapping[str, Any]]:
        """Reset to the start of an episode (T4b.11; ADR-002 §Decisions)."""
        ...  # pragma: no cover

    def step(
        self,
        action: dict[str, NDArray[np.floating]],
    ) -> tuple[Mapping[str, Any], float, bool, bool, Mapping[str, Any]]:
        """Advance one tick (T4b.11; ADR-002 §Decisions).

        Takes a concrete ``dict`` rather than a ``Mapping`` because the
        chamber-side :class:`MPECooperativePushEnv` and the future
        ManiSkill v3 wrappers all require dict-keyed access (mutation
        of the action dict is intentional in some wrappers' rate-limit
        / collision-injection paths).
        """
        ...  # pragma: no cover

reset

reset(
    *,
    seed: int | None = None,
    options: dict[str, Any] | None = None,
) -> tuple[Mapping[str, Any], Mapping[str, Any]]

Reset to the start of an episode (T4b.11; ADR-002 §Decisions).

Source code in src/concerto/training/ego_aht.py

def reset(
    self,
    *,
    seed: int | None = None,
    options: dict[str, Any] | None = None,
) -> tuple[Mapping[str, Any], Mapping[str, Any]]:
    """Reset to the start of an episode (T4b.11; ADR-002 §Decisions)."""
    ...  # pragma: no cover

step

step(
    action: dict[str, NDArray[floating]],
) -> tuple[
    Mapping[str, Any], float, bool, bool, Mapping[str, Any]
]

Advance one tick (T4b.11; ADR-002 §Decisions).

Takes a concrete dict rather than a Mapping because the chamber-side :class:MPECooperativePushEnv and the future ManiSkill v3 wrappers all require dict-keyed access (mutation of the action dict is intentional in some wrappers' rate-limit / collision-injection paths).

Source code in src/concerto/training/ego_aht.py

def step(
    self,
    action: dict[str, NDArray[np.floating]],
) -> tuple[Mapping[str, Any], float, bool, bool, Mapping[str, Any]]:
    """Advance one tick (T4b.11; ADR-002 §Decisions).

    Takes a concrete ``dict`` rather than a ``Mapping`` because the
    chamber-side :class:`MPECooperativePushEnv` and the future
    ManiSkill v3 wrappers all require dict-keyed access (mutation
    of the action dict is intentional in some wrappers' rate-limit
    / collision-injection paths).
    """
    ...  # pragma: no cover

PartnerLike

Bases: Protocol

Structural FrozenPartner contract the loop needs (T4b.11; ADR-009 §Decision).

Defined locally to keep concerto.* free of chamber.* imports. The M4a :class:chamber.partners.api.FrozenPartner satisfies this Protocol structurally — both the heuristic + the future frozen-RL adapters drop in unchanged.

The spec attribute is declared as :class:Any so concrete implementations can attach any spec type (M4a's :class:chamber.partners.api.PartnerSpec); the loop only uses it for diagnostic logging, never structurally. Any is required here rather than object because Protocol attributes are invariant and concrete subtypes (PartnerSpec) are not assignable to a mutable object annotation.

Source code in src/concerto/training/ego_aht.py

@runtime_checkable
class PartnerLike(Protocol):
    """Structural ``FrozenPartner`` contract the loop needs (T4b.11; ADR-009 §Decision).

    Defined locally to keep ``concerto.*`` free of ``chamber.*`` imports.
    The M4a :class:`chamber.partners.api.FrozenPartner` satisfies this
    Protocol structurally — both the heuristic + the future frozen-RL
    adapters drop in unchanged.

    The ``spec`` attribute is declared as :class:`Any` so concrete
    implementations can attach any spec type (M4a's
    :class:`chamber.partners.api.PartnerSpec`); the loop only uses it
    for diagnostic logging, never structurally. ``Any`` is required
    here rather than ``object`` because Protocol attributes are
    invariant and concrete subtypes (PartnerSpec) are not assignable to
    a mutable ``object`` annotation.
    """

    spec: Any

    def reset(self, *, seed: int | None = None) -> None:
        """Reset internal episode state (ADR-009 §Decision)."""
        ...  # pragma: no cover

    def act(
        self,
        obs: Mapping[str, Any],
        *,
        deterministic: bool = True,
    ) -> NDArray[np.floating]:
        """Pick an action for the partner's own uid (ADR-009 §Decision)."""
        ...  # pragma: no cover

act

act(
    obs: Mapping[str, Any], *, deterministic: bool = True
) -> NDArray[np.floating]

Pick an action for the partner's own uid (ADR-009 §Decision).

Source code in src/concerto/training/ego_aht.py

def act(
    self,
    obs: Mapping[str, Any],
    *,
    deterministic: bool = True,
) -> NDArray[np.floating]:
    """Pick an action for the partner's own uid (ADR-009 §Decision)."""
    ...  # pragma: no cover

reset

reset(*, seed: int | None = None) -> None

Reset internal episode state (ADR-009 §Decision).

Source code in src/concerto/training/ego_aht.py

def reset(self, *, seed: int | None = None) -> None:
    """Reset internal episode state (ADR-009 §Decision)."""
    ...  # pragma: no cover

RandomEgoTrainer

Reference :class:EgoTrainer that samples uniformly from the action space.

Exists so :func:train can be exercised end-to-end before the HARL fork lands (T4b.4-T4b.7). Not a real learner — :meth:update is a no-op, :meth:state_dict returns an empty dict — but the loop's plumbing (env stepping, partner act, checkpoint emission, JSONL logging) is fully exercised. T4b.13 will swap to EgoAHTHAPPO via the trainer-factory seam (ADR-002 §Decisions; plan/05 §3.5).

Source code in src/concerto/training/ego_aht.py

class RandomEgoTrainer:
    """Reference :class:`EgoTrainer` that samples uniformly from the action space.

    Exists so :func:`train` can be exercised end-to-end before the HARL
    fork lands (T4b.4-T4b.7). Not a real learner — :meth:`update` is a
    no-op, :meth:`state_dict` returns an empty dict — but the loop's
    plumbing (env stepping, partner act, checkpoint emission, JSONL
    logging) is fully exercised. T4b.13 will swap to ``EgoAHTHAPPO``
    via the trainer-factory seam (ADR-002 §Decisions; plan/05 §3.5).
    """

    def __init__(self, *, ego_uid: str, action_dim: int, root_seed: int) -> None:
        """Build a uniform-random reference trainer (T4b.11; ADR-002 §Decisions).

        Args:
            ego_uid: Stored for downstream identity propagation (the
                trainer doesn't read it at action time but the loop
                uses it as the dict-action key).
            action_dim: Length of the ego's action vector.
            root_seed: Project seed; the trainer's RNG is derived via
                :func:`concerto.training.seeding.derive_substream` for
                P6 reproducibility.
        """
        self._ego_uid = ego_uid
        self._action_dim = action_dim
        self._rng: np.random.Generator = derive_substream(
            "training.ego_random", root_seed=root_seed
        ).default_rng()

    def act(
        self,
        obs: Mapping[str, Any],
        *,
        deterministic: bool = False,
    ) -> NDArray[np.floating]:
        """Sample uniformly from [-1, 1]^action_dim (ADR-002 §Decisions; plan/05 §3.5)."""
        del obs
        if deterministic:
            return np.zeros(self._action_dim, dtype=np.float32)
        return self._rng.uniform(-1.0, 1.0, size=self._action_dim).astype(np.float32)

    def observe(
        self,
        obs: Mapping[str, Any],
        reward: Any,  # noqa: ANN401 - scalar or per-env vector (P1.05.10); see EgoTrainer.observe
        done: Any,  # noqa: ANN401 - scalar or per-env vector
        *,
        truncated: Any = False,  # noqa: ANN401 - scalar or per-env vector
        final_obs: Mapping[str, Any] | None = None,
    ) -> None:
        """No-op (ADR-002 §Decisions): reference trainer has no rollout buffer."""
        del obs, reward, done, truncated, final_obs

    def update(self) -> None:
        """No-op (ADR-002 §Decisions): reference trainer has no learnable params."""

    def state_dict(self) -> dict[str, Any]:
        """Return an empty dict (ADR-002 §Decisions: trainer is parameter-free)."""
        return {}

__init__

__init__(
    *, ego_uid: str, action_dim: int, root_seed: int
) -> None

Build a uniform-random reference trainer (T4b.11; ADR-002 §Decisions).

Parameters:

• ego_uid (str) –

  Stored for downstream identity propagation (the trainer doesn't read it at action time but the loop uses it as the dict-action key).

• action_dim (int) –

  Length of the ego's action vector.

• root_seed (int) –

  Project seed; the trainer's RNG is derived via :func:concerto.training.seeding.derive_substream for P6 reproducibility.

Source code in src/concerto/training/ego_aht.py

def __init__(self, *, ego_uid: str, action_dim: int, root_seed: int) -> None:
    """Build a uniform-random reference trainer (T4b.11; ADR-002 §Decisions).

    Args:
        ego_uid: Stored for downstream identity propagation (the
            trainer doesn't read it at action time but the loop
            uses it as the dict-action key).
        action_dim: Length of the ego's action vector.
        root_seed: Project seed; the trainer's RNG is derived via
            :func:`concerto.training.seeding.derive_substream` for
            P6 reproducibility.
    """
    self._ego_uid = ego_uid
    self._action_dim = action_dim
    self._rng: np.random.Generator = derive_substream(
        "training.ego_random", root_seed=root_seed
    ).default_rng()

act

act(
    obs: Mapping[str, Any], *, deterministic: bool = False
) -> NDArray[np.floating]

Sample uniformly from [-1, 1]^action_dim (ADR-002 §Decisions; plan/05 §3.5).

Source code in src/concerto/training/ego_aht.py

def act(
    self,
    obs: Mapping[str, Any],
    *,
    deterministic: bool = False,
) -> NDArray[np.floating]:
    """Sample uniformly from [-1, 1]^action_dim (ADR-002 §Decisions; plan/05 §3.5)."""
    del obs
    if deterministic:
        return np.zeros(self._action_dim, dtype=np.float32)
    return self._rng.uniform(-1.0, 1.0, size=self._action_dim).astype(np.float32)

observe

observe(
    obs: Mapping[str, Any],
    reward: Any,
    done: Any,
    *,
    truncated: Any = False,
    final_obs: Mapping[str, Any] | None = None,
) -> None

No-op (ADR-002 §Decisions): reference trainer has no rollout buffer.

Source code in src/concerto/training/ego_aht.py

def observe(
    self,
    obs: Mapping[str, Any],
    reward: Any,  # noqa: ANN401 - scalar or per-env vector (P1.05.10); see EgoTrainer.observe
    done: Any,  # noqa: ANN401 - scalar or per-env vector
    *,
    truncated: Any = False,  # noqa: ANN401 - scalar or per-env vector
    final_obs: Mapping[str, Any] | None = None,
) -> None:
    """No-op (ADR-002 §Decisions): reference trainer has no rollout buffer."""
    del obs, reward, done, truncated, final_obs

state_dict

state_dict() -> dict[str, Any]

Return an empty dict (ADR-002 §Decisions: trainer is parameter-free).

Source code in src/concerto/training/ego_aht.py

def state_dict(self) -> dict[str, Any]:
    """Return an empty dict (ADR-002 §Decisions: trainer is parameter-free)."""
    return {}

update

update() -> None

No-op (ADR-002 §Decisions): reference trainer has no learnable params.

Source code in src/concerto/training/ego_aht.py

def update(self) -> None:
    """No-op (ADR-002 §Decisions): reference trainer has no learnable params."""

RewardCurve dataclass

Result of one ego-AHT training run (T4b.11; T4b.13 consumer; ADR-002 §Decisions).

Attributes:

• run_id (str) –

  16-hex run identifier (from :class:concerto.training.logging.RunContext).

• per_step_ego_rewards (list[float]) –

  One entry per env step. T4b.13's empirical- guarantee assertion runs over the moving-window-of-10 mean of this series.

• per_episode_ego_rewards (list[float]) –

  Sum-of-step reward per episode. Coarser than per_step; the canonical "epoch reward" the empirical-guarantee plot embeds in docs/explanation/why-aht.md.

• checkpoint_paths (list[Path]) –

  Absolute paths of every .pt artefact saved during the run. T4b.14 reads the canonical 50%-step file from this list.

Source code in src/concerto/training/ego_aht.py

@dataclass(frozen=True)
class RewardCurve:
    """Result of one ego-AHT training run (T4b.11; T4b.13 consumer; ADR-002 §Decisions).

    Attributes:
        run_id: 16-hex run identifier (from
            :class:`concerto.training.logging.RunContext`).
        per_step_ego_rewards: One entry per env step. T4b.13's empirical-
            guarantee assertion runs over the moving-window-of-10 mean
            of this series.
        per_episode_ego_rewards: Sum-of-step reward per episode. Coarser
            than ``per_step``; the canonical "epoch reward" the
            empirical-guarantee plot embeds in
            ``docs/explanation/why-aht.md``.
        checkpoint_paths: Absolute paths of every ``.pt`` artefact saved
            during the run. T4b.14 reads the canonical 50%-step file
            from this list.
    """

    run_id: str
    per_step_ego_rewards: list[float] = field(default_factory=list)
    per_episode_ego_rewards: list[float] = field(default_factory=list)
    checkpoint_paths: list[Path] = field(default_factory=list)

TrainerFactory

Bases: Protocol

Constructor that builds an :class:EgoTrainer (T4b.11; ADR-002 §Decisions).

The seam through which :func:train plugs in the algorithm. :func:chamber.benchmarks.training_runner.run_training selects :meth:EgoPPOTrainer.from_config <chamber.benchmarks.ego_ppo_trainer.EgoPPOTrainer.from_config> by default (M4b-8a / plan/05 §3.5).

The factory receives the partner so it can refuse to construct against a non-frozen partner before any tensor allocation (ADR-009 §Consequences; plan/05 §6 #3). The default factory :meth:~chamber.benchmarks.ego_ppo_trainer.EgoPPOTrainer.from_config calls :func:~chamber.benchmarks.ego_ppo_trainer._assert_partner_is_frozen on the partner as its first construction step.

Source code in src/concerto/training/ego_aht.py

class TrainerFactory(Protocol):
    """Constructor that builds an :class:`EgoTrainer` (T4b.11; ADR-002 §Decisions).

    The seam through which :func:`train` plugs in the algorithm.
    :func:`chamber.benchmarks.training_runner.run_training` selects
    :meth:`EgoPPOTrainer.from_config <chamber.benchmarks.ego_ppo_trainer.EgoPPOTrainer.from_config>`
    by default (M4b-8a / plan/05 §3.5).

    The factory receives the partner so it can refuse to construct
    against a non-frozen partner before any tensor allocation
    (ADR-009 §Consequences; plan/05 §6 #3). The default factory
    :meth:`~chamber.benchmarks.ego_ppo_trainer.EgoPPOTrainer.from_config`
    calls :func:`~chamber.benchmarks.ego_ppo_trainer._assert_partner_is_frozen`
    on the partner as its first construction step.
    """

    def __call__(
        self,
        cfg: EgoAHTConfig,
        *,
        env: EnvLike,
        partner: PartnerLike,
        ego_uid: str,
        logger: structlog.BoundLogger | None = None,
    ) -> EgoTrainer:
        """Build a trainer (ADR-002 §Decisions; ADR-017; plan/05 §3.5; ADR-009 §Consequences).

        ``logger`` is the optional structlog BoundLogger from
        :func:`concerto.training.logging.bind_run_logger` (P1.05.11 /
        ADR-017 §Decisions). When supplied, concrete trainers like
        :class:`chamber.benchmarks.ego_ppo_trainer.EgoPPOTrainer`
        thread it through their constructor so PPO update scalars
        flow through the same JSONL + W&B sinks as the driver's
        own events. Default ``None`` preserves pre-P1.05.11 silent
        behaviour.
        """
        ...  # pragma: no cover

__call__

__call__(
    cfg: EgoAHTConfig,
    *,
    env: EnvLike,
    partner: PartnerLike,
    ego_uid: str,
    logger: BoundLogger | None = None,
) -> EgoTrainer

Build a trainer (ADR-002 §Decisions; ADR-017; plan/05 §3.5; ADR-009 §Consequences).

logger is the optional structlog BoundLogger from :func:concerto.training.logging.bind_run_logger (P1.05.11 / ADR-017 §Decisions). When supplied, concrete trainers like :class:chamber.benchmarks.ego_ppo_trainer.EgoPPOTrainer thread it through their constructor so PPO update scalars flow through the same JSONL + W&B sinks as the driver's own events. Default None preserves pre-P1.05.11 silent behaviour.

Source code in src/concerto/training/ego_aht.py

def __call__(
    self,
    cfg: EgoAHTConfig,
    *,
    env: EnvLike,
    partner: PartnerLike,
    ego_uid: str,
    logger: structlog.BoundLogger | None = None,
) -> EgoTrainer:
    """Build a trainer (ADR-002 §Decisions; ADR-017; plan/05 §3.5; ADR-009 §Consequences).

    ``logger`` is the optional structlog BoundLogger from
    :func:`concerto.training.logging.bind_run_logger` (P1.05.11 /
    ADR-017 §Decisions). When supplied, concrete trainers like
    :class:`chamber.benchmarks.ego_ppo_trainer.EgoPPOTrainer`
    thread it through their constructor so PPO update scalars
    flow through the same JSONL + W&B sinks as the driver's
    own events. Default ``None`` preserves pre-P1.05.11 silent
    behaviour.
    """
    ...  # pragma: no cover

TrainingResult

Bases: NamedTuple

Return value of :func:train and :func:chamber.benchmarks.training_runner.run_training.

Pairs the diagnostic reward stream (:class:RewardCurve) with the trained ego policy (:class:EgoTrainer) so Phase-1 callers like :class:chamber.benchmarks.stage1_common.TrainedPolicyFactory (P1.04 / ADR-007 §Stage 1b) can wrap result.trainer.act in a per-step closure without paying a checkpoint round-trip cost. The trainer's internal state (HARL HAPPO actor + critic + optimisers) survives :func:train's scope through this return value rather than being reloaded from disk.

NamedTuple (not a bare tuple[RewardCurve, EgoTrainer]) so call sites use the field names — result.curve / result.trainer — instead of positional indexing. Tuple-unpack still works (curve, trainer = run_training(cfg)) for callers that prefer it.

Attributes:

• curve (RewardCurve) –

  The diagnostic per-step + per-episode reward stream T4b.13's empirical-guarantee assertion runs over. Same shape as before P1.04 — this NamedTuple is a wrapper, not a replacement.

• trainer (EgoTrainer) –

  The trained :class:EgoTrainer instance, with the HARL HAPPO actor weights at their post-training state. Use trainer.act(obs, deterministic=True) for evaluation rollouts. When :func:train is called without a trainer_factory (Phase-0 reference path), this is the :class:RandomEgoTrainer fallback (parameter-free).

Source code in src/concerto/training/ego_aht.py

class TrainingResult(NamedTuple):
    """Return value of :func:`train` and :func:`chamber.benchmarks.training_runner.run_training`.

    Pairs the diagnostic reward stream (:class:`RewardCurve`) with the
    trained ego policy (:class:`EgoTrainer`) so Phase-1 callers like
    :class:`chamber.benchmarks.stage1_common.TrainedPolicyFactory`
    (P1.04 / ADR-007 §Stage 1b) can wrap ``result.trainer.act`` in a
    per-step closure without paying a checkpoint round-trip cost. The
    trainer's internal state (HARL HAPPO actor + critic + optimisers)
    survives :func:`train`'s scope through this return value rather
    than being reloaded from disk.

    NamedTuple (not a bare ``tuple[RewardCurve, EgoTrainer]``) so call
    sites use the field names — ``result.curve`` /
    ``result.trainer`` — instead of positional indexing. Tuple-unpack
    still works (``curve, trainer = run_training(cfg)``) for callers
    that prefer it.

    Attributes:
        curve: The diagnostic per-step + per-episode reward stream
            T4b.13's empirical-guarantee assertion runs over. Same
            shape as before P1.04 — this NamedTuple is a wrapper, not
            a replacement.
        trainer: The trained :class:`EgoTrainer` instance, with the
            HARL HAPPO actor weights at their post-training state. Use
            ``trainer.act(obs, deterministic=True)`` for evaluation
            rollouts. When :func:`train` is called without a
            ``trainer_factory`` (Phase-0 reference path), this is the
            :class:`RandomEgoTrainer` fallback (parameter-free).
    """

    curve: RewardCurve
    trainer: EgoTrainer

train

train(
    cfg: EgoAHTConfig,
    *,
    env: EnvLike,
    partner: PartnerLike,
    trainer_factory: TrainerFactory | None = None,
    repo_root: Path | None = None,
    safety_filter: EgoOnlySafetyFilter | None = None,
    safety_state: SafetyState | None = None,
    safety_bounds: Bounds | None = None,
    safety_snapshot_builder: Callable[
        [EnvLike], dict[str, AgentSnapshot]
    ]
    | None = None,
    safety_dt: float | None = None,
    safety_emergency_controllers: Mapping[
        str, EmergencyController
    ]
    | None = None,
) -> TrainingResult

Run one ego-AHT training loop (T4b.11; ADR-002 §Decisions; plan/05 §3.5).

Wires up logging, seeding, per-step rollout, checkpoint emission, and the trainer-factory seam. Returns a :class:TrainingResult (P1.04 / ADR-007 §Stage 1b) carrying both the diagnostic :class:RewardCurve and the trained :class:EgoTrainer instance, so Phase-1 callers (notably :class:chamber.benchmarks.stage1_common.TrainedPolicyFactory) can wrap result.trainer.act in a per-cell closure without paying a checkpoint round-trip.

The pre-P1.04 return type was the bare :class:RewardCurve; the NamedTuple wrapper is backward-compatible at the tuple-unpack level (curve, trainer = train(...)) but reads more cleanly at named call sites (result.curve / result.trainer).

Parameters:

• cfg (EgoAHTConfig) –

  Validated :class:~concerto.training.config.EgoAHTConfig.

• env (EnvLike) –

  Concrete env instance satisfying the :class:EnvLike structural Protocol. Built upstream by :func:chamber.benchmarks.training_runner.build_env.

• partner (PartnerLike) –

  Concrete frozen partner satisfying :class:PartnerLike. Built upstream by :func:chamber.benchmarks.training_runner.build_partner.

• trainer_factory (TrainerFactory | None, default: None ) –

  Constructor that builds the :class:EgoTrainer. When None (default), uses :class:RandomEgoTrainer — the Phase-0 in-concerto.* fallback. The chamber-side wrapper :func:chamber.benchmarks.training_runner.run_training injects the M4b-8a :class:~chamber.benchmarks.ego_ppo_trainer.EgoPPOTrainer (the real HARL-HAPPO trainer; plan/05 §3.5) here.

• repo_root (Path | None, default: None ) –

  Working-tree root for the run-metadata bundle (defaults to :func:pathlib.Path.cwd).

• safety_filter (EgoOnlySafetyFilter | None, default: None ) –

  Optional CBF-QP outer filter (P1.04.5; ADR-007 §Stage 1b). All five safety kwargs must be passed together when cfg.safety.enabled=True; passing any with the cfg disabled (or partial sets) raises :class:ValueError (intent-mismatch contract).

• safety_state (SafetyState | None, default: None ) –

  Optional :class:SafetyState — the conformal slack vector (mutated in place per step by :func:update_lambda_from_predictor).

• safety_bounds (Bounds | None, default: None ) –

  Optional per-task :class:Bounds — the cell's CBF/Cartesian envelope (audit-gate predicate A's RHS is sourced from cartesian_accel_capacity).

• safety_snapshot_builder (Callable[[EnvLike], dict[str, AgentSnapshot]] | None, default: None ) –

  Optional (env) -> dict[str, AgentSnapshot] callable that the loop invokes per step to build the per-uid Cartesian snapshot map the filter consumes via partner_predicted_states.

• safety_dt (float | None, default: None ) –

  Optional control-step dt in seconds for the constant-velocity predictor lookahead + numerical- difference velocity. Typically env.control_timestep.

• safety_emergency_controllers (Mapping[str, EmergencyController] | None, default: None ) –

  Optional per-uid :class:concerto.safety.emergency.EmergencyController dispatch map (P1.04.6; ADR-007 §Stage 1b Rev 8). Consulted by :func:concerto.safety.braking.maybe_brake at each per-step braking call to translate the aggregate Cartesian repulsion into the per-uid control-space override. None falls back to a per-uid :class:concerto.safety.emergency.CartesianAccelEmergencyController — correct for double-integrator agents but a silent dimension-mismatch foot-gun for 7-DOF arms. Wired by :class:chamber.benchmarks.stage1_common.TrainedPolicyFactory via :func:chamber.benchmarks.training_runner.build_emergency_controllers. Honoured only when cfg.safety.enabled=True AND the rest of the safety stack is wired.

Returns:

• TrainingResult –

  class:TrainingResult NamedTuple carrying curve (the

• TrainingResult –

  class:RewardCurve with per-step + per-episode ego rewards

• TrainingResult –

  and saved checkpoint paths) and trainer (the trained

• TrainingResult –

  class:EgoTrainer instance whose act method evaluation

• TrainingResult –

  rollouts wrap).

Source code in src/concerto/training/ego_aht.py

def train(  # noqa: PLR0912, PLR0915 - P1.04.5 added safety-stack integration to the canonical training loop; the body's branch + statement counts exceed the default thresholds because the safety path is interleaved per step. Refactoring into a SafetyFilterDriver collaborator is the Phase-2 cleanup path (see Plan-subagent D1 alternative).
    cfg: EgoAHTConfig,
    *,
    env: EnvLike,
    partner: PartnerLike,
    trainer_factory: TrainerFactory | None = None,
    repo_root: Path | None = None,
    # ----- P1.04.5: safety-stack wiring (ADR-007 §Stage 1b). -----
    # All five default to ``None``; absence means pre-P1.04.5 behaviour
    # (the loop runs unfiltered against the partner). Presence requires
    # all five together — validated below. ``cfg.safety.enabled`` is the
    # operator-intent toggle; cfg-says-enabled-but-kwargs-not-passed and
    # cfg-says-disabled-but-kwargs-passed both loud-fail (intent
    # mismatch).
    safety_filter: EgoOnlySafetyFilter | None = None,
    safety_state: SafetyState | None = None,
    safety_bounds: Bounds | None = None,
    safety_snapshot_builder: (Callable[[EnvLike], dict[str, AgentSnapshot]] | None) = None,
    safety_dt: float | None = None,
    # ----- P1.04.6: braking-fallback parity (ADR-007 §Stage 1b Rev 8). -----
    # ``safety_emergency_controllers`` is the per-uid emergency-controller
    # dispatch map :func:`concerto.safety.braking.maybe_brake` consults.
    # When ``None`` the braking layer falls back to a per-uid
    # :class:`CartesianAccelEmergencyController` — correct for
    # double-integrator agents but a silent dimension-mismatch foot-gun
    # for 7-DOF arms; the chamber-side caller
    # (:class:`chamber.benchmarks.stage1_common.TrainedPolicyFactory`)
    # populates it via
    # :func:`chamber.benchmarks.training_runner.build_emergency_controllers`.
    # Read only when ``cfg.safety.enabled=True`` AND the other safety
    # kwargs are passed (the validation block below ties presence to
    # ``_safety_active``).
    safety_emergency_controllers: Mapping[str, EmergencyController] | None = None,
) -> TrainingResult:
    """Run one ego-AHT training loop (T4b.11; ADR-002 §Decisions; plan/05 §3.5).

    Wires up logging, seeding, per-step rollout, checkpoint emission, and
    the trainer-factory seam. Returns a :class:`TrainingResult` (P1.04 /
    ADR-007 §Stage 1b) carrying both the diagnostic
    :class:`RewardCurve` and the trained :class:`EgoTrainer` instance,
    so Phase-1 callers (notably
    :class:`chamber.benchmarks.stage1_common.TrainedPolicyFactory`) can
    wrap ``result.trainer.act`` in a per-cell closure without paying
    a checkpoint round-trip.

    The pre-P1.04 return type was the bare :class:`RewardCurve`; the
    NamedTuple wrapper is backward-compatible at the tuple-unpack level
    (``curve, trainer = train(...)``) but reads more cleanly at named
    call sites (``result.curve`` / ``result.trainer``).

    Args:
        cfg: Validated :class:`~concerto.training.config.EgoAHTConfig`.
        env: Concrete env instance satisfying the :class:`EnvLike`
            structural Protocol. Built upstream by
            :func:`chamber.benchmarks.training_runner.build_env`.
        partner: Concrete frozen partner satisfying :class:`PartnerLike`.
            Built upstream by
            :func:`chamber.benchmarks.training_runner.build_partner`.
        trainer_factory: Constructor that builds the
            :class:`EgoTrainer`. When ``None`` (default), uses
            :class:`RandomEgoTrainer` — the Phase-0 in-``concerto.*``
            fallback. The chamber-side wrapper
            :func:`chamber.benchmarks.training_runner.run_training`
            injects the M4b-8a
            :class:`~chamber.benchmarks.ego_ppo_trainer.EgoPPOTrainer`
            (the real HARL-HAPPO trainer; plan/05 §3.5) here.
        repo_root: Working-tree root for the run-metadata bundle
            (defaults to :func:`pathlib.Path.cwd`).
        safety_filter: Optional CBF-QP outer filter (P1.04.5;
            ADR-007 §Stage 1b). All five safety kwargs must be passed
            together when ``cfg.safety.enabled=True``; passing any
            with the cfg disabled (or partial sets) raises
            :class:`ValueError` (intent-mismatch contract).
        safety_state: Optional :class:`SafetyState` — the conformal
            slack vector (mutated in place per step by
            :func:`update_lambda_from_predictor`).
        safety_bounds: Optional per-task :class:`Bounds` — the
            cell's CBF/Cartesian envelope (audit-gate predicate A's
            RHS is sourced from ``cartesian_accel_capacity``).
        safety_snapshot_builder: Optional ``(env) -> dict[str,
            AgentSnapshot]`` callable that the loop invokes per step
            to build the per-uid Cartesian snapshot map the filter
            consumes via ``partner_predicted_states``.
        safety_dt: Optional control-step dt in seconds for the
            constant-velocity predictor lookahead + numerical-
            difference velocity. Typically ``env.control_timestep``.
        safety_emergency_controllers: Optional per-uid
            :class:`concerto.safety.emergency.EmergencyController`
            dispatch map (P1.04.6; ADR-007 §Stage 1b Rev 8). Consulted
            by :func:`concerto.safety.braking.maybe_brake` at each
            per-step braking call to translate the aggregate Cartesian
            repulsion into the per-uid control-space override.
            ``None`` falls back to a per-uid
            :class:`concerto.safety.emergency.CartesianAccelEmergencyController`
            — correct for double-integrator agents but a silent
            dimension-mismatch foot-gun for 7-DOF arms. Wired by
            :class:`chamber.benchmarks.stage1_common.TrainedPolicyFactory`
            via
            :func:`chamber.benchmarks.training_runner.build_emergency_controllers`.
            Honoured only when ``cfg.safety.enabled=True`` AND the rest
            of the safety stack is wired.

    Returns:
        :class:`TrainingResult` NamedTuple carrying ``curve`` (the
        :class:`RewardCurve` with per-step + per-episode ego rewards
        and saved checkpoint paths) and ``trainer`` (the trained
        :class:`EgoTrainer` instance whose ``act`` method evaluation
        rollouts wrap).
    """
    repo_root = repo_root or Path.cwd()
    # RUNID-COLLISION fix (issue #214; ADR-002 §Revision history
    # 2026-06-10): fold the config into the run_id so same-seed
    # same-commit cells differing only in regime knobs (gamma, num_envs,
    # frames, …) cannot collide. model_dump_json() is
    # field-definition-ordered and therefore byte-stable for equal
    # configs (Pydantic v2). Operator-side sink fields are EXCLUDED —
    # artifacts_root / log_dir / wandb are where outputs land, not what
    # the run computes, and two same-seed runs that differ only in
    # scratch dirs must keep one identity (the P6 byte-identity test
    # pins exactly that). The fingerprint also rides ``extra`` so
    # every JSONL line carries it for archive-side disambiguation.
    config_fingerprint = hashlib.sha256(
        cfg.model_dump_json(exclude={"artifacts_root", "log_dir", "wandb"}).encode("utf-8")
    ).hexdigest()[:16]
    ctx = compute_run_metadata(
        seed=cfg.seed,
        run_kind=cfg.algo,
        repo_root=repo_root,
        extra={
            "task": cfg.env.task,
            "partner_class": cfg.partner.class_name,
            "config_hash": config_fingerprint,
            # EXPLORATORY stamp (2026-06-11 homo-static slice §2): a
            # static-override run can never sit silently in an archive.
            **(
                {"exploratory_partner_static": "true"}
                if cfg.exploratory.partner_static_override
                else {}
            ),
        },
        config_fingerprint=config_fingerprint,
    )
    jsonl_path = cfg.log_dir / f"{ctx.run_id}.jsonl"
    logger = bind_run_logger(ctx, jsonl_path=jsonl_path)
    logger.info(
        "training_start",
        total_frames=cfg.total_frames,
        checkpoint_every=cfg.checkpoint_every,
    )

    ego_uid, partner_uid = cfg.env.agent_uids
    if trainer_factory is None:
        trainer: EgoTrainer = RandomEgoTrainer(
            ego_uid=ego_uid,
            action_dim=_RANDOM_TRAINER_FALLBACK_ACTION_DIM,
            root_seed=cfg.seed,
        )
    else:
        # P1.05.11 / ADR-017: thread the bound logger into the trainer
        # factory so PPO update scalars flow through the same JSONL +
        # W&B sinks as the driver's own events. Factories that do not
        # accept ``logger`` (legacy / external) are still supported —
        # the kwarg is optional at the Protocol level.
        trainer = trainer_factory(
            cfg,
            env=env,
            partner=partner,
            ego_uid=ego_uid,
            logger=logger,
        )

    # P1.04.5: validate the safety-stack kwargs against cfg.safety.enabled
    # (ADR-007 §Stage 1b lifecycle contract). Intent-mismatch loud-fails:
    # cfg-says-enabled-but-some-kwarg-None and cfg-says-disabled-but-some-
    # kwarg-not-None both raise. Both-aligned paths (all five None when
    # disabled; all five non-None when enabled) proceed.
    _safety_kwargs_passed = (
        safety_filter is not None
        and safety_state is not None
        and safety_bounds is not None
        and safety_snapshot_builder is not None
        and safety_dt is not None
    )
    _safety_kwargs_partial = (
        safety_filter is not None
        or safety_state is not None
        or safety_bounds is not None
        or safety_snapshot_builder is not None
        or safety_dt is not None
    ) and not _safety_kwargs_passed
    if _safety_kwargs_partial:
        msg = (
            "train(): safety-stack kwargs must be passed as a complete set "
            "(safety_filter + safety_state + safety_bounds + "
            "safety_snapshot_builder + safety_dt) or all None. Partial "
            "wiring is an operator-intent mismatch."
        )
        raise ValueError(msg)
    # P1.05.10 (ADR-007 §Stage 1b regime-alignment revision): the
    # vector/safety conflict is checked BEFORE the kwargs-completeness
    # check — at num_envs > 1 the safety posture is invalid regardless
    # of how the kwargs were wired, and the more specific error must
    # win so the operator reaches for the documented override.
    _num_envs: int = int(getattr(cfg.env, "num_envs", 1))
    if _num_envs > 1 and cfg.safety.enabled:
        msg = (
            f"train(): cfg.env.num_envs={_num_envs} with cfg.safety.enabled=True "
            "is not supported — the training-time safety stack is single-env "
            "(ADR-004 §Decision snapshot contract; ADR-007 §Stage 1b "
            "regime-alignment revision). Run vectorised cells with the "
            "operator override safety.enabled=false, or num_envs=1 for "
            "filtered runs."
        )
        raise ValueError(msg)
    if cfg.safety.enabled and not _safety_kwargs_passed:
        msg = (
            "train(): cfg.safety.enabled is True but the safety-stack kwargs "
            "were not passed. The chamber-side caller "
            "(chamber.benchmarks.stage1_common.TrainedPolicyFactory) wires "
            "them; tests that invoke train() directly with cfg.safety.enabled "
            "must construct the SafetyState + filter + bounds + snapshot "
            "builder + dt themselves (see "
            "chamber.benchmarks.training_runner.build_safety_*)."
        )
        raise ValueError(msg)
    if not cfg.safety.enabled and _safety_kwargs_passed:
        msg = (
            "train(): cfg.safety.enabled is False but safety-stack kwargs "
            "were passed. Either set cfg.safety.enabled=True (and run with "
            "the filter) or drop the kwargs (and run unfiltered). Mixed "
            "intent is loud-fail by design (ADR-007 §Stage 1b discipline)."
        )
        raise ValueError(msg)
    _safety_active: bool = cfg.safety.enabled and _safety_kwargs_passed

    obs, _ = env.reset(seed=cfg.seed)
    partner.reset(seed=cfg.seed)
    curve = RewardCurve(run_id=ctx.run_id)
    episode_reward_acc = 0.0
    episode_in_progress = True
    # Episode index is incremented on each terminated/truncated boundary,
    # NOT inferred from step // episode_length — the latter would silently
    # misnumber for envs that early-terminate (P6 anti-pattern flagged in
    # local pre-PR review).
    episode_index = 0

    # P1.04.5: safety-stack runtime state.
    aggregator = None
    snaps_prev: dict[str, AgentSnapshot] | None = None
    # The validation block above guarantees all five safety kwargs are
    # non-None iff _safety_active is True. The casts below narrow for
    # pyright across the loop body (S101 avoided by not using ``assert``).
    _filter = cast("EgoOnlySafetyFilter", safety_filter)
    _state = cast("SafetyState", safety_state)
    _bounds = cast("Bounds", safety_bounds)
    _builder = cast("Callable[[EnvLike], dict[str, AgentSnapshot]]", safety_snapshot_builder)
    _dt = cast("float", safety_dt)
    # Lazy imports to keep concerto.training.ego_aht Tier-1-import-safe;
    # the safety_telemetry module only resolves when train() is called,
    # not at concerto.training import time. ADR-004 §Decision: the
    # safety stack is itself a concerto.* module, so this keeps train()
    # importable for consumers that don't pull in safety_telemetry.
    # Imports are unconditional (not inside `if _safety_active:`) so
    # the symbols are bound for pyright's flow analysis across the
    # loop body; their *use* is still guarded by `_safety_active`.
    from concerto.safety.braking import maybe_brake  # noqa: PLC0415
    from concerto.safety.conformal import (  # noqa: PLC0415 - lazy by design (see comment above)
        constant_velocity_predict,
        update_lambda_from_predictor,
    )
    from concerto.safety.errors import ConcertoSafetyInfeasible  # noqa: PLC0415
    from concerto.training.safety_telemetry import SafetyAggregator  # noqa: PLC0415

    if _safety_active:
        _filter.reset(seed=cfg.seed)
        # P1.05.7 / #180: emit lambda_clamp_bound so the audit-gate hook
        # can distinguish the clamp-saturated regime (var=0 by design)
        # from "adapted but stuck" (var=0 by degenerate update).
        aggregator = SafetyAggregator(
            n_pairs=len(_state.lambda_),
            cartesian_accel_capacity=_bounds.cartesian_accel_capacity,
            saturation_threshold=cfg.safety.saturation_threshold,
            lambda_clamp_bound=cfg.safety.clamp_floor_ratio * _bounds.cartesian_accel_capacity,
        )

    # Rollout-window task-progress accumulators (ADR-017 §Schema). These
    # surface the high-value signals the experiment-analysis agent reads —
    # numeric reward, per-stage grasp/place/success rates, and the gripper
    # command — that the pre-P1.05.11 ``last_reward``-only logging dropped.
    # Reset at every rollout-update boundary; emitted via log_scalars so the
    # chamber-analyze CLI + W&B both receive them.
    _win = {
        "reward": 0.0,
        "n": 0,
        "grasp": 0.0,
        "place": 0.0,
        "static": 0.0,
        "success": 0.0,
        "has_stage": False,
        "grip_sum": 0.0,
        "grip_min": float("inf"),
        "grip_n": 0,
    }

    if _num_envs > 1:
        # P1.05.10 (ADR-007 §Stage 1b regime-alignment revision): the
        # vectorised rollout loop. The env is the chamber-side
        # auto-reset wrapper chain (per-env partial reset on done;
        # pre-reset obs in info["final_observation"]), so this loop
        # never calls env.reset() mid-run — per-episode cube/goal
        # randomisation comes from the env's per-env-index
        # derive_substream streams (P6 / ADR-002). The per-update
        # batch is num_envs x cfg.happo.rollout_length transitions;
        # JSONL `step` fields stay frame-denominated so per-window
        # events remain comparable with single-env runs.
        _train_vectorised_loop(
            cfg=cfg,
            env=env,
            partner=partner,
            trainer=trainer,
            curve=curve,
            logger=logger,
            ctx_run_id=ctx.run_id,
            git_sha=ctx.git_sha,
            pyproject_hash=ctx.pyproject_hash,
            obs=obs,
            ego_uid=ego_uid,
            partner_uid=partner_uid,
            num_envs=_num_envs,
        )
        logger.info(
            "training_end",
            n_episodes=len(curve.per_episode_ego_rewards),
            n_checkpoints=len(curve.checkpoint_paths),
        )
        return TrainingResult(curve=curve, trainer=trainer)

    for step in range(cfg.total_frames):
        ego_action_nominal = trainer.act(obs)
        partner_action = partner.act(obs)
        if _safety_active and aggregator is not None:
            snaps_now = _builder(env)
            # Conformal update against the previous step's snapshots
            # (skipped on first step + at episode boundaries, where
            # snaps_prev is None — the predictor cannot meaningfully
            # forecast across a reset).
            if snaps_prev is not None:
                # P1.05.7 / issue #180: symmetric clamp on λ. The bound
                # is ``clamp_floor_ratio x cartesian_accel_capacity``;
                # the audit-gate predicate A trips at
                # ``saturation_threshold x cap`` (the SafetyConfig
                # @model_validator guarantees the strict inequality
                # so the buffer is non-zero). Without the clamp the
                # negative-eps regime drifts unboundedly negative —
                # P1.05 100k-frame AS-hetero probe measured drift
                # exactly -η x |ε| = -5e-04 / step, projecting
                # λ_ss ≈ -49.76 at the production budget.
                update_lambda_from_predictor(
                    _state,
                    snaps_now=snaps_now,
                    snaps_prev=snaps_prev,
                    alpha_pair=2.0 * _bounds.cartesian_accel_capacity,
                    gamma=cfg.safety.cbf_gamma,
                    dt=_dt,
                    in_warmup=(_state.warmup_steps_remaining > 0),
                    lambda_bound=cfg.safety.clamp_floor_ratio * _bounds.cartesian_accel_capacity,
                )
            # Forecast partner state for the next control step
            # (constant-velocity stub per ADR-004 §Decision).
            partner_predicted = {
                uid: constant_velocity_predict(snaps_now[uid], _dt)
                for uid in snaps_now
                if uid != ego_uid
            }
            # P1.04.6 (ADR-007 §Stage 1b Rev 8): per-step braking
            # fallback in front of the CBF-QP — matches the deployment-
            # time composition order in
            # ``tests/integration/test_safety_in_loop.py``. Independent
            # of QP feasibility (Wang-Ames-Egerstedt 2017 eq. 17). We
            # build a proposed-action dict over BOTH uids so
            # :func:`maybe_brake` evaluates pairwise TTC over the cell,
            # but only adopt the override for ``ego_uid`` — the partner
            # is frozen per ADR-009 §Decision and its action stays
            # untouched. ``safe_ego`` is what propagates into the
            # trainer's learning signal.
            proposed_for_braking = {
                ego_uid: np.asarray(ego_action_nominal, dtype=np.float64),
                partner_uid: np.asarray(partner_action, dtype=np.float64),
            }
            braking_override, braking_fired = maybe_brake(
                proposed_for_braking,
                snaps_now,
                bounds=_bounds,
                tau_brake=cfg.safety.tau_brake,
                emergency_controllers=safety_emergency_controllers,
            )
            if braking_fired and braking_override is not None:
                # Per-step backstop fired: take the ego override and
                # skip the QP for this step. ``fallback_fired`` (the
                # CBF-QP's internal 1-D projection fallback flag) stays
                # ``False`` — those two flags are independent telemetry
                # channels on the audit-gate (one is "QP ran and used
                # its internal fallback"; the other is "QP did not run,
                # braking took over"). ``qp_infeasible`` is also False:
                # the QP did not raise, it simply was not called.
                ego_action = np.asarray(braking_override[ego_uid], dtype=ego_action_nominal.dtype)
                fallback_fired = False
                qp_infeasible = False
            else:
                try:
                    safe_ego, info = _filter.filter(
                        np.asarray(ego_action_nominal, dtype=np.float64),
                        obs={
                            "agent_states": snaps_now,
                            "meta": {"partner_id": cfg.partner.class_name},
                        },
                        state=_state,
                        bounds=_bounds,
                        ego_uid=ego_uid,
                        partner_predicted_states=partner_predicted,
                        dt=_dt,
                    )
                    ego_action = np.asarray(safe_ego, dtype=ego_action_nominal.dtype)
                    fallback_fired = bool(info["fallback_fired"])
                    qp_infeasible = False
                except ConcertoSafetyInfeasible:
                    # Pre-P1.04.6 training-time policy was to pass the
                    # nominal action through; P1.04.6's braking layer
                    # now runs upstream of this branch, so reaching
                    # here means the QP raised AFTER braking didn't
                    # fire (i.e. TTC >= tau_brake but the QP still
                    # found no feasible projection — a tighter QP
                    # constraint than the braking TTC predicts).
                    # Surface as the unfiltered-passthrough still, so
                    # the trainer can learn from the consequence; the
                    # ``qp_infeasible`` flag is what audits this.
                    ego_action = ego_action_nominal
                    fallback_fired = False
                    qp_infeasible = True
            snaps_prev = snaps_now
            aggregator.observe(
                _state.lambda_,
                fallback_fired=fallback_fired,
                qp_infeasible=qp_infeasible,
                braking_fired=braking_fired,
            )
        else:
            ego_action = ego_action_nominal
        action = {ego_uid: ego_action, partner_uid: partner_action}
        # The trainer.observe(s') contract: this loop passes the *next*
        # observation (the post-step obs), reward, and done flag. M4b-7's
        # HARL trainer is responsible for buffering pre-step obs internally
        # by tracking the last act() input. Phase-0 simplification per
        # plan/05 §3.5; revisit if a future on-policy trainer needs the
        # explicit (s, a, r, s', done) tuple.
        obs, reward, terminated, truncated, step_info = env.step(action)
        curve.per_step_ego_rewards.append(reward)
        episode_reward_acc += reward
        # Accumulate task-progress + gripper signals for the rollout-window
        # scalar emission (experiment-analysis instrumentation; ADR-017).
        _win["reward"] += float(reward)
        _win["n"] += 1
        _grasp = _stage_flag_rate(step_info, "is_grasped")
        if _grasp is not None:
            _win["has_stage"] = True
            _win["grasp"] += _grasp
            _win["place"] += _stage_flag_rate(step_info, "is_obj_placed") or 0.0
            _win["static"] += _stage_flag_rate(step_info, "is_robot_static") or 0.0
            _win["success"] += _stage_flag_rate(step_info, "success") or 0.0
        _grip = _last_action_scalar(ego_action_nominal)
        if _grip is not None:
            _win["grip_sum"] += _grip
            _win["grip_min"] = min(_win["grip_min"], _grip)
            _win["grip_n"] += 1
        # Pardo 2017 / issue #62: thread terminated AND truncated
        # separately. ``done`` keeps the historical episode-boundary
        # meaning (terminated OR truncated) so the loop's reset logic is
        # unchanged; ``truncated`` is the kwarg-only flag PPO-style
        # trainers use to bootstrap GAE correctly at time-limit
        # boundaries.
        trainer.observe(obs, reward, terminated or truncated, truncated=truncated)

        if (step + 1) % cfg.happo.rollout_length == 0:
            trainer.update()
            if aggregator is not None:
                window = aggregator.flush_window_stats()
                logger.info("safety_telemetry", step=step + 1, **window)
            logger.info(
                "rollout_update",
                step=step + 1,
                last_reward=reward,
            )
            # Namespaced task-progress scalars for W&B + chamber-analyze
            # (numeric reward + per-stage rates + gripper command). These are
            # the signals the experiment-analysis agent reads; pre-P1.05.11
            # runs had only the string ``last_reward`` (ADR-017 §Schema).
            _n = max(1, _win["n"])
            _scalars: dict[str, float] = {"mean_reward": _win["reward"] / _n}
            if _win["has_stage"]:
                _scalars["grasp_rate"] = _win["grasp"] / _n
                _scalars["place_rate"] = _win["place"] / _n
                _scalars["static_rate"] = _win["static"] / _n
                _scalars["success_rate"] = _win["success"] / _n
            if _win["grip_n"]:
                _scalars["gripper_cmd_mean"] = _win["grip_sum"] / _win["grip_n"]
                _scalars["gripper_cmd_min"] = _win["grip_min"]
            log_scalars(logger, step=step + 1, namespace="rollout", **_scalars)
            _win = {
                "reward": 0.0,
                "n": 0,
                "grasp": 0.0,
                "place": 0.0,
                "static": 0.0,
                "success": 0.0,
                "has_stage": False,
                "grip_sum": 0.0,
                "grip_min": float("inf"),
                "grip_n": 0,
            }

        if (step + 1) % cfg.checkpoint_every == 0:
            ckpt_path = _save_run_checkpoint(
                cfg=cfg,
                ctx_run_id=ctx.run_id,
                seed=cfg.seed,
                step=step + 1,
                git_sha=ctx.git_sha,
                pyproject_hash=ctx.pyproject_hash,
                state_dict=trainer.state_dict(),
            )
            curve.checkpoint_paths.append(ckpt_path)
            logger.info("checkpoint_saved", step=step + 1, path=str(ckpt_path))

        if terminated or truncated:
            curve.per_episode_ego_rewards.append(episode_reward_acc)
            episode_reward_acc = 0.0
            episode_in_progress = False
            episode_index += 1
            # P1.04.5: reset snaps_prev so the conformal update on the
            # first step of the new episode does not diff across the
            # reset boundary (the cross-episode position delta would
            # produce a spurious large prediction-gap loss). SafetyState
            # itself is NOT reset — D3 of the design pass mandates
            # per-cell accumulation per Huriot-Sibai §IV.A.
            if _safety_active:
                snaps_prev = None
            # P6 reproducibility: derive a per-episode seed via a stable
            # substream rather than additive int mixing (cfg.seed +
            # episode_index would collide across runs). The substream
            # name pins the episode index uniquely under cfg.seed.
            episode_seed_int = int(
                derive_substream(f"training.episode.{episode_index}", root_seed=cfg.seed)
                .default_rng()
                .integers(0, 2**31 - 1)
            )
            obs, _ = env.reset(seed=episode_seed_int)
            partner.reset(seed=episode_seed_int)
            episode_in_progress = True

    # Tail-end episode (final partial chunk) — capture so the curve has
    # full coverage for the empirical-guarantee assertion. Use the
    # episode_in_progress sentinel rather than `episode_reward_acc != 0.0`
    # so a legitimately-zero accumulated reward isn't dropped.
    if episode_in_progress:
        curve.per_episode_ego_rewards.append(episode_reward_acc)

    # P1.04.5: emit the per-cell safety_telemetry_final summary the
    # audit-gate hook reads (predicates A + B; ADR-007 §Stage 1b).
    if aggregator is not None:
        final_summary = aggregator.finalise(
            safety_enabled=cfg.safety.enabled,
            predictor_kind=cfg.safety.predictor_kind,
        )
        event_name = str(final_summary.pop("event", "safety_telemetry_final"))
        logger.info(event_name, **final_summary)
    logger.info(
        "training_end",
        n_episodes=len(curve.per_episode_ego_rewards),
        n_checkpoints=len(curve.checkpoint_paths),
    )
    return TrainingResult(curve=curve, trainer=trainer)

CHAMBER — the benchmark

chamber.envs

CHAMBER environment wrappers above ManiSkill v3.

ADR-001 §Decision: extend ManiSkill v3 with three thin wrappers covering the four heterogeneity axes. ADR-005 §Decision: SAPIEN 3 + Warp-MPM is the physics substrate, inherited from ManiSkill v3.

ChamberEnvCompatibilityError

Bases: RuntimeError

Raised when a wrapped env does not satisfy CHAMBER wrapper assumptions.

ADR-001 §Risks: a silent fallback during a Stage-0 spike would invalidate the gate; failing loudly forces ADR re-review.

Source code in src/chamber/envs/errors.py

class ChamberEnvCompatibilityError(RuntimeError):
    """Raised when a wrapped env does not satisfy CHAMBER wrapper assumptions.

    ADR-001 §Risks: a silent fallback during a Stage-0 spike would invalidate
    the gate; failing loudly forces ADR re-review.
    """

CommShapingWrapper

Bases: Wrapper

Inject comm-channel output into the observation dict as obs["comm"].

Wraps any env whose observation space is a gym.spaces.Dict. On each reset and step, calls channel.encode(obs) and stores the result under the "comm" key. The channel itself controls all degradation semantics (latency, drop, jitter); this wrapper is a pure carrier.

ADR-001 §Decision item 3; ADR-003 §Decision; ADR-006 §Decision.

Parameters:

• env (Env) –

  Env with a gym.spaces.Dict observation space.

• channel (CommChannel) –

  A :class:chamber.comm.api.CommChannel instance. In M1 this is a stub :class:chamber.comm.FixedFormatCommChannel that emits an empty packet shell. M2 fills the real fixed-format encoding.

Raises:

• ChamberEnvCompatibilityError –

  if the inner observation space is not a gym.spaces.Dict (ADR-001 §Risks).

Source code in src/chamber/envs/comm_shaping.py

class CommShapingWrapper(gym.Wrapper):  # type: ignore[type-arg]
    """Inject comm-channel output into the observation dict as ``obs["comm"]``.

    Wraps any env whose observation space is a ``gym.spaces.Dict``. On each
    reset and step, calls ``channel.encode(obs)`` and stores the result under
    the ``"comm"`` key. The channel itself controls all degradation semantics
    (latency, drop, jitter); this wrapper is a pure carrier.

    ADR-001 §Decision item 3; ADR-003 §Decision; ADR-006 §Decision.

    Args:
        env: Env with a ``gym.spaces.Dict`` observation space.
        channel: A :class:`chamber.comm.api.CommChannel` instance. In M1 this
            is a stub :class:`chamber.comm.FixedFormatCommChannel` that emits
            an empty packet shell. M2 fills the real fixed-format encoding.

    Raises:
        ChamberEnvCompatibilityError: if the inner observation space is not a
            ``gym.spaces.Dict`` (ADR-001 §Risks).
    """

    def __init__(self, env: gym.Env, channel: CommChannel) -> None:  # type: ignore[type-arg]
        """Validate the obs space and extend it with a ``comm`` sub-space."""
        super().__init__(env)
        if not isinstance(env.observation_space, gym.spaces.Dict):
            raise ChamberEnvCompatibilityError(
                f"CommShapingWrapper requires a gym.spaces.Dict observation space; "
                f"got {type(env.observation_space).__name__}. See ADR-001 §Risks."
            )
        self._channel = channel
        self._extend_observation_space()

    def _extend_observation_space(self) -> None:
        self.observation_space = gym.spaces.Dict(
            {
                **self.env.observation_space.spaces,  # type: ignore[attr-defined]
                "comm": gym.spaces.Dict({}),  # M2 fills the real comm obs space.
            }
        )

    def reset(self, **kwargs: object) -> tuple[dict, dict]:  # type: ignore[override]
        """Reset the env and channel, injecting comm into the initial obs.

        ADR-001 §Decision item 3; ADR-003 §Decision.
        """
        obs, info = self.env.reset(**kwargs)  # type: ignore[arg-type]
        self._channel.reset()
        obs = dict(obs)
        obs["comm"] = self._channel.encode(obs)
        return obs, info

    def step(self, action: object) -> tuple[dict, object, bool, bool, dict]:  # type: ignore[override]
        """Step the env and inject updated comm into obs.

        ADR-001 §Decision item 3; ADR-003 §Decision.
        """
        obs, reward, terminated, truncated, info = self.env.step(action)
        obs = dict(obs)
        obs["comm"] = self._channel.encode(obs)
        return obs, reward, terminated, truncated, info

__init__

__init__(env: Env, channel: CommChannel) -> None

Validate the obs space and extend it with a comm sub-space.

Source code in src/chamber/envs/comm_shaping.py

def __init__(self, env: gym.Env, channel: CommChannel) -> None:  # type: ignore[type-arg]
    """Validate the obs space and extend it with a ``comm`` sub-space."""
    super().__init__(env)
    if not isinstance(env.observation_space, gym.spaces.Dict):
        raise ChamberEnvCompatibilityError(
            f"CommShapingWrapper requires a gym.spaces.Dict observation space; "
            f"got {type(env.observation_space).__name__}. See ADR-001 §Risks."
        )
    self._channel = channel
    self._extend_observation_space()

reset

reset(**kwargs: object) -> tuple[dict, dict]

Reset the env and channel, injecting comm into the initial obs.

ADR-001 §Decision item 3; ADR-003 §Decision.

Source code in src/chamber/envs/comm_shaping.py

def reset(self, **kwargs: object) -> tuple[dict, dict]:  # type: ignore[override]
    """Reset the env and channel, injecting comm into the initial obs.

    ADR-001 §Decision item 3; ADR-003 §Decision.
    """
    obs, info = self.env.reset(**kwargs)  # type: ignore[arg-type]
    self._channel.reset()
    obs = dict(obs)
    obs["comm"] = self._channel.encode(obs)
    return obs, info

step

step(
    action: object,
) -> tuple[dict, object, bool, bool, dict]

Step the env and inject updated comm into obs.

ADR-001 §Decision item 3; ADR-003 §Decision.

Source code in src/chamber/envs/comm_shaping.py

def step(self, action: object) -> tuple[dict, object, bool, bool, dict]:  # type: ignore[override]
    """Step the env and inject updated comm into obs.

    ADR-001 §Decision item 3; ADR-003 §Decision.
    """
    obs, reward, terminated, truncated, info = self.env.step(action)
    obs = dict(obs)
    obs["comm"] = self._channel.encode(obs)
    return obs, reward, terminated, truncated, info

ConditionConfig

Bases: NamedTuple

Resolved per-condition configuration (ADR-007 §Stage 1b).

Returned by :func:resolve_condition. Pure-Python NamedTuple so Tier-1 tests can construct fakes without any SAPIEN dependency.

Attributes:

• condition_id (str) –

  The verbatim pre-registration condition_id string (one of the four Stage-1 strings).

• agent_uids (tuple[str, str]) –

  Ordered (ego_uid, partner_uid) tuple. The ego is the agent the trainer updates / the safety filter authorises; the partner is the frozen / heuristic partner.

• obs_mode (str) –

  ManiSkill v3 env-level obs_mode superset string passed to :class:BaseEnv.__init__. The OM channel-filter wrapper (:class:chamber.envs.stage1_obs_filter.Stage1OMChannelFilter) slices this superset per-uid to the condition's actual channel keep-set.

• is_om_condition (bool) –

  True for the two OM condition_id strings (vision_only / vision_plus_force_torque_plus_proprio). Drives whether the channel-filter wrapper is engaged downstream.

• ft_synthesis_enabled (bool) –

  True for the OM-hetero condition. The env always injects the synthesised force-torque channel into obs["agent"]["panda_wristcam"]["force_torque"]; the channel filter then masks or keeps it per condition. The flag here is informational only (consumed by the smoke scripts and the docstring report).

Source code in src/chamber/envs/stage1_pickplace.py

class ConditionConfig(NamedTuple):
    """Resolved per-condition configuration (ADR-007 §Stage 1b).

    Returned by :func:`resolve_condition`. Pure-Python NamedTuple so
    Tier-1 tests can construct fakes without any SAPIEN dependency.

    Attributes:
        condition_id: The verbatim pre-registration ``condition_id``
            string (one of the four Stage-1 strings).
        agent_uids: Ordered ``(ego_uid, partner_uid)`` tuple. The ego
            is the agent the trainer updates / the safety filter
            authorises; the partner is the frozen / heuristic partner.
        obs_mode: ManiSkill v3 env-level ``obs_mode`` superset string
            passed to :class:`BaseEnv.__init__`. The OM channel-filter
            wrapper (:class:`chamber.envs.stage1_obs_filter.Stage1OMChannelFilter`)
            slices this superset per-uid to the condition's actual
            channel keep-set.
        is_om_condition: ``True`` for the two OM ``condition_id`` strings
            (``vision_only`` / ``vision_plus_force_torque_plus_proprio``).
            Drives whether the channel-filter wrapper is engaged
            downstream.
        ft_synthesis_enabled: ``True`` for the OM-hetero condition. The
            env always *injects* the synthesised force-torque channel
            into ``obs["agent"]["panda_wristcam"]["force_torque"]``; the
            channel filter then masks or keeps it per condition. The
            flag here is informational only (consumed by the smoke
            scripts and the docstring report).
    """

    condition_id: str
    agent_uids: tuple[str, str]
    obs_mode: str
    is_om_condition: bool
    ft_synthesis_enabled: bool

MPECooperativePushEnv

Bases: Env

2-agent MPE-style cooperative continuous-control env (T4b.13; ADR-002 risk-mitigation #1).

See module docstring for the task design. The env exposes the standard Gymnasium reset + step API with multi-agent dict actions / dict observations keyed by uid, matching :class:tests.fakes.FakeMultiAgentEnv so the M2/M3 wrapper stack drops in unchanged (plan/01 §3).

Source code in src/chamber/envs/mpe_cooperative_push.py

class MPECooperativePushEnv(gym.Env):  # type: ignore[type-arg]
    """2-agent MPE-style cooperative continuous-control env (T4b.13; ADR-002 risk-mitigation #1).

    See module docstring for the task design. The env exposes the standard
    Gymnasium ``reset`` + ``step`` API with multi-agent dict actions / dict
    observations keyed by ``uid``, matching :class:`tests.fakes.FakeMultiAgentEnv`
    so the M2/M3 wrapper stack drops in unchanged (plan/01 §3).
    """

    metadata: ClassVar[dict[str, list[str]]] = {"render_modes": []}  # type: ignore[misc]

    #: Number of agents the env supports — fixed at 2 by the cooperative-coverage task.
    _N_AGENTS: ClassVar[int] = 2

    def __init__(
        self,
        *,
        agent_uids: tuple[str, str] = ("ego", "partner"),
        episode_length: int = DEFAULT_EPISODE_LENGTH,
        root_seed: int = 0,
    ) -> None:
        """Build a 2-agent Cooperative-Push env (T4b.13; plan/05 §3.5).

        Args:
            agent_uids: The two uids the env exposes. The default
                ``("ego", "partner")`` matches the ego-AHT training loop
                convention. Reordering swaps which agent the trainer
                updates and which is held frozen — the env is agnostic.
            episode_length: Truncation horizon in env ticks (default
                :data:`DEFAULT_EPISODE_LENGTH`).
            root_seed: Project-wide root seed; the env derives a
                deterministic numpy ``Generator`` from this via
                :func:`concerto.training.seeding.derive_substream`
                (P6 reproducibility).

        Raises:
            ValueError: If ``agent_uids`` does not have exactly two
                distinct entries.
        """
        super().__init__()
        if len(agent_uids) != self._N_AGENTS or agent_uids[0] == agent_uids[1]:
            raise ValueError(
                f"agent_uids must be a 2-tuple of distinct strings; got {agent_uids!r}"
            )
        self._uids: tuple[str, str] = agent_uids
        self._episode_length: int = int(episode_length)
        self._root_seed: int = int(root_seed)

        self.action_space = gym.spaces.Dict(
            {
                uid: gym.spaces.Box(
                    low=-VELOCITY_BOUND,
                    high=VELOCITY_BOUND,
                    shape=(2,),
                    dtype=np.float32,
                )
                for uid in self._uids
            }
        )
        # state channel: self_pos(2) + self_vel(2) + landmark_rel(4) + partner_rel(2) = 10.
        agent_state = gym.spaces.Box(low=-np.inf, high=np.inf, shape=(10,), dtype=np.float32)
        self.observation_space = gym.spaces.Dict(
            {
                "agent": gym.spaces.Dict(
                    {uid: gym.spaces.Dict({"state": agent_state}) for uid in self._uids}
                )
            }
        )

        self._rng: np.random.Generator = derive_substream(
            _SUBSTREAM_NAME, root_seed=self._root_seed
        ).default_rng()
        # Per-episode mutable state — set by reset.
        self._step_count: int = 0
        self._positions: dict[str, NDArray[np.float64]] = {}
        self._velocities: dict[str, NDArray[np.float64]] = {}
        self._landmark_positions: NDArray[np.float64] = np.zeros((N_LANDMARKS, 2))

    def reset(
        self,
        *,
        seed: int | None = None,
        options: dict[str, Any] | None = None,
    ) -> tuple[dict[str, Any], dict[str, Any]]:
        """Reset to a determinism-harnessed initial state (T4b.13; ADR-002 risk-mitigation #1; P6).

        .. note::

            This env's seeding semantics intentionally diverge from
            Gymnasium's convention (where ``reset(seed=K)`` is the
            *complete* seed source). Here, ``reset(seed=K)`` is folded
            with the constructor's ``root_seed`` via
            :func:`concerto.training.seeding.derive_substream` using the
            substream name ``"env.mpe_cooperative_push.episode.{K}"`` —
            so two training runs at distinct ``root_seed`` values do
            *not* collide on the same per-episode RNG even at the same
            ``K``. This matches the project-wide seeding philosophy
            (P6 + ADR-002 §Decisions): the ``root_seed`` is the
            run-level pin, and per-episode ``seed`` is an episode index
            scoped under it.

        Args:
            seed: Per-episode seed (episode index, NOT a complete seed).
                When provided, re-derives the env's RNG via
                ``derive_substream(f"env.mpe_cooperative_push.episode.{seed}",
                root_seed=self._root_seed)``. When ``None``, continues
                from the RNG's existing state (Gymnasium convention).
            options: Reserved for the Gymnasium API; ignored.

        Returns:
            ``(obs, info)`` where ``obs`` matches the
            :attr:`observation_space` shape and ``info`` is empty.
        """
        del options
        if seed is not None:
            self._rng = derive_substream(
                f"{_SUBSTREAM_NAME}.episode.{seed}",
                root_seed=self._root_seed,
            ).default_rng()
        self._step_count = 0
        self._landmark_positions = self._rng.uniform(
            -POSITION_BOUND, POSITION_BOUND, size=(N_LANDMARKS, 2)
        )
        for uid in self._uids:
            self._positions[uid] = self._rng.uniform(-POSITION_BOUND, POSITION_BOUND, size=(2,))
            self._velocities[uid] = np.zeros(2, dtype=np.float64)
        return self._build_obs(), {}

    def step(
        self,
        action: dict[str, NDArray[np.floating]],
    ) -> tuple[dict[str, Any], float, bool, bool, dict[str, Any]]:
        """Advance one tick (T4b.13; ADR-002 risk-mitigation #1; plan/05 §3.5).

        Args:
            action: Dict keyed by ``uid``, each value a 2-D velocity
                command. Components are clipped to
                ``[-VELOCITY_BOUND, +VELOCITY_BOUND]`` before integration
                so a misbehaving partner cannot escape the plane.

        Returns:
            ``(obs, reward, terminated, truncated, info)``. ``reward`` is
            the *shared* cooperative-coverage scalar (both agents see the
            same value); the trainer's ego/partner split happens upstream
            in :func:`concerto.training.ego_aht.train`. ``terminated`` is
            always ``False`` (no terminal state); ``truncated`` is ``True``
            on the last tick of the episode.

        Raises:
            ValueError: If ``action`` is missing a required uid.
        """
        for uid in self._uids:
            if uid not in action:
                raise ValueError(
                    f"step() action missing uid {uid!r}; got keys {list(action.keys())}"
                )
        for uid in self._uids:
            a = np.clip(
                np.asarray(action[uid], dtype=np.float64),
                -VELOCITY_BOUND,
                VELOCITY_BOUND,
            )
            self._velocities[uid] = a
            self._positions[uid] = np.clip(
                self._positions[uid] + a * DT, -POSITION_BOUND, POSITION_BOUND
            )
        self._step_count += 1
        truncated = self._step_count >= self._episode_length
        return self._build_obs(), self._compute_reward(), False, truncated, {}

    def _build_obs(self) -> dict[str, Any]:
        """Pack the Gymnasium-conformant obs dict (plan/01 §3; plan/04 §3.4)."""
        out_agents: dict[str, dict[str, NDArray[np.float32]]] = {}
        for uid in self._uids:
            self_pos = self._positions[uid]
            self_vel = self._velocities[uid]
            landmark_rel = (self._landmark_positions - self_pos).flatten()
            partner_uid = self._uids[1] if uid == self._uids[0] else self._uids[0]
            partner_rel = self._positions[partner_uid] - self_pos
            state = np.concatenate([self_pos, self_vel, landmark_rel, partner_rel]).astype(
                np.float32
            )
            out_agents[uid] = {"state": state}
        return {"agent": out_agents}

    def _compute_reward(self) -> float:
        """Shared cooperative-coverage scalar (plan/05 §3.5).

        ``r = -sum_landmark min_agent dist(agent, landmark)``. Both
        agents always see the same value so the trainer can route it to
        the ego's policy update without a credit-assignment step.

        Edge case: when an agent sits exactly on a landmark, that
        landmark contributes ``0`` to the sum. Perfect coverage (one
        agent per landmark, both at distance ``0``) yields ``r = 0`` —
        the natural ceiling. The empirical-guarantee assertion in
        T4b.13 is on *moving-window-of-10 non-decreasing*, not on
        approaching this ceiling.

        ``np.linalg.norm`` matches PettingZoo ``simple_spread_v3``'s
        Euclidean reward (squared distance would change the gradient
        shape and break the "matches simple_spread" claim should
        Phase 1 ever cross-validate against the real env).
        """
        # Phase 1 TODO: cross-validate trajectory against
        # mpe2.simple_spread_v3 once the dep-auditor has cleared mpe2.
        total = 0.0
        for landmark in self._landmark_positions:
            distances = [
                float(np.linalg.norm(self._positions[uid] - landmark)) for uid in self._uids
            ]
            total += min(distances)
        return -total

__init__

__init__(
    *,
    agent_uids: tuple[str, str] = ("ego", "partner"),
    episode_length: int = DEFAULT_EPISODE_LENGTH,
    root_seed: int = 0,
) -> None

Build a 2-agent Cooperative-Push env (T4b.13; plan/05 §3.5).

Parameters:

• agent_uids (tuple[str, str], default: ('ego', 'partner') ) –

  The two uids the env exposes. The default ("ego", "partner") matches the ego-AHT training loop convention. Reordering swaps which agent the trainer updates and which is held frozen — the env is agnostic.

• episode_length (int, default: DEFAULT_EPISODE_LENGTH ) –

  Truncation horizon in env ticks (default :data:DEFAULT_EPISODE_LENGTH).

• root_seed (int, default: 0 ) –

  Project-wide root seed; the env derives a deterministic numpy Generator from this via :func:concerto.training.seeding.derive_substream (P6 reproducibility).

Raises:

• ValueError –

  If agent_uids does not have exactly two distinct entries.

Source code in src/chamber/envs/mpe_cooperative_push.py

def __init__(
    self,
    *,
    agent_uids: tuple[str, str] = ("ego", "partner"),
    episode_length: int = DEFAULT_EPISODE_LENGTH,
    root_seed: int = 0,
) -> None:
    """Build a 2-agent Cooperative-Push env (T4b.13; plan/05 §3.5).

    Args:
        agent_uids: The two uids the env exposes. The default
            ``("ego", "partner")`` matches the ego-AHT training loop
            convention. Reordering swaps which agent the trainer
            updates and which is held frozen — the env is agnostic.
        episode_length: Truncation horizon in env ticks (default
            :data:`DEFAULT_EPISODE_LENGTH`).
        root_seed: Project-wide root seed; the env derives a
            deterministic numpy ``Generator`` from this via
            :func:`concerto.training.seeding.derive_substream`
            (P6 reproducibility).

    Raises:
        ValueError: If ``agent_uids`` does not have exactly two
            distinct entries.
    """
    super().__init__()
    if len(agent_uids) != self._N_AGENTS or agent_uids[0] == agent_uids[1]:
        raise ValueError(
            f"agent_uids must be a 2-tuple of distinct strings; got {agent_uids!r}"
        )
    self._uids: tuple[str, str] = agent_uids
    self._episode_length: int = int(episode_length)
    self._root_seed: int = int(root_seed)

    self.action_space = gym.spaces.Dict(
        {
            uid: gym.spaces.Box(
                low=-VELOCITY_BOUND,
                high=VELOCITY_BOUND,
                shape=(2,),
                dtype=np.float32,
            )
            for uid in self._uids
        }
    )
    # state channel: self_pos(2) + self_vel(2) + landmark_rel(4) + partner_rel(2) = 10.
    agent_state = gym.spaces.Box(low=-np.inf, high=np.inf, shape=(10,), dtype=np.float32)
    self.observation_space = gym.spaces.Dict(
        {
            "agent": gym.spaces.Dict(
                {uid: gym.spaces.Dict({"state": agent_state}) for uid in self._uids}
            )
        }
    )

    self._rng: np.random.Generator = derive_substream(
        _SUBSTREAM_NAME, root_seed=self._root_seed
    ).default_rng()
    # Per-episode mutable state — set by reset.
    self._step_count: int = 0
    self._positions: dict[str, NDArray[np.float64]] = {}
    self._velocities: dict[str, NDArray[np.float64]] = {}
    self._landmark_positions: NDArray[np.float64] = np.zeros((N_LANDMARKS, 2))

reset

reset(
    *,
    seed: int | None = None,
    options: dict[str, Any] | None = None,
) -> tuple[dict[str, Any], dict[str, Any]]

Reset to a determinism-harnessed initial state (T4b.13; ADR-002 risk-mitigation #1; P6).

.. note::

This env's seeding semantics intentionally diverge from
Gymnasium's convention (where ``reset(seed=K)`` is the
*complete* seed source). Here, ``reset(seed=K)`` is folded
with the constructor's ``root_seed`` via
:func:`concerto.training.seeding.derive_substream` using the
substream name ``"env.mpe_cooperative_push.episode.{K}"`` —
so two training runs at distinct ``root_seed`` values do
*not* collide on the same per-episode RNG even at the same
``K``. This matches the project-wide seeding philosophy
(P6 + ADR-002 §Decisions): the ``root_seed`` is the
run-level pin, and per-episode ``seed`` is an episode index
scoped under it.

Parameters:

• seed (int | None, default: None ) –

  Per-episode seed (episode index, NOT a complete seed). When provided, re-derives the env's RNG via derive_substream(f"env.mpe_cooperative_push.episode.{seed}", root_seed=self._root_seed). When None, continues from the RNG's existing state (Gymnasium convention).

• options (dict[str, Any] | None, default: None ) –

  Reserved for the Gymnasium API; ignored.

Returns:

• dict[str, Any] –

  (obs, info) where obs matches the

• dict[str, Any] –

  attr:observation_space shape and info is empty.

Source code in src/chamber/envs/mpe_cooperative_push.py

def reset(
    self,
    *,
    seed: int | None = None,
    options: dict[str, Any] | None = None,
) -> tuple[dict[str, Any], dict[str, Any]]:
    """Reset to a determinism-harnessed initial state (T4b.13; ADR-002 risk-mitigation #1; P6).

    .. note::

        This env's seeding semantics intentionally diverge from
        Gymnasium's convention (where ``reset(seed=K)`` is the
        *complete* seed source). Here, ``reset(seed=K)`` is folded
        with the constructor's ``root_seed`` via
        :func:`concerto.training.seeding.derive_substream` using the
        substream name ``"env.mpe_cooperative_push.episode.{K}"`` —
        so two training runs at distinct ``root_seed`` values do
        *not* collide on the same per-episode RNG even at the same
        ``K``. This matches the project-wide seeding philosophy
        (P6 + ADR-002 §Decisions): the ``root_seed`` is the
        run-level pin, and per-episode ``seed`` is an episode index
        scoped under it.

    Args:
        seed: Per-episode seed (episode index, NOT a complete seed).
            When provided, re-derives the env's RNG via
            ``derive_substream(f"env.mpe_cooperative_push.episode.{seed}",
            root_seed=self._root_seed)``. When ``None``, continues
            from the RNG's existing state (Gymnasium convention).
        options: Reserved for the Gymnasium API; ignored.

    Returns:
        ``(obs, info)`` where ``obs`` matches the
        :attr:`observation_space` shape and ``info`` is empty.
    """
    del options
    if seed is not None:
        self._rng = derive_substream(
            f"{_SUBSTREAM_NAME}.episode.{seed}",
            root_seed=self._root_seed,
        ).default_rng()
    self._step_count = 0
    self._landmark_positions = self._rng.uniform(
        -POSITION_BOUND, POSITION_BOUND, size=(N_LANDMARKS, 2)
    )
    for uid in self._uids:
        self._positions[uid] = self._rng.uniform(-POSITION_BOUND, POSITION_BOUND, size=(2,))
        self._velocities[uid] = np.zeros(2, dtype=np.float64)
    return self._build_obs(), {}

step

step(
    action: dict[str, NDArray[floating]],
) -> tuple[
    dict[str, Any], float, bool, bool, dict[str, Any]
]

Advance one tick (T4b.13; ADR-002 risk-mitigation #1; plan/05 §3.5).

Parameters:

• action (dict[str, NDArray[floating]]) –

  Dict keyed by uid, each value a 2-D velocity command. Components are clipped to [-VELOCITY_BOUND, +VELOCITY_BOUND] before integration so a misbehaving partner cannot escape the plane.

Returns:

• dict[str, Any] –

  (obs, reward, terminated, truncated, info). reward is

• float –

  the shared cooperative-coverage scalar (both agents see the

• bool –

  same value); the trainer's ego/partner split happens upstream

• in ( bool ) –

  func:concerto.training.ego_aht.train. terminated is

• dict[str, Any] –

  always False (no terminal state); truncated is True

• tuple[dict[str, Any], float, bool, bool, dict[str, Any]] –

  on the last tick of the episode.

Raises:

• ValueError –

  If action is missing a required uid.

Source code in src/chamber/envs/mpe_cooperative_push.py

def step(
    self,
    action: dict[str, NDArray[np.floating]],
) -> tuple[dict[str, Any], float, bool, bool, dict[str, Any]]:
    """Advance one tick (T4b.13; ADR-002 risk-mitigation #1; plan/05 §3.5).

    Args:
        action: Dict keyed by ``uid``, each value a 2-D velocity
            command. Components are clipped to
            ``[-VELOCITY_BOUND, +VELOCITY_BOUND]`` before integration
            so a misbehaving partner cannot escape the plane.

    Returns:
        ``(obs, reward, terminated, truncated, info)``. ``reward`` is
        the *shared* cooperative-coverage scalar (both agents see the
        same value); the trainer's ego/partner split happens upstream
        in :func:`concerto.training.ego_aht.train`. ``terminated`` is
        always ``False`` (no terminal state); ``truncated`` is ``True``
        on the last tick of the episode.

    Raises:
        ValueError: If ``action`` is missing a required uid.
    """
    for uid in self._uids:
        if uid not in action:
            raise ValueError(
                f"step() action missing uid {uid!r}; got keys {list(action.keys())}"
            )
    for uid in self._uids:
        a = np.clip(
            np.asarray(action[uid], dtype=np.float64),
            -VELOCITY_BOUND,
            VELOCITY_BOUND,
        )
        self._velocities[uid] = a
        self._positions[uid] = np.clip(
            self._positions[uid] + a * DT, -POSITION_BOUND, POSITION_BOUND
        )
    self._step_count += 1
    truncated = self._step_count >= self._episode_length
    return self._build_obs(), self._compute_reward(), False, truncated, {}

PartnerIdAnnotationWrapper

Bases: Wrapper

Inject obs["meta"]["partner_id"] on every reset and step (ADR-006 risk #3).

Wraps any env whose observation space is a :class:gym.spaces.Dict. The wrapper extends the obs space with a "meta" sub-Dict (empty in Phase-0 — Gymnasium's :class:gym.spaces.Dict does not natively type string values, so the actual partner_id field is carried in the runtime observation dict rather than declared in the space).

Note

:meth:gym.spaces.Dict.contains returns False on the "meta" sub-dict because the declared inner space is empty; this matches :class:chamber.envs.CommShapingWrapper's precedent for its "comm" sub-space (no current consumer validates an obs via observation_space.contains). Adding a string-typed inner Space would require an upstream Gymnasium change.

Phase-0 binds partner_id at construction. For a Phase-1 Stage-3 PF spike with mid-episode swap, call :meth:set_partner_id before the next :meth:step; the wrapper will surface the new value on the subsequent obs.

Parameters:

• env (Env) –

  Inner env with a :class:gym.spaces.Dict observation space.

• partner_id (str) –

  Stable 16-hex-char hash from :attr:chamber.partners.api.PartnerSpec.partner_id. The wrapper does not validate the format — :class:PartnerSpec is the source of truth.

Raises:

• ChamberEnvCompatibilityError –

  When the inner observation space is not a :class:gym.spaces.Dict (ADR-001 §Risks; matches :class:chamber.envs.CommShapingWrapper's compatibility contract).

Source code in src/chamber/envs/partner_meta.py

class PartnerIdAnnotationWrapper(gym.Wrapper):  # type: ignore[type-arg]
    """Inject ``obs["meta"]["partner_id"]`` on every reset and step (ADR-006 risk #3).

    Wraps any env whose observation space is a :class:`gym.spaces.Dict`.
    The wrapper extends the obs space with a ``"meta"`` sub-Dict (empty
    in Phase-0 — Gymnasium's :class:`gym.spaces.Dict` does not natively
    type string values, so the actual ``partner_id`` field is carried
    in the runtime observation dict rather than declared in the space).

    Note:
        :meth:`gym.spaces.Dict.contains` returns ``False`` on the
        ``"meta"`` sub-dict because the declared inner space is empty;
        this matches :class:`chamber.envs.CommShapingWrapper`'s
        precedent for its ``"comm"`` sub-space (no current consumer
        validates an obs via ``observation_space.contains``). Adding a
        string-typed inner Space would require an upstream Gymnasium
        change.

    Phase-0 binds ``partner_id`` at construction. For a Phase-1
    Stage-3 PF spike with mid-episode swap, call :meth:`set_partner_id`
    before the next :meth:`step`; the wrapper will surface the new
    value on the subsequent obs.

    Args:
        env: Inner env with a :class:`gym.spaces.Dict` observation space.
        partner_id: Stable 16-hex-char hash from
            :attr:`chamber.partners.api.PartnerSpec.partner_id`. The
            wrapper does not validate the format — :class:`PartnerSpec`
            is the source of truth.

    Raises:
        ChamberEnvCompatibilityError: When the inner observation space
            is not a :class:`gym.spaces.Dict` (ADR-001 §Risks; matches
            :class:`chamber.envs.CommShapingWrapper`'s compatibility
            contract).
    """

    def __init__(self, env: gym.Env, *, partner_id: str) -> None:  # type: ignore[type-arg]
        """Validate the obs space and bind the partner identity (ADR-006 risk #3)."""
        super().__init__(env)
        if not isinstance(env.observation_space, gym.spaces.Dict):
            msg = (
                f"PartnerIdAnnotationWrapper requires a gym.spaces.Dict observation "
                f"space; got {type(env.observation_space).__name__}. See ADR-001 §Risks."
            )
            raise ChamberEnvCompatibilityError(msg)
        self._partner_id: str = partner_id
        self._extend_observation_space()

    def _extend_observation_space(self) -> None:
        """Add an empty ``"meta"`` sub-space (Gymnasium has no string-typed Space)."""
        existing = dict(self.env.observation_space.spaces)  # type: ignore[attr-defined]
        existing.setdefault(_META_KEY, gym.spaces.Dict({}))
        self.observation_space = gym.spaces.Dict(existing)

    @property
    def partner_id(self) -> str:
        """Return the partner identity the wrapper currently injects (ADR-006 risk #3).

        Returns:
            The stable 16-hex-char hash bound at construction or via
            :meth:`set_partner_id`.
        """
        return self._partner_id

    def set_partner_id(self, partner_id: str) -> None:
        """Rebind the partner identity for the next reset / step (ADR-004 §risk-mitigation #2).

        Used by Phase-1 mid-episode-swap experiments (ADR-007 Stage-3 PF):
        call this before the next :meth:`step` and the wrapper will
        surface the new value on the subsequent obs. The change does
        NOT trigger a new :meth:`reset` automatically — the conformal
        filter does that itself when it observes the new
        ``partner_id`` on ``obs["meta"]``.

        Args:
            partner_id: New stable hash from
                :attr:`chamber.partners.api.PartnerSpec.partner_id`.
        """
        self._partner_id = partner_id

    def reset(  # type: ignore[override]
        self, **kwargs: object
    ) -> tuple[dict, dict]:
        """Reset the env and inject ``partner_id`` into the initial obs (ADR-006 risk #3)."""
        obs, info = self.env.reset(**kwargs)  # type: ignore[arg-type]
        return self._annotate(obs), info

    def step(  # type: ignore[override]
        self, action: object
    ) -> tuple[dict, object, bool, bool, dict]:
        """Step the env and inject the current ``partner_id`` (ADR-006 risk #3)."""
        obs, reward, terminated, truncated, info = self.env.step(action)
        return self._annotate(obs), reward, terminated, truncated, info

    def _annotate(self, obs: Mapping[str, object]) -> dict[str, object]:
        """Return a copy of ``obs`` with ``obs["meta"]["partner_id"]`` set."""
        out = dict(obs)
        existing_meta = out.get(_META_KEY)
        meta: dict[str, object] = dict(existing_meta) if isinstance(existing_meta, dict) else {}
        meta[_PARTNER_ID_KEY] = self._partner_id
        out[_META_KEY] = meta
        return out

partner_id property

partner_id: str

Return the partner identity the wrapper currently injects (ADR-006 risk #3).

Returns:

• str –

  The stable 16-hex-char hash bound at construction or via

• str –

  meth:set_partner_id.

__init__

__init__(env: Env, *, partner_id: str) -> None

Validate the obs space and bind the partner identity (ADR-006 risk #3).

Source code in src/chamber/envs/partner_meta.py

def __init__(self, env: gym.Env, *, partner_id: str) -> None:  # type: ignore[type-arg]
    """Validate the obs space and bind the partner identity (ADR-006 risk #3)."""
    super().__init__(env)
    if not isinstance(env.observation_space, gym.spaces.Dict):
        msg = (
            f"PartnerIdAnnotationWrapper requires a gym.spaces.Dict observation "
            f"space; got {type(env.observation_space).__name__}. See ADR-001 §Risks."
        )
        raise ChamberEnvCompatibilityError(msg)
    self._partner_id: str = partner_id
    self._extend_observation_space()

reset

reset(**kwargs: object) -> tuple[dict, dict]

Reset the env and inject partner_id into the initial obs (ADR-006 risk #3).

Source code in src/chamber/envs/partner_meta.py

def reset(  # type: ignore[override]
    self, **kwargs: object
) -> tuple[dict, dict]:
    """Reset the env and inject ``partner_id`` into the initial obs (ADR-006 risk #3)."""
    obs, info = self.env.reset(**kwargs)  # type: ignore[arg-type]
    return self._annotate(obs), info

set_partner_id

set_partner_id(partner_id: str) -> None

Rebind the partner identity for the next reset / step (ADR-004 §risk-mitigation #2).

Used by Phase-1 mid-episode-swap experiments (ADR-007 Stage-3 PF): call this before the next :meth:step and the wrapper will surface the new value on the subsequent obs. The change does NOT trigger a new :meth:reset automatically — the conformal filter does that itself when it observes the new partner_id on obs["meta"].

Parameters:

• partner_id (str) –

  New stable hash from :attr:chamber.partners.api.PartnerSpec.partner_id.

Source code in src/chamber/envs/partner_meta.py

def set_partner_id(self, partner_id: str) -> None:
    """Rebind the partner identity for the next reset / step (ADR-004 §risk-mitigation #2).

    Used by Phase-1 mid-episode-swap experiments (ADR-007 Stage-3 PF):
    call this before the next :meth:`step` and the wrapper will
    surface the new value on the subsequent obs. The change does
    NOT trigger a new :meth:`reset` automatically — the conformal
    filter does that itself when it observes the new
    ``partner_id`` on ``obs["meta"]``.

    Args:
        partner_id: New stable hash from
            :attr:`chamber.partners.api.PartnerSpec.partner_id`.
    """
    self._partner_id = partner_id

step

step(
    action: object,
) -> tuple[dict, object, bool, bool, dict]

Step the env and inject the current partner_id (ADR-006 risk #3).

Source code in src/chamber/envs/partner_meta.py

def step(  # type: ignore[override]
    self, action: object
) -> tuple[dict, object, bool, bool, dict]:
    """Step the env and inject the current ``partner_id`` (ADR-006 risk #3)."""
    obs, reward, terminated, truncated, info = self.env.step(action)
    return self._annotate(obs), reward, terminated, truncated, info

PerAgentActionRepeatWrapper

Bases: Wrapper

Apply different action-repeat counts per agent uid.

Effective control frequency for agent a is::

base_freq / action_repeat[a]

At each env.step call, an agent whose repeat counter has not elapsed re-applies its most recent action instead of the newly submitted one.

ADR-001 §Decision item 2; ADR-007 Stage 2 CR axis (rev 3 §Stage 2).

Parameters:

• env (Env) –

  Env exposing a gym.spaces.Dict action space keyed by agent uid.

• action_repeat (Mapping[str, int]) –

  Mapping from agent uid to a positive integer repeat count. Keys absent from this mapping default to repeat=1 (pass-through).

Raises:

• ChamberEnvCompatibilityError –

  if the action space is not a gym.spaces.Dict keyed by agent uid (ADR-001 §Risks).

• ValueError –

  if any repeat count is less than 1.

Source code in src/chamber/envs/action_repeat.py

class PerAgentActionRepeatWrapper(gym.Wrapper):  # type: ignore[type-arg]
    """Apply different action-repeat counts per agent uid.

    Effective control frequency for agent ``a`` is::

        base_freq / action_repeat[a]

    At each ``env.step`` call, an agent whose repeat counter has not elapsed
    re-applies its most recent action instead of the newly submitted one.

    ADR-001 §Decision item 2; ADR-007 Stage 2 CR axis (rev 3 §Stage 2).

    Args:
        env: Env exposing a ``gym.spaces.Dict`` action space keyed by agent uid.
        action_repeat: Mapping from agent uid to a positive integer repeat count.
            Keys absent from this mapping default to repeat=1 (pass-through).

    Raises:
        ChamberEnvCompatibilityError: if the action space is not a
            ``gym.spaces.Dict`` keyed by agent uid (ADR-001 §Risks).
        ValueError: if any repeat count is less than 1.
    """

    def __init__(self, env: gym.Env, action_repeat: Mapping[str, int]) -> None:  # type: ignore[type-arg]
        """Validate the action space and store per-agent repeat counts."""
        super().__init__(env)
        if not isinstance(env.action_space, gym.spaces.Dict):
            raise ChamberEnvCompatibilityError(
                f"PerAgentActionRepeatWrapper requires a gym.spaces.Dict action "
                f"space keyed by agent uid; got {type(env.action_space).__name__}. "
                f"See ADR-001 §Risks."
            )
        for uid, count in action_repeat.items():
            if count < 1:
                raise ValueError(f"action_repeat[{uid!r}] must be ≥ 1, got {count}")
        self._action_repeat: dict[str, int] = dict(action_repeat)
        self._counters: dict[str, int] = dict.fromkeys(action_repeat, 0)
        self._last_action: dict[str, object] = {}

    def step(self, action: dict) -> tuple:  # type: ignore[override]
        """Step with per-agent action repeat applied.

        ADR-001 §Validation criteria condition (c): the slow agent's effective
        action update interval matches 1/rate within one env tick.
        """
        resolved: dict[str, object] = {}
        for uid, act in action.items():
            repeat = self._action_repeat.get(uid, 1)
            counter = self._counters.get(uid, 0)
            if counter == 0:
                resolved[uid] = act
                self._last_action[uid] = act
                self._counters[uid] = repeat - 1
            else:
                resolved[uid] = self._last_action[uid]
                self._counters[uid] = counter - 1
        return self.env.step(resolved)

    def reset(self, **kwargs: object) -> tuple:  # type: ignore[override]
        """Reset the env and clear all per-agent repeat state.

        ADR-001 §Decision item 2: no state leaks across episodes.
        """
        obs, info = self.env.reset(**kwargs)  # type: ignore[arg-type]
        self._counters = dict.fromkeys(self._action_repeat, 0)
        self._last_action = {}
        return obs, info

__init__

__init__(
    env: Env, action_repeat: Mapping[str, int]
) -> None

Validate the action space and store per-agent repeat counts.

Source code in src/chamber/envs/action_repeat.py

def __init__(self, env: gym.Env, action_repeat: Mapping[str, int]) -> None:  # type: ignore[type-arg]
    """Validate the action space and store per-agent repeat counts."""
    super().__init__(env)
    if not isinstance(env.action_space, gym.spaces.Dict):
        raise ChamberEnvCompatibilityError(
            f"PerAgentActionRepeatWrapper requires a gym.spaces.Dict action "
            f"space keyed by agent uid; got {type(env.action_space).__name__}. "
            f"See ADR-001 §Risks."
        )
    for uid, count in action_repeat.items():
        if count < 1:
            raise ValueError(f"action_repeat[{uid!r}] must be ≥ 1, got {count}")
    self._action_repeat: dict[str, int] = dict(action_repeat)
    self._counters: dict[str, int] = dict.fromkeys(action_repeat, 0)
    self._last_action: dict[str, object] = {}

reset

reset(**kwargs: object) -> tuple

Reset the env and clear all per-agent repeat state.

ADR-001 §Decision item 2: no state leaks across episodes.

Source code in src/chamber/envs/action_repeat.py

def reset(self, **kwargs: object) -> tuple:  # type: ignore[override]
    """Reset the env and clear all per-agent repeat state.

    ADR-001 §Decision item 2: no state leaks across episodes.
    """
    obs, info = self.env.reset(**kwargs)  # type: ignore[arg-type]
    self._counters = dict.fromkeys(self._action_repeat, 0)
    self._last_action = {}
    return obs, info

step

step(action: dict) -> tuple

Step with per-agent action repeat applied.

ADR-001 §Validation criteria condition (c): the slow agent's effective action update interval matches 1/rate within one env tick.

Source code in src/chamber/envs/action_repeat.py

def step(self, action: dict) -> tuple:  # type: ignore[override]
    """Step with per-agent action repeat applied.

    ADR-001 §Validation criteria condition (c): the slow agent's effective
    action update interval matches 1/rate within one env tick.
    """
    resolved: dict[str, object] = {}
    for uid, act in action.items():
        repeat = self._action_repeat.get(uid, 1)
        counter = self._counters.get(uid, 0)
        if counter == 0:
            resolved[uid] = act
            self._last_action[uid] = act
            self._counters[uid] = repeat - 1
        else:
            resolved[uid] = self._last_action[uid]
            self._counters[uid] = counter - 1
    return self.env.step(resolved)

Stage0StateSynthesizer

Bases: ObservationWrapper

Inject per-uid state into Stage-0 observations (ADR-001 §Validation; #184).

Stage-0 parallel to :class:chamber.envs.stage1_obs_filter.Stage1ASStateSynthesizer. For every uid in inner.action_space whose observation_space["agent"][uid] is a :class:gym.spaces.Dict without a "state" key, this wrapper concatenates the uid's 1-D Box channels (alphabetical order) into a flat state Box and injects it at every step. Uids that already expose state and non-Dict per-uid spaces are passed through unchanged.

Parameters:

• env (Env[Any, Any]) –

  A multi-agent env with a Dict observation_space whose "agent" entry is itself a Dict keyed by uid, and whose action_space is a Dict keyed by the same uids.

Raises:

• TypeError –

  If observation_space is not a Dict, or observation_space["agent"] is not a Dict, or action_space is not a Dict.

• ChamberEnvCompatibilityError –

  If a uid that needs synthesis has no 1-D Box channels available — there is nothing to concatenate into a flat state vector.

Source code in src/chamber/envs/stage0_state_synth.py

class Stage0StateSynthesizer(gym.ObservationWrapper):  # type: ignore[type-arg]
    """Inject per-uid ``state`` into Stage-0 observations (ADR-001 §Validation; #184).

    Stage-0 parallel to
    :class:`chamber.envs.stage1_obs_filter.Stage1ASStateSynthesizer`. For
    every uid in ``inner.action_space`` whose
    ``observation_space["agent"][uid]`` is a :class:`gym.spaces.Dict`
    without a ``"state"`` key, this wrapper concatenates the uid's 1-D
    Box channels (alphabetical order) into a flat ``state`` Box and
    injects it at every step. Uids that already expose ``state`` and
    non-Dict per-uid spaces are passed through unchanged.

    Args:
        env: A multi-agent env with a Dict ``observation_space`` whose
            ``"agent"`` entry is itself a Dict keyed by uid, and whose
            ``action_space`` is a Dict keyed by the same uids.

    Raises:
        TypeError: If ``observation_space`` is not a Dict, or
            ``observation_space["agent"]`` is not a Dict, or
            ``action_space`` is not a Dict.
        ChamberEnvCompatibilityError: If a uid that needs synthesis has
            no 1-D Box channels available — there is nothing to
            concatenate into a flat state vector.
    """

    def __init__(self, env: gym.Env[Any, Any]) -> None:
        """Detect which uids need synthesis at construction (ADR-001 §Validation criteria)."""
        super().__init__(env)
        inner_obs_space = env.observation_space
        if not isinstance(inner_obs_space, gym.spaces.Dict):
            raise TypeError(
                "Stage0StateSynthesizer requires a gym.spaces.Dict observation "
                f"space; got {type(inner_obs_space).__name__}. ADR-001 §Validation criteria."
            )
        inner_action_space = env.action_space
        if not isinstance(inner_action_space, gym.spaces.Dict):
            raise TypeError(
                "Stage0StateSynthesizer requires a gym.spaces.Dict action space; "
                f"got {type(inner_action_space).__name__}. ADR-001 §Validation criteria."
            )
        inner_uids: tuple[str, ...] = tuple(inner_action_space.spaces.keys())
        (
            self.observation_space,
            self._synthesise_state_for,
            self._state_synthesis_keys,
        ) = _build_synthesised_obs_space(inner_obs_space, inner_uids)

    def observation(self, observation: Mapping[str, Any]) -> dict[str, Any]:
        """Inject synthesised ``state`` keys per uid (ADR-001 §Validation criteria)."""
        if not self._synthesise_state_for:
            return dict(observation)
        out: dict[str, Any] = dict(observation)
        agent_in = observation.get("agent", {})
        agent_out: dict[str, Any] = dict(agent_in)
        for uid in self._synthesise_state_for:
            sub_in = agent_in.get(uid, {})
            if not isinstance(sub_in, dict):
                continue
            keys = self._state_synthesis_keys[uid]
            pieces = [np.asarray(sub_in[k], dtype=np.float32).ravel() for k in keys]
            sub_out = dict(sub_in)
            sub_out[_STATE_KEY] = (
                np.concatenate(pieces) if pieces else np.zeros(0, dtype=np.float32)
            )
            agent_out[uid] = sub_out
        out["agent"] = agent_out
        return out

__init__

__init__(env: Env[Any, Any]) -> None

Detect which uids need synthesis at construction (ADR-001 §Validation criteria).

Source code in src/chamber/envs/stage0_state_synth.py

def __init__(self, env: gym.Env[Any, Any]) -> None:
    """Detect which uids need synthesis at construction (ADR-001 §Validation criteria)."""
    super().__init__(env)
    inner_obs_space = env.observation_space
    if not isinstance(inner_obs_space, gym.spaces.Dict):
        raise TypeError(
            "Stage0StateSynthesizer requires a gym.spaces.Dict observation "
            f"space; got {type(inner_obs_space).__name__}. ADR-001 §Validation criteria."
        )
    inner_action_space = env.action_space
    if not isinstance(inner_action_space, gym.spaces.Dict):
        raise TypeError(
            "Stage0StateSynthesizer requires a gym.spaces.Dict action space; "
            f"got {type(inner_action_space).__name__}. ADR-001 §Validation criteria."
        )
    inner_uids: tuple[str, ...] = tuple(inner_action_space.spaces.keys())
    (
        self.observation_space,
        self._synthesise_state_for,
        self._state_synthesis_keys,
    ) = _build_synthesised_obs_space(inner_obs_space, inner_uids)

observation

observation(
    observation: Mapping[str, Any],
) -> dict[str, Any]

Inject synthesised state keys per uid (ADR-001 §Validation criteria).

Source code in src/chamber/envs/stage0_state_synth.py

def observation(self, observation: Mapping[str, Any]) -> dict[str, Any]:
    """Inject synthesised ``state`` keys per uid (ADR-001 §Validation criteria)."""
    if not self._synthesise_state_for:
        return dict(observation)
    out: dict[str, Any] = dict(observation)
    agent_in = observation.get("agent", {})
    agent_out: dict[str, Any] = dict(agent_in)
    for uid in self._synthesise_state_for:
        sub_in = agent_in.get(uid, {})
        if not isinstance(sub_in, dict):
            continue
        keys = self._state_synthesis_keys[uid]
        pieces = [np.asarray(sub_in[k], dtype=np.float32).ravel() for k in keys]
        sub_out = dict(sub_in)
        sub_out[_STATE_KEY] = (
            np.concatenate(pieces) if pieces else np.zeros(0, dtype=np.float32)
        )
        agent_out[uid] = sub_out
    out["agent"] = agent_out
    return out

Stage1ASStateSynthesizer

Bases: ObservationWrapper

Synthesise obs["agent"][uid]["state"] for AS conditions (ADR-007 §Stage 1b).

ManiSkill v3.0.1 obs_mode="state_dict" (used by the Stage-1 AS conditions) emits per-agent Dict(qpos: Box, qvel: Box, ...) with no top-level "state" key. But :meth:chamber.benchmarks.ego_ppo_trainer.EgoPPOTrainer.from_config reads env.observation_space["agent"][ego_uid]["state"] as a 1-D Box and derives obs_dim = ego_state_space.shape[0]. This wrapper synthesises that state key.

Ego state widening (P1.05.8; ADR-007 §Stage 1b Rev 12; ADR-009 §Decision). Per the module docstring, the ego uid's synthesised state concatenates [ego_qpos, ego_qvel, partner_qpos, partner_qvel, cube_pose, goal_pos, tcp_pose]. The non-ego (partner) entry's state stays at concat(qpos, qvel) of the partner alone (the partner does not see the task or the ego). Per-condition state dim is env-emit-dependent and pinned by the Tier-1 + Tier-2 tests; the trainer reads the shape off the env at construction time.

Pass-through for OM conditions (is_om_condition=True — those go through :class:Stage1OMChannelFilter instead) and for envs whose condition_id is missing or unrecognised (Tier-1 safety: keeps the wrapper a no-op for envs that don't satisfy the Stage-1b condition_id contract).

Parameters:

• env (Env[Any, Any]) –

  Inner env exposing a condition_id attribute. For AS conditions, must also expose obs["agent"][ego_uid] and obs["agent"][partner_uid] Dicts with qpos / qvel Boxes, and obs["extra"] Dict with cube_pose (last-dim 7), goal_pos (last-dim 3), tcp_pose (last-dim 7).

Raises:

• TypeError –

  If env.observation_space is not a :class:gym.spaces.Dict, or — for active AS conditions — if the required obs["extra"] task fields are missing or mistyped. The error message names the missing / wrong-typed key and cites ADR-007 §Stage 1b Rev 12, so a future operator who breaks the contract surfaces it at env construction rather than weeks later as a silent zero-fill regression of Surface 6.

Source code in src/chamber/envs/stage1_obs_filter.py

class Stage1ASStateSynthesizer(gym.ObservationWrapper):  # type: ignore[type-arg]
    """Synthesise ``obs["agent"][uid]["state"]`` for AS conditions (ADR-007 §Stage 1b).

    ManiSkill v3.0.1 ``obs_mode="state_dict"`` (used by the Stage-1 AS
    conditions) emits per-agent ``Dict(qpos: Box, qvel: Box, ...)`` with
    no top-level ``"state"`` key. But
    :meth:`chamber.benchmarks.ego_ppo_trainer.EgoPPOTrainer.from_config`
    reads ``env.observation_space["agent"][ego_uid]["state"]`` as a 1-D
    Box and derives ``obs_dim = ego_state_space.shape[0]``. This
    wrapper synthesises that ``state`` key.

    **Ego state widening (P1.05.8; ADR-007 §Stage 1b Rev 12;
    ADR-009 §Decision).** Per the module docstring, the ego uid's
    synthesised ``state`` concatenates ``[ego_qpos, ego_qvel,
    partner_qpos, partner_qvel, cube_pose, goal_pos, tcp_pose]``.
    The non-ego (partner) entry's ``state`` stays at
    ``concat(qpos, qvel)`` of the partner alone (the partner does
    not see the task or the ego). Per-condition state dim is
    env-emit-dependent and pinned by the Tier-1 + Tier-2 tests; the
    trainer reads the shape off the env at construction time.

    Pass-through for OM conditions (``is_om_condition=True`` — those go
    through :class:`Stage1OMChannelFilter` instead) and for envs whose
    ``condition_id`` is missing or unrecognised (Tier-1 safety: keeps
    the wrapper a no-op for envs that don't satisfy the Stage-1b
    ``condition_id`` contract).

    Args:
        env: Inner env exposing a ``condition_id`` attribute. For AS
            conditions, must also expose ``obs["agent"][ego_uid]``
            and ``obs["agent"][partner_uid]`` Dicts with ``qpos`` /
            ``qvel`` Boxes, and ``obs["extra"]`` Dict with
            ``cube_pose`` (last-dim 7), ``goal_pos`` (last-dim 3),
            ``tcp_pose`` (last-dim 7).

    Raises:
        TypeError: If ``env.observation_space`` is not a
            :class:`gym.spaces.Dict`, or — for active AS conditions —
            if the required ``obs["extra"]`` task fields are missing
            or mistyped. The error message names the missing /
            wrong-typed key and cites ADR-007 §Stage 1b Rev 12, so a
            future operator who breaks the contract surfaces it at
            env construction rather than weeks later as a silent
            zero-fill regression of Surface 6.
    """

    def __init__(self, env: gym.Env[Any, Any]) -> None:
        """Detect AS-condition envs at construction (ADR-007 §Stage 1b Rev 12)."""
        super().__init__(env)
        if not isinstance(env.observation_space, gym.spaces.Dict):
            msg = (
                "Stage1ASStateSynthesizer requires a gym.spaces.Dict observation "
                f"space; got {type(env.observation_space).__name__}."
            )
            raise TypeError(msg)
        condition_id = getattr(env, "condition_id", None)
        if condition_id is None and hasattr(env, "get_wrapper_attr"):
            try:
                condition_id = env.get_wrapper_attr("condition_id")
            except AttributeError:
                condition_id = None
        # Local import to avoid the chamber.envs.stage1_pickplace ↔
        # chamber.envs.stage1_obs_filter circular import that arises now
        # that make_stage1_pickplace_env applies this wrapper.
        from chamber.envs.stage1_pickplace import resolve_condition

        config = None
        if isinstance(condition_id, str):
            try:
                config = resolve_condition(condition_id)
            except ValueError:
                config = None
        self._active: bool = config is not None and not config.is_om_condition
        # Cache ego / partner uids when active so the per-step
        # ``observation()`` callable does not have to re-resolve.
        self._ego_uid: str | None = None
        self._partner_uid: str | None = None
        if self._active and config is not None:
            self._ego_uid, self._partner_uid = config.agent_uids
            self.observation_space = self._build_observation_space(env.observation_space)

    def _build_observation_space(self, inner: gym.spaces.Dict) -> gym.spaces.Dict:
        """Inject the widened 1-D ``state`` Box per agent (ADR-007 §Stage 1b Rev 12).

        Ego uid's ``state`` Box has shape ``(ego_qpos + ego_qvel +
        partner_qpos + partner_qvel + 7 + 3 + 7,)``; non-ego entries
        keep the per-uid ``concat(qpos, qvel)`` shape.
        """
        # pragma: no cover - guarded by _active
        if self._ego_uid is None or self._partner_uid is None:
            return inner
        agent = inner.spaces.get("agent")
        if not isinstance(agent, gym.spaces.Dict):
            msg = (
                "Stage1ASStateSynthesizer: inner env's observation_space is missing "
                "a Dict 'agent' sub-space. Required by the AS synthesiser to "
                "compose per-uid 'state' Boxes. ADR-007 §Stage 1b Rev 12."
            )
            raise TypeError(msg)
        # Resolve ego / partner sub-spaces and validate qpos / qvel Box-ness.
        ego_qpos_dim, ego_qvel_dim = _resolve_qpos_qvel_dims(agent, uid=self._ego_uid, role="ego")
        partner_qpos_dim, partner_qvel_dim = _resolve_qpos_qvel_dims(
            agent, uid=self._partner_uid, role="partner"
        )
        # Validate ``obs["extra"]`` carries the three task fields with the
        # expected trailing dims.
        extra_total_dim = _validate_and_sum_task_extras(inner)
        ego_state_dim = (
            ego_qpos_dim + ego_qvel_dim + partner_qpos_dim + partner_qvel_dim + extra_total_dim
        )

        new_agent_spaces: dict[str, gym.spaces.Space[Any]] = {}
        for uid, sub in agent.spaces.items():
            if isinstance(sub, gym.spaces.Dict):
                qpos = sub.spaces.get("qpos")
                qvel = sub.spaces.get("qvel")
                if isinstance(qpos, gym.spaces.Box) and isinstance(qvel, gym.spaces.Box):
                    if uid == self._ego_uid:
                        state_dim = ego_state_dim
                    else:
                        state_dim = int(qpos.shape[-1]) + int(qvel.shape[-1])
                    # P1.05.10: mirror the inner space's batching. A
                    # vectorised build's qpos Box is (num_envs, dof) with
                    # num_envs > 1 — the synthesised state Box is then
                    # (num_envs, state_dim) so space and runtime obs
                    # agree. Single-env builds — including the (1, dof)
                    # squeezed-batch layout ManiSkill emits at
                    # num_envs=1 — keep the historical flat (state_dim,)
                    # Box (the runtime concat ravels the batch-1 case to
                    # 1-D too). Consumers read the per-env dim via
                    # shape[-1] (see EgoPPOTrainer.from_config).
                    qpos_shape = qpos.shape if qpos.shape is not None else (state_dim,)
                    state_shape = (
                        (int(qpos_shape[0]), state_dim)
                        if len(qpos_shape) > 1 and int(qpos_shape[0]) > 1
                        else (state_dim,)
                    )
                    state_box = gym.spaces.Box(
                        low=-np.inf,
                        high=np.inf,
                        shape=state_shape,
                        dtype=np.float32,
                    )
                    augmented = dict(sub.spaces)
                    augmented["state"] = state_box
                    new_agent_spaces[uid] = gym.spaces.Dict(augmented)
                    continue
            new_agent_spaces[uid] = sub
        new_spaces = dict(inner.spaces)
        new_spaces["agent"] = gym.spaces.Dict(new_agent_spaces)
        return gym.spaces.Dict(new_spaces)

    def observation(self, observation: dict[str, Any]) -> dict[str, Any]:  # type: ignore[override]
        """Inject the widened ego ``state`` (ADR-007 §Stage 1b Rev 12)."""
        if not self._active:
            return observation
        agent = observation.get("agent")
        if not isinstance(agent, dict):
            return observation
        if self._ego_uid is None or self._partner_uid is None:  # pragma: no cover
            return observation
        extra = observation.get("extra")
        if not isinstance(extra, dict):
            msg = (
                "Stage1ASStateSynthesizer: runtime obs is missing the 'extra' "
                "sub-dict required by the widened ego state contract. "
                "Expected keys: cube_pose, goal_pos, tcp_pose. "
                "See ADR-007 §Stage 1b Rev 12."
            )
            raise TypeError(msg)
        partner_sub = agent.get(self._partner_uid)
        if (
            not isinstance(partner_sub, dict)
            or "qpos" not in partner_sub
            or "qvel" not in partner_sub
        ):
            msg = (
                f"Stage1ASStateSynthesizer: runtime obs missing partner uid "
                f"{self._partner_uid!r} with qpos+qvel keys. The widened ego "
                "state contract requires direct partner-pose observation "
                "(ADR-009 §Decision direct-observation-of-partner-pose). "
                "See ADR-007 §Stage 1b Rev 12."
            )
            raise TypeError(msg)
        task_arrays: dict[str, Any] = {}
        for field_name, _ in _AS_TASK_EXTRA_FIELDS:
            value = extra.get(field_name)
            if value is None:
                msg = (
                    f"Stage1ASStateSynthesizer: runtime obs missing task field "
                    f"'extra.{field_name}'. The widened ego state contract "
                    "requires cube / goal / TCP pose. See ADR-007 §Stage 1b Rev 12."
                )
                raise TypeError(msg)
            task_arrays[field_name] = value

        new_agent: dict[str, Any] = {}
        for uid, sub in agent.items():
            if isinstance(sub, dict) and "qpos" in sub and "qvel" in sub:
                augmented = dict(sub)
                if uid == self._ego_uid:
                    augmented["state"] = _flat_widened_state_concat(
                        sub["qpos"],
                        sub["qvel"],
                        partner_sub["qpos"],
                        partner_sub["qvel"],
                        task_arrays["cube_pose"],
                        task_arrays["goal_pos"],
                        task_arrays["tcp_pose"],
                    )
                else:
                    augmented["state"] = _flat_state_concat(sub["qpos"], sub["qvel"])
                new_agent[uid] = augmented
            else:
                new_agent[uid] = sub
        out = dict(observation)
        out["agent"] = new_agent
        return out

    def __getattr__(self, name: str) -> Any:  # noqa: ANN401 - mirrors gym.Wrapper's inherited __getattr__ signature
        """Forward attribute access to the inner env (Tier-2 caller contract).

        Gymnasium 1.3 removed :class:`gym.Wrapper`'s implicit
        ``__getattr__``; existing P1.03 callers of
        :func:`make_stage1_pickplace_env` read SAPIEN-env attributes
        directly (``env.agent``, ``env._jacobian_provider``,
        ``env.condition_config``...). Forwarding here keeps that
        contract without forcing every caller to switch to
        :meth:`gym.Wrapper.get_wrapper_attr`.

        ``__getattr__`` only fires when normal attribute lookup misses;
        ``self.env`` is set by :meth:`gym.Wrapper.__init__` before any
        downstream access, so the delegation is safe. The ``env``-name
        guard is a defensive backstop against recursive lookup on the
        env attr itself (only reachable in pathological half-init
        paths).
        """
        if name == "env":
            raise AttributeError(name)
        return getattr(self.env, name)

__getattr__

__getattr__(name: str) -> Any

Forward attribute access to the inner env (Tier-2 caller contract).

Gymnasium 1.3 removed :class:gym.Wrapper's implicit __getattr__; existing P1.03 callers of :func:make_stage1_pickplace_env read SAPIEN-env attributes directly (env.agent, env._jacobian_provider, env.condition_config...). Forwarding here keeps that contract without forcing every caller to switch to :meth:gym.Wrapper.get_wrapper_attr.

__getattr__ only fires when normal attribute lookup misses; self.env is set by :meth:gym.Wrapper.__init__ before any downstream access, so the delegation is safe. The env-name guard is a defensive backstop against recursive lookup on the env attr itself (only reachable in pathological half-init paths).

Source code in src/chamber/envs/stage1_obs_filter.py

def __getattr__(self, name: str) -> Any:  # noqa: ANN401 - mirrors gym.Wrapper's inherited __getattr__ signature
    """Forward attribute access to the inner env (Tier-2 caller contract).

    Gymnasium 1.3 removed :class:`gym.Wrapper`'s implicit
    ``__getattr__``; existing P1.03 callers of
    :func:`make_stage1_pickplace_env` read SAPIEN-env attributes
    directly (``env.agent``, ``env._jacobian_provider``,
    ``env.condition_config``...). Forwarding here keeps that
    contract without forcing every caller to switch to
    :meth:`gym.Wrapper.get_wrapper_attr`.

    ``__getattr__`` only fires when normal attribute lookup misses;
    ``self.env`` is set by :meth:`gym.Wrapper.__init__` before any
    downstream access, so the delegation is safe. The ``env``-name
    guard is a defensive backstop against recursive lookup on the
    env attr itself (only reachable in pathological half-init
    paths).
    """
    if name == "env":
        raise AttributeError(name)
    return getattr(self.env, name)

__init__

__init__(env: Env[Any, Any]) -> None

Detect AS-condition envs at construction (ADR-007 §Stage 1b Rev 12).

Source code in src/chamber/envs/stage1_obs_filter.py

def __init__(self, env: gym.Env[Any, Any]) -> None:
    """Detect AS-condition envs at construction (ADR-007 §Stage 1b Rev 12)."""
    super().__init__(env)
    if not isinstance(env.observation_space, gym.spaces.Dict):
        msg = (
            "Stage1ASStateSynthesizer requires a gym.spaces.Dict observation "
            f"space; got {type(env.observation_space).__name__}."
        )
        raise TypeError(msg)
    condition_id = getattr(env, "condition_id", None)
    if condition_id is None and hasattr(env, "get_wrapper_attr"):
        try:
            condition_id = env.get_wrapper_attr("condition_id")
        except AttributeError:
            condition_id = None
    # Local import to avoid the chamber.envs.stage1_pickplace ↔
    # chamber.envs.stage1_obs_filter circular import that arises now
    # that make_stage1_pickplace_env applies this wrapper.
    from chamber.envs.stage1_pickplace import resolve_condition

    config = None
    if isinstance(condition_id, str):
        try:
            config = resolve_condition(condition_id)
        except ValueError:
            config = None
    self._active: bool = config is not None and not config.is_om_condition
    # Cache ego / partner uids when active so the per-step
    # ``observation()`` callable does not have to re-resolve.
    self._ego_uid: str | None = None
    self._partner_uid: str | None = None
    if self._active and config is not None:
        self._ego_uid, self._partner_uid = config.agent_uids
        self.observation_space = self._build_observation_space(env.observation_space)

observation

observation(observation: dict[str, Any]) -> dict[str, Any]

Inject the widened ego state (ADR-007 §Stage 1b Rev 12).

Source code in src/chamber/envs/stage1_obs_filter.py

def observation(self, observation: dict[str, Any]) -> dict[str, Any]:  # type: ignore[override]
    """Inject the widened ego ``state`` (ADR-007 §Stage 1b Rev 12)."""
    if not self._active:
        return observation
    agent = observation.get("agent")
    if not isinstance(agent, dict):
        return observation
    if self._ego_uid is None or self._partner_uid is None:  # pragma: no cover
        return observation
    extra = observation.get("extra")
    if not isinstance(extra, dict):
        msg = (
            "Stage1ASStateSynthesizer: runtime obs is missing the 'extra' "
            "sub-dict required by the widened ego state contract. "
            "Expected keys: cube_pose, goal_pos, tcp_pose. "
            "See ADR-007 §Stage 1b Rev 12."
        )
        raise TypeError(msg)
    partner_sub = agent.get(self._partner_uid)
    if (
        not isinstance(partner_sub, dict)
        or "qpos" not in partner_sub
        or "qvel" not in partner_sub
    ):
        msg = (
            f"Stage1ASStateSynthesizer: runtime obs missing partner uid "
            f"{self._partner_uid!r} with qpos+qvel keys. The widened ego "
            "state contract requires direct partner-pose observation "
            "(ADR-009 §Decision direct-observation-of-partner-pose). "
            "See ADR-007 §Stage 1b Rev 12."
        )
        raise TypeError(msg)
    task_arrays: dict[str, Any] = {}
    for field_name, _ in _AS_TASK_EXTRA_FIELDS:
        value = extra.get(field_name)
        if value is None:
            msg = (
                f"Stage1ASStateSynthesizer: runtime obs missing task field "
                f"'extra.{field_name}'. The widened ego state contract "
                "requires cube / goal / TCP pose. See ADR-007 §Stage 1b Rev 12."
            )
            raise TypeError(msg)
        task_arrays[field_name] = value

    new_agent: dict[str, Any] = {}
    for uid, sub in agent.items():
        if isinstance(sub, dict) and "qpos" in sub and "qvel" in sub:
            augmented = dict(sub)
            if uid == self._ego_uid:
                augmented["state"] = _flat_widened_state_concat(
                    sub["qpos"],
                    sub["qvel"],
                    partner_sub["qpos"],
                    partner_sub["qvel"],
                    task_arrays["cube_pose"],
                    task_arrays["goal_pos"],
                    task_arrays["tcp_pose"],
                )
            else:
                augmented["state"] = _flat_state_concat(sub["qpos"], sub["qvel"])
            new_agent[uid] = augmented
        else:
            new_agent[uid] = sub
    out = dict(observation)
    out["agent"] = new_agent
    return out

Stage1OMChannelFilter

Bases: ObservationWrapper

OM-axis per-condition channel filter (ADR-007 §Stage 1b).

Reads the inner env's condition_id at construction time and captures the resulting filter policy. The wrapper does not re-read condition_id on every step — Stage-1b envs are built once per (seed, condition) cell (see stage1_as.py:253-275) and the condition is fixed for the env's lifetime.

Parameters:

• env (Env[Any, Any]) –

  Inner env exposing a condition_id attribute. The :class:chamber.envs.stage1_pickplace.Stage1PickPlaceEnv class satisfies this; the wrapper falls back to a pass-through identity if condition_id is missing or not one of the two OM strings.

Raises:

• TypeError –

  If the inner env's observation space is not a :class:gym.spaces.Dict (the wrapper relies on dict-shaped obs).

Source code in src/chamber/envs/stage1_obs_filter.py

class Stage1OMChannelFilter(gym.ObservationWrapper):  # type: ignore[type-arg]
    """OM-axis per-condition channel filter (ADR-007 §Stage 1b).

    Reads the inner env's ``condition_id`` at construction time and
    captures the resulting filter policy. The wrapper does not re-read
    ``condition_id`` on every step — Stage-1b envs are built once per
    ``(seed, condition)`` cell (see ``stage1_as.py:253-275``) and the
    condition is fixed for the env's lifetime.

    Args:
        env: Inner env exposing a ``condition_id`` attribute. The
            :class:`chamber.envs.stage1_pickplace.Stage1PickPlaceEnv`
            class satisfies this; the wrapper falls back to a
            pass-through identity if ``condition_id`` is missing or
            not one of the two OM strings.

    Raises:
        TypeError: If the inner env's observation space is not a
            :class:`gym.spaces.Dict` (the wrapper relies on dict-shaped
            obs).
    """

    def __init__(self, env: gym.Env[Any, Any]) -> None:
        """Store the per-condition filter policy (ADR-007 §Stage 1b)."""
        super().__init__(env)
        if not isinstance(env.observation_space, gym.spaces.Dict):
            msg = (
                "Stage1OMChannelFilter requires a gym.spaces.Dict observation "
                f"space; got {type(env.observation_space).__name__}."
            )
            raise TypeError(msg)
        # Read condition_id once at construction; the env-per-cell
        # cadence makes this safe and saves a hot-path attr lookup.
        condition_id = getattr(env, "condition_id", None)
        if condition_id is None and hasattr(env, "get_wrapper_attr"):
            try:
                condition_id = env.get_wrapper_attr("condition_id")
            except AttributeError:
                condition_id = None
        self._condition_id: str | None = condition_id
        self._filter_active: bool = condition_id in _FILTERED_CONDITIONS

    @property
    def condition_id(self) -> str | None:
        """ADR-007 §Stage 1b OM axis: the condition_id resolved at construction."""
        return self._condition_id

    def observation(self, observation: dict[str, Any]) -> dict[str, Any]:  # type: ignore[override]
        """Apply the per-condition channel mask (ADR-007 §Stage 1b).

        OM-vision-only zero-masks the per-uid agent-proprio sub-dicts
        and the ``obs["extra"]["force_torque"]`` channel; keeps
        ``obs["extra"]["tcp_pose"]`` + ``obs["extra"]["goal_pos"]``
        (the minimal task-relevant fields) plus ``obs["sensor_data"]``
        (RGB-D camera) untouched. Other conditions pass through.
        """
        if not self._filter_active:
            return observation
        out = dict(observation)
        # Zero-mask per-uid agent proprio (the "no proprioception" half
        # of the vision-only condition_id semantics).
        agent = observation.get("agent")
        if isinstance(agent, dict):
            zeroed_agent: dict[str, Any] = {}
            for uid, sub in agent.items():
                if isinstance(sub, dict):
                    zeroed_agent[uid] = {
                        ch: _zeros_like_preserving_backend(val) for ch, val in sub.items()
                    }
                else:
                    zeroed_agent[uid] = sub
            out["agent"] = zeroed_agent
        # Zero-mask task extras NOT in the vision-only keep-set (the
        # "no force-torque" half of the vision-only semantics).
        extra = observation.get("extra")
        if isinstance(extra, dict):
            filtered_extra: dict[str, Any] = {}
            for ch, val in extra.items():
                if ch in _OM_VISION_ONLY_EXTRA_KEEP:
                    filtered_extra[ch] = val
                else:
                    filtered_extra[ch] = _zeros_like_preserving_backend(val)
            out["extra"] = filtered_extra
        return out

    def __getattr__(self, name: str) -> Any:  # noqa: ANN401 - mirrors Stage1ASStateSynthesizer's forwarding contract
        """Forward attribute access to the inner env (Tier-2 caller contract).

        Mirrors :meth:`Stage1ASStateSynthesizer.__getattr__`: Gymnasium 1.3
        removed :class:`gym.Wrapper`'s implicit forwarding, so callers of
        :func:`chamber.envs.stage1_pickplace.make_stage1_pickplace_env`
        — which now applies this wrapper on top of the AS synthesizer —
        would otherwise lose access to SAPIEN-env attributes such as
        ``env.agent``, ``env.obs_mode``, ``env.condition_config``.
        """
        if name == "env":
            raise AttributeError(name)
        return getattr(self.env, name)

condition_id property

condition_id: str | None

ADR-007 §Stage 1b OM axis: the condition_id resolved at construction.

__getattr__

__getattr__(name: str) -> Any

Forward attribute access to the inner env (Tier-2 caller contract).

Mirrors :meth:Stage1ASStateSynthesizer.__getattr__: Gymnasium 1.3 removed :class:gym.Wrapper's implicit forwarding, so callers of :func:chamber.envs.stage1_pickplace.make_stage1_pickplace_env — which now applies this wrapper on top of the AS synthesizer — would otherwise lose access to SAPIEN-env attributes such as env.agent, env.obs_mode, env.condition_config.

Source code in src/chamber/envs/stage1_obs_filter.py

def __getattr__(self, name: str) -> Any:  # noqa: ANN401 - mirrors Stage1ASStateSynthesizer's forwarding contract
    """Forward attribute access to the inner env (Tier-2 caller contract).

    Mirrors :meth:`Stage1ASStateSynthesizer.__getattr__`: Gymnasium 1.3
    removed :class:`gym.Wrapper`'s implicit forwarding, so callers of
    :func:`chamber.envs.stage1_pickplace.make_stage1_pickplace_env`
    — which now applies this wrapper on top of the AS synthesizer —
    would otherwise lose access to SAPIEN-env attributes such as
    ``env.agent``, ``env.obs_mode``, ``env.condition_config``.
    """
    if name == "env":
        raise AttributeError(name)
    return getattr(self.env, name)

__init__

__init__(env: Env[Any, Any]) -> None

Store the per-condition filter policy (ADR-007 §Stage 1b).

Source code in src/chamber/envs/stage1_obs_filter.py

def __init__(self, env: gym.Env[Any, Any]) -> None:
    """Store the per-condition filter policy (ADR-007 §Stage 1b)."""
    super().__init__(env)
    if not isinstance(env.observation_space, gym.spaces.Dict):
        msg = (
            "Stage1OMChannelFilter requires a gym.spaces.Dict observation "
            f"space; got {type(env.observation_space).__name__}."
        )
        raise TypeError(msg)
    # Read condition_id once at construction; the env-per-cell
    # cadence makes this safe and saves a hot-path attr lookup.
    condition_id = getattr(env, "condition_id", None)
    if condition_id is None and hasattr(env, "get_wrapper_attr"):
        try:
            condition_id = env.get_wrapper_attr("condition_id")
        except AttributeError:
            condition_id = None
    self._condition_id: str | None = condition_id
    self._filter_active: bool = condition_id in _FILTERED_CONDITIONS

observation

observation(observation: dict[str, Any]) -> dict[str, Any]

Apply the per-condition channel mask (ADR-007 §Stage 1b).

OM-vision-only zero-masks the per-uid agent-proprio sub-dicts and the obs["extra"]["force_torque"] channel; keeps obs["extra"]["tcp_pose"] + obs["extra"]["goal_pos"] (the minimal task-relevant fields) plus obs["sensor_data"] (RGB-D camera) untouched. Other conditions pass through.

Source code in src/chamber/envs/stage1_obs_filter.py

def observation(self, observation: dict[str, Any]) -> dict[str, Any]:  # type: ignore[override]
    """Apply the per-condition channel mask (ADR-007 §Stage 1b).

    OM-vision-only zero-masks the per-uid agent-proprio sub-dicts
    and the ``obs["extra"]["force_torque"]`` channel; keeps
    ``obs["extra"]["tcp_pose"]`` + ``obs["extra"]["goal_pos"]``
    (the minimal task-relevant fields) plus ``obs["sensor_data"]``
    (RGB-D camera) untouched. Other conditions pass through.
    """
    if not self._filter_active:
        return observation
    out = dict(observation)
    # Zero-mask per-uid agent proprio (the "no proprioception" half
    # of the vision-only condition_id semantics).
    agent = observation.get("agent")
    if isinstance(agent, dict):
        zeroed_agent: dict[str, Any] = {}
        for uid, sub in agent.items():
            if isinstance(sub, dict):
                zeroed_agent[uid] = {
                    ch: _zeros_like_preserving_backend(val) for ch, val in sub.items()
                }
            else:
                zeroed_agent[uid] = sub
        out["agent"] = zeroed_agent
    # Zero-mask task extras NOT in the vision-only keep-set (the
    # "no force-torque" half of the vision-only semantics).
    extra = observation.get("extra")
    if isinstance(extra, dict):
        filtered_extra: dict[str, Any] = {}
        for ch, val in extra.items():
            if ch in _OM_VISION_ONLY_EXTRA_KEEP:
                filtered_extra[ch] = val
            else:
                filtered_extra[ch] = _zeros_like_preserving_backend(val)
        out["extra"] = filtered_extra
    return out

TextureFilterObsWrapper

Bases: ObservationWrapper

Filter observation channels per agent uid, zero-masking unlisted channels.

Tensor shapes are preserved — masked channels become zero arrays of the same shape and dtype. This keeps downstream policy networks oblivious to which modalities a given partner actually receives.

ADR-001 §Decision item 1; ADR-007 §Stage 1 OM axis.

Parameters:

• env (Env) –

  Env whose observation has shape {"agent": {uid: {channel: array}}}.

• keep_per_agent (Mapping[str, Iterable[str]]) –

  Mapping from agent uid to the iterable of channel keys to keep. Channels not listed are zero-masked. Uids absent from this mapping are passed through unchanged.

Source code in src/chamber/envs/texture_filter.py

class TextureFilterObsWrapper(gym.ObservationWrapper):  # type: ignore[type-arg]
    """Filter observation channels per agent uid, zero-masking unlisted channels.

    Tensor shapes are preserved — masked channels become zero arrays of the
    same shape and dtype. This keeps downstream policy networks oblivious to
    which modalities a given partner actually receives.

    ADR-001 §Decision item 1; ADR-007 §Stage 1 OM axis.

    Args:
        env: Env whose observation has shape ``{"agent": {uid: {channel: array}}}``.
        keep_per_agent: Mapping from agent uid to the iterable of channel keys
            to keep. Channels not listed are zero-masked. Uids absent from this
            mapping are passed through unchanged.
    """

    def __init__(self, env: gym.Env, keep_per_agent: Mapping[str, Iterable[str]]) -> None:  # type: ignore[type-arg]
        """Store per-agent channel keep-sets as frozensets for O(1) lookup."""
        super().__init__(env)
        self._keep: dict[str, frozenset[str]] = {
            uid: frozenset(keys) for uid, keys in keep_per_agent.items()
        }

    def observation(self, observation: dict) -> dict:  # type: ignore[override]
        """Apply per-agent channel mask, zero-filling unlisted channels.

        ADR-001 §Decision item 1: obs modality is a controllable heterogeneity
        axis; shapes are invariant so vector rollout is unaffected.
        """
        agent_obs = observation.get("agent")
        if not isinstance(agent_obs, dict):
            return observation
        filtered_agents: dict[str, dict] = {}
        for uid, per_agent in agent_obs.items():
            if uid not in self._keep or not isinstance(per_agent, dict):
                filtered_agents[uid] = per_agent
                continue
            keep = self._keep[uid]
            filtered_agents[uid] = {
                ch: val if ch in keep else np.zeros_like(val) for ch, val in per_agent.items()
            }
        return {**observation, "agent": filtered_agents}

__init__

__init__(
    env: Env, keep_per_agent: Mapping[str, Iterable[str]]
) -> None

Store per-agent channel keep-sets as frozensets for O(1) lookup.

Source code in src/chamber/envs/texture_filter.py

def __init__(self, env: gym.Env, keep_per_agent: Mapping[str, Iterable[str]]) -> None:  # type: ignore[type-arg]
    """Store per-agent channel keep-sets as frozensets for O(1) lookup."""
    super().__init__(env)
    self._keep: dict[str, frozenset[str]] = {
        uid: frozenset(keys) for uid, keys in keep_per_agent.items()
    }

observation

observation(observation: dict) -> dict

Apply per-agent channel mask, zero-filling unlisted channels.

ADR-001 §Decision item 1: obs modality is a controllable heterogeneity axis; shapes are invariant so vector rollout is unaffected.

Source code in src/chamber/envs/texture_filter.py

def observation(self, observation: dict) -> dict:  # type: ignore[override]
    """Apply per-agent channel mask, zero-filling unlisted channels.

    ADR-001 §Decision item 1: obs modality is a controllable heterogeneity
    axis; shapes are invariant so vector rollout is unaffected.
    """
    agent_obs = observation.get("agent")
    if not isinstance(agent_obs, dict):
        return observation
    filtered_agents: dict[str, dict] = {}
    for uid, per_agent in agent_obs.items():
        if uid not in self._keep or not isinstance(per_agent, dict):
            filtered_agents[uid] = per_agent
            continue
        keep = self._keep[uid]
        filtered_agents[uid] = {
            ch: val if ch in keep else np.zeros_like(val) for ch, val in per_agent.items()
        }
    return {**observation, "agent": filtered_agents}

build_control_models_for_condition

build_control_models_for_condition(
    condition_id: str,
    *,
    jacobian_fn: Callable[[AgentSnapshot], NDArray[float64]]
    | None = None,
    fetch_action_dim: int | None = None,
    panda_action_dim: int = 8,
) -> dict[str, AgentControlModel]

Build per-uid :class:AgentControlModel map for condition_id (ADR-004 §Decision).

Pure Tier-1 function — no SAPIEN dependency. The Jacobian callable is plumbed in by the env at construction time (see :meth:Stage1PickPlaceEnv.build_control_models); Tier-1 tests pass jacobian_fn=None to exercise the model-construction path, which keeps the placeholder per :class:JacobianControlModel's loud-fail-on-use contract (concerto/safety/api.py:552).

Parameters:

• condition_id (str) –

  Stage-1 condition_id (raises if unknown).

• jacobian_fn (Callable[[AgentSnapshot], NDArray[float64]] | None, default: None ) –

  Optional Jacobian callable to embed in the panda uid's :class:JacobianControlModel. None means the placeholder model is returned (Tier-1 path); pass the env's closure-via-env-reference callable (lambda snap: env._jacobian_provider(snap, env._latest_qpos["panda_wristcam"])) to get a working model for Tier-2 / production.

• fetch_action_dim (int | None, default: None ) –

  Action dimension of the fetch uid's Box. None (default) is the Tier-1 sentinel — :class:DoubleIntegratorControlModel with action_dim=2 (just the differential-drive base axis; the arm + body + gripper are folded into the same model with the canonical "treat the whole action as a 1-D Cartesian acceleration" approximation P1.05.5 will tighten). Tier-2 paths pass the actual env.action_space[uid].shape[0].

• panda_action_dim (int, default: 8 ) –

  Action dimension of the panda uid's Box. Defaults to 8 (7 arm joint deltas + 1 mimic-gripper joint delta under pd_joint_delta_pos). Both panda_wristcam and panda_partner share this shape.

Returns:

• dict[str, AgentControlModel] –

  {uid: AgentControlModel} map keyed by the condition's

• dict[str, AgentControlModel] –

  attr:ConditionConfig.agent_uids. The panda uid (always the

• dict[str, AgentControlModel] –

  ego, always present) gets a :class:JacobianControlModel; the

• dict[str, AgentControlModel] –

  partner uid gets a :class:JacobianControlModel for

• dict[str, AgentControlModel] –

  panda_partner (AS-homo) or

• dict[str, AgentControlModel] –

  class:DoubleIntegratorControlModel for fetch (AS-hetero /

• dict[str, AgentControlModel] –

  OM-*).

Raises:

• ValueError –

  If condition_id is not in the four-condition table (delegated to :func:resolve_condition).

Source code in src/chamber/envs/stage1_pickplace.py

def build_control_models_for_condition(
    condition_id: str,
    *,
    jacobian_fn: Callable[[AgentSnapshot], NDArray[np.float64]] | None = None,
    fetch_action_dim: int | None = None,
    panda_action_dim: int = 8,
) -> dict[str, AgentControlModel]:
    """Build per-uid :class:`AgentControlModel` map for ``condition_id`` (ADR-004 §Decision).

    Pure Tier-1 function — no SAPIEN dependency. The Jacobian callable
    is plumbed in by the env at construction time (see
    :meth:`Stage1PickPlaceEnv.build_control_models`); Tier-1 tests pass
    ``jacobian_fn=None`` to exercise the model-construction path, which
    keeps the placeholder per :class:`JacobianControlModel`'s
    loud-fail-on-use contract (``concerto/safety/api.py:552``).

    Args:
        condition_id: Stage-1 ``condition_id`` (raises if unknown).
        jacobian_fn: Optional Jacobian callable to embed in the panda
            uid's :class:`JacobianControlModel`. ``None`` means the
            placeholder model is returned (Tier-1 path); pass the env's
            closure-via-env-reference callable
            (``lambda snap: env._jacobian_provider(snap, env._latest_qpos["panda_wristcam"])``)
            to get a working model for Tier-2 / production.
        fetch_action_dim: Action dimension of the fetch uid's Box.
            ``None`` (default) is the Tier-1 sentinel — :class:`DoubleIntegratorControlModel`
            with ``action_dim=2`` (just the differential-drive base axis;
            the arm + body + gripper are folded into the same model
            with the canonical "treat the whole action as a 1-D
            Cartesian acceleration" approximation P1.05.5 will tighten).
            Tier-2 paths pass the actual ``env.action_space[uid].shape[0]``.
        panda_action_dim: Action dimension of the panda uid's Box.
            Defaults to ``8`` (7 arm joint deltas + 1 mimic-gripper
            joint delta under ``pd_joint_delta_pos``). Both
            ``panda_wristcam`` and ``panda_partner`` share this shape.

    Returns:
        ``{uid: AgentControlModel}`` map keyed by the condition's
        :attr:`ConditionConfig.agent_uids`. The panda uid (always the
        ego, always present) gets a :class:`JacobianControlModel`; the
        partner uid gets a :class:`JacobianControlModel` for
        ``panda_partner`` (AS-homo) or
        :class:`DoubleIntegratorControlModel` for ``fetch`` (AS-hetero /
        OM-*).

    Raises:
        ValueError: If ``condition_id`` is not in the four-condition
            table (delegated to :func:`resolve_condition`).
    """
    config = resolve_condition(condition_id)
    ego_uid, partner_uid = config.agent_uids
    models: dict[str, AgentControlModel] = {}
    # Ego is always panda_wristcam — 7-DOF arm + mimic-gripper.
    # JacobianControlModel position_dim=3 (Cartesian) matches the
    # AgentSnapshot Cartesian-only contract (cbf_qp.py:103-110).
    models[ego_uid] = JacobianControlModel(
        uid=ego_uid,
        action_dim=panda_action_dim,
        position_dim=3,
        jacobian_fn=jacobian_fn,
        max_cartesian_accel_value=PANDA_CARTESIAN_ACCEL_CAPACITY_MS2,
    )
    if partner_uid == "panda_partner":
        # AS-homo: second panda, identical kinematics, same Jacobian
        # callable wired by the env via the closure pattern.
        models[partner_uid] = JacobianControlModel(
            uid=partner_uid,
            action_dim=panda_action_dim,
            position_dim=3,
            jacobian_fn=jacobian_fn,
            max_cartesian_accel_value=PANDA_CARTESIAN_ACCEL_CAPACITY_MS2,
        )
    else:
        # AS-hetero / OM-*: fetch base+arm uses DoubleIntegratorControlModel.
        # action_dim default 2 covers the 2-DOF differential-drive base
        # slice that ADR-007 §Stage 1 AS spike framing names; real
        # Tier-2 path passes the full action_space shape.
        effective_action_dim = 2 if fetch_action_dim is None else fetch_action_dim
        models[partner_uid] = DoubleIntegratorControlModel(
            uid=partner_uid,
            action_dim=effective_action_dim,
        )
    return models

make_stage1_pickplace_env

make_stage1_pickplace_env(
    *,
    condition_id: str,
    episode_length: int = DEFAULT_EPISODE_LENGTH,
    root_seed: int = 0,
    num_envs: int = 1,
    render_mode: str | None = None,
    render_backend: str | None = None,
    force_torque_noise_sigma: float = SYNTHESISED_FT_NOISE_SIGMA_N,
) -> gym.Env[Any, Any]

Build a :class:Stage1PickPlaceEnv instance (ADR-007 §Stage 1b).

Factory entry point. SAPIEN / ManiSkill imports are deferred to the body so python -c "import chamber.envs.stage1_pickplace" works on a Vulkan-less host (Tier-1 contract). The :class:Stage1PickPlaceEnv class itself is defined inside the factory body — same pattern as :func:chamber.benchmarks.stage0_smoke.make_stage0_env.

Parameters:

• condition_id (str) –

  One of the four Stage-1 condition_id strings; raises :class:ValueError on any other input (cf. :func:resolve_condition).

• episode_length (int, default: DEFAULT_EPISODE_LENGTH ) –

  Truncation horizon, in env ticks. Default :data:DEFAULT_EPISODE_LENGTH (100). See module docstring for the budget rationale.

• root_seed (int, default: 0 ) –

  Project root seed routed to the env's :func:concerto.training.seeding.derive_substream substream for P6 reproducibility (P6 / ADR-002 determinism rule).

• num_envs (int, default: 1 ) –

  ManiSkill vectorisation count; default 1 (the historical single-env cell, byte-identical per ADR-002). > 1 (P1.05.10; ADR-007 §Stage 1b regime-alignment revision) builds the GPU-parallel cell: ManiSkill selects the physx_cuda sim backend, cube/goal randomisation draws from per-env-index derive_substream streams (P6), and the returned wrapper chain is topped with :class:chamber.envs.stage1_vector.Stage1AutoResetWrapper (per-env partial reset on done + info["final_observation"]). The training-time safety stack is not batched in this slice — vectorised cells must run with safety.enabled=false (:meth:Stage1PickPlaceEnv.build_agent_snapshots raises at num_envs > 1).

• render_mode (str | None, default: None ) –

  ManiSkill render_mode (None, "human", "rgb_array", etc.). None (default) disables rendering for the spike-runner path.

• render_backend (str | None, default: None ) –

  ManiSkill render_backend ("gpu", "none", …). None (default) falls through to ManiSkill's own default. The Stage-0 smoke env uses CHAMBER_RENDER_BACKEND env-var probe + the visual-material strip patch; Stage-1b follows the same pattern but exposes the backend choice as a constructor kwarg too.

• force_torque_noise_sigma (float, default: SYNTHESISED_FT_NOISE_SIGMA_N ) –

  sigma of the zero-mean Gaussian noise added to the synthesised force-torque channel, in Newtons. Default :data:SYNTHESISED_FT_NOISE_SIGMA_N. Override only with an ADR-007 §Revision history entry (the value is load-bearing for the OM gate; see module docstring).

Returns:

• Env[Any, Any] –

  class:Stage1PickPlaceEnv instance, ready to call

• Env[Any, Any] –

  reset(seed=K) on. The action space is a

• Env[Any, Any] –

  class:gym.spaces.Dict keyed by the resolved

• Env[Any, Any] –

  attr:ConditionConfig.agent_uids.

Raises:

• ValueError –

  If condition_id is unknown (see :func:resolve_condition).

• ChamberEnvCompatibilityError –

  If ManiSkill / SAPIEN / Vulkan initialisation fails (CPU-only host without a fallback render_backend="none"; see ADR-001 §Risks).

Source code in src/chamber/envs/stage1_pickplace.py

def make_stage1_pickplace_env(
    *,
    condition_id: str,
    episode_length: int = DEFAULT_EPISODE_LENGTH,
    root_seed: int = 0,
    num_envs: int = 1,
    render_mode: str | None = None,
    render_backend: str | None = None,
    force_torque_noise_sigma: float = SYNTHESISED_FT_NOISE_SIGMA_N,
) -> gym.Env[Any, Any]:
    """Build a :class:`Stage1PickPlaceEnv` instance (ADR-007 §Stage 1b).

    Factory entry point. SAPIEN / ManiSkill imports are deferred to the
    body so ``python -c "import chamber.envs.stage1_pickplace"`` works
    on a Vulkan-less host (Tier-1 contract). The
    :class:`Stage1PickPlaceEnv` class itself is defined inside the
    factory body — same pattern as
    :func:`chamber.benchmarks.stage0_smoke.make_stage0_env`.

    Args:
        condition_id: One of the four Stage-1 ``condition_id`` strings;
            raises :class:`ValueError` on any other input
            (cf. :func:`resolve_condition`).
        episode_length: Truncation horizon, in env ticks. Default
            :data:`DEFAULT_EPISODE_LENGTH` (100). See module docstring
            for the budget rationale.
        root_seed: Project root seed routed to the env's
            :func:`concerto.training.seeding.derive_substream` substream
            for P6 reproducibility (P6 / ADR-002 determinism rule).
        num_envs: ManiSkill vectorisation count; default 1 (the
            historical single-env cell, byte-identical per ADR-002).
            ``> 1`` (P1.05.10; ADR-007 §Stage 1b regime-alignment
            revision) builds the GPU-parallel cell: ManiSkill selects
            the ``physx_cuda`` sim backend, cube/goal randomisation
            draws from per-env-index ``derive_substream`` streams (P6),
            and the returned wrapper chain is topped with
            :class:`chamber.envs.stage1_vector.Stage1AutoResetWrapper`
            (per-env partial reset on done +
            ``info["final_observation"]``). The training-time safety
            stack is not batched in this slice — vectorised cells must
            run with ``safety.enabled=false``
            (:meth:`Stage1PickPlaceEnv.build_agent_snapshots` raises at
            ``num_envs > 1``).
        render_mode: ManiSkill ``render_mode`` (``None``,
            ``"human"``, ``"rgb_array"``, etc.). ``None`` (default)
            disables rendering for the spike-runner path.
        render_backend: ManiSkill ``render_backend`` (``"gpu"``,
            ``"none"``, …). ``None`` (default) falls through to
            ManiSkill's own default. The Stage-0 smoke env uses
            ``CHAMBER_RENDER_BACKEND`` env-var probe + the
            visual-material strip patch; Stage-1b follows the same
            pattern but exposes the backend choice as a constructor
            kwarg too.
        force_torque_noise_sigma: sigma of the zero-mean Gaussian noise
            added to the synthesised force-torque channel, in Newtons.
            Default :data:`SYNTHESISED_FT_NOISE_SIGMA_N`. Override only
            with an ADR-007 §Revision history entry (the value is
            load-bearing for the OM gate; see module docstring).

    Returns:
        :class:`Stage1PickPlaceEnv` instance, ready to call
        ``reset(seed=K)`` on. The action space is a
        :class:`gym.spaces.Dict` keyed by the resolved
        :attr:`ConditionConfig.agent_uids`.

    Raises:
        ValueError: If ``condition_id`` is unknown (see
            :func:`resolve_condition`).
        ChamberEnvCompatibilityError: If ManiSkill / SAPIEN / Vulkan
            initialisation fails (CPU-only host without a fallback
            ``render_backend="none"``; see ADR-001 §Risks).
    """
    # Validate condition_id eagerly (the inner __init__ will resolve again,
    # but raising here gives the user a useful traceback in the Tier-1
    # bogus-id path without paying the SAPIEN-import cost).
    resolve_condition(condition_id)
    try:
        import mani_skill.envs  # noqa: F401 - registers ManiSkill env IDs
        import sapien
        import torch
        from mani_skill.envs.sapien_env import BaseEnv
        from mani_skill.utils.building import actors
        from mani_skill.utils.scene_builder.table import TableSceneBuilder
        from mani_skill.utils.structs.pose import Pose

        # Trigger PandaPartner registration before BaseEnv reaches the
        # multi-agent build loop. The chamber.agents package's
        # try/except ensures this import is the place where a Tier-1
        # context would have already failed if it was going to.
        import chamber.agents  # noqa: F401 - side-effect import for register_agent
        from chamber.agents.panda_jacobian import (
            CARTESIAN_POSITION_DIM,
            PANDA_ARM_DOF,
            PandaJacobianProvider,
        )
        from chamber.envs._sapien_compat import (
            load_agent_with_bare_uids,
            patch_sapien_urdf_no_visual_material,
        )
    except ImportError as exc:
        raise ChamberEnvCompatibilityError(
            "Stage1PickPlaceEnv requires mani_skill / sapien / pytorch_kinematics "
            "in the active venv. Install per pyproject.toml; see ADR-001 §Risks."
        ) from exc

    if render_backend == "none":
        # Headless host workaround — same idempotent SAPIEN URDF patch
        # the Stage-0 smoke env relies on (ADR-001 §Risks).
        patch_sapien_urdf_no_visual_material()

    class Stage1PickPlaceEnv(BaseEnv):  # type: ignore[misc, valid-type]
        """Two-robot pick-place env (ADR-007 §Stage 1b; ADR-001 §Decision).

        Subclasses :class:`mani_skill.envs.sapien_env.BaseEnv` directly
        (matching :class:`chamber.benchmarks.stage0_smoke._Stage0SmokeEnv`).
        See the module docstring for the wrapper-only-discipline /
        synthesised-FT / closure-via-env-Jacobian / cooperation-gradient
        rationale.

        Implements the four condition_id strings the AS / OM pre-
        registrations name; the obs-mode superset is set per condition
        at constructor time, the per-uid channel filtering happens in
        :class:`chamber.envs.stage1_obs_filter.Stage1OMChannelFilter`
        (kept separate so the AS path doesn't pay the filter cost).
        """

        SUPPORTED_ROBOTS: ClassVar[list[tuple[str, str]]] = [  # type: ignore[assignment]
            ("panda_wristcam", "panda_partner"),
            ("panda_wristcam", "fetch"),
        ]

        def __init__(
            self,
            *,
            condition_id: str,
            episode_length: int,
            root_seed: int,
            num_envs: int,
            render_mode: str | None,
            render_backend: str | None,
            force_torque_noise_sigma: float,
        ) -> None:
            """Build the env (ADR-007 §Stage 1b).

            Stores the condition-resolved metadata, sets up the
            determinism harness, then calls
            ``super().__init__(robot_uids=config.agent_uids, ...)``.
            The Jacobian provider is constructed *after* the super-init
            because it reads the panda's URDF directly (independent of
            SAPIEN scene state); the closure plumbed into
            :meth:`build_control_models` then reads ``self._latest_qpos``
            which the env updates each :meth:`_before_simulation_step`.
            """
            self._condition_config: ConditionConfig = resolve_condition(condition_id)
            self._episode_length: int = int(episode_length)
            self._root_seed: int = int(root_seed)
            self._force_torque_noise_sigma: float = float(force_torque_noise_sigma)
            self._rng: np.random.Generator = derive_substream(
                _SUBSTREAM_NAME, root_seed=self._root_seed
            ).default_rng()
            # P1.05.10 (ADR-007 §Stage 1b regime-alignment; P6 / ADR-002):
            # per-env-index cube/goal substreams for vectorised builds.
            # Each parallel env's episode randomisation draws from its own
            # independently-derived stream, advanced only when that env
            # resets — so the draw sequence per env is reproducible
            # regardless of how partial resets interleave across the
            # batch. num_envs==1 keeps the single shared ``self._rng``
            # (cube/goal + FT noise interleaved on one stream) so the
            # historical 1-env path stays byte-identical on CPU.
            self._num_envs_requested: int = int(num_envs)
            self._env_rngs: list[np.random.Generator] = (
                [
                    derive_substream(
                        f"{_SUBSTREAM_NAME}.env{i:04d}", root_seed=self._root_seed
                    ).default_rng()
                    for i in range(self._num_envs_requested)
                ]
                if self._num_envs_requested > 1
                else []
            )
            # Per-uid latest qpos cache for the Jacobian closure; populated
            # before each ``step``. See module docstring on the closure-
            # via-env-reference workaround (decision Q3 mod 3; ADR-004
            # §Open questions / slice P1.05.5).
            self._latest_qpos: dict[str, NDArray[np.float64]] = {}
            # PickCubeEnv-style task parameters; consistent with the
            # upstream defaults so the success / reward shaping path
            # behaves predictably under the multi-agent rig.
            self._cube_half_size: float = 0.02
            self._goal_thresh: float = 0.025
            self._cube_spawn_half_size: float = 0.05
            self._cube_spawn_center: tuple[float, float] = (0.0, 0.0)
            self._max_goal_height: float = 0.3
            # Attributes that ``_initialize_episode`` / ``_before_simulation_step``
            # touch MUST be assigned before ``super().__init__()``: ManiSkill's
            # ``BaseEnv.__init__`` calls ``self.reset(...)`` during super-init
            # (mani_skill/envs/sapien_env.py:327), which invokes
            # ``_initialize_episode`` *and* the post-reset qpos primer below
            # before the subclass body resumes. Subclass attributes written
            # after super-init do not yet exist when those hooks fire.
            self._panda_arm_dof: int = PANDA_ARM_DOF
            # Per-uid cache for the numerical-difference velocity in
            # build_agent_snapshots (D8 of the P1.04.5 design pass).
            # Cleared by _initialize_episode at every reset so the
            # cross-episode position delta doesn't produce a spurious
            # first-step velocity. The first-step velocity defaults to
            # zero on each fresh episode (the agents start at rest by
            # construction).
            self._prev_positions: dict[str, NDArray[np.float64]] = {}
            try:
                super().__init__(
                    robot_uids=self._condition_config.agent_uids,  # type: ignore[arg-type]
                    num_envs=num_envs,
                    obs_mode=self._condition_config.obs_mode,
                    control_mode="pd_joint_delta_pos",
                    render_mode=render_mode,
                    render_backend=render_backend if render_backend is not None else "gpu",
                )
            except RuntimeError as exc:
                raise ChamberEnvCompatibilityError(
                    "SAPIEN/Vulkan initialisation failed during "
                    f"Stage1PickPlaceEnv(condition_id={condition_id!r}) build: "
                    f"{exc}\nSet CHAMBER_RENDER_BACKEND=none (or "
                    'render_backend="none") on CUDA-only hosts; see ADR-001 §Risks.'
                ) from exc
            # Jacobian provider is wristcam-URDF based; the partner
            # (panda_partner) shares the kinematic chain so a single
            # provider serves both panda uids. ``panda_v2.urdf`` and
            # ``panda_v3.urdf`` differ only in the wristcam mount
            # (extrinsic frame); the 7 arm joints + TCP link are
            # identical, so reusing the v3-URDF chain for the partner
            # introduces no error in the linear Jacobian.
            self._jacobian_provider: PandaJacobianProvider = PandaJacobianProvider()
            # Per-uid safety radii (Q3 of the P1.04.5 design pass).
            # Asserted at construction against URDF-envelope minimums.
            self._safety_radii: dict[str, float] = {
                uid: PANDA_SAFETY_RADIUS_M
                if uid in ("panda_wristcam", "panda_partner")
                else FETCH_SAFETY_RADIUS_M
                for uid in self._condition_config.agent_uids
            }
            _validate_safety_radii(self._safety_radii)

        # ----- ManiSkill v3 BaseEnv hooks -----

        @property
        def _default_human_render_camera_configs(self) -> Any:  # noqa: ANN401 - ManiSkill CameraConfig has no project type
            """Third-person render camera for rollout visualisation (ADR-007 §Stage 1b).

            The Stage-1b env subclasses :class:`BaseEnv` directly and
            otherwise defines no human-render camera, so ``env.render()``
            returns ``None`` and a saved checkpoint cannot be visualised.
            This adds a single fixed third-person camera looking at the
            table workspace so a checkpoint can be rolled out and rendered
            to RGB frames (reach / grasp / lift inspection). Render-only:
            it feeds neither any observation channel nor the gate contract,
            so it does not affect determinism or the comparison protocol.
            """
            from mani_skill.sensors.camera import CameraConfig
            from mani_skill.utils import sapien_utils

            pose = sapien_utils.look_at(eye=[0.7, 0.7, 0.6], target=[0.0, 0.0, 0.1])
            return CameraConfig(
                "render_camera",
                pose=pose,
                width=640,
                height=480,
                fov=1.0,
                near=0.01,
                far=100.0,
            )

        def _load_agent(  # type: ignore[override]
            self,
            options: dict[str, Any],
            initial_agent_poses: object = None,
            build_separate: bool = False,
        ) -> None:
            """Multi-robot ``_load_agent`` override with per-uid base poses.

            Delegates to
            :func:`chamber.envs._sapien_compat.load_agent_with_bare_uids`
            for the suffix-strip rebind. Passes an explicit per-agent
            pose list so the two robots don't collide at the table
            origin.
            """
            if initial_agent_poses is None:
                poses: list[object] = []
                for uid in self.robot_uids:  # type: ignore[union-attr]
                    xyz = _AGENT_BASE_POSE_XYZ.get(uid)
                    if xyz is None:
                        # Unknown uid (shouldn't happen given the
                        # condition table) — leave SAPIEN to use URDF
                        # default root pose.
                        poses.append(None)
                    else:
                        poses.append(sapien.Pose(p=list(xyz)))
                initial_agent_poses = poses
            load_agent_with_bare_uids(
                self,
                options,
                initial_agent_poses=initial_agent_poses,
                build_separate=build_separate,
            )

        def _load_scene(self, options: dict[str, Any]) -> None:
            """Build the table + cube + goal site (PickCubeEnv recipe; ADR-007 §Stage 1b)."""
            del options
            # NOTE: ``robot_init_qpos_noise`` is INERT for the AS robot_uids tuples —
            # TableSceneBuilder.initialize() has no branch for them, so it never
            # applies the noise (nor sets any robot qpos). The canonical reset pose
            # is written deterministically in _initialize_episode (ADR-007 Rev 16);
            # do NOT "restore parity" by re-adding init noise via torch.rand — route
            # any future perturbation through self._rng (P6 / ADR-002).
            self.table_scene = TableSceneBuilder(self, robot_init_qpos_noise=0.02)
            self.table_scene.build()
            self.cube = actors.build_cube(
                self.scene,
                half_size=self._cube_half_size,
                color=[1, 0, 0, 1],
                name="cube",
                initial_pose=sapien.Pose(p=[0, 0, self._cube_half_size]),
            )
            self.goal_site = actors.build_sphere(
                self.scene,
                radius=self._goal_thresh,
                color=[0, 1, 0, 1],
                name="goal_site",
                body_type="kinematic",
                add_collision=False,
                initial_pose=sapien.Pose(),
            )
            self._hidden_objects.append(self.goal_site)  # type: ignore[attr-defined]

        def _initialize_episode(self, env_idx: torch.Tensor, options: dict[str, Any]) -> None:
            """Reset cube + goal poses per episode (P6 determinism via :attr:`_rng`)."""
            del options
            # Clear the per-agent position cache so build_agent_snapshots'
            # first-step velocity (numerical-difference) defaults to
            # zero on each fresh episode rather than diffing against
            # the previous episode's final position (R2 of the P1.04.5
            # risk register).
            self._prev_positions.clear()
            with torch.device(self.device):  # type: ignore[attr-defined]
                b = len(env_idx)
                self.table_scene.initialize(env_idx)
                # Reset-state init (ADR-007 §Stage 1b Rev 16). The upstream
                # TableSceneBuilder has no branch for the AS robot_uids tuples
                # and no terminal else, so it never set these robots' qpos —
                # every episode otherwise started with the arm folded at zero and
                # the gripper closed. Set each agent's canonical ready pose +
                # open gripper here, mirroring the builder's covered branches.
                # Deterministic (no init noise) so two reset(seed=K) calls stay
                # byte-identical on CPU (P6 / ADR-002); a noise term, if added
                # later, MUST draw from self._rng (not torch.rand, not the
                # builder's _episode_rng). Base poses are owned by _load_agent.
                for uid in self.robot_uids:  # type: ignore[union-attr]
                    ready = _READY_QPOS_BY_UID.get(uid)
                    if ready is None:
                        continue
                    qpos = torch.from_numpy(np.tile(ready, (b, 1)).astype(np.float32)).to(
                        self.device
                    )
                    self.agent.agents_dict[uid].reset(qpos)  # type: ignore[attr-defined]
                # Cube xy uniform in the spawn box; z at half-size so it
                # rests on the table surface. Routed through the env's
                # P6-harnessed RNG instead of torch.rand so two
                # reset(seed=K) calls reproduce byte-identical state
                # (P6 / ADR-002 determinism rule). Vectorised builds
                # (P1.05.10) draw each resetting env's cube/goal from its
                # own per-env-index substream (see __init__) so partial-
                # reset interleaving cannot perturb another env's stream.
                env_indices: list[int] = (
                    [int(i) for i in env_idx.detach().cpu().tolist()] if self._env_rngs else []
                )
                if self._env_rngs:
                    xy_cube_np = np.stack(
                        [
                            self._env_rngs[i].uniform(
                                -self._cube_spawn_half_size, self._cube_spawn_half_size, size=2
                            )
                            for i in env_indices
                        ]
                    )
                else:
                    xy_cube_np = self._rng.uniform(
                        -self._cube_spawn_half_size, self._cube_spawn_half_size, size=(b, 2)
                    )
                # .to(self.device): from_numpy tensors are CPU-resident;
                # GPU-parallel builds (P1.05.10) run the scene on cuda and
                # mixed-device arithmetic below would raise. No-op on CPU sim.
                xy_cube = torch.from_numpy(np.asarray(xy_cube_np, dtype=np.float32)).to(self.device)
                xyz = torch.zeros((b, 3))
                xyz[:, 0] = xy_cube[:, 0] + self._cube_spawn_center[0]
                xyz[:, 1] = xy_cube[:, 1] + self._cube_spawn_center[1]
                xyz[:, 2] = self._cube_half_size
                # No rotation randomisation in P1.03 — upstream PickCubeEnv
                # uses ``randomization.random_quaternions(b, lock_x=True,
                # lock_y=True)``; for the two-robot env the orientation
                # matters less than the position. Re-enable if pilot data
                # shows it changes the AS gap.
                self.cube.set_pose(Pose.create_from_pq(xyz))

                # Goal xy in the same envelope; z uniform in [0, max].
                if self._env_rngs:
                    xy_goal_np = np.stack(
                        [
                            self._env_rngs[i].uniform(
                                -self._cube_spawn_half_size, self._cube_spawn_half_size, size=2
                            )
                            for i in env_indices
                        ]
                    )
                    z_goal_np = np.stack(
                        [self._env_rngs[i].uniform(0.0, self._max_goal_height) for i in env_indices]
                    )
                else:
                    xy_goal_np = self._rng.uniform(
                        -self._cube_spawn_half_size, self._cube_spawn_half_size, size=(b, 2)
                    )
                    z_goal_np = self._rng.uniform(0.0, self._max_goal_height, size=(b,))
                xy_goal = torch.from_numpy(np.asarray(xy_goal_np, dtype=np.float32)).to(self.device)
                z_goal = torch.from_numpy(np.asarray(z_goal_np, dtype=np.float32)).to(self.device)
                goal_xyz = torch.zeros((b, 3))
                goal_xyz[:, 0] = xy_goal[:, 0] + self._cube_spawn_center[0]
                goal_xyz[:, 1] = xy_goal[:, 1] + self._cube_spawn_center[1]
                goal_xyz[:, 2] = z_goal + xyz[:, 2]
                self.goal_site.set_pose(Pose.create_from_pq(goal_xyz))
            # Prime the qpos cache so the Jacobian closure has a valid
            # value at the first safety-filter call. The training loop
            # in ``concerto.training.ego_aht.train`` queries the filter
            # *before* the first ``env.step()`` (act-then-step order),
            # so the per-physics-step ``_before_simulation_step`` hook
            # has not yet fired after a reset. Without this primer the
            # closure raises the "qpos not yet cached" guard.
            self._refresh_latest_qpos()

        def step(self, action: Any) -> tuple[Any, Any, Any, Any, dict[str, Any]]:  # type: ignore[override]  # noqa: ANN401 - ManiSkill action/obs/info are unconstrained dict-of-tensors
            """Enforce the ``episode_length`` time-limit truncation (ADR-007 §Stage 1b).

            ManiSkill v3's :meth:`BaseEnv.step` hard-codes ``truncated=False``
            (``mani_skill/envs/sapien_env.py`` L1069): time-limit truncation is
            normally supplied by the gym ``TimeLimit`` wrapper that ``gym.make``
            adds, which a *directly*-instantiated ``BaseEnv`` subclass does not
            have. Without this override the env never emits ``truncated=True``,
            so the training loop (:func:`concerto.training.ego_aht.train`, which
            resets only on ``terminated | truncated``) never re-initialises an
            episode — the cube/goal are sampled once and the GAE sees a
            non-terminating MDP whose critic converges to the infinite-horizon
            value ``r/(1-gamma)`` with collapsed advantages (root cause
            ENV-NO-TRUNCATION; firing ``2026-05-24-p1-05-9``). We truncate when
            ``BaseEnv``'s own ``elapsed_steps`` property (its step counter,
            incremented in ``super().step`` and reset per episode at
            ``sapien_env.py`` L927) reaches ``episode_length`` — read through
            the public property rather than the underlying ``_elapsed_steps``
            attribute (ADR-001 wrapper-only). This is the ``BaseEnv``-subclass
            analogue of
            the ``_step_count >= _episode_length`` time-limit the sibling envs
            (:mod:`chamber.envs.mpe_cooperative_push`,
            :mod:`chamber.benchmarks.stage0_smoke_adapter`) apply. Reward-,
            obs-, and render-neutral: only the ``truncated`` flag changes, so
            the comparison protocol and determinism contract are untouched
            beyond the (intended) per-episode reset cadence.
            """
            obs, reward, terminated, truncated, info = super().step(action)
            truncated = truncated | (self.elapsed_steps >= self._episode_length)
            return obs, reward, terminated, truncated, info

        # ----- Observation / reward / success (panda-routed; ADR-007 §Stage 1b) -----

        @property
        def _panda_agent(self) -> Any:  # noqa: ANN401 - ManiSkill Panda agent has no project type
            """Return the panda_wristcam :class:`Panda` agent instance (ego).

            Routes through ``self.agent.agents_dict`` instead of the
            single-agent ``self.agent`` attribute upstream PickCubeEnv
            relies on. Used by :meth:`evaluate` and
            :meth:`compute_normalized_dense_reward` so the success
            predicates and reward shaping respect the multi-agent rig.
            """
            return self.agent.agents_dict["panda_wristcam"]  # type: ignore[attr-defined, no-any-return]

        def _get_obs_extra(self, info: dict[str, Any]) -> dict[str, Any]:
            """Inject task obs + synthesised force-torque (ADR-007 §Stage 1b).

            Extras include:

            - ``tcp_pose`` — panda end-effector pose (mirrors upstream
              PickCubeEnv).
            - ``goal_pos`` — the goal site's xyz position.
            - ``cube_pose`` / ``cube_to_tcp_pos`` / ``cube_to_goal_pos``
              — present only when ``"state"`` is in the env's
              ``obs_mode`` (matches upstream PickCubeEnv's branch).
            - **``force_torque`` (this env's contribution)** — a 6-D
              Cartesian force vector per panda fingertip
              (``[fx_l, fy_l, fz_l, fx_r, fy_r, fz_r]``), synthesised
              from
              :meth:`PhysxArticulation.get_net_contact_forces([finger_links])`
              plus zero-mean sigma=:data:`SYNTHESISED_FT_NOISE_SIGMA_N`
              Gaussian noise routed through the env's P6-harnessed RNG.
              **Not** a real Panda wrist FT sensor reading; see module
              docstring and ADR-007 §Open questions for the wrist-mount
              ablation deferral.
            """
            del info
            panda = self._panda_agent
            obs: dict[str, Any] = {
                "tcp_pose": panda.tcp_pose.raw_pose,
                "goal_pos": self.goal_site.pose.p,
            }
            if "state" in self.obs_mode:  # type: ignore[operator]
                obs["cube_pose"] = self.cube.pose.raw_pose
                obs["cube_to_tcp_pos"] = self.cube.pose.p - panda.tcp_pose.p
                obs["cube_to_goal_pos"] = self.goal_site.pose.p - self.cube.pose.p
            # Synthesised FT: always injected so the OM channel-filter
            # wrapper has something to keep/zero per condition. The
            # AS conditions' state_dict obs_mode ignores it downstream.
            obs["force_torque"] = self._compute_synthesised_force_torque()
            return obs

        def _compute_synthesised_force_torque(self) -> NDArray[np.float32]:
            """Synthesise the 6-D fingertip-contact FT vector (ADR-007 §Stage 1b)."""
            panda = self._panda_agent
            fingers = ["panda_leftfinger", "panda_rightfinger"]
            try:
                # ``get_net_contact_forces`` returns shape ``(N_envs, n_links, 3)``
                # (Cartesian force per link) at SAPIEN's contact-manager
                # boundary (mani_skill/utils/structs/articulation.py:490).
                forces = panda.robot.get_net_contact_forces(fingers)
            except (RuntimeError, KeyError):
                # Finger links not yet registered (pre-reset state) —
                # return zeros so the wrapper-chain shape stays stable.
                return np.zeros((1, 6), dtype=np.float32)
            f_np = np.asarray(forces.detach().cpu(), dtype=np.float32)  # type: ignore[union-attr]
            # Flatten the per-link Cartesian force into a 6-D vector;
            # add zero-mean Gaussian noise from the P6-harnessed RNG so
            # the OM-hetero gate's signal-to-noise lands at the
            # documented Franka-spec lower bound.
            flat = f_np.reshape(f_np.shape[0], -1)  # (N_envs, 6)
            if self._force_torque_noise_sigma > 0.0:
                noise = self._rng.normal(
                    loc=0.0,
                    scale=self._force_torque_noise_sigma,
                    size=flat.shape,
                ).astype(np.float32)
                flat = flat + noise
            return flat

        def evaluate(self) -> dict[str, Any]:
            """ADR-007 §Stage 1b: multi-agent success predicate (panda-routed)."""
            panda = self._panda_agent
            is_obj_placed = (
                torch.linalg.norm(self.goal_site.pose.p - self.cube.pose.p, axis=1)
                <= self._goal_thresh
            )
            is_grasped = panda.is_grasping(self.cube)
            is_robot_static = panda.is_static(0.2)
            return {
                "success": is_obj_placed & is_robot_static,
                "is_obj_placed": is_obj_placed,
                "is_robot_static": is_robot_static,
                "is_grasped": is_grasped,
            }

        def privileged_settle_state(self) -> dict[str, Any]:
            """Privileged Phi inputs for the settle wrapper (ADR-007 §Stage 1b Rev 18; #232).

            Training-time reward computation is privileged by
            construction: these reads come from the same live handles
            :meth:`compute_normalized_dense_reward` and :meth:`evaluate`
            already use, never from the (possibly condition-filtered)
            observation — the OM vision-only keep-set zero-masks
            ``cube_pose`` and the per-uid proprio, so an obs-derived
            potential would differ between the two OM conditions and
            violate the Rev 18 condition-symmetry mandate.

            Returns:
                ``ego_qvel`` — the ego panda's full joint velocity
                (``(num_envs, 9)``; the wrapper applies the arm-only
                reduction), ``cube_pos`` / ``goal_pos`` — xyz positions
                (``(num_envs, 3)``), all live torch tensors.
            """
            return {
                "ego_qvel": self._panda_agent.robot.get_qvel(),
                "cube_pos": self.cube.pose.p,
                "goal_pos": self.goal_site.pose.p,
            }

        def compute_normalized_dense_reward(
            self,
            obs: Any,  # noqa: ANN401 - ManiSkill obs is an unconstrained dict-of-tensors
            action: Any,  # noqa: ANN401 - ManiSkill action is an unconstrained dict-of-tensors
            info: dict[str, Any],
        ) -> Any:  # noqa: ANN401 - upstream returns torch tensor, no project type
            """ADR-007 §Stage 1b: multi-agent normalised dense reward (panda-routed).

            Matches the upstream ``PickCubeEnv.compute_dense_reward`` shape
            (reaching + grasp + place * grasp + static * placed + 5*success)
            divided by 5. The reward signal is panda-centric (the panda
            does the picking); the fetch / partner is graded implicitly
            through whether it gets out of the way / cooperates on
            placement — explicit fetch-side reward shaping is a P1.04
            follow-up.
            """
            del obs, action
            panda = self._panda_agent
            tcp_to_obj_dist = torch.linalg.norm(self.cube.pose.p - panda.tcp_pose.p, axis=1)
            reaching_reward = 1 - torch.tanh(5 * tcp_to_obj_dist)
            reward = reaching_reward
            is_grasped = info["is_grasped"]
            reward = reward + is_grasped
            obj_to_goal_dist = torch.linalg.norm(self.goal_site.pose.p - self.cube.pose.p, axis=1)
            place_reward = 1 - torch.tanh(5 * obj_to_goal_dist)
            reward = reward + place_reward * is_grasped
            qvel = panda.robot.get_qvel()
            qvel = qvel[..., :-2]  # drop the two gripper-finger DOF
            static_reward = 1 - torch.tanh(5 * torch.linalg.norm(qvel, axis=1))
            reward = reward + static_reward * info["is_obj_placed"]
            reward[info["success"]] = 5
            return reward / 5

        # ----- Per-step qpos refresh (Jacobian closure feed) -----

        def _refresh_latest_qpos(self) -> None:
            """Snapshot every panda uid's arm qpos into :attr:`_latest_qpos`.

            P1.04.5; ADR-007 §Stage 1b. Called from both
            :meth:`_before_simulation_step` (each physics step) and
            :meth:`_initialize_episode` (post-reset primer). The latter
            primes the cache between ``env.reset()`` and the first
            ``env.step()`` so the safety filter — which the training
            loop runs *before* the first step — can read a valid qpos
            without raising the "qpos not yet cached" guard.
            """
            for uid in self.robot_uids:  # type: ignore[union-attr]
                if uid in ("panda_wristcam", "panda_partner"):
                    agent = self.agent.agents_dict[uid]  # type: ignore[attr-defined]
                    full_qpos = agent.robot.get_qpos()
                    # Slice off the 2 gripper-finger joints; the
                    # Jacobian chain to panda_hand_tcp covers the 7 arm
                    # joints only.
                    qpos_arm = np.asarray(
                        full_qpos.detach().cpu(),
                        dtype=np.float64,  # type: ignore[union-attr]
                    ).reshape(-1)[: self._panda_arm_dof]
                    self._latest_qpos[uid] = qpos_arm

        def _before_simulation_step(self) -> None:
            """Cache panda arm qpos before each physics step (Jacobian closure feed).

            The :class:`JacobianControlModel` callable wired by
            :meth:`build_control_models` reads
            ``self._latest_qpos["panda_wristcam"]`` to compute the
            Jacobian at the current configuration. ManiSkill's
            :class:`BaseEnv` calls this hook once per physics step
            before SAPIEN advances; updating the cache here gives the
            closure access to the most recent qpos at the next safety-
            filter invocation. See module docstring on the closure-
            via-env-reference workaround (P1.05.5 contingent
            follow-up).
            """
            super()._before_simulation_step()
            self._refresh_latest_qpos()

        # ----- Public API for the safety-stack consumer -----

        @property
        def condition_id(self) -> str:
            """ADR-007 §Stage 1b: the :attr:`ConditionConfig.condition_id` this env was built for."""  # noqa: E501
            return self._condition_config.condition_id

        @property
        def condition_config(self) -> ConditionConfig:
            """The resolved :class:`ConditionConfig` for read-only consumers (ADR-007 §Stage 1b)."""
            return self._condition_config

        @property
        def num_envs_requested(self) -> int:
            """ADR-007 §Stage 1b regime-alignment: the ``num_envs`` this env was built with.

            Exposed so the vector auto-reset wrapper
            (:class:`chamber.envs.stage1_vector.Stage1AutoResetWrapper`)
            and the Tier-2 tests can read the requested parallelisation
            count without reaching for ManiSkill's internal attribute.
            """
            return self._num_envs_requested

        @property
        def ego_uid(self) -> str:
            """ADR-007 §Stage 1b: the ego uid for the active condition.

            First element of :attr:`ConditionConfig.agent_uids` by the
            Phase-0 ``_CONDITION_UIDS`` convention. Consumed by the
            Phase-1 :class:`chamber.benchmarks.stage1_common.TrainedPolicyFactory`
            (P1.04) so the factory can read the ego uid from the env
            rather than from a side-table — single source of truth at
            the env layer.
            """
            return self._condition_config.agent_uids[0]

        @property
        def partner_uid(self) -> str:
            """ADR-007 §Stage 1b: the partner uid for the active condition.

            Second element of :attr:`ConditionConfig.agent_uids` (the
            ego is the first; the partner is the second by the Phase-0
            ``_CONDITION_UIDS`` convention from
            :mod:`chamber.benchmarks.stage1_as` /
            :mod:`chamber.benchmarks.stage1_om`). Consumed by the
            Phase-1 :class:`chamber.benchmarks.stage1_common.TrainedPolicyFactory`
            (P1.04) to route the per-condition partner-stack dispatch
            (``panda_partner`` for AS-homo; ``fetch`` for AS-hetero /
            OM-*). Single source of truth at the env layer — future
            Stage-2/3 envs (P1.06+) follow the same property contract
            without needing a factory-side dispatch table.
            """
            return self._condition_config.agent_uids[1]

        def build_control_models(self) -> Mapping[str, AgentControlModel]:
            """Return per-uid :class:`AgentControlModel` map (ADR-004 §Decision).

            Plumbed in by
            :func:`chamber.benchmarks.training_runner.build_control_models`
            via the ``getattr(env, "build_control_models", None)``
            delegation route (P1.03 / Task B).

            The Jacobian callable is the closure-via-env-reference
            workaround documented in the module docstring: it captures
            ``self`` and reads ``self._latest_qpos["panda_wristcam"]``
            at call time. The closure stays valid across the 20
            evaluation episodes within each ``(seed, condition)`` cell
            because
            :func:`chamber.benchmarks.stage1_as._run_axis_with_factories`
            builds the env once per cell and reuses it
            (``stage1_as.py:253-275``).

            For the AS-homo condition both panda uids share the same
            Jacobian provider (their kinematic chains are identical;
            see :class:`chamber.agents.panda_jacobian.PandaJacobianProvider`'s
            choice of URDF). The closure resolves to the correct uid's
            latest qpos at call time.
            """
            # Source the panda action dim from the action space (same
            # path the fetch dim is sourced from below). Falls back to
            # 8 — the ``pd_joint_delta_pos`` default (7 arm + 1 mimic-
            # gripper). The closure captures this value once at
            # build-time, which is correct: action-space shape is fixed
            # over an env's lifetime.
            panda_action_dim = 8
            action_space = self.action_space
            if isinstance(action_space, gym.spaces.Dict):
                sub_panda = action_space.spaces.get("panda_wristcam")
                if isinstance(sub_panda, gym.spaces.Box) and sub_panda.shape is not None:
                    panda_action_dim = int(sub_panda.shape[0])

            def _panda_jacobian(snap: AgentSnapshot) -> NDArray[np.float64]:
                # Pull the live qpos from the env's cache; the closure
                # captures self by reference so the latest pre-step
                # value is always used.
                qpos = self._latest_qpos.get("panda_wristcam")
                if qpos is None:
                    msg = (
                        "Stage1PickPlaceEnv: panda_wristcam qpos not yet cached. "
                        "The JacobianControlModel closure was invoked before "
                        "the first env.step() — reset the env first."
                    )
                    raise RuntimeError(msg)
                # PandaJacobianProvider returns the linear (3, 7) Jacobian
                # for the 7-joint chain to ``panda_hand_tcp``. The
                # ``pd_joint_delta_pos`` control mode's panda action is
                # 8-D (7 arm deltas + 1 mimic-gripper delta — see the
                # ``panda_action_dim=8`` default in
                # :func:`build_control_models_for_condition`). Pad with
                # a zero column so the JacobianControlModel matmul
                # ``jac @ action`` composes: the mimic-gripper joint is
                # a sibling of ``panda_hand``, not in the TCP kinematic
                # chain, so its contribution to TCP Cartesian position
                # is zero by construction.
                jac_3x7 = self._jacobian_provider(snap, qpos)
                jac_padded = np.zeros((CARTESIAN_POSITION_DIM, panda_action_dim), dtype=np.float64)
                jac_padded[:, : self._panda_arm_dof] = jac_3x7
                return jac_padded

            fetch_uid_dim: int | None = None
            partner_uid = self._condition_config.agent_uids[1]
            if partner_uid == "fetch" and isinstance(action_space, gym.spaces.Dict):
                sub = action_space.spaces.get(partner_uid)
                if isinstance(sub, gym.spaces.Box) and sub.shape is not None:
                    fetch_uid_dim = int(sub.shape[0])
            return build_control_models_for_condition(
                self._condition_config.condition_id,
                jacobian_fn=_panda_jacobian,
                fetch_action_dim=fetch_uid_dim,
                panda_action_dim=panda_action_dim,
            )

        # ----- P1.04.5: safety-stack snapshot + bounds wiring -----

        def build_agent_snapshots(self) -> dict[str, AgentSnapshot]:
            """Build per-uid Cartesian :class:`AgentSnapshot` map (P1.04.5; ADR-007 §Stage 1b).

            Reads each agent's Cartesian position (TCP pose for the
            pandas; base-link pose for the fetch) and computes velocity
            via numerical-difference against the cached
            :attr:`_prev_positions` from the previous step. First-step
            velocity defaults to zero on every fresh episode (the
            agents start at rest by construction; the cache is cleared
            in :meth:`_initialize_episode`).

            Used by the P1.04.5 safety-stack integration: the
            :func:`concerto.training.ego_aht.train` loop calls this
            once per step (when the safety filter is wired) to build
            the snapshot map the CBF-QP outer filter consumes via the
            ``partner_predicted_states`` kwarg + the conformal update's
            ``snaps_now`` / ``snaps_prev`` pair.

            Returns:
                ``{uid: AgentSnapshot(position, velocity, radius)}`` for
                every uid in :attr:`ConditionConfig.agent_uids`. Position
                is the 3-D Cartesian centre (panda TCP for the pandas;
                fetch base origin for the fetch); velocity is the
                numerical-difference against the previous call (zero on
                first call after :meth:`_initialize_episode`); radius
                is from :data:`PANDA_SAFETY_RADIUS_M` /
                :data:`FETCH_SAFETY_RADIUS_M` (validated at env
                construction by :func:`_validate_safety_radii`).
            """
            # P1.05.10 (ADR-007 §Stage 1b regime-alignment): the snapshot
            # map is a per-pair scalar contract (AgentSnapshot is one 3-D
            # Cartesian body per uid) consumed by the un-batched CBF-QP /
            # conformal / braking stack. Vectorised builds have no batched
            # safety stack in this slice — ``train()`` loud-fails when
            # ``num_envs > 1`` and ``cfg.safety.enabled=True`` — so a
            # multi-env call here is always a wiring bug. Raise rather
            # than silently slicing env 0 (the pre-P1.05.10 defensive
            # slice would have mis-reported env 0's geometry as the
            # whole cell's).
            if self._num_envs_requested > 1:
                msg = (
                    "Stage1PickPlaceEnv.build_agent_snapshots: not supported at "
                    f"num_envs={self._num_envs_requested} — the safety-stack "
                    "snapshot contract is single-env (ADR-004 §Decision; "
                    "ADR-007 §Stage 1b regime-alignment revision). Run "
                    "vectorised training with safety.enabled=false (operator "
                    "override), or build a num_envs=1 cell for filtered runs."
                )
                raise RuntimeError(msg)
            snapshots: dict[str, AgentSnapshot] = {}
            for uid in self._condition_config.agent_uids:
                agent = self.agent.agents_dict[uid]  # type: ignore[attr-defined]
                if uid in ("panda_wristcam", "panda_partner"):
                    # Panda: TCP pose. Squeeze the (num_envs=1, 3)
                    # batch dim to a flat 3-vector for the AgentSnapshot.
                    pos_raw = agent.tcp_pose.p
                else:
                    # Fetch: base-link pose (the robot's root pose).
                    pos_raw = agent.robot.get_pose().p
                position = np.asarray(
                    pos_raw.detach().cpu(),
                    dtype=np.float64,  # type: ignore[union-attr]
                ).reshape(-1)
                _cartesian_dim = 3  # ADR-004 §Decision: AgentSnapshot is 3-D Cartesian.
                if position.shape[0] > _cartesian_dim:
                    position = position[:_cartesian_dim]
                prev = self._prev_positions.get(uid)
                if prev is None:
                    velocity = np.zeros(3, dtype=np.float64)
                else:
                    # Numerical-difference velocity. The dt is the
                    # control_timestep; for the AgentSnapshot's contract
                    # this is the per-step Cartesian velocity. The
                    # safety filter's conformal update consumes this
                    # value alongside dt to compute the predicted
                    # pose; the consistency is the caller's
                    # responsibility (see
                    # chamber.benchmarks.training_runner.build_safety_dt).
                    velocity = (position - prev) / float(self.control_timestep)
                self._prev_positions[uid] = position
                snapshots[uid] = AgentSnapshot(
                    position=position,
                    velocity=velocity,
                    radius=self._safety_radii[uid],
                )
            return snapshots

        def build_bounds(self) -> Bounds:
            """Build the per-task :class:`Bounds` envelope (P1.04.5; ADR-006 §Decision).

            Sourced from the module-level constants pinned in P1.03
            (cartesian_accel_capacity) plus sensible Phase-1 defaults
            for the remaining fields. Consumed by the safety filter +
            the audit-gate predicate A's RHS (``cartesian_accel_capacity``).
            """
            return Bounds(
                action_linf_component=0.1,
                cartesian_accel_capacity=PANDA_CARTESIAN_ACCEL_CAPACITY_MS2,
                action_rate=10.0,
                comm_latency_ms=0.0,
                force_limit=50.0,
            )

    inner = Stage1PickPlaceEnv(
        condition_id=condition_id,
        episode_length=episode_length,
        root_seed=root_seed,
        num_envs=num_envs,
        render_mode=render_mode,
        render_backend=render_backend,
        force_torque_noise_sigma=force_torque_noise_sigma,
    )
    # AS conditions: ManiSkill v3 obs_mode="state_dict" emits per-agent
    # Dict(qpos, qvel) but EgoPPOTrainer.from_config reads
    # obs["agent"][ego_uid]["state"]. The AS synthesizer adds that key;
    # pass-through for OM conditions. The OM channel filter then masks
    # per-condition for OM-vision-only; pass-through for AS and OM-hetero.
    # Wired in fixed order so OM callers of the factory don't have to
    # wrap manually (issue #165 §Proposed scope 4).
    from chamber.envs.stage1_obs_filter import (
        Stage1ASStateSynthesizer,
        Stage1OMChannelFilter,
    )

    wrapped: gym.Env[Any, Any] = Stage1OMChannelFilter(Stage1ASStateSynthesizer(inner))
    if num_envs > 1:
        # P1.05.10 (ADR-007 §Stage 1b regime-alignment): vectorised
        # builds get the chamber-side auto-reset wrapper outermost so
        # the training loop sees standard vector semantics (per-env
        # partial reset on done; pre-reset final obs surfaced via
        # ``info["final_observation"]`` for the Pardo truncation
        # bootstrap). Single-env builds keep the historical
        # reset-from-the-loop contract byte-identically (ADR-002).
        from chamber.envs.stage1_vector import Stage1AutoResetWrapper

        wrapped = Stage1AutoResetWrapper(wrapped)
    return wrapped

resolve_condition

resolve_condition(condition_id: str) -> ConditionConfig

Resolve a pre-registered condition_id to its config (ADR-007 §Stage 1b).

Pure Tier-1 function — no SAPIEN dependency. Tier-1 tests pin the four-condition coverage and the ValueError raise on bogus IDs.

Parameters:

• condition_id (str) –

  One of the four verbatim Stage-1 pre-registration strings (see spikes/preregistration/{AS,OM}.yaml).

Returns:

• Resolved ( ConditionConfig ) –

  class:ConditionConfig carrying the

• ConditionConfig –

  agent_uids tuple, env-level obs_mode superset, and the

• ConditionConfig –

  boolean flags downstream wrappers / scripts read.

Raises:

• ValueError –

  If condition_id is not one of the four Stage-1 pre-registration strings. The message names the four valid options and cites ADR-007 §Discipline (the project anti-pattern for editing prereg YAMLs).

Source code in src/chamber/envs/stage1_pickplace.py

def resolve_condition(condition_id: str) -> ConditionConfig:
    """Resolve a pre-registered ``condition_id`` to its config (ADR-007 §Stage 1b).

    Pure Tier-1 function — no SAPIEN dependency. Tier-1 tests pin the
    four-condition coverage and the ``ValueError`` raise on bogus IDs.

    Args:
        condition_id: One of the four verbatim Stage-1 pre-registration
            strings (see ``spikes/preregistration/{AS,OM}.yaml``).

    Returns:
        Resolved :class:`ConditionConfig` carrying the
        ``agent_uids`` tuple, env-level ``obs_mode`` superset, and the
        boolean flags downstream wrappers / scripts read.

    Raises:
        ValueError: If ``condition_id`` is not one of the four
            Stage-1 pre-registration strings. The message names the
            four valid options and cites ADR-007 §Discipline (the
            project anti-pattern for editing prereg YAMLs).
    """
    try:
        return _CONDITION_TABLE[condition_id]
    except KeyError as exc:
        msg = (
            f"Stage1PickPlaceEnv: condition_id {condition_id!r} is not one of the "
            f"four Stage-1 pre-registration strings {sorted(_CONDITION_TABLE)!r}. "
            "If the prereg YAML has been edited, re-issue with a new git_tag "
            "per ADR-007 §Discipline; do not rename condition_ids in code."
        )
        raise ValueError(msg) from exc

Per-agent action-repeat wrapper.

ADR-001 §Decision item 2; ADR-007 Stage 2 CR axis (rev 3 §Stage 2).

PerAgentActionRepeatWrapper

Bases: Wrapper

Apply different action-repeat counts per agent uid.

Effective control frequency for agent a is::

base_freq / action_repeat[a]

At each env.step call, an agent whose repeat counter has not elapsed re-applies its most recent action instead of the newly submitted one.

ADR-001 §Decision item 2; ADR-007 Stage 2 CR axis (rev 3 §Stage 2).

Parameters:

• env (Env) –

  Env exposing a gym.spaces.Dict action space keyed by agent uid.

• action_repeat (Mapping[str, int]) –

  Mapping from agent uid to a positive integer repeat count. Keys absent from this mapping default to repeat=1 (pass-through).

Raises:

• ChamberEnvCompatibilityError –

  if the action space is not a gym.spaces.Dict keyed by agent uid (ADR-001 §Risks).

• ValueError –

  if any repeat count is less than 1.

Source code in src/chamber/envs/action_repeat.py

class PerAgentActionRepeatWrapper(gym.Wrapper):  # type: ignore[type-arg]
    """Apply different action-repeat counts per agent uid.

    Effective control frequency for agent ``a`` is::

        base_freq / action_repeat[a]

    At each ``env.step`` call, an agent whose repeat counter has not elapsed
    re-applies its most recent action instead of the newly submitted one.

    ADR-001 §Decision item 2; ADR-007 Stage 2 CR axis (rev 3 §Stage 2).

    Args:
        env: Env exposing a ``gym.spaces.Dict`` action space keyed by agent uid.
        action_repeat: Mapping from agent uid to a positive integer repeat count.
            Keys absent from this mapping default to repeat=1 (pass-through).

    Raises:
        ChamberEnvCompatibilityError: if the action space is not a
            ``gym.spaces.Dict`` keyed by agent uid (ADR-001 §Risks).
        ValueError: if any repeat count is less than 1.
    """

    def __init__(self, env: gym.Env, action_repeat: Mapping[str, int]) -> None:  # type: ignore[type-arg]
        """Validate the action space and store per-agent repeat counts."""
        super().__init__(env)
        if not isinstance(env.action_space, gym.spaces.Dict):
            raise ChamberEnvCompatibilityError(
                f"PerAgentActionRepeatWrapper requires a gym.spaces.Dict action "
                f"space keyed by agent uid; got {type(env.action_space).__name__}. "
                f"See ADR-001 §Risks."
            )
        for uid, count in action_repeat.items():
            if count < 1:
                raise ValueError(f"action_repeat[{uid!r}] must be ≥ 1, got {count}")
        self._action_repeat: dict[str, int] = dict(action_repeat)
        self._counters: dict[str, int] = dict.fromkeys(action_repeat, 0)
        self._last_action: dict[str, object] = {}

    def step(self, action: dict) -> tuple:  # type: ignore[override]
        """Step with per-agent action repeat applied.

        ADR-001 §Validation criteria condition (c): the slow agent's effective
        action update interval matches 1/rate within one env tick.
        """
        resolved: dict[str, object] = {}
        for uid, act in action.items():
            repeat = self._action_repeat.get(uid, 1)
            counter = self._counters.get(uid, 0)
            if counter == 0:
                resolved[uid] = act
                self._last_action[uid] = act
                self._counters[uid] = repeat - 1
            else:
                resolved[uid] = self._last_action[uid]
                self._counters[uid] = counter - 1
        return self.env.step(resolved)

    def reset(self, **kwargs: object) -> tuple:  # type: ignore[override]
        """Reset the env and clear all per-agent repeat state.

        ADR-001 §Decision item 2: no state leaks across episodes.
        """
        obs, info = self.env.reset(**kwargs)  # type: ignore[arg-type]
        self._counters = dict.fromkeys(self._action_repeat, 0)
        self._last_action = {}
        return obs, info

__init__

__init__(
    env: Env, action_repeat: Mapping[str, int]
) -> None

Validate the action space and store per-agent repeat counts.

Source code in src/chamber/envs/action_repeat.py

def __init__(self, env: gym.Env, action_repeat: Mapping[str, int]) -> None:  # type: ignore[type-arg]
    """Validate the action space and store per-agent repeat counts."""
    super().__init__(env)
    if not isinstance(env.action_space, gym.spaces.Dict):
        raise ChamberEnvCompatibilityError(
            f"PerAgentActionRepeatWrapper requires a gym.spaces.Dict action "
            f"space keyed by agent uid; got {type(env.action_space).__name__}. "
            f"See ADR-001 §Risks."
        )
    for uid, count in action_repeat.items():
        if count < 1:
            raise ValueError(f"action_repeat[{uid!r}] must be ≥ 1, got {count}")
    self._action_repeat: dict[str, int] = dict(action_repeat)
    self._counters: dict[str, int] = dict.fromkeys(action_repeat, 0)
    self._last_action: dict[str, object] = {}

reset

reset(**kwargs: object) -> tuple

Reset the env and clear all per-agent repeat state.

ADR-001 §Decision item 2: no state leaks across episodes.

Source code in src/chamber/envs/action_repeat.py

def reset(self, **kwargs: object) -> tuple:  # type: ignore[override]
    """Reset the env and clear all per-agent repeat state.

    ADR-001 §Decision item 2: no state leaks across episodes.
    """
    obs, info = self.env.reset(**kwargs)  # type: ignore[arg-type]
    self._counters = dict.fromkeys(self._action_repeat, 0)
    self._last_action = {}
    return obs, info

step

step(action: dict) -> tuple

Step with per-agent action repeat applied.

ADR-001 §Validation criteria condition (c): the slow agent's effective action update interval matches 1/rate within one env tick.

Source code in src/chamber/envs/action_repeat.py

def step(self, action: dict) -> tuple:  # type: ignore[override]
    """Step with per-agent action repeat applied.

    ADR-001 §Validation criteria condition (c): the slow agent's effective
    action update interval matches 1/rate within one env tick.
    """
    resolved: dict[str, object] = {}
    for uid, act in action.items():
        repeat = self._action_repeat.get(uid, 1)
        counter = self._counters.get(uid, 0)
        if counter == 0:
            resolved[uid] = act
            self._last_action[uid] = act
            self._counters[uid] = repeat - 1
        else:
            resolved[uid] = self._last_action[uid]
            self._counters[uid] = counter - 1
    return self.env.step(resolved)

Per-agent observation-channel filter.

ADR-001 §Decision item 1 (obs modality heterogeneity axis); ADR-007 §Stage 1 OM axis (rev 3 §Stage 1).

TextureFilterObsWrapper

Bases: ObservationWrapper

Filter observation channels per agent uid, zero-masking unlisted channels.

Tensor shapes are preserved — masked channels become zero arrays of the same shape and dtype. This keeps downstream policy networks oblivious to which modalities a given partner actually receives.

ADR-001 §Decision item 1; ADR-007 §Stage 1 OM axis.

Parameters:

• env (Env) –

  Env whose observation has shape {"agent": {uid: {channel: array}}}.

• keep_per_agent (Mapping[str, Iterable[str]]) –

  Mapping from agent uid to the iterable of channel keys to keep. Channels not listed are zero-masked. Uids absent from this mapping are passed through unchanged.

Source code in src/chamber/envs/texture_filter.py

class TextureFilterObsWrapper(gym.ObservationWrapper):  # type: ignore[type-arg]
    """Filter observation channels per agent uid, zero-masking unlisted channels.

    Tensor shapes are preserved — masked channels become zero arrays of the
    same shape and dtype. This keeps downstream policy networks oblivious to
    which modalities a given partner actually receives.

    ADR-001 §Decision item 1; ADR-007 §Stage 1 OM axis.

    Args:
        env: Env whose observation has shape ``{"agent": {uid: {channel: array}}}``.
        keep_per_agent: Mapping from agent uid to the iterable of channel keys
            to keep. Channels not listed are zero-masked. Uids absent from this
            mapping are passed through unchanged.
    """

    def __init__(self, env: gym.Env, keep_per_agent: Mapping[str, Iterable[str]]) -> None:  # type: ignore[type-arg]
        """Store per-agent channel keep-sets as frozensets for O(1) lookup."""
        super().__init__(env)
        self._keep: dict[str, frozenset[str]] = {
            uid: frozenset(keys) for uid, keys in keep_per_agent.items()
        }

    def observation(self, observation: dict) -> dict:  # type: ignore[override]
        """Apply per-agent channel mask, zero-filling unlisted channels.

        ADR-001 §Decision item 1: obs modality is a controllable heterogeneity
        axis; shapes are invariant so vector rollout is unaffected.
        """
        agent_obs = observation.get("agent")
        if not isinstance(agent_obs, dict):
            return observation
        filtered_agents: dict[str, dict] = {}
        for uid, per_agent in agent_obs.items():
            if uid not in self._keep or not isinstance(per_agent, dict):
                filtered_agents[uid] = per_agent
                continue
            keep = self._keep[uid]
            filtered_agents[uid] = {
                ch: val if ch in keep else np.zeros_like(val) for ch, val in per_agent.items()
            }
        return {**observation, "agent": filtered_agents}

__init__

__init__(
    env: Env, keep_per_agent: Mapping[str, Iterable[str]]
) -> None

Store per-agent channel keep-sets as frozensets for O(1) lookup.

Source code in src/chamber/envs/texture_filter.py

def __init__(self, env: gym.Env, keep_per_agent: Mapping[str, Iterable[str]]) -> None:  # type: ignore[type-arg]
    """Store per-agent channel keep-sets as frozensets for O(1) lookup."""
    super().__init__(env)
    self._keep: dict[str, frozenset[str]] = {
        uid: frozenset(keys) for uid, keys in keep_per_agent.items()
    }

observation

observation(observation: dict) -> dict

Apply per-agent channel mask, zero-filling unlisted channels.

ADR-001 §Decision item 1: obs modality is a controllable heterogeneity axis; shapes are invariant so vector rollout is unaffected.

Source code in src/chamber/envs/texture_filter.py

def observation(self, observation: dict) -> dict:  # type: ignore[override]
    """Apply per-agent channel mask, zero-filling unlisted channels.

    ADR-001 §Decision item 1: obs modality is a controllable heterogeneity
    axis; shapes are invariant so vector rollout is unaffected.
    """
    agent_obs = observation.get("agent")
    if not isinstance(agent_obs, dict):
        return observation
    filtered_agents: dict[str, dict] = {}
    for uid, per_agent in agent_obs.items():
        if uid not in self._keep or not isinstance(per_agent, dict):
            filtered_agents[uid] = per_agent
            continue
        keep = self._keep[uid]
        filtered_agents[uid] = {
            ch: val if ch in keep else np.zeros_like(val) for ch, val in per_agent.items()
        }
    return {**observation, "agent": filtered_agents}

Communication-channel observation injector (M1 carrier; M2 fills logic).

ADR-001 §Decision item 3 (comm shaping is the outermost wrapper); ADR-003 §Decision (fixed-format + optional learned overlay via CommChannel); ADR-006 §Decision (URLLC-anchored numeric bounds enforced by the channel impl).

The actual comm logic (fixed-format encoding, AoI accounting, optional learned overlay, URLLC-anchored degradation) lives in :mod:chamber.comm (M2). This wrapper is a thin adapter that places the comm output into obs["comm"].

CommShapingWrapper

Bases: Wrapper

Inject comm-channel output into the observation dict as obs["comm"].

Wraps any env whose observation space is a gym.spaces.Dict. On each reset and step, calls channel.encode(obs) and stores the result under the "comm" key. The channel itself controls all degradation semantics (latency, drop, jitter); this wrapper is a pure carrier.

ADR-001 §Decision item 3; ADR-003 §Decision; ADR-006 §Decision.

Parameters:

• env (Env) –

  Env with a gym.spaces.Dict observation space.

• channel (CommChannel) –

  A :class:chamber.comm.api.CommChannel instance. In M1 this is a stub :class:chamber.comm.FixedFormatCommChannel that emits an empty packet shell. M2 fills the real fixed-format encoding.

Raises:

• ChamberEnvCompatibilityError –

  if the inner observation space is not a gym.spaces.Dict (ADR-001 §Risks).

Source code in src/chamber/envs/comm_shaping.py

class CommShapingWrapper(gym.Wrapper):  # type: ignore[type-arg]
    """Inject comm-channel output into the observation dict as ``obs["comm"]``.

    Wraps any env whose observation space is a ``gym.spaces.Dict``. On each
    reset and step, calls ``channel.encode(obs)`` and stores the result under
    the ``"comm"`` key. The channel itself controls all degradation semantics
    (latency, drop, jitter); this wrapper is a pure carrier.

    ADR-001 §Decision item 3; ADR-003 §Decision; ADR-006 §Decision.

    Args:
        env: Env with a ``gym.spaces.Dict`` observation space.
        channel: A :class:`chamber.comm.api.CommChannel` instance. In M1 this
            is a stub :class:`chamber.comm.FixedFormatCommChannel` that emits
            an empty packet shell. M2 fills the real fixed-format encoding.

    Raises:
        ChamberEnvCompatibilityError: if the inner observation space is not a
            ``gym.spaces.Dict`` (ADR-001 §Risks).
    """

    def __init__(self, env: gym.Env, channel: CommChannel) -> None:  # type: ignore[type-arg]
        """Validate the obs space and extend it with a ``comm`` sub-space."""
        super().__init__(env)
        if not isinstance(env.observation_space, gym.spaces.Dict):
            raise ChamberEnvCompatibilityError(
                f"CommShapingWrapper requires a gym.spaces.Dict observation space; "
                f"got {type(env.observation_space).__name__}. See ADR-001 §Risks."
            )
        self._channel = channel
        self._extend_observation_space()

    def _extend_observation_space(self) -> None:
        self.observation_space = gym.spaces.Dict(
            {
                **self.env.observation_space.spaces,  # type: ignore[attr-defined]
                "comm": gym.spaces.Dict({}),  # M2 fills the real comm obs space.
            }
        )

    def reset(self, **kwargs: object) -> tuple[dict, dict]:  # type: ignore[override]
        """Reset the env and channel, injecting comm into the initial obs.

        ADR-001 §Decision item 3; ADR-003 §Decision.
        """
        obs, info = self.env.reset(**kwargs)  # type: ignore[arg-type]
        self._channel.reset()
        obs = dict(obs)
        obs["comm"] = self._channel.encode(obs)
        return obs, info

    def step(self, action: object) -> tuple[dict, object, bool, bool, dict]:  # type: ignore[override]
        """Step the env and inject updated comm into obs.

        ADR-001 §Decision item 3; ADR-003 §Decision.
        """
        obs, reward, terminated, truncated, info = self.env.step(action)
        obs = dict(obs)
        obs["comm"] = self._channel.encode(obs)
        return obs, reward, terminated, truncated, info

__init__

__init__(env: Env, channel: CommChannel) -> None

Validate the obs space and extend it with a comm sub-space.

Source code in src/chamber/envs/comm_shaping.py

def __init__(self, env: gym.Env, channel: CommChannel) -> None:  # type: ignore[type-arg]
    """Validate the obs space and extend it with a ``comm`` sub-space."""
    super().__init__(env)
    if not isinstance(env.observation_space, gym.spaces.Dict):
        raise ChamberEnvCompatibilityError(
            f"CommShapingWrapper requires a gym.spaces.Dict observation space; "
            f"got {type(env.observation_space).__name__}. See ADR-001 §Risks."
        )
    self._channel = channel
    self._extend_observation_space()

reset

reset(**kwargs: object) -> tuple[dict, dict]

Reset the env and channel, injecting comm into the initial obs.

ADR-001 §Decision item 3; ADR-003 §Decision.

Source code in src/chamber/envs/comm_shaping.py

def reset(self, **kwargs: object) -> tuple[dict, dict]:  # type: ignore[override]
    """Reset the env and channel, injecting comm into the initial obs.

    ADR-001 §Decision item 3; ADR-003 §Decision.
    """
    obs, info = self.env.reset(**kwargs)  # type: ignore[arg-type]
    self._channel.reset()
    obs = dict(obs)
    obs["comm"] = self._channel.encode(obs)
    return obs, info

step

step(
    action: object,
) -> tuple[dict, object, bool, bool, dict]

Step the env and inject updated comm into obs.

ADR-001 §Decision item 3; ADR-003 §Decision.

Source code in src/chamber/envs/comm_shaping.py

def step(self, action: object) -> tuple[dict, object, bool, bool, dict]:  # type: ignore[override]
    """Step the env and inject updated comm into obs.

    ADR-001 §Decision item 3; ADR-003 §Decision.
    """
    obs, reward, terminated, truncated, info = self.env.step(action)
    obs = dict(obs)
    obs["comm"] = self._channel.encode(obs)
    return obs, reward, terminated, truncated, info

2-agent MPE Cooperative-Push env for the empirical-guarantee experiment (T4b.13).

Plan/05 §3.5 (decision row "Empirical guarantee Phase-0 verification") + ADR-002 risk-mitigation #1: the Phase-0 ego-AHT empirical-guarantee experiment runs on a 2-agent MPE-style cooperative continuous-control task. This module ships a deterministic hand-rolled equivalent of PettingZoo's simple_spread_v3 rather than depending on PettingZoo itself — Phase 0 keeps the dependency footprint minimal (PettingZoo deprecated MPE in 1.25 and split it into the younger mpe2 package; either lift would mean a dep-auditor pass for a single Phase-0 task). The task structure matches:

• Two agents (default uids ego and partner) on the unit-square plane [-1, 1]^2 with continuous 2-D velocity actions clipped to [-1, 1] per axis.
• Two landmarks fixed per episode at random positions sampled from a determinism-harnessed numpy Generator (seed routed via :func:concerto.training.seeding.derive_substream).
• Shared reward (both agents see the same scalar): r = -sum_landmark min_agent ||agent_pos - landmark_pos||. The cooperative-coverage gradient encourages the agents to pick distinct landmarks; a single agent cannot drive r to zero on its own.
• Episode length fixed at :data:DEFAULT_EPISODE_LENGTH; truncation only (no terminal state).

The env is intentionally Gymnasium-compatible with CONCERTO's other wrappers (M2 comm + M3 safety): observation is keyed by obs["agent"][uid] with the state channel that :class:chamber.partners.heuristic.ScriptedHeuristicPartner already reads in its three-tier fallback (plan/04 §3.4). Wrapping this env through :class:chamber.envs.action_repeat.PerAgentActionRepeatWrapper, :class:chamber.envs.comm_shaping.CommShapingWrapper, etc. is therefore a zero-config drop-in.

Determinism (P6): two reset(seed=K) calls on the same root_seed produce byte-identical landmark layouts and agent start poses; the same action stream then produces a byte-identical state trajectory and reward curve. test_mpe_cooperative_push.py::test_determinism_byte_identical_traj pins this contract.

MPECooperativePushEnv

Bases: Env

2-agent MPE-style cooperative continuous-control env (T4b.13; ADR-002 risk-mitigation #1).

See module docstring for the task design. The env exposes the standard Gymnasium reset + step API with multi-agent dict actions / dict observations keyed by uid, matching :class:tests.fakes.FakeMultiAgentEnv so the M2/M3 wrapper stack drops in unchanged (plan/01 §3).

Source code in src/chamber/envs/mpe_cooperative_push.py

class MPECooperativePushEnv(gym.Env):  # type: ignore[type-arg]
    """2-agent MPE-style cooperative continuous-control env (T4b.13; ADR-002 risk-mitigation #1).

    See module docstring for the task design. The env exposes the standard
    Gymnasium ``reset`` + ``step`` API with multi-agent dict actions / dict
    observations keyed by ``uid``, matching :class:`tests.fakes.FakeMultiAgentEnv`
    so the M2/M3 wrapper stack drops in unchanged (plan/01 §3).
    """

    metadata: ClassVar[dict[str, list[str]]] = {"render_modes": []}  # type: ignore[misc]

    #: Number of agents the env supports — fixed at 2 by the cooperative-coverage task.
    _N_AGENTS: ClassVar[int] = 2

    def __init__(
        self,
        *,
        agent_uids: tuple[str, str] = ("ego", "partner"),
        episode_length: int = DEFAULT_EPISODE_LENGTH,
        root_seed: int = 0,
    ) -> None:
        """Build a 2-agent Cooperative-Push env (T4b.13; plan/05 §3.5).

        Args:
            agent_uids: The two uids the env exposes. The default
                ``("ego", "partner")`` matches the ego-AHT training loop
                convention. Reordering swaps which agent the trainer
                updates and which is held frozen — the env is agnostic.
            episode_length: Truncation horizon in env ticks (default
                :data:`DEFAULT_EPISODE_LENGTH`).
            root_seed: Project-wide root seed; the env derives a
                deterministic numpy ``Generator`` from this via
                :func:`concerto.training.seeding.derive_substream`
                (P6 reproducibility).

        Raises:
            ValueError: If ``agent_uids`` does not have exactly two
                distinct entries.
        """
        super().__init__()
        if len(agent_uids) != self._N_AGENTS or agent_uids[0] == agent_uids[1]:
            raise ValueError(
                f"agent_uids must be a 2-tuple of distinct strings; got {agent_uids!r}"
            )
        self._uids: tuple[str, str] = agent_uids
        self._episode_length: int = int(episode_length)
        self._root_seed: int = int(root_seed)

        self.action_space = gym.spaces.Dict(
            {
                uid: gym.spaces.Box(
                    low=-VELOCITY_BOUND,
                    high=VELOCITY_BOUND,
                    shape=(2,),
                    dtype=np.float32,
                )
                for uid in self._uids
            }
        )
        # state channel: self_pos(2) + self_vel(2) + landmark_rel(4) + partner_rel(2) = 10.
        agent_state = gym.spaces.Box(low=-np.inf, high=np.inf, shape=(10,), dtype=np.float32)
        self.observation_space = gym.spaces.Dict(
            {
                "agent": gym.spaces.Dict(
                    {uid: gym.spaces.Dict({"state": agent_state}) for uid in self._uids}
                )
            }
        )

        self._rng: np.random.Generator = derive_substream(
            _SUBSTREAM_NAME, root_seed=self._root_seed
        ).default_rng()
        # Per-episode mutable state — set by reset.
        self._step_count: int = 0
        self._positions: dict[str, NDArray[np.float64]] = {}
        self._velocities: dict[str, NDArray[np.float64]] = {}
        self._landmark_positions: NDArray[np.float64] = np.zeros((N_LANDMARKS, 2))

    def reset(
        self,
        *,
        seed: int | None = None,
        options: dict[str, Any] | None = None,
    ) -> tuple[dict[str, Any], dict[str, Any]]:
        """Reset to a determinism-harnessed initial state (T4b.13; ADR-002 risk-mitigation #1; P6).

        .. note::

            This env's seeding semantics intentionally diverge from
            Gymnasium's convention (where ``reset(seed=K)`` is the
            *complete* seed source). Here, ``reset(seed=K)`` is folded
            with the constructor's ``root_seed`` via
            :func:`concerto.training.seeding.derive_substream` using the
            substream name ``"env.mpe_cooperative_push.episode.{K}"`` —
            so two training runs at distinct ``root_seed`` values do
            *not* collide on the same per-episode RNG even at the same
            ``K``. This matches the project-wide seeding philosophy
            (P6 + ADR-002 §Decisions): the ``root_seed`` is the
            run-level pin, and per-episode ``seed`` is an episode index
            scoped under it.

        Args:
            seed: Per-episode seed (episode index, NOT a complete seed).
                When provided, re-derives the env's RNG via
                ``derive_substream(f"env.mpe_cooperative_push.episode.{seed}",
                root_seed=self._root_seed)``. When ``None``, continues
                from the RNG's existing state (Gymnasium convention).
            options: Reserved for the Gymnasium API; ignored.

        Returns:
            ``(obs, info)`` where ``obs`` matches the
            :attr:`observation_space` shape and ``info`` is empty.
        """
        del options
        if seed is not None:
            self._rng = derive_substream(
                f"{_SUBSTREAM_NAME}.episode.{seed}",
                root_seed=self._root_seed,
            ).default_rng()
        self._step_count = 0
        self._landmark_positions = self._rng.uniform(
            -POSITION_BOUND, POSITION_BOUND, size=(N_LANDMARKS, 2)
        )
        for uid in self._uids:
            self._positions[uid] = self._rng.uniform(-POSITION_BOUND, POSITION_BOUND, size=(2,))
            self._velocities[uid] = np.zeros(2, dtype=np.float64)
        return self._build_obs(), {}

    def step(
        self,
        action: dict[str, NDArray[np.floating]],
    ) -> tuple[dict[str, Any], float, bool, bool, dict[str, Any]]:
        """Advance one tick (T4b.13; ADR-002 risk-mitigation #1; plan/05 §3.5).

        Args:
            action: Dict keyed by ``uid``, each value a 2-D velocity
                command. Components are clipped to
                ``[-VELOCITY_BOUND, +VELOCITY_BOUND]`` before integration
                so a misbehaving partner cannot escape the plane.

        Returns:
            ``(obs, reward, terminated, truncated, info)``. ``reward`` is
            the *shared* cooperative-coverage scalar (both agents see the
            same value); the trainer's ego/partner split happens upstream
            in :func:`concerto.training.ego_aht.train`. ``terminated`` is
            always ``False`` (no terminal state); ``truncated`` is ``True``
            on the last tick of the episode.

        Raises:
            ValueError: If ``action`` is missing a required uid.
        """
        for uid in self._uids:
            if uid not in action:
                raise ValueError(
                    f"step() action missing uid {uid!r}; got keys {list(action.keys())}"
                )
        for uid in self._uids:
            a = np.clip(
                np.asarray(action[uid], dtype=np.float64),
                -VELOCITY_BOUND,
                VELOCITY_BOUND,
            )
            self._velocities[uid] = a
            self._positions[uid] = np.clip(
                self._positions[uid] + a * DT, -POSITION_BOUND, POSITION_BOUND
            )
        self._step_count += 1
        truncated = self._step_count >= self._episode_length
        return self._build_obs(), self._compute_reward(), False, truncated, {}

    def _build_obs(self) -> dict[str, Any]:
        """Pack the Gymnasium-conformant obs dict (plan/01 §3; plan/04 §3.4)."""
        out_agents: dict[str, dict[str, NDArray[np.float32]]] = {}
        for uid in self._uids:
            self_pos = self._positions[uid]
            self_vel = self._velocities[uid]
            landmark_rel = (self._landmark_positions - self_pos).flatten()
            partner_uid = self._uids[1] if uid == self._uids[0] else self._uids[0]
            partner_rel = self._positions[partner_uid] - self_pos
            state = np.concatenate([self_pos, self_vel, landmark_rel, partner_rel]).astype(
                np.float32
            )
            out_agents[uid] = {"state": state}
        return {"agent": out_agents}

    def _compute_reward(self) -> float:
        """Shared cooperative-coverage scalar (plan/05 §3.5).

        ``r = -sum_landmark min_agent dist(agent, landmark)``. Both
        agents always see the same value so the trainer can route it to
        the ego's policy update without a credit-assignment step.

        Edge case: when an agent sits exactly on a landmark, that
        landmark contributes ``0`` to the sum. Perfect coverage (one
        agent per landmark, both at distance ``0``) yields ``r = 0`` —
        the natural ceiling. The empirical-guarantee assertion in
        T4b.13 is on *moving-window-of-10 non-decreasing*, not on
        approaching this ceiling.

        ``np.linalg.norm`` matches PettingZoo ``simple_spread_v3``'s
        Euclidean reward (squared distance would change the gradient
        shape and break the "matches simple_spread" claim should
        Phase 1 ever cross-validate against the real env).
        """
        # Phase 1 TODO: cross-validate trajectory against
        # mpe2.simple_spread_v3 once the dep-auditor has cleared mpe2.
        total = 0.0
        for landmark in self._landmark_positions:
            distances = [
                float(np.linalg.norm(self._positions[uid] - landmark)) for uid in self._uids
            ]
            total += min(distances)
        return -total

__init__

__init__(
    *,
    agent_uids: tuple[str, str] = ("ego", "partner"),
    episode_length: int = DEFAULT_EPISODE_LENGTH,
    root_seed: int = 0,
) -> None

Build a 2-agent Cooperative-Push env (T4b.13; plan/05 §3.5).

Parameters:

• agent_uids (tuple[str, str], default: ('ego', 'partner') ) –

  The two uids the env exposes. The default ("ego", "partner") matches the ego-AHT training loop convention. Reordering swaps which agent the trainer updates and which is held frozen — the env is agnostic.

• episode_length (int, default: DEFAULT_EPISODE_LENGTH ) –

  Truncation horizon in env ticks (default :data:DEFAULT_EPISODE_LENGTH).

• root_seed (int, default: 0 ) –

  Project-wide root seed; the env derives a deterministic numpy Generator from this via :func:concerto.training.seeding.derive_substream (P6 reproducibility).

Raises:

• ValueError –

  If agent_uids does not have exactly two distinct entries.

Source code in src/chamber/envs/mpe_cooperative_push.py

def __init__(
    self,
    *,
    agent_uids: tuple[str, str] = ("ego", "partner"),
    episode_length: int = DEFAULT_EPISODE_LENGTH,
    root_seed: int = 0,
) -> None:
    """Build a 2-agent Cooperative-Push env (T4b.13; plan/05 §3.5).

    Args:
        agent_uids: The two uids the env exposes. The default
            ``("ego", "partner")`` matches the ego-AHT training loop
            convention. Reordering swaps which agent the trainer
            updates and which is held frozen — the env is agnostic.
        episode_length: Truncation horizon in env ticks (default
            :data:`DEFAULT_EPISODE_LENGTH`).
        root_seed: Project-wide root seed; the env derives a
            deterministic numpy ``Generator`` from this via
            :func:`concerto.training.seeding.derive_substream`
            (P6 reproducibility).

    Raises:
        ValueError: If ``agent_uids`` does not have exactly two
            distinct entries.
    """
    super().__init__()
    if len(agent_uids) != self._N_AGENTS or agent_uids[0] == agent_uids[1]:
        raise ValueError(
            f"agent_uids must be a 2-tuple of distinct strings; got {agent_uids!r}"
        )
    self._uids: tuple[str, str] = agent_uids
    self._episode_length: int = int(episode_length)
    self._root_seed: int = int(root_seed)

    self.action_space = gym.spaces.Dict(
        {
            uid: gym.spaces.Box(
                low=-VELOCITY_BOUND,
                high=VELOCITY_BOUND,
                shape=(2,),
                dtype=np.float32,
            )
            for uid in self._uids
        }
    )
    # state channel: self_pos(2) + self_vel(2) + landmark_rel(4) + partner_rel(2) = 10.
    agent_state = gym.spaces.Box(low=-np.inf, high=np.inf, shape=(10,), dtype=np.float32)
    self.observation_space = gym.spaces.Dict(
        {
            "agent": gym.spaces.Dict(
                {uid: gym.spaces.Dict({"state": agent_state}) for uid in self._uids}
            )
        }
    )

    self._rng: np.random.Generator = derive_substream(
        _SUBSTREAM_NAME, root_seed=self._root_seed
    ).default_rng()
    # Per-episode mutable state — set by reset.
    self._step_count: int = 0
    self._positions: dict[str, NDArray[np.float64]] = {}
    self._velocities: dict[str, NDArray[np.float64]] = {}
    self._landmark_positions: NDArray[np.float64] = np.zeros((N_LANDMARKS, 2))

reset

reset(
    *,
    seed: int | None = None,
    options: dict[str, Any] | None = None,
) -> tuple[dict[str, Any], dict[str, Any]]

Reset to a determinism-harnessed initial state (T4b.13; ADR-002 risk-mitigation #1; P6).

.. note::

This env's seeding semantics intentionally diverge from
Gymnasium's convention (where ``reset(seed=K)`` is the
*complete* seed source). Here, ``reset(seed=K)`` is folded
with the constructor's ``root_seed`` via
:func:`concerto.training.seeding.derive_substream` using the
substream name ``"env.mpe_cooperative_push.episode.{K}"`` —
so two training runs at distinct ``root_seed`` values do
*not* collide on the same per-episode RNG even at the same
``K``. This matches the project-wide seeding philosophy
(P6 + ADR-002 §Decisions): the ``root_seed`` is the
run-level pin, and per-episode ``seed`` is an episode index
scoped under it.

Parameters:

• seed (int | None, default: None ) –

  Per-episode seed (episode index, NOT a complete seed). When provided, re-derives the env's RNG via derive_substream(f"env.mpe_cooperative_push.episode.{seed}", root_seed=self._root_seed). When None, continues from the RNG's existing state (Gymnasium convention).

• options (dict[str, Any] | None, default: None ) –

  Reserved for the Gymnasium API; ignored.

Returns:

• dict[str, Any] –

  (obs, info) where obs matches the

• dict[str, Any] –

  attr:observation_space shape and info is empty.

Source code in src/chamber/envs/mpe_cooperative_push.py

def reset(
    self,
    *,
    seed: int | None = None,
    options: dict[str, Any] | None = None,
) -> tuple[dict[str, Any], dict[str, Any]]:
    """Reset to a determinism-harnessed initial state (T4b.13; ADR-002 risk-mitigation #1; P6).

    .. note::

        This env's seeding semantics intentionally diverge from
        Gymnasium's convention (where ``reset(seed=K)`` is the
        *complete* seed source). Here, ``reset(seed=K)`` is folded
        with the constructor's ``root_seed`` via
        :func:`concerto.training.seeding.derive_substream` using the
        substream name ``"env.mpe_cooperative_push.episode.{K}"`` —
        so two training runs at distinct ``root_seed`` values do
        *not* collide on the same per-episode RNG even at the same
        ``K``. This matches the project-wide seeding philosophy
        (P6 + ADR-002 §Decisions): the ``root_seed`` is the
        run-level pin, and per-episode ``seed`` is an episode index
        scoped under it.

    Args:
        seed: Per-episode seed (episode index, NOT a complete seed).
            When provided, re-derives the env's RNG via
            ``derive_substream(f"env.mpe_cooperative_push.episode.{seed}",
            root_seed=self._root_seed)``. When ``None``, continues
            from the RNG's existing state (Gymnasium convention).
        options: Reserved for the Gymnasium API; ignored.

    Returns:
        ``(obs, info)`` where ``obs`` matches the
        :attr:`observation_space` shape and ``info`` is empty.
    """
    del options
    if seed is not None:
        self._rng = derive_substream(
            f"{_SUBSTREAM_NAME}.episode.{seed}",
            root_seed=self._root_seed,
        ).default_rng()
    self._step_count = 0
    self._landmark_positions = self._rng.uniform(
        -POSITION_BOUND, POSITION_BOUND, size=(N_LANDMARKS, 2)
    )
    for uid in self._uids:
        self._positions[uid] = self._rng.uniform(-POSITION_BOUND, POSITION_BOUND, size=(2,))
        self._velocities[uid] = np.zeros(2, dtype=np.float64)
    return self._build_obs(), {}

step

step(
    action: dict[str, NDArray[floating]],
) -> tuple[
    dict[str, Any], float, bool, bool, dict[str, Any]
]

Advance one tick (T4b.13; ADR-002 risk-mitigation #1; plan/05 §3.5).

Parameters:

• action (dict[str, NDArray[floating]]) –

  Dict keyed by uid, each value a 2-D velocity command. Components are clipped to [-VELOCITY_BOUND, +VELOCITY_BOUND] before integration so a misbehaving partner cannot escape the plane.

Returns:

• dict[str, Any] –

  (obs, reward, terminated, truncated, info). reward is

• float –

  the shared cooperative-coverage scalar (both agents see the

• bool –

  same value); the trainer's ego/partner split happens upstream

• in ( bool ) –

  func:concerto.training.ego_aht.train. terminated is

• dict[str, Any] –

  always False (no terminal state); truncated is True

• tuple[dict[str, Any], float, bool, bool, dict[str, Any]] –

  on the last tick of the episode.

Raises:

• ValueError –

  If action is missing a required uid.

Source code in src/chamber/envs/mpe_cooperative_push.py

def step(
    self,
    action: dict[str, NDArray[np.floating]],
) -> tuple[dict[str, Any], float, bool, bool, dict[str, Any]]:
    """Advance one tick (T4b.13; ADR-002 risk-mitigation #1; plan/05 §3.5).

    Args:
        action: Dict keyed by ``uid``, each value a 2-D velocity
            command. Components are clipped to
            ``[-VELOCITY_BOUND, +VELOCITY_BOUND]`` before integration
            so a misbehaving partner cannot escape the plane.

    Returns:
        ``(obs, reward, terminated, truncated, info)``. ``reward`` is
        the *shared* cooperative-coverage scalar (both agents see the
        same value); the trainer's ego/partner split happens upstream
        in :func:`concerto.training.ego_aht.train`. ``terminated`` is
        always ``False`` (no terminal state); ``truncated`` is ``True``
        on the last tick of the episode.

    Raises:
        ValueError: If ``action`` is missing a required uid.
    """
    for uid in self._uids:
        if uid not in action:
            raise ValueError(
                f"step() action missing uid {uid!r}; got keys {list(action.keys())}"
            )
    for uid in self._uids:
        a = np.clip(
            np.asarray(action[uid], dtype=np.float64),
            -VELOCITY_BOUND,
            VELOCITY_BOUND,
        )
        self._velocities[uid] = a
        self._positions[uid] = np.clip(
            self._positions[uid] + a * DT, -POSITION_BOUND, POSITION_BOUND
        )
    self._step_count += 1
    truncated = self._step_count >= self._episode_length
    return self._build_obs(), self._compute_reward(), False, truncated, {}

Stage-1b pick-place env (ADR-007 §Stage 1b; P1.03 / PR #).

Real ManiSkill v3 wrap of the canonical pick-place task with the panda + fetch / panda + panda_partner robot tuples. Supports the four Stage-1 condition_id strings the AS / OM pre-registrations name verbatim (spikes/preregistration/AS.yaml, spikes/preregistration/OM.yaml; git tags prereg-stage1-{AS,OM}-2026-05-15):

• AS-homo: stage1_pickplace_panda_only_mappo_shared_param -> agents ("panda_wristcam", "panda_partner").
• AS-hetero: stage1_pickplace_panda_plus_fetch_ego_aht_happo_per_agent -> agents ("panda_wristcam", "fetch").
• OM-homo: stage1_pickplace_vision_only -> agents ("panda_wristcam", "fetch"); vision-only channel keep-set.
• OM-hetero: stage1_pickplace_vision_plus_force_torque_plus_proprio -> same agents; vision + synthesised FT + proprio channel keep-set.

Per ADR-007 §Discipline the pre-registration YAMLs and their git tags carry forward unchanged from Phase 0 — Stage 1b uses the same condition IDs, seed list (5 seeds, 20 episodes per seed = 100 episodes per condition), and episode budget; only the env implementation behind the condition IDs changes. Editing a prereg YAML post-launch is a project anti-pattern (ADR-007 §Discipline).

Stage-1a's MPE stand-in (:class:chamber.envs.mpe_cooperative_push.MPECooperativePushEnv) sequenced rig validation; this env is the Stage-1b science evaluation target. Compute budget per ADR-007 §Stage 1b: 5 GPU-h per axis on A100; :data:DEFAULT_EPISODE_LENGTH = 100 chosen to fit the budget given ~0.8-1.2 s/step at multi-agent SAPIEN scale.

Wrapper-only discipline (ADR-001 §Decision (wrapper-only)): no patches to mani_skill/; no _* private imports. The env subclasses :class:mani_skill.envs.sapien_env.BaseEnv directly (matching the Stage-0 smoke env's _Stage0SmokeEnv pattern, but with the canonical pick-place reward and a two-robot tuple). The :func:chamber.envs._sapien_compat.load_agent_with_bare_uids shim handles the multi-agent uid-suffix strip-rebind that both Stage-0 and Stage-1 need.

Action space and the AS axis (decision Q3 / ADR-004 §Decision): All agents use control_mode="pd_joint_delta_pos" so the 7-DOF panda arm action stays joint-space, not Cartesian — preserving the AS axis's intended "7-DOF arm vs 2-DOF differential-drive base" heterogeneity (ADR-007 §Stage 1 AS spike framing). The CBF-QP outer filter's Cartesian-acceleration interpretation of the action is then an approximation absorbed by the conformal-slack overlay (Huriot & Sibai 2025 §VI); see the ADR-007 §Stage 1b note for the quantitative dimensional analysis ("off by 1/dt² (~2500x at dt=0.02s, small-Δp scale)") and ADR-004 §Open questions / slice P1.05.5 for the contingent long-term fix (extend :class:AgentSnapshot with qpos).

Force-torque synthesis (decision Q2 / ADR-007 §Revision history rev. 5): The OM-hetero "force_torque" channel is synthesised from the panda gripper's fingertip contact wrenches via :meth:Articulation.get_net_contact_forces(["panda_leftfinger", "panda_rightfinger"]) plus zero-mean Gaussian noise at :data:SYNTHESISED_FT_NOISE_SIGMA_N Newtons (default 0.5 N — at the lower bound of the real Franka wrist-FT noise floor of 0.5-1.5 N). This is not a real Panda wrist FT sensor reading. Wrist-mounted virtual FT is a Phase-1.5 ablation (ADR-007 §Open questions; Stage-1b+0.5 follow-up). The sigma value lives in this module + the ADR-007 §Revision history entry only — never in the prereg YAML (ADR-007 §Discipline: tag rotation forbidden).

Cooperation gradient (decision Q in design conversation): Cube and goal spawn locations follow the upstream PickCubeEnv defaults for now (cube within ±5 cm of the table origin; goal within the same envelope, z ∈ [0, 0.3]). The cooperative gradient between AS-homo (two pandas) and AS-hetero (panda + fetch) is itself a Stage-1b empirical question; pose tuning is sequenced as a P1.04 follow-up once the first pilot's success-rate landscape is known (don't gold-plate at design time).

Tier-1 / Tier-2 split (decision 9): The module's top-level imports are intentionally Tier-1-safe (numpy, gymnasium, concerto.safety.api types, chamber.envs.errors). ManiSkill / SAPIEN / pytorch_kinematics imports happen inside :func:make_stage1_pickplace_env so python -c "import chamber.envs.stage1_pickplace" succeeds on a Vulkan-less host. The pure-function Tier-1 surface (:func:resolve_condition, :func:build_control_models_for_condition) is what the Tier-1 tests exercise; Tier-2 SAPIEN-gated tests cover real env construction.

References: - ADR-001 §Decision (wrapper-only); ADR-001 §Validation criteria (Stage-0 pattern this env mirrors). - ADR-004 §Decision (CBF-QP + JacobianControlModel contract); ADR-004 §Open questions (AgentSnapshot.qpos extension, slice P1.05.5). - ADR-005 §Decision (SAPIEN 3 + Warp-MPM substrate, inherited from ManiSkill v3). - ADR-007 §Stage 1b (this env's spec); ADR-007 §Discipline (tag rotation forbidden); ADR-007 §Open questions (FT wrist-mount ablation, P1.05.5 contingent slice). - spikes/preregistration/{AS,OM}.yaml (the condition_id strings this env resolves verbatim). - :class:concerto.safety.api.JacobianControlModel, :class:concerto.safety.api.DoubleIntegratorControlModel (the per-uid control models :meth:Stage1PickPlaceEnv.build_control_models returns).

ConditionConfig

Bases: NamedTuple

Resolved per-condition configuration (ADR-007 §Stage 1b).

Returned by :func:resolve_condition. Pure-Python NamedTuple so Tier-1 tests can construct fakes without any SAPIEN dependency.

Attributes:

• condition_id (str) –

  The verbatim pre-registration condition_id string (one of the four Stage-1 strings).

• agent_uids (tuple[str, str]) –

  Ordered (ego_uid, partner_uid) tuple. The ego is the agent the trainer updates / the safety filter authorises; the partner is the frozen / heuristic partner.

• obs_mode (str) –

  ManiSkill v3 env-level obs_mode superset string passed to :class:BaseEnv.__init__. The OM channel-filter wrapper (:class:chamber.envs.stage1_obs_filter.Stage1OMChannelFilter) slices this superset per-uid to the condition's actual channel keep-set.

• is_om_condition (bool) –

  True for the two OM condition_id strings (vision_only / vision_plus_force_torque_plus_proprio). Drives whether the channel-filter wrapper is engaged downstream.

• ft_synthesis_enabled (bool) –

  True for the OM-hetero condition. The env always injects the synthesised force-torque channel into obs["agent"]["panda_wristcam"]["force_torque"]; the channel filter then masks or keeps it per condition. The flag here is informational only (consumed by the smoke scripts and the docstring report).

Source code in src/chamber/envs/stage1_pickplace.py

class ConditionConfig(NamedTuple):
    """Resolved per-condition configuration (ADR-007 §Stage 1b).

    Returned by :func:`resolve_condition`. Pure-Python NamedTuple so
    Tier-1 tests can construct fakes without any SAPIEN dependency.

    Attributes:
        condition_id: The verbatim pre-registration ``condition_id``
            string (one of the four Stage-1 strings).
        agent_uids: Ordered ``(ego_uid, partner_uid)`` tuple. The ego
            is the agent the trainer updates / the safety filter
            authorises; the partner is the frozen / heuristic partner.
        obs_mode: ManiSkill v3 env-level ``obs_mode`` superset string
            passed to :class:`BaseEnv.__init__`. The OM channel-filter
            wrapper (:class:`chamber.envs.stage1_obs_filter.Stage1OMChannelFilter`)
            slices this superset per-uid to the condition's actual
            channel keep-set.
        is_om_condition: ``True`` for the two OM ``condition_id`` strings
            (``vision_only`` / ``vision_plus_force_torque_plus_proprio``).
            Drives whether the channel-filter wrapper is engaged
            downstream.
        ft_synthesis_enabled: ``True`` for the OM-hetero condition. The
            env always *injects* the synthesised force-torque channel
            into ``obs["agent"]["panda_wristcam"]["force_torque"]``; the
            channel filter then masks or keeps it per condition. The
            flag here is informational only (consumed by the smoke
            scripts and the docstring report).
    """

    condition_id: str
    agent_uids: tuple[str, str]
    obs_mode: str
    is_om_condition: bool
    ft_synthesis_enabled: bool

build_control_models_for_condition

build_control_models_for_condition(
    condition_id: str,
    *,
    jacobian_fn: Callable[[AgentSnapshot], NDArray[float64]]
    | None = None,
    fetch_action_dim: int | None = None,
    panda_action_dim: int = 8,
) -> dict[str, AgentControlModel]

Build per-uid :class:AgentControlModel map for condition_id (ADR-004 §Decision).

Pure Tier-1 function — no SAPIEN dependency. The Jacobian callable is plumbed in by the env at construction time (see :meth:Stage1PickPlaceEnv.build_control_models); Tier-1 tests pass jacobian_fn=None to exercise the model-construction path, which keeps the placeholder per :class:JacobianControlModel's loud-fail-on-use contract (concerto/safety/api.py:552).

Parameters:

• condition_id (str) –

  Stage-1 condition_id (raises if unknown).

• jacobian_fn (Callable[[AgentSnapshot], NDArray[float64]] | None, default: None ) –

  Optional Jacobian callable to embed in the panda uid's :class:JacobianControlModel. None means the placeholder model is returned (Tier-1 path); pass the env's closure-via-env-reference callable (lambda snap: env._jacobian_provider(snap, env._latest_qpos["panda_wristcam"])) to get a working model for Tier-2 / production.

• fetch_action_dim (int | None, default: None ) –

  Action dimension of the fetch uid's Box. None (default) is the Tier-1 sentinel — :class:DoubleIntegratorControlModel with action_dim=2 (just the differential-drive base axis; the arm + body + gripper are folded into the same model with the canonical "treat the whole action as a 1-D Cartesian acceleration" approximation P1.05.5 will tighten). Tier-2 paths pass the actual env.action_space[uid].shape[0].

• panda_action_dim (int, default: 8 ) –

  Action dimension of the panda uid's Box. Defaults to 8 (7 arm joint deltas + 1 mimic-gripper joint delta under pd_joint_delta_pos). Both panda_wristcam and panda_partner share this shape.

Returns:

• dict[str, AgentControlModel] –

  {uid: AgentControlModel} map keyed by the condition's

• dict[str, AgentControlModel] –

  attr:ConditionConfig.agent_uids. The panda uid (always the

• dict[str, AgentControlModel] –

  ego, always present) gets a :class:JacobianControlModel; the

• dict[str, AgentControlModel] –

  partner uid gets a :class:JacobianControlModel for

• dict[str, AgentControlModel] –

  panda_partner (AS-homo) or

• dict[str, AgentControlModel] –

  class:DoubleIntegratorControlModel for fetch (AS-hetero /

• dict[str, AgentControlModel] –

  OM-*).

Raises:

• ValueError –

  If condition_id is not in the four-condition table (delegated to :func:resolve_condition).

Source code in src/chamber/envs/stage1_pickplace.py

def build_control_models_for_condition(
    condition_id: str,
    *,
    jacobian_fn: Callable[[AgentSnapshot], NDArray[np.float64]] | None = None,
    fetch_action_dim: int | None = None,
    panda_action_dim: int = 8,
) -> dict[str, AgentControlModel]:
    """Build per-uid :class:`AgentControlModel` map for ``condition_id`` (ADR-004 §Decision).

    Pure Tier-1 function — no SAPIEN dependency. The Jacobian callable
    is plumbed in by the env at construction time (see
    :meth:`Stage1PickPlaceEnv.build_control_models`); Tier-1 tests pass
    ``jacobian_fn=None`` to exercise the model-construction path, which
    keeps the placeholder per :class:`JacobianControlModel`'s
    loud-fail-on-use contract (``concerto/safety/api.py:552``).

    Args:
        condition_id: Stage-1 ``condition_id`` (raises if unknown).
        jacobian_fn: Optional Jacobian callable to embed in the panda
            uid's :class:`JacobianControlModel`. ``None`` means the
            placeholder model is returned (Tier-1 path); pass the env's
            closure-via-env-reference callable
            (``lambda snap: env._jacobian_provider(snap, env._latest_qpos["panda_wristcam"])``)
            to get a working model for Tier-2 / production.
        fetch_action_dim: Action dimension of the fetch uid's Box.
            ``None`` (default) is the Tier-1 sentinel — :class:`DoubleIntegratorControlModel`
            with ``action_dim=2`` (just the differential-drive base axis;
            the arm + body + gripper are folded into the same model
            with the canonical "treat the whole action as a 1-D
            Cartesian acceleration" approximation P1.05.5 will tighten).
            Tier-2 paths pass the actual ``env.action_space[uid].shape[0]``.
        panda_action_dim: Action dimension of the panda uid's Box.
            Defaults to ``8`` (7 arm joint deltas + 1 mimic-gripper
            joint delta under ``pd_joint_delta_pos``). Both
            ``panda_wristcam`` and ``panda_partner`` share this shape.

    Returns:
        ``{uid: AgentControlModel}`` map keyed by the condition's
        :attr:`ConditionConfig.agent_uids`. The panda uid (always the
        ego, always present) gets a :class:`JacobianControlModel`; the
        partner uid gets a :class:`JacobianControlModel` for
        ``panda_partner`` (AS-homo) or
        :class:`DoubleIntegratorControlModel` for ``fetch`` (AS-hetero /
        OM-*).

    Raises:
        ValueError: If ``condition_id`` is not in the four-condition
            table (delegated to :func:`resolve_condition`).
    """
    config = resolve_condition(condition_id)
    ego_uid, partner_uid = config.agent_uids
    models: dict[str, AgentControlModel] = {}
    # Ego is always panda_wristcam — 7-DOF arm + mimic-gripper.
    # JacobianControlModel position_dim=3 (Cartesian) matches the
    # AgentSnapshot Cartesian-only contract (cbf_qp.py:103-110).
    models[ego_uid] = JacobianControlModel(
        uid=ego_uid,
        action_dim=panda_action_dim,
        position_dim=3,
        jacobian_fn=jacobian_fn,
        max_cartesian_accel_value=PANDA_CARTESIAN_ACCEL_CAPACITY_MS2,
    )
    if partner_uid == "panda_partner":
        # AS-homo: second panda, identical kinematics, same Jacobian
        # callable wired by the env via the closure pattern.
        models[partner_uid] = JacobianControlModel(
            uid=partner_uid,
            action_dim=panda_action_dim,
            position_dim=3,
            jacobian_fn=jacobian_fn,
            max_cartesian_accel_value=PANDA_CARTESIAN_ACCEL_CAPACITY_MS2,
        )
    else:
        # AS-hetero / OM-*: fetch base+arm uses DoubleIntegratorControlModel.
        # action_dim default 2 covers the 2-DOF differential-drive base
        # slice that ADR-007 §Stage 1 AS spike framing names; real
        # Tier-2 path passes the full action_space shape.
        effective_action_dim = 2 if fetch_action_dim is None else fetch_action_dim
        models[partner_uid] = DoubleIntegratorControlModel(
            uid=partner_uid,
            action_dim=effective_action_dim,
        )
    return models

make_stage1_pickplace_env

make_stage1_pickplace_env(
    *,
    condition_id: str,
    episode_length: int = DEFAULT_EPISODE_LENGTH,
    root_seed: int = 0,
    num_envs: int = 1,
    render_mode: str | None = None,
    render_backend: str | None = None,
    force_torque_noise_sigma: float = SYNTHESISED_FT_NOISE_SIGMA_N,
) -> gym.Env[Any, Any]

Build a :class:Stage1PickPlaceEnv instance (ADR-007 §Stage 1b).

Factory entry point. SAPIEN / ManiSkill imports are deferred to the body so python -c "import chamber.envs.stage1_pickplace" works on a Vulkan-less host (Tier-1 contract). The :class:Stage1PickPlaceEnv class itself is defined inside the factory body — same pattern as :func:chamber.benchmarks.stage0_smoke.make_stage0_env.

Parameters:

• condition_id (str) –

  One of the four Stage-1 condition_id strings; raises :class:ValueError on any other input (cf. :func:resolve_condition).

• episode_length (int, default: DEFAULT_EPISODE_LENGTH ) –

  Truncation horizon, in env ticks. Default :data:DEFAULT_EPISODE_LENGTH (100). See module docstring for the budget rationale.

• root_seed (int, default: 0 ) –

  Project root seed routed to the env's :func:concerto.training.seeding.derive_substream substream for P6 reproducibility (P6 / ADR-002 determinism rule).

• num_envs (int, default: 1 ) –

  ManiSkill vectorisation count; default 1 (the historical single-env cell, byte-identical per ADR-002). > 1 (P1.05.10; ADR-007 §Stage 1b regime-alignment revision) builds the GPU-parallel cell: ManiSkill selects the physx_cuda sim backend, cube/goal randomisation draws from per-env-index derive_substream streams (P6), and the returned wrapper chain is topped with :class:chamber.envs.stage1_vector.Stage1AutoResetWrapper (per-env partial reset on done + info["final_observation"]). The training-time safety stack is not batched in this slice — vectorised cells must run with safety.enabled=false (:meth:Stage1PickPlaceEnv.build_agent_snapshots raises at num_envs > 1).

• render_mode (str | None, default: None ) –

  ManiSkill render_mode (None, "human", "rgb_array", etc.). None (default) disables rendering for the spike-runner path.

• render_backend (str | None, default: None ) –

  ManiSkill render_backend ("gpu", "none", …). None (default) falls through to ManiSkill's own default. The Stage-0 smoke env uses CHAMBER_RENDER_BACKEND env-var probe + the visual-material strip patch; Stage-1b follows the same pattern but exposes the backend choice as a constructor kwarg too.

• force_torque_noise_sigma (float, default: SYNTHESISED_FT_NOISE_SIGMA_N ) –

  sigma of the zero-mean Gaussian noise added to the synthesised force-torque channel, in Newtons. Default :data:SYNTHESISED_FT_NOISE_SIGMA_N. Override only with an ADR-007 §Revision history entry (the value is load-bearing for the OM gate; see module docstring).

Returns:

• Env[Any, Any] –

  class:Stage1PickPlaceEnv instance, ready to call

• Env[Any, Any] –

  reset(seed=K) on. The action space is a

• Env[Any, Any] –

  class:gym.spaces.Dict keyed by the resolved

• Env[Any, Any] –

  attr:ConditionConfig.agent_uids.

Raises:

• ValueError –

  If condition_id is unknown (see :func:resolve_condition).

• ChamberEnvCompatibilityError –

  If ManiSkill / SAPIEN / Vulkan initialisation fails (CPU-only host without a fallback render_backend="none"; see ADR-001 §Risks).

Source code in src/chamber/envs/stage1_pickplace.py

def make_stage1_pickplace_env(
    *,
    condition_id: str,
    episode_length: int = DEFAULT_EPISODE_LENGTH,
    root_seed: int = 0,
    num_envs: int = 1,
    render_mode: str | None = None,
    render_backend: str | None = None,
    force_torque_noise_sigma: float = SYNTHESISED_FT_NOISE_SIGMA_N,
) -> gym.Env[Any, Any]:
    """Build a :class:`Stage1PickPlaceEnv` instance (ADR-007 §Stage 1b).

    Factory entry point. SAPIEN / ManiSkill imports are deferred to the
    body so ``python -c "import chamber.envs.stage1_pickplace"`` works
    on a Vulkan-less host (Tier-1 contract). The
    :class:`Stage1PickPlaceEnv` class itself is defined inside the
    factory body — same pattern as
    :func:`chamber.benchmarks.stage0_smoke.make_stage0_env`.

    Args:
        condition_id: One of the four Stage-1 ``condition_id`` strings;
            raises :class:`ValueError` on any other input
            (cf. :func:`resolve_condition`).
        episode_length: Truncation horizon, in env ticks. Default
            :data:`DEFAULT_EPISODE_LENGTH` (100). See module docstring
            for the budget rationale.
        root_seed: Project root seed routed to the env's
            :func:`concerto.training.seeding.derive_substream` substream
            for P6 reproducibility (P6 / ADR-002 determinism rule).
        num_envs: ManiSkill vectorisation count; default 1 (the
            historical single-env cell, byte-identical per ADR-002).
            ``> 1`` (P1.05.10; ADR-007 §Stage 1b regime-alignment
            revision) builds the GPU-parallel cell: ManiSkill selects
            the ``physx_cuda`` sim backend, cube/goal randomisation
            draws from per-env-index ``derive_substream`` streams (P6),
            and the returned wrapper chain is topped with
            :class:`chamber.envs.stage1_vector.Stage1AutoResetWrapper`
            (per-env partial reset on done +
            ``info["final_observation"]``). The training-time safety
            stack is not batched in this slice — vectorised cells must
            run with ``safety.enabled=false``
            (:meth:`Stage1PickPlaceEnv.build_agent_snapshots` raises at
            ``num_envs > 1``).
        render_mode: ManiSkill ``render_mode`` (``None``,
            ``"human"``, ``"rgb_array"``, etc.). ``None`` (default)
            disables rendering for the spike-runner path.
        render_backend: ManiSkill ``render_backend`` (``"gpu"``,
            ``"none"``, …). ``None`` (default) falls through to
            ManiSkill's own default. The Stage-0 smoke env uses
            ``CHAMBER_RENDER_BACKEND`` env-var probe + the
            visual-material strip patch; Stage-1b follows the same
            pattern but exposes the backend choice as a constructor
            kwarg too.
        force_torque_noise_sigma: sigma of the zero-mean Gaussian noise
            added to the synthesised force-torque channel, in Newtons.
            Default :data:`SYNTHESISED_FT_NOISE_SIGMA_N`. Override only
            with an ADR-007 §Revision history entry (the value is
            load-bearing for the OM gate; see module docstring).

    Returns:
        :class:`Stage1PickPlaceEnv` instance, ready to call
        ``reset(seed=K)`` on. The action space is a
        :class:`gym.spaces.Dict` keyed by the resolved
        :attr:`ConditionConfig.agent_uids`.

    Raises:
        ValueError: If ``condition_id`` is unknown (see
            :func:`resolve_condition`).
        ChamberEnvCompatibilityError: If ManiSkill / SAPIEN / Vulkan
            initialisation fails (CPU-only host without a fallback
            ``render_backend="none"``; see ADR-001 §Risks).
    """
    # Validate condition_id eagerly (the inner __init__ will resolve again,
    # but raising here gives the user a useful traceback in the Tier-1
    # bogus-id path without paying the SAPIEN-import cost).
    resolve_condition(condition_id)
    try:
        import mani_skill.envs  # noqa: F401 - registers ManiSkill env IDs
        import sapien
        import torch
        from mani_skill.envs.sapien_env import BaseEnv
        from mani_skill.utils.building import actors
        from mani_skill.utils.scene_builder.table import TableSceneBuilder
        from mani_skill.utils.structs.pose import Pose

        # Trigger PandaPartner registration before BaseEnv reaches the
        # multi-agent build loop. The chamber.agents package's
        # try/except ensures this import is the place where a Tier-1
        # context would have already failed if it was going to.
        import chamber.agents  # noqa: F401 - side-effect import for register_agent
        from chamber.agents.panda_jacobian import (
            CARTESIAN_POSITION_DIM,
            PANDA_ARM_DOF,
            PandaJacobianProvider,
        )
        from chamber.envs._sapien_compat import (
            load_agent_with_bare_uids,
            patch_sapien_urdf_no_visual_material,
        )
    except ImportError as exc:
        raise ChamberEnvCompatibilityError(
            "Stage1PickPlaceEnv requires mani_skill / sapien / pytorch_kinematics "
            "in the active venv. Install per pyproject.toml; see ADR-001 §Risks."
        ) from exc

    if render_backend == "none":
        # Headless host workaround — same idempotent SAPIEN URDF patch
        # the Stage-0 smoke env relies on (ADR-001 §Risks).
        patch_sapien_urdf_no_visual_material()

    class Stage1PickPlaceEnv(BaseEnv):  # type: ignore[misc, valid-type]
        """Two-robot pick-place env (ADR-007 §Stage 1b; ADR-001 §Decision).

        Subclasses :class:`mani_skill.envs.sapien_env.BaseEnv` directly
        (matching :class:`chamber.benchmarks.stage0_smoke._Stage0SmokeEnv`).
        See the module docstring for the wrapper-only-discipline /
        synthesised-FT / closure-via-env-Jacobian / cooperation-gradient
        rationale.

        Implements the four condition_id strings the AS / OM pre-
        registrations name; the obs-mode superset is set per condition
        at constructor time, the per-uid channel filtering happens in
        :class:`chamber.envs.stage1_obs_filter.Stage1OMChannelFilter`
        (kept separate so the AS path doesn't pay the filter cost).
        """

        SUPPORTED_ROBOTS: ClassVar[list[tuple[str, str]]] = [  # type: ignore[assignment]
            ("panda_wristcam", "panda_partner"),
            ("panda_wristcam", "fetch"),
        ]

        def __init__(
            self,
            *,
            condition_id: str,
            episode_length: int,
            root_seed: int,
            num_envs: int,
            render_mode: str | None,
            render_backend: str | None,
            force_torque_noise_sigma: float,
        ) -> None:
            """Build the env (ADR-007 §Stage 1b).

            Stores the condition-resolved metadata, sets up the
            determinism harness, then calls
            ``super().__init__(robot_uids=config.agent_uids, ...)``.
            The Jacobian provider is constructed *after* the super-init
            because it reads the panda's URDF directly (independent of
            SAPIEN scene state); the closure plumbed into
            :meth:`build_control_models` then reads ``self._latest_qpos``
            which the env updates each :meth:`_before_simulation_step`.
            """
            self._condition_config: ConditionConfig = resolve_condition(condition_id)
            self._episode_length: int = int(episode_length)
            self._root_seed: int = int(root_seed)
            self._force_torque_noise_sigma: float = float(force_torque_noise_sigma)
            self._rng: np.random.Generator = derive_substream(
                _SUBSTREAM_NAME, root_seed=self._root_seed
            ).default_rng()
            # P1.05.10 (ADR-007 §Stage 1b regime-alignment; P6 / ADR-002):
            # per-env-index cube/goal substreams for vectorised builds.
            # Each parallel env's episode randomisation draws from its own
            # independently-derived stream, advanced only when that env
            # resets — so the draw sequence per env is reproducible
            # regardless of how partial resets interleave across the
            # batch. num_envs==1 keeps the single shared ``self._rng``
            # (cube/goal + FT noise interleaved on one stream) so the
            # historical 1-env path stays byte-identical on CPU.
            self._num_envs_requested: int = int(num_envs)
            self._env_rngs: list[np.random.Generator] = (
                [
                    derive_substream(
                        f"{_SUBSTREAM_NAME}.env{i:04d}", root_seed=self._root_seed
                    ).default_rng()
                    for i in range(self._num_envs_requested)
                ]
                if self._num_envs_requested > 1
                else []
            )
            # Per-uid latest qpos cache for the Jacobian closure; populated
            # before each ``step``. See module docstring on the closure-
            # via-env-reference workaround (decision Q3 mod 3; ADR-004
            # §Open questions / slice P1.05.5).
            self._latest_qpos: dict[str, NDArray[np.float64]] = {}
            # PickCubeEnv-style task parameters; consistent with the
            # upstream defaults so the success / reward shaping path
            # behaves predictably under the multi-agent rig.
            self._cube_half_size: float = 0.02
            self._goal_thresh: float = 0.025
            self._cube_spawn_half_size: float = 0.05
            self._cube_spawn_center: tuple[float, float] = (0.0, 0.0)
            self._max_goal_height: float = 0.3
            # Attributes that ``_initialize_episode`` / ``_before_simulation_step``
            # touch MUST be assigned before ``super().__init__()``: ManiSkill's
            # ``BaseEnv.__init__`` calls ``self.reset(...)`` during super-init
            # (mani_skill/envs/sapien_env.py:327), which invokes
            # ``_initialize_episode`` *and* the post-reset qpos primer below
            # before the subclass body resumes. Subclass attributes written
            # after super-init do not yet exist when those hooks fire.
            self._panda_arm_dof: int = PANDA_ARM_DOF
            # Per-uid cache for the numerical-difference velocity in
            # build_agent_snapshots (D8 of the P1.04.5 design pass).
            # Cleared by _initialize_episode at every reset so the
            # cross-episode position delta doesn't produce a spurious
            # first-step velocity. The first-step velocity defaults to
            # zero on each fresh episode (the agents start at rest by
            # construction).
            self._prev_positions: dict[str, NDArray[np.float64]] = {}
            try:
                super().__init__(
                    robot_uids=self._condition_config.agent_uids,  # type: ignore[arg-type]
                    num_envs=num_envs,
                    obs_mode=self._condition_config.obs_mode,
                    control_mode="pd_joint_delta_pos",
                    render_mode=render_mode,
                    render_backend=render_backend if render_backend is not None else "gpu",
                )
            except RuntimeError as exc:
                raise ChamberEnvCompatibilityError(
                    "SAPIEN/Vulkan initialisation failed during "
                    f"Stage1PickPlaceEnv(condition_id={condition_id!r}) build: "
                    f"{exc}\nSet CHAMBER_RENDER_BACKEND=none (or "
                    'render_backend="none") on CUDA-only hosts; see ADR-001 §Risks.'
                ) from exc
            # Jacobian provider is wristcam-URDF based; the partner
            # (panda_partner) shares the kinematic chain so a single
            # provider serves both panda uids. ``panda_v2.urdf`` and
            # ``panda_v3.urdf`` differ only in the wristcam mount
            # (extrinsic frame); the 7 arm joints + TCP link are
            # identical, so reusing the v3-URDF chain for the partner
            # introduces no error in the linear Jacobian.
            self._jacobian_provider: PandaJacobianProvider = PandaJacobianProvider()
            # Per-uid safety radii (Q3 of the P1.04.5 design pass).
            # Asserted at construction against URDF-envelope minimums.
            self._safety_radii: dict[str, float] = {
                uid: PANDA_SAFETY_RADIUS_M
                if uid in ("panda_wristcam", "panda_partner")
                else FETCH_SAFETY_RADIUS_M
                for uid in self._condition_config.agent_uids
            }
            _validate_safety_radii(self._safety_radii)

        # ----- ManiSkill v3 BaseEnv hooks -----

        @property
        def _default_human_render_camera_configs(self) -> Any:  # noqa: ANN401 - ManiSkill CameraConfig has no project type
            """Third-person render camera for rollout visualisation (ADR-007 §Stage 1b).

            The Stage-1b env subclasses :class:`BaseEnv` directly and
            otherwise defines no human-render camera, so ``env.render()``
            returns ``None`` and a saved checkpoint cannot be visualised.
            This adds a single fixed third-person camera looking at the
            table workspace so a checkpoint can be rolled out and rendered
            to RGB frames (reach / grasp / lift inspection). Render-only:
            it feeds neither any observation channel nor the gate contract,
            so it does not affect determinism or the comparison protocol.
            """
            from mani_skill.sensors.camera import CameraConfig
            from mani_skill.utils import sapien_utils

            pose = sapien_utils.look_at(eye=[0.7, 0.7, 0.6], target=[0.0, 0.0, 0.1])
            return CameraConfig(
                "render_camera",
                pose=pose,
                width=640,
                height=480,
                fov=1.0,
                near=0.01,
                far=100.0,
            )

        def _load_agent(  # type: ignore[override]
            self,
            options: dict[str, Any],
            initial_agent_poses: object = None,
            build_separate: bool = False,
        ) -> None:
            """Multi-robot ``_load_agent`` override with per-uid base poses.

            Delegates to
            :func:`chamber.envs._sapien_compat.load_agent_with_bare_uids`
            for the suffix-strip rebind. Passes an explicit per-agent
            pose list so the two robots don't collide at the table
            origin.
            """
            if initial_agent_poses is None:
                poses: list[object] = []
                for uid in self.robot_uids:  # type: ignore[union-attr]
                    xyz = _AGENT_BASE_POSE_XYZ.get(uid)
                    if xyz is None:
                        # Unknown uid (shouldn't happen given the
                        # condition table) — leave SAPIEN to use URDF
                        # default root pose.
                        poses.append(None)
                    else:
                        poses.append(sapien.Pose(p=list(xyz)))
                initial_agent_poses = poses
            load_agent_with_bare_uids(
                self,
                options,
                initial_agent_poses=initial_agent_poses,
                build_separate=build_separate,
            )

        def _load_scene(self, options: dict[str, Any]) -> None:
            """Build the table + cube + goal site (PickCubeEnv recipe; ADR-007 §Stage 1b)."""
            del options
            # NOTE: ``robot_init_qpos_noise`` is INERT for the AS robot_uids tuples —
            # TableSceneBuilder.initialize() has no branch for them, so it never
            # applies the noise (nor sets any robot qpos). The canonical reset pose
            # is written deterministically in _initialize_episode (ADR-007 Rev 16);
            # do NOT "restore parity" by re-adding init noise via torch.rand — route
            # any future perturbation through self._rng (P6 / ADR-002).
            self.table_scene = TableSceneBuilder(self, robot_init_qpos_noise=0.02)
            self.table_scene.build()
            self.cube = actors.build_cube(
                self.scene,
                half_size=self._cube_half_size,
                color=[1, 0, 0, 1],
                name="cube",
                initial_pose=sapien.Pose(p=[0, 0, self._cube_half_size]),
            )
            self.goal_site = actors.build_sphere(
                self.scene,
                radius=self._goal_thresh,
                color=[0, 1, 0, 1],
                name="goal_site",
                body_type="kinematic",
                add_collision=False,
                initial_pose=sapien.Pose(),
            )
            self._hidden_objects.append(self.goal_site)  # type: ignore[attr-defined]

        def _initialize_episode(self, env_idx: torch.Tensor, options: dict[str, Any]) -> None:
            """Reset cube + goal poses per episode (P6 determinism via :attr:`_rng`)."""
            del options
            # Clear the per-agent position cache so build_agent_snapshots'
            # first-step velocity (numerical-difference) defaults to
            # zero on each fresh episode rather than diffing against
            # the previous episode's final position (R2 of the P1.04.5
            # risk register).
            self._prev_positions.clear()
            with torch.device(self.device):  # type: ignore[attr-defined]
                b = len(env_idx)
                self.table_scene.initialize(env_idx)
                # Reset-state init (ADR-007 §Stage 1b Rev 16). The upstream
                # TableSceneBuilder has no branch for the AS robot_uids tuples
                # and no terminal else, so it never set these robots' qpos —
                # every episode otherwise started with the arm folded at zero and
                # the gripper closed. Set each agent's canonical ready pose +
                # open gripper here, mirroring the builder's covered branches.
                # Deterministic (no init noise) so two reset(seed=K) calls stay
                # byte-identical on CPU (P6 / ADR-002); a noise term, if added
                # later, MUST draw from self._rng (not torch.rand, not the
                # builder's _episode_rng). Base poses are owned by _load_agent.
                for uid in self.robot_uids:  # type: ignore[union-attr]
                    ready = _READY_QPOS_BY_UID.get(uid)
                    if ready is None:
                        continue
                    qpos = torch.from_numpy(np.tile(ready, (b, 1)).astype(np.float32)).to(
                        self.device
                    )
                    self.agent.agents_dict[uid].reset(qpos)  # type: ignore[attr-defined]
                # Cube xy uniform in the spawn box; z at half-size so it
                # rests on the table surface. Routed through the env's
                # P6-harnessed RNG instead of torch.rand so two
                # reset(seed=K) calls reproduce byte-identical state
                # (P6 / ADR-002 determinism rule). Vectorised builds
                # (P1.05.10) draw each resetting env's cube/goal from its
                # own per-env-index substream (see __init__) so partial-
                # reset interleaving cannot perturb another env's stream.
                env_indices: list[int] = (
                    [int(i) for i in env_idx.detach().cpu().tolist()] if self._env_rngs else []
                )
                if self._env_rngs:
                    xy_cube_np = np.stack(
                        [
                            self._env_rngs[i].uniform(
                                -self._cube_spawn_half_size, self._cube_spawn_half_size, size=2
                            )
                            for i in env_indices
                        ]
                    )
                else:
                    xy_cube_np = self._rng.uniform(
                        -self._cube_spawn_half_size, self._cube_spawn_half_size, size=(b, 2)
                    )
                # .to(self.device): from_numpy tensors are CPU-resident;
                # GPU-parallel builds (P1.05.10) run the scene on cuda and
                # mixed-device arithmetic below would raise. No-op on CPU sim.
                xy_cube = torch.from_numpy(np.asarray(xy_cube_np, dtype=np.float32)).to(self.device)
                xyz = torch.zeros((b, 3))
                xyz[:, 0] = xy_cube[:, 0] + self._cube_spawn_center[0]
                xyz[:, 1] = xy_cube[:, 1] + self._cube_spawn_center[1]
                xyz[:, 2] = self._cube_half_size
                # No rotation randomisation in P1.03 — upstream PickCubeEnv
                # uses ``randomization.random_quaternions(b, lock_x=True,
                # lock_y=True)``; for the two-robot env the orientation
                # matters less than the position. Re-enable if pilot data
                # shows it changes the AS gap.
                self.cube.set_pose(Pose.create_from_pq(xyz))

                # Goal xy in the same envelope; z uniform in [0, max].
                if self._env_rngs:
                    xy_goal_np = np.stack(
                        [
                            self._env_rngs[i].uniform(
                                -self._cube_spawn_half_size, self._cube_spawn_half_size, size=2
                            )
                            for i in env_indices
                        ]
                    )
                    z_goal_np = np.stack(
                        [self._env_rngs[i].uniform(0.0, self._max_goal_height) for i in env_indices]
                    )
                else:
                    xy_goal_np = self._rng.uniform(
                        -self._cube_spawn_half_size, self._cube_spawn_half_size, size=(b, 2)
                    )
                    z_goal_np = self._rng.uniform(0.0, self._max_goal_height, size=(b,))
                xy_goal = torch.from_numpy(np.asarray(xy_goal_np, dtype=np.float32)).to(self.device)
                z_goal = torch.from_numpy(np.asarray(z_goal_np, dtype=np.float32)).to(self.device)
                goal_xyz = torch.zeros((b, 3))
                goal_xyz[:, 0] = xy_goal[:, 0] + self._cube_spawn_center[0]
                goal_xyz[:, 1] = xy_goal[:, 1] + self._cube_spawn_center[1]
                goal_xyz[:, 2] = z_goal + xyz[:, 2]
                self.goal_site.set_pose(Pose.create_from_pq(goal_xyz))
            # Prime the qpos cache so the Jacobian closure has a valid
            # value at the first safety-filter call. The training loop
            # in ``concerto.training.ego_aht.train`` queries the filter
            # *before* the first ``env.step()`` (act-then-step order),
            # so the per-physics-step ``_before_simulation_step`` hook
            # has not yet fired after a reset. Without this primer the
            # closure raises the "qpos not yet cached" guard.
            self._refresh_latest_qpos()

        def step(self, action: Any) -> tuple[Any, Any, Any, Any, dict[str, Any]]:  # type: ignore[override]  # noqa: ANN401 - ManiSkill action/obs/info are unconstrained dict-of-tensors
            """Enforce the ``episode_length`` time-limit truncation (ADR-007 §Stage 1b).

            ManiSkill v3's :meth:`BaseEnv.step` hard-codes ``truncated=False``
            (``mani_skill/envs/sapien_env.py`` L1069): time-limit truncation is
            normally supplied by the gym ``TimeLimit`` wrapper that ``gym.make``
            adds, which a *directly*-instantiated ``BaseEnv`` subclass does not
            have. Without this override the env never emits ``truncated=True``,
            so the training loop (:func:`concerto.training.ego_aht.train`, which
            resets only on ``terminated | truncated``) never re-initialises an
            episode — the cube/goal are sampled once and the GAE sees a
            non-terminating MDP whose critic converges to the infinite-horizon
            value ``r/(1-gamma)`` with collapsed advantages (root cause
            ENV-NO-TRUNCATION; firing ``2026-05-24-p1-05-9``). We truncate when
            ``BaseEnv``'s own ``elapsed_steps`` property (its step counter,
            incremented in ``super().step`` and reset per episode at
            ``sapien_env.py`` L927) reaches ``episode_length`` — read through
            the public property rather than the underlying ``_elapsed_steps``
            attribute (ADR-001 wrapper-only). This is the ``BaseEnv``-subclass
            analogue of
            the ``_step_count >= _episode_length`` time-limit the sibling envs
            (:mod:`chamber.envs.mpe_cooperative_push`,
            :mod:`chamber.benchmarks.stage0_smoke_adapter`) apply. Reward-,
            obs-, and render-neutral: only the ``truncated`` flag changes, so
            the comparison protocol and determinism contract are untouched
            beyond the (intended) per-episode reset cadence.
            """
            obs, reward, terminated, truncated, info = super().step(action)
            truncated = truncated | (self.elapsed_steps >= self._episode_length)
            return obs, reward, terminated, truncated, info

        # ----- Observation / reward / success (panda-routed; ADR-007 §Stage 1b) -----

        @property
        def _panda_agent(self) -> Any:  # noqa: ANN401 - ManiSkill Panda agent has no project type
            """Return the panda_wristcam :class:`Panda` agent instance (ego).

            Routes through ``self.agent.agents_dict`` instead of the
            single-agent ``self.agent`` attribute upstream PickCubeEnv
            relies on. Used by :meth:`evaluate` and
            :meth:`compute_normalized_dense_reward` so the success
            predicates and reward shaping respect the multi-agent rig.
            """
            return self.agent.agents_dict["panda_wristcam"]  # type: ignore[attr-defined, no-any-return]

        def _get_obs_extra(self, info: dict[str, Any]) -> dict[str, Any]:
            """Inject task obs + synthesised force-torque (ADR-007 §Stage 1b).

            Extras include:

            - ``tcp_pose`` — panda end-effector pose (mirrors upstream
              PickCubeEnv).
            - ``goal_pos`` — the goal site's xyz position.
            - ``cube_pose`` / ``cube_to_tcp_pos`` / ``cube_to_goal_pos``
              — present only when ``"state"`` is in the env's
              ``obs_mode`` (matches upstream PickCubeEnv's branch).
            - **``force_torque`` (this env's contribution)** — a 6-D
              Cartesian force vector per panda fingertip
              (``[fx_l, fy_l, fz_l, fx_r, fy_r, fz_r]``), synthesised
              from
              :meth:`PhysxArticulation.get_net_contact_forces([finger_links])`
              plus zero-mean sigma=:data:`SYNTHESISED_FT_NOISE_SIGMA_N`
              Gaussian noise routed through the env's P6-harnessed RNG.
              **Not** a real Panda wrist FT sensor reading; see module
              docstring and ADR-007 §Open questions for the wrist-mount
              ablation deferral.
            """
            del info
            panda = self._panda_agent
            obs: dict[str, Any] = {
                "tcp_pose": panda.tcp_pose.raw_pose,
                "goal_pos": self.goal_site.pose.p,
            }
            if "state" in self.obs_mode:  # type: ignore[operator]
                obs["cube_pose"] = self.cube.pose.raw_pose
                obs["cube_to_tcp_pos"] = self.cube.pose.p - panda.tcp_pose.p
                obs["cube_to_goal_pos"] = self.goal_site.pose.p - self.cube.pose.p
            # Synthesised FT: always injected so the OM channel-filter
            # wrapper has something to keep/zero per condition. The
            # AS conditions' state_dict obs_mode ignores it downstream.
            obs["force_torque"] = self._compute_synthesised_force_torque()
            return obs

        def _compute_synthesised_force_torque(self) -> NDArray[np.float32]:
            """Synthesise the 6-D fingertip-contact FT vector (ADR-007 §Stage 1b)."""
            panda = self._panda_agent
            fingers = ["panda_leftfinger", "panda_rightfinger"]
            try:
                # ``get_net_contact_forces`` returns shape ``(N_envs, n_links, 3)``
                # (Cartesian force per link) at SAPIEN's contact-manager
                # boundary (mani_skill/utils/structs/articulation.py:490).
                forces = panda.robot.get_net_contact_forces(fingers)
            except (RuntimeError, KeyError):
                # Finger links not yet registered (pre-reset state) —
                # return zeros so the wrapper-chain shape stays stable.
                return np.zeros((1, 6), dtype=np.float32)
            f_np = np.asarray(forces.detach().cpu(), dtype=np.float32)  # type: ignore[union-attr]
            # Flatten the per-link Cartesian force into a 6-D vector;
            # add zero-mean Gaussian noise from the P6-harnessed RNG so
            # the OM-hetero gate's signal-to-noise lands at the
            # documented Franka-spec lower bound.
            flat = f_np.reshape(f_np.shape[0], -1)  # (N_envs, 6)
            if self._force_torque_noise_sigma > 0.0:
                noise = self._rng.normal(
                    loc=0.0,
                    scale=self._force_torque_noise_sigma,
                    size=flat.shape,
                ).astype(np.float32)
                flat = flat + noise
            return flat

        def evaluate(self) -> dict[str, Any]:
            """ADR-007 §Stage 1b: multi-agent success predicate (panda-routed)."""
            panda = self._panda_agent
            is_obj_placed = (
                torch.linalg.norm(self.goal_site.pose.p - self.cube.pose.p, axis=1)
                <= self._goal_thresh
            )
            is_grasped = panda.is_grasping(self.cube)
            is_robot_static = panda.is_static(0.2)
            return {
                "success": is_obj_placed & is_robot_static,
                "is_obj_placed": is_obj_placed,
                "is_robot_static": is_robot_static,
                "is_grasped": is_grasped,
            }

        def privileged_settle_state(self) -> dict[str, Any]:
            """Privileged Phi inputs for the settle wrapper (ADR-007 §Stage 1b Rev 18; #232).

            Training-time reward computation is privileged by
            construction: these reads come from the same live handles
            :meth:`compute_normalized_dense_reward` and :meth:`evaluate`
            already use, never from the (possibly condition-filtered)
            observation — the OM vision-only keep-set zero-masks
            ``cube_pose`` and the per-uid proprio, so an obs-derived
            potential would differ between the two OM conditions and
            violate the Rev 18 condition-symmetry mandate.

            Returns:
                ``ego_qvel`` — the ego panda's full joint velocity
                (``(num_envs, 9)``; the wrapper applies the arm-only
                reduction), ``cube_pos`` / ``goal_pos`` — xyz positions
                (``(num_envs, 3)``), all live torch tensors.
            """
            return {
                "ego_qvel": self._panda_agent.robot.get_qvel(),
                "cube_pos": self.cube.pose.p,
                "goal_pos": self.goal_site.pose.p,
            }

        def compute_normalized_dense_reward(
            self,
            obs: Any,  # noqa: ANN401 - ManiSkill obs is an unconstrained dict-of-tensors
            action: Any,  # noqa: ANN401 - ManiSkill action is an unconstrained dict-of-tensors
            info: dict[str, Any],
        ) -> Any:  # noqa: ANN401 - upstream returns torch tensor, no project type
            """ADR-007 §Stage 1b: multi-agent normalised dense reward (panda-routed).

            Matches the upstream ``PickCubeEnv.compute_dense_reward`` shape
            (reaching + grasp + place * grasp + static * placed + 5*success)
            divided by 5. The reward signal is panda-centric (the panda
            does the picking); the fetch / partner is graded implicitly
            through whether it gets out of the way / cooperates on
            placement — explicit fetch-side reward shaping is a P1.04
            follow-up.
            """
            del obs, action
            panda = self._panda_agent
            tcp_to_obj_dist = torch.linalg.norm(self.cube.pose.p - panda.tcp_pose.p, axis=1)
            reaching_reward = 1 - torch.tanh(5 * tcp_to_obj_dist)
            reward = reaching_reward
            is_grasped = info["is_grasped"]
            reward = reward + is_grasped
            obj_to_goal_dist = torch.linalg.norm(self.goal_site.pose.p - self.cube.pose.p, axis=1)
            place_reward = 1 - torch.tanh(5 * obj_to_goal_dist)
            reward = reward + place_reward * is_grasped
            qvel = panda.robot.get_qvel()
            qvel = qvel[..., :-2]  # drop the two gripper-finger DOF
            static_reward = 1 - torch.tanh(5 * torch.linalg.norm(qvel, axis=1))
            reward = reward + static_reward * info["is_obj_placed"]
            reward[info["success"]] = 5
            return reward / 5

        # ----- Per-step qpos refresh (Jacobian closure feed) -----

        def _refresh_latest_qpos(self) -> None:
            """Snapshot every panda uid's arm qpos into :attr:`_latest_qpos`.

            P1.04.5; ADR-007 §Stage 1b. Called from both
            :meth:`_before_simulation_step` (each physics step) and
            :meth:`_initialize_episode` (post-reset primer). The latter
            primes the cache between ``env.reset()`` and the first
            ``env.step()`` so the safety filter — which the training
            loop runs *before* the first step — can read a valid qpos
            without raising the "qpos not yet cached" guard.
            """
            for uid in self.robot_uids:  # type: ignore[union-attr]
                if uid in ("panda_wristcam", "panda_partner"):
                    agent = self.agent.agents_dict[uid]  # type: ignore[attr-defined]
                    full_qpos = agent.robot.get_qpos()
                    # Slice off the 2 gripper-finger joints; the
                    # Jacobian chain to panda_hand_tcp covers the 7 arm
                    # joints only.
                    qpos_arm = np.asarray(
                        full_qpos.detach().cpu(),
                        dtype=np.float64,  # type: ignore[union-attr]
                    ).reshape(-1)[: self._panda_arm_dof]
                    self._latest_qpos[uid] = qpos_arm

        def _before_simulation_step(self) -> None:
            """Cache panda arm qpos before each physics step (Jacobian closure feed).

            The :class:`JacobianControlModel` callable wired by
            :meth:`build_control_models` reads
            ``self._latest_qpos["panda_wristcam"]`` to compute the
            Jacobian at the current configuration. ManiSkill's
            :class:`BaseEnv` calls this hook once per physics step
            before SAPIEN advances; updating the cache here gives the
            closure access to the most recent qpos at the next safety-
            filter invocation. See module docstring on the closure-
            via-env-reference workaround (P1.05.5 contingent
            follow-up).
            """
            super()._before_simulation_step()
            self._refresh_latest_qpos()

        # ----- Public API for the safety-stack consumer -----

        @property
        def condition_id(self) -> str:
            """ADR-007 §Stage 1b: the :attr:`ConditionConfig.condition_id` this env was built for."""  # noqa: E501
            return self._condition_config.condition_id

        @property
        def condition_config(self) -> ConditionConfig:
            """The resolved :class:`ConditionConfig` for read-only consumers (ADR-007 §Stage 1b)."""
            return self._condition_config

        @property
        def num_envs_requested(self) -> int:
            """ADR-007 §Stage 1b regime-alignment: the ``num_envs`` this env was built with.

            Exposed so the vector auto-reset wrapper
            (:class:`chamber.envs.stage1_vector.Stage1AutoResetWrapper`)
            and the Tier-2 tests can read the requested parallelisation
            count without reaching for ManiSkill's internal attribute.
            """
            return self._num_envs_requested

        @property
        def ego_uid(self) -> str:
            """ADR-007 §Stage 1b: the ego uid for the active condition.

            First element of :attr:`ConditionConfig.agent_uids` by the
            Phase-0 ``_CONDITION_UIDS`` convention. Consumed by the
            Phase-1 :class:`chamber.benchmarks.stage1_common.TrainedPolicyFactory`
            (P1.04) so the factory can read the ego uid from the env
            rather than from a side-table — single source of truth at
            the env layer.
            """
            return self._condition_config.agent_uids[0]

        @property
        def partner_uid(self) -> str:
            """ADR-007 §Stage 1b: the partner uid for the active condition.

            Second element of :attr:`ConditionConfig.agent_uids` (the
            ego is the first; the partner is the second by the Phase-0
            ``_CONDITION_UIDS`` convention from
            :mod:`chamber.benchmarks.stage1_as` /
            :mod:`chamber.benchmarks.stage1_om`). Consumed by the
            Phase-1 :class:`chamber.benchmarks.stage1_common.TrainedPolicyFactory`
            (P1.04) to route the per-condition partner-stack dispatch
            (``panda_partner`` for AS-homo; ``fetch`` for AS-hetero /
            OM-*). Single source of truth at the env layer — future
            Stage-2/3 envs (P1.06+) follow the same property contract
            without needing a factory-side dispatch table.
            """
            return self._condition_config.agent_uids[1]

        def build_control_models(self) -> Mapping[str, AgentControlModel]:
            """Return per-uid :class:`AgentControlModel` map (ADR-004 §Decision).

            Plumbed in by
            :func:`chamber.benchmarks.training_runner.build_control_models`
            via the ``getattr(env, "build_control_models", None)``
            delegation route (P1.03 / Task B).

            The Jacobian callable is the closure-via-env-reference
            workaround documented in the module docstring: it captures
            ``self`` and reads ``self._latest_qpos["panda_wristcam"]``
            at call time. The closure stays valid across the 20
            evaluation episodes within each ``(seed, condition)`` cell
            because
            :func:`chamber.benchmarks.stage1_as._run_axis_with_factories`
            builds the env once per cell and reuses it
            (``stage1_as.py:253-275``).

            For the AS-homo condition both panda uids share the same
            Jacobian provider (their kinematic chains are identical;
            see :class:`chamber.agents.panda_jacobian.PandaJacobianProvider`'s
            choice of URDF). The closure resolves to the correct uid's
            latest qpos at call time.
            """
            # Source the panda action dim from the action space (same
            # path the fetch dim is sourced from below). Falls back to
            # 8 — the ``pd_joint_delta_pos`` default (7 arm + 1 mimic-
            # gripper). The closure captures this value once at
            # build-time, which is correct: action-space shape is fixed
            # over an env's lifetime.
            panda_action_dim = 8
            action_space = self.action_space
            if isinstance(action_space, gym.spaces.Dict):
                sub_panda = action_space.spaces.get("panda_wristcam")
                if isinstance(sub_panda, gym.spaces.Box) and sub_panda.shape is not None:
                    panda_action_dim = int(sub_panda.shape[0])

            def _panda_jacobian(snap: AgentSnapshot) -> NDArray[np.float64]:
                # Pull the live qpos from the env's cache; the closure
                # captures self by reference so the latest pre-step
                # value is always used.
                qpos = self._latest_qpos.get("panda_wristcam")
                if qpos is None:
                    msg = (
                        "Stage1PickPlaceEnv: panda_wristcam qpos not yet cached. "
                        "The JacobianControlModel closure was invoked before "
                        "the first env.step() — reset the env first."
                    )
                    raise RuntimeError(msg)
                # PandaJacobianProvider returns the linear (3, 7) Jacobian
                # for the 7-joint chain to ``panda_hand_tcp``. The
                # ``pd_joint_delta_pos`` control mode's panda action is
                # 8-D (7 arm deltas + 1 mimic-gripper delta — see the
                # ``panda_action_dim=8`` default in
                # :func:`build_control_models_for_condition`). Pad with
                # a zero column so the JacobianControlModel matmul
                # ``jac @ action`` composes: the mimic-gripper joint is
                # a sibling of ``panda_hand``, not in the TCP kinematic
                # chain, so its contribution to TCP Cartesian position
                # is zero by construction.
                jac_3x7 = self._jacobian_provider(snap, qpos)
                jac_padded = np.zeros((CARTESIAN_POSITION_DIM, panda_action_dim), dtype=np.float64)
                jac_padded[:, : self._panda_arm_dof] = jac_3x7
                return jac_padded

            fetch_uid_dim: int | None = None
            partner_uid = self._condition_config.agent_uids[1]
            if partner_uid == "fetch" and isinstance(action_space, gym.spaces.Dict):
                sub = action_space.spaces.get(partner_uid)
                if isinstance(sub, gym.spaces.Box) and sub.shape is not None:
                    fetch_uid_dim = int(sub.shape[0])
            return build_control_models_for_condition(
                self._condition_config.condition_id,
                jacobian_fn=_panda_jacobian,
                fetch_action_dim=fetch_uid_dim,
                panda_action_dim=panda_action_dim,
            )

        # ----- P1.04.5: safety-stack snapshot + bounds wiring -----

        def build_agent_snapshots(self) -> dict[str, AgentSnapshot]:
            """Build per-uid Cartesian :class:`AgentSnapshot` map (P1.04.5; ADR-007 §Stage 1b).

            Reads each agent's Cartesian position (TCP pose for the
            pandas; base-link pose for the fetch) and computes velocity
            via numerical-difference against the cached
            :attr:`_prev_positions` from the previous step. First-step
            velocity defaults to zero on every fresh episode (the
            agents start at rest by construction; the cache is cleared
            in :meth:`_initialize_episode`).

            Used by the P1.04.5 safety-stack integration: the
            :func:`concerto.training.ego_aht.train` loop calls this
            once per step (when the safety filter is wired) to build
            the snapshot map the CBF-QP outer filter consumes via the
            ``partner_predicted_states`` kwarg + the conformal update's
            ``snaps_now`` / ``snaps_prev`` pair.

            Returns:
                ``{uid: AgentSnapshot(position, velocity, radius)}`` for
                every uid in :attr:`ConditionConfig.agent_uids`. Position
                is the 3-D Cartesian centre (panda TCP for the pandas;
                fetch base origin for the fetch); velocity is the
                numerical-difference against the previous call (zero on
                first call after :meth:`_initialize_episode`); radius
                is from :data:`PANDA_SAFETY_RADIUS_M` /
                :data:`FETCH_SAFETY_RADIUS_M` (validated at env
                construction by :func:`_validate_safety_radii`).
            """
            # P1.05.10 (ADR-007 §Stage 1b regime-alignment): the snapshot
            # map is a per-pair scalar contract (AgentSnapshot is one 3-D
            # Cartesian body per uid) consumed by the un-batched CBF-QP /
            # conformal / braking stack. Vectorised builds have no batched
            # safety stack in this slice — ``train()`` loud-fails when
            # ``num_envs > 1`` and ``cfg.safety.enabled=True`` — so a
            # multi-env call here is always a wiring bug. Raise rather
            # than silently slicing env 0 (the pre-P1.05.10 defensive
            # slice would have mis-reported env 0's geometry as the
            # whole cell's).
            if self._num_envs_requested > 1:
                msg = (
                    "Stage1PickPlaceEnv.build_agent_snapshots: not supported at "
                    f"num_envs={self._num_envs_requested} — the safety-stack "
                    "snapshot contract is single-env (ADR-004 §Decision; "
                    "ADR-007 §Stage 1b regime-alignment revision). Run "
                    "vectorised training with safety.enabled=false (operator "
                    "override), or build a num_envs=1 cell for filtered runs."
                )
                raise RuntimeError(msg)
            snapshots: dict[str, AgentSnapshot] = {}
            for uid in self._condition_config.agent_uids:
                agent = self.agent.agents_dict[uid]  # type: ignore[attr-defined]
                if uid in ("panda_wristcam", "panda_partner"):
                    # Panda: TCP pose. Squeeze the (num_envs=1, 3)
                    # batch dim to a flat 3-vector for the AgentSnapshot.
                    pos_raw = agent.tcp_pose.p
                else:
                    # Fetch: base-link pose (the robot's root pose).
                    pos_raw = agent.robot.get_pose().p
                position = np.asarray(
                    pos_raw.detach().cpu(),
                    dtype=np.float64,  # type: ignore[union-attr]
                ).reshape(-1)
                _cartesian_dim = 3  # ADR-004 §Decision: AgentSnapshot is 3-D Cartesian.
                if position.shape[0] > _cartesian_dim:
                    position = position[:_cartesian_dim]
                prev = self._prev_positions.get(uid)
                if prev is None:
                    velocity = np.zeros(3, dtype=np.float64)
                else:
                    # Numerical-difference velocity. The dt is the
                    # control_timestep; for the AgentSnapshot's contract
                    # this is the per-step Cartesian velocity. The
                    # safety filter's conformal update consumes this
                    # value alongside dt to compute the predicted
                    # pose; the consistency is the caller's
                    # responsibility (see
                    # chamber.benchmarks.training_runner.build_safety_dt).
                    velocity = (position - prev) / float(self.control_timestep)
                self._prev_positions[uid] = position
                snapshots[uid] = AgentSnapshot(
                    position=position,
                    velocity=velocity,
                    radius=self._safety_radii[uid],
                )
            return snapshots

        def build_bounds(self) -> Bounds:
            """Build the per-task :class:`Bounds` envelope (P1.04.5; ADR-006 §Decision).

            Sourced from the module-level constants pinned in P1.03
            (cartesian_accel_capacity) plus sensible Phase-1 defaults
            for the remaining fields. Consumed by the safety filter +
            the audit-gate predicate A's RHS (``cartesian_accel_capacity``).
            """
            return Bounds(
                action_linf_component=0.1,
                cartesian_accel_capacity=PANDA_CARTESIAN_ACCEL_CAPACITY_MS2,
                action_rate=10.0,
                comm_latency_ms=0.0,
                force_limit=50.0,
            )

    inner = Stage1PickPlaceEnv(
        condition_id=condition_id,
        episode_length=episode_length,
        root_seed=root_seed,
        num_envs=num_envs,
        render_mode=render_mode,
        render_backend=render_backend,
        force_torque_noise_sigma=force_torque_noise_sigma,
    )
    # AS conditions: ManiSkill v3 obs_mode="state_dict" emits per-agent
    # Dict(qpos, qvel) but EgoPPOTrainer.from_config reads
    # obs["agent"][ego_uid]["state"]. The AS synthesizer adds that key;
    # pass-through for OM conditions. The OM channel filter then masks
    # per-condition for OM-vision-only; pass-through for AS and OM-hetero.
    # Wired in fixed order so OM callers of the factory don't have to
    # wrap manually (issue #165 §Proposed scope 4).
    from chamber.envs.stage1_obs_filter import (
        Stage1ASStateSynthesizer,
        Stage1OMChannelFilter,
    )

    wrapped: gym.Env[Any, Any] = Stage1OMChannelFilter(Stage1ASStateSynthesizer(inner))
    if num_envs > 1:
        # P1.05.10 (ADR-007 §Stage 1b regime-alignment): vectorised
        # builds get the chamber-side auto-reset wrapper outermost so
        # the training loop sees standard vector semantics (per-env
        # partial reset on done; pre-reset final obs surfaced via
        # ``info["final_observation"]`` for the Pardo truncation
        # bootstrap). Single-env builds keep the historical
        # reset-from-the-loop contract byte-identically (ADR-002).
        from chamber.envs.stage1_vector import Stage1AutoResetWrapper

        wrapped = Stage1AutoResetWrapper(wrapped)
    return wrapped

resolve_condition

resolve_condition(condition_id: str) -> ConditionConfig

Resolve a pre-registered condition_id to its config (ADR-007 §Stage 1b).

Pure Tier-1 function — no SAPIEN dependency. Tier-1 tests pin the four-condition coverage and the ValueError raise on bogus IDs.

Parameters:

• condition_id (str) –

  One of the four verbatim Stage-1 pre-registration strings (see spikes/preregistration/{AS,OM}.yaml).

Returns:

• Resolved ( ConditionConfig ) –

  class:ConditionConfig carrying the

• ConditionConfig –

  agent_uids tuple, env-level obs_mode superset, and the

• ConditionConfig –

  boolean flags downstream wrappers / scripts read.

Raises:

• ValueError –

  If condition_id is not one of the four Stage-1 pre-registration strings. The message names the four valid options and cites ADR-007 §Discipline (the project anti-pattern for editing prereg YAMLs).

Source code in src/chamber/envs/stage1_pickplace.py

def resolve_condition(condition_id: str) -> ConditionConfig:
    """Resolve a pre-registered ``condition_id`` to its config (ADR-007 §Stage 1b).

    Pure Tier-1 function — no SAPIEN dependency. Tier-1 tests pin the
    four-condition coverage and the ``ValueError`` raise on bogus IDs.

    Args:
        condition_id: One of the four verbatim Stage-1 pre-registration
            strings (see ``spikes/preregistration/{AS,OM}.yaml``).

    Returns:
        Resolved :class:`ConditionConfig` carrying the
        ``agent_uids`` tuple, env-level ``obs_mode`` superset, and the
        boolean flags downstream wrappers / scripts read.

    Raises:
        ValueError: If ``condition_id`` is not one of the four
            Stage-1 pre-registration strings. The message names the
            four valid options and cites ADR-007 §Discipline (the
            project anti-pattern for editing prereg YAMLs).
    """
    try:
        return _CONDITION_TABLE[condition_id]
    except KeyError as exc:
        msg = (
            f"Stage1PickPlaceEnv: condition_id {condition_id!r} is not one of the "
            f"four Stage-1 pre-registration strings {sorted(_CONDITION_TABLE)!r}. "
            "If the prereg YAML has been edited, re-issue with a new git_tag "
            "per ADR-007 §Discipline; do not rename condition_ids in code."
        )
        raise ValueError(msg) from exc

Stage-1 observation wrappers (ADR-007 §Stage 1b; ADR-009 §Decision).

Two wrappers, applied in fixed order by :func:chamber.envs.stage1_pickplace.make_stage1_pickplace_env:

1. :class:Stage1ASStateSynthesizer — synthesises obs["agent"][uid]["state"] for AS conditions, bridging ManiSkill v3 obs_mode="state_dict" (which emits per-agent Dict(qpos, qvel, ...)) to :class:chamber.benchmarks.ego_ppo_trainer.EgoPPOTrainer's obs["agent"][ego_uid]["state"] contract. Pass-through for OM conditions and for envs without a recognised condition_id.

Ego state widening (P1.05.8; ADR-007 §Stage 1b Rev 12; ADR-009 §Decision direct-observation-of-partner-pose). The ego uid's synthesised state Box concatenates, in this order:

   [ego_qpos, ego_qvel,
    partner_qpos, partner_qvel,
    cube_pose, goal_pos, tcp_pose]

The order is load-bearing for the audit-trail reproducibility of trained-checkpoint diffs and for the positional Tier-1 regression test in tests/unit/test_stage1_pickplace_tier1.py. The non-ego (partner) entry's state Box stays at the existing concat(qpos, qvel) of the partner alone — no task fields, no cross-agent observation. Only the ego sees the task.

This widening is the Surface 6 remediation from the failed 2026-05-20 Stage-1b AS launch (PR #182). Pre-P1.05.8 the synthesiser composed the ego's state Box from the ego's own concat(qpos, qvel) only — cube / goal / TCP / partner state were structurally invisible to :func:chamber.benchmarks.ego_ppo_trainer._flat_ego_obs even though the env populated them under obs["extra"] and the partner's sibling subtree. The consultation brief at spikes/results/stage1-failure-investigation/2026-05-20/CONSULTATION_BRIEF.md §4 Q1 decided to widen at this seam (the trainer's _flat_ego_obs reads state; the wrapper's job is to define what state means for the env). ADR-009 §Decision was amended in the same slice to record that direct partner-pose observation does not violate the black-box-policy contract — that contract is about policy access (weights / reward / training data, enforced by :data:chamber.partners.interface._FORBIDDEN_ATTRS), not pose visibility. A real robot's cameras / LIDAR / proximity sensors see other robots' poses; observing the partner's joint state in simulation is the same affordance.

The relative task fields (cube_to_tcp_pos, cube_to_goal_pos) are deliberately excluded — they are linear combinations of the absolute pose fields already concatenated and would inflate the actor's input dimensionality without adding rank. The synthesised force_torque channel is also excluded; it is the OM-hetero discriminant, and the OM vision-head slice that would have consumed it (formerly P1.05.6 / issue #177) was retired under ADR-026 §Decision 3/5.

Per-condition state dim is env-emit-dependent (panda_partner under AS-homo vs fetch under AS-hetero) and pinned per-condition by the Tier-1 + Tier-2 tests in the P1.05.8 PR. The trainer's :meth:chamber.benchmarks.ego_ppo_trainer.EgoPPOTrainer.from_config reads env.observation_space["agent"][ego_uid]["state"].shape[0] at construction time per (seed, condition) cell, so the per-condition divergence does not trip any global constant.

1. :class:Stage1OMChannelFilter — per-condition channel keep-set for the OM axis. The Stage-1 AS conditions don't filter at all (they use obs_mode="state_dict" which already excludes the camera data the OM axis differentiates on); the wrapper passes those conditions through untouched.

For the two OM conditions:

• stage1_pickplace_vision_only — keep obs["sensor_data"] (the RGB-D camera channels) plus the task-extra fields the policy needs to be functional at the Stage-1b episode budget (tcp_pose, goal_pos). Zero-mask the agent-proprio sub-dicts under obs["agent"][uid] and the synthesised obs["extra"]["force_torque"] channel.
• stage1_pickplace_vision_plus_force_torque_plus_proprio — pass-through (no filtering); the policy sees everything.

ManiSkill v3 obs layout reminder (mani_skill/envs/sapien_env.py:546-630): obs["agent"][uid] carries proprio (state, joint_pos, joint_vel); obs["extra"] carries task-level fields from :meth:_get_obs_extra; obs["sensor_data"] carries camera channels when the env's obs_mode is image-bearing.

Shape preservation: zero-masked channels become zero arrays of the same shape and dtype (mirrors :class:chamber.envs.texture_filter.TextureFilterObsWrapper's pattern). This keeps downstream policy networks oblivious to which modalities a given uid actually receives at runtime — only the values change across conditions, not the shapes.

Batch contract (P1.05.10; ADR-007 §Stage 1b regime-alignment revision). Single-env builds (num_envs=1) emit the historical flat 1-D state vector byte-identically to pre-P1.05.10 (ADR-002). Vectorised builds (num_envs > 1) emit state as (num_envs, state_dim) — the concat helpers coerce every per-uid / task-extra field to (batch, dim), loud-fail on inconsistent batch dims, and concat along the trailing axis. The synthesised state Box mirrors the inner space's batching; consumers read the per-env dim via shape[-1].

Quaternion sign-flip caveat. cube_pose and tcp_pose carry quaternion entries (qw, qx, qy, qz). SAPIEN does not pin a quaternion sign convention at the obs layer — two physically identical poses may emit q or -q depending on integrator floating-point drift. This is a downstream science concern (manifests as policy non-determinism in extreme cases), not a Surface-6 concern; flagged here so a future investigator has the lead.

References: - ADR-007 §Stage 1b (the AS / OM axis spec); spikes/preregistration/AS.yaml and spikes/preregistration/OM.yaml (the condition_id strings these wrappers resolve verbatim). - ADR-007 §Stage 1b Rev 12 (the Surface 6 remediation entry). - ADR-009 §Decision (direct-observation-of-partner-pose paragraph). - ADR-002 §Revision history 2026-05-21 (the Tier-2 acceptance-gap finding + extension of the trainer-obs-reader contract). - :class:chamber.envs.texture_filter.TextureFilterObsWrapper (the parallel pattern for the Stage-0 smoke env's per-uid keep-set). - :class:chamber.envs.stage1_pickplace.Stage1PickPlaceEnv (the inner env that supplies the synthesised FT channel and the condition_id attribute). - spikes/results/stage1-failure-investigation/2026-05-20/CONSULTATION_BRIEF.md (the §4a runbook decision rationale).

Stage1ASStateSynthesizer

Bases: ObservationWrapper

Synthesise obs["agent"][uid]["state"] for AS conditions (ADR-007 §Stage 1b).

ManiSkill v3.0.1 obs_mode="state_dict" (used by the Stage-1 AS conditions) emits per-agent Dict(qpos: Box, qvel: Box, ...) with no top-level "state" key. But :meth:chamber.benchmarks.ego_ppo_trainer.EgoPPOTrainer.from_config reads env.observation_space["agent"][ego_uid]["state"] as a 1-D Box and derives obs_dim = ego_state_space.shape[0]. This wrapper synthesises that state key.

Ego state widening (P1.05.8; ADR-007 §Stage 1b Rev 12; ADR-009 §Decision). Per the module docstring, the ego uid's synthesised state concatenates [ego_qpos, ego_qvel, partner_qpos, partner_qvel, cube_pose, goal_pos, tcp_pose]. The non-ego (partner) entry's state stays at concat(qpos, qvel) of the partner alone (the partner does not see the task or the ego). Per-condition state dim is env-emit-dependent and pinned by the Tier-1 + Tier-2 tests; the trainer reads the shape off the env at construction time.

Pass-through for OM conditions (is_om_condition=True — those go through :class:Stage1OMChannelFilter instead) and for envs whose condition_id is missing or unrecognised (Tier-1 safety: keeps the wrapper a no-op for envs that don't satisfy the Stage-1b condition_id contract).

Parameters:

• env (Env[Any, Any]) –

  Inner env exposing a condition_id attribute. For AS conditions, must also expose obs["agent"][ego_uid] and obs["agent"][partner_uid] Dicts with qpos / qvel Boxes, and obs["extra"] Dict with cube_pose (last-dim 7), goal_pos (last-dim 3), tcp_pose (last-dim 7).

Raises:

• TypeError –

  If env.observation_space is not a :class:gym.spaces.Dict, or — for active AS conditions — if the required obs["extra"] task fields are missing or mistyped. The error message names the missing / wrong-typed key and cites ADR-007 §Stage 1b Rev 12, so a future operator who breaks the contract surfaces it at env construction rather than weeks later as a silent zero-fill regression of Surface 6.

Source code in src/chamber/envs/stage1_obs_filter.py

class Stage1ASStateSynthesizer(gym.ObservationWrapper):  # type: ignore[type-arg]
    """Synthesise ``obs["agent"][uid]["state"]`` for AS conditions (ADR-007 §Stage 1b).

    ManiSkill v3.0.1 ``obs_mode="state_dict"`` (used by the Stage-1 AS
    conditions) emits per-agent ``Dict(qpos: Box, qvel: Box, ...)`` with
    no top-level ``"state"`` key. But
    :meth:`chamber.benchmarks.ego_ppo_trainer.EgoPPOTrainer.from_config`
    reads ``env.observation_space["agent"][ego_uid]["state"]`` as a 1-D
    Box and derives ``obs_dim = ego_state_space.shape[0]``. This
    wrapper synthesises that ``state`` key.

    **Ego state widening (P1.05.8; ADR-007 §Stage 1b Rev 12;
    ADR-009 §Decision).** Per the module docstring, the ego uid's
    synthesised ``state`` concatenates ``[ego_qpos, ego_qvel,
    partner_qpos, partner_qvel, cube_pose, goal_pos, tcp_pose]``.
    The non-ego (partner) entry's ``state`` stays at
    ``concat(qpos, qvel)`` of the partner alone (the partner does
    not see the task or the ego). Per-condition state dim is
    env-emit-dependent and pinned by the Tier-1 + Tier-2 tests; the
    trainer reads the shape off the env at construction time.

    Pass-through for OM conditions (``is_om_condition=True`` — those go
    through :class:`Stage1OMChannelFilter` instead) and for envs whose
    ``condition_id`` is missing or unrecognised (Tier-1 safety: keeps
    the wrapper a no-op for envs that don't satisfy the Stage-1b
    ``condition_id`` contract).

    Args:
        env: Inner env exposing a ``condition_id`` attribute. For AS
            conditions, must also expose ``obs["agent"][ego_uid]``
            and ``obs["agent"][partner_uid]`` Dicts with ``qpos`` /
            ``qvel`` Boxes, and ``obs["extra"]`` Dict with
            ``cube_pose`` (last-dim 7), ``goal_pos`` (last-dim 3),
            ``tcp_pose`` (last-dim 7).

    Raises:
        TypeError: If ``env.observation_space`` is not a
            :class:`gym.spaces.Dict`, or — for active AS conditions —
            if the required ``obs["extra"]`` task fields are missing
            or mistyped. The error message names the missing /
            wrong-typed key and cites ADR-007 §Stage 1b Rev 12, so a
            future operator who breaks the contract surfaces it at
            env construction rather than weeks later as a silent
            zero-fill regression of Surface 6.
    """

    def __init__(self, env: gym.Env[Any, Any]) -> None:
        """Detect AS-condition envs at construction (ADR-007 §Stage 1b Rev 12)."""
        super().__init__(env)
        if not isinstance(env.observation_space, gym.spaces.Dict):
            msg = (
                "Stage1ASStateSynthesizer requires a gym.spaces.Dict observation "
                f"space; got {type(env.observation_space).__name__}."
            )
            raise TypeError(msg)
        condition_id = getattr(env, "condition_id", None)
        if condition_id is None and hasattr(env, "get_wrapper_attr"):
            try:
                condition_id = env.get_wrapper_attr("condition_id")
            except AttributeError:
                condition_id = None
        # Local import to avoid the chamber.envs.stage1_pickplace ↔
        # chamber.envs.stage1_obs_filter circular import that arises now
        # that make_stage1_pickplace_env applies this wrapper.
        from chamber.envs.stage1_pickplace import resolve_condition

        config = None
        if isinstance(condition_id, str):
            try:
                config = resolve_condition(condition_id)
            except ValueError:
                config = None
        self._active: bool = config is not None and not config.is_om_condition
        # Cache ego / partner uids when active so the per-step
        # ``observation()`` callable does not have to re-resolve.
        self._ego_uid: str | None = None
        self._partner_uid: str | None = None
        if self._active and config is not None:
            self._ego_uid, self._partner_uid = config.agent_uids
            self.observation_space = self._build_observation_space(env.observation_space)

    def _build_observation_space(self, inner: gym.spaces.Dict) -> gym.spaces.Dict:
        """Inject the widened 1-D ``state`` Box per agent (ADR-007 §Stage 1b Rev 12).

        Ego uid's ``state`` Box has shape ``(ego_qpos + ego_qvel +
        partner_qpos + partner_qvel + 7 + 3 + 7,)``; non-ego entries
        keep the per-uid ``concat(qpos, qvel)`` shape.
        """
        # pragma: no cover - guarded by _active
        if self._ego_uid is None or self._partner_uid is None:
            return inner
        agent = inner.spaces.get("agent")
        if not isinstance(agent, gym.spaces.Dict):
            msg = (
                "Stage1ASStateSynthesizer: inner env's observation_space is missing "
                "a Dict 'agent' sub-space. Required by the AS synthesiser to "
                "compose per-uid 'state' Boxes. ADR-007 §Stage 1b Rev 12."
            )
            raise TypeError(msg)
        # Resolve ego / partner sub-spaces and validate qpos / qvel Box-ness.
        ego_qpos_dim, ego_qvel_dim = _resolve_qpos_qvel_dims(agent, uid=self._ego_uid, role="ego")
        partner_qpos_dim, partner_qvel_dim = _resolve_qpos_qvel_dims(
            agent, uid=self._partner_uid, role="partner"
        )
        # Validate ``obs["extra"]`` carries the three task fields with the
        # expected trailing dims.
        extra_total_dim = _validate_and_sum_task_extras(inner)
        ego_state_dim = (
            ego_qpos_dim + ego_qvel_dim + partner_qpos_dim + partner_qvel_dim + extra_total_dim
        )

        new_agent_spaces: dict[str, gym.spaces.Space[Any]] = {}
        for uid, sub in agent.spaces.items():
            if isinstance(sub, gym.spaces.Dict):
                qpos = sub.spaces.get("qpos")
                qvel = sub.spaces.get("qvel")
                if isinstance(qpos, gym.spaces.Box) and isinstance(qvel, gym.spaces.Box):
                    if uid == self._ego_uid:
                        state_dim = ego_state_dim
                    else:
                        state_dim = int(qpos.shape[-1]) + int(qvel.shape[-1])
                    # P1.05.10: mirror the inner space's batching. A
                    # vectorised build's qpos Box is (num_envs, dof) with
                    # num_envs > 1 — the synthesised state Box is then
                    # (num_envs, state_dim) so space and runtime obs
                    # agree. Single-env builds — including the (1, dof)
                    # squeezed-batch layout ManiSkill emits at
                    # num_envs=1 — keep the historical flat (state_dim,)
                    # Box (the runtime concat ravels the batch-1 case to
                    # 1-D too). Consumers read the per-env dim via
                    # shape[-1] (see EgoPPOTrainer.from_config).
                    qpos_shape = qpos.shape if qpos.shape is not None else (state_dim,)
                    state_shape = (
                        (int(qpos_shape[0]), state_dim)
                        if len(qpos_shape) > 1 and int(qpos_shape[0]) > 1
                        else (state_dim,)
                    )
                    state_box = gym.spaces.Box(
                        low=-np.inf,
                        high=np.inf,
                        shape=state_shape,
                        dtype=np.float32,
                    )
                    augmented = dict(sub.spaces)
                    augmented["state"] = state_box
                    new_agent_spaces[uid] = gym.spaces.Dict(augmented)
                    continue
            new_agent_spaces[uid] = sub
        new_spaces = dict(inner.spaces)
        new_spaces["agent"] = gym.spaces.Dict(new_agent_spaces)
        return gym.spaces.Dict(new_spaces)

    def observation(self, observation: dict[str, Any]) -> dict[str, Any]:  # type: ignore[override]
        """Inject the widened ego ``state`` (ADR-007 §Stage 1b Rev 12)."""
        if not self._active:
            return observation
        agent = observation.get("agent")
        if not isinstance(agent, dict):
            return observation
        if self._ego_uid is None or self._partner_uid is None:  # pragma: no cover
            return observation
        extra = observation.get("extra")
        if not isinstance(extra, dict):
            msg = (
                "Stage1ASStateSynthesizer: runtime obs is missing the 'extra' "
                "sub-dict required by the widened ego state contract. "
                "Expected keys: cube_pose, goal_pos, tcp_pose. "
                "See ADR-007 §Stage 1b Rev 12."
            )
            raise TypeError(msg)
        partner_sub = agent.get(self._partner_uid)
        if (
            not isinstance(partner_sub, dict)
            or "qpos" not in partner_sub
            or "qvel" not in partner_sub
        ):
            msg = (
                f"Stage1ASStateSynthesizer: runtime obs missing partner uid "
                f"{self._partner_uid!r} with qpos+qvel keys. The widened ego "
                "state contract requires direct partner-pose observation "
                "(ADR-009 §Decision direct-observation-of-partner-pose). "
                "See ADR-007 §Stage 1b Rev 12."
            )
            raise TypeError(msg)
        task_arrays: dict[str, Any] = {}
        for field_name, _ in _AS_TASK_EXTRA_FIELDS:
            value = extra.get(field_name)
            if value is None:
                msg = (
                    f"Stage1ASStateSynthesizer: runtime obs missing task field "
                    f"'extra.{field_name}'. The widened ego state contract "
                    "requires cube / goal / TCP pose. See ADR-007 §Stage 1b Rev 12."
                )
                raise TypeError(msg)
            task_arrays[field_name] = value

        new_agent: dict[str, Any] = {}
        for uid, sub in agent.items():
            if isinstance(sub, dict) and "qpos" in sub and "qvel" in sub:
                augmented = dict(sub)
                if uid == self._ego_uid:
                    augmented["state"] = _flat_widened_state_concat(
                        sub["qpos"],
                        sub["qvel"],
                        partner_sub["qpos"],
                        partner_sub["qvel"],
                        task_arrays["cube_pose"],
                        task_arrays["goal_pos"],
                        task_arrays["tcp_pose"],
                    )
                else:
                    augmented["state"] = _flat_state_concat(sub["qpos"], sub["qvel"])
                new_agent[uid] = augmented
            else:
                new_agent[uid] = sub
        out = dict(observation)
        out["agent"] = new_agent
        return out

    def __getattr__(self, name: str) -> Any:  # noqa: ANN401 - mirrors gym.Wrapper's inherited __getattr__ signature
        """Forward attribute access to the inner env (Tier-2 caller contract).

        Gymnasium 1.3 removed :class:`gym.Wrapper`'s implicit
        ``__getattr__``; existing P1.03 callers of
        :func:`make_stage1_pickplace_env` read SAPIEN-env attributes
        directly (``env.agent``, ``env._jacobian_provider``,
        ``env.condition_config``...). Forwarding here keeps that
        contract without forcing every caller to switch to
        :meth:`gym.Wrapper.get_wrapper_attr`.

        ``__getattr__`` only fires when normal attribute lookup misses;
        ``self.env`` is set by :meth:`gym.Wrapper.__init__` before any
        downstream access, so the delegation is safe. The ``env``-name
        guard is a defensive backstop against recursive lookup on the
        env attr itself (only reachable in pathological half-init
        paths).
        """
        if name == "env":
            raise AttributeError(name)
        return getattr(self.env, name)

__getattr__

__getattr__(name: str) -> Any

Forward attribute access to the inner env (Tier-2 caller contract).

Gymnasium 1.3 removed :class:gym.Wrapper's implicit __getattr__; existing P1.03 callers of :func:make_stage1_pickplace_env read SAPIEN-env attributes directly (env.agent, env._jacobian_provider, env.condition_config...). Forwarding here keeps that contract without forcing every caller to switch to :meth:gym.Wrapper.get_wrapper_attr.

__getattr__ only fires when normal attribute lookup misses; self.env is set by :meth:gym.Wrapper.__init__ before any downstream access, so the delegation is safe. The env-name guard is a defensive backstop against recursive lookup on the env attr itself (only reachable in pathological half-init paths).

Source code in src/chamber/envs/stage1_obs_filter.py

def __getattr__(self, name: str) -> Any:  # noqa: ANN401 - mirrors gym.Wrapper's inherited __getattr__ signature
    """Forward attribute access to the inner env (Tier-2 caller contract).

    Gymnasium 1.3 removed :class:`gym.Wrapper`'s implicit
    ``__getattr__``; existing P1.03 callers of
    :func:`make_stage1_pickplace_env` read SAPIEN-env attributes
    directly (``env.agent``, ``env._jacobian_provider``,
    ``env.condition_config``...). Forwarding here keeps that
    contract without forcing every caller to switch to
    :meth:`gym.Wrapper.get_wrapper_attr`.

    ``__getattr__`` only fires when normal attribute lookup misses;
    ``self.env`` is set by :meth:`gym.Wrapper.__init__` before any
    downstream access, so the delegation is safe. The ``env``-name
    guard is a defensive backstop against recursive lookup on the
    env attr itself (only reachable in pathological half-init
    paths).
    """
    if name == "env":
        raise AttributeError(name)
    return getattr(self.env, name)

__init__

__init__(env: Env[Any, Any]) -> None

Detect AS-condition envs at construction (ADR-007 §Stage 1b Rev 12).

Source code in src/chamber/envs/stage1_obs_filter.py

def __init__(self, env: gym.Env[Any, Any]) -> None:
    """Detect AS-condition envs at construction (ADR-007 §Stage 1b Rev 12)."""
    super().__init__(env)
    if not isinstance(env.observation_space, gym.spaces.Dict):
        msg = (
            "Stage1ASStateSynthesizer requires a gym.spaces.Dict observation "
            f"space; got {type(env.observation_space).__name__}."
        )
        raise TypeError(msg)
    condition_id = getattr(env, "condition_id", None)
    if condition_id is None and hasattr(env, "get_wrapper_attr"):
        try:
            condition_id = env.get_wrapper_attr("condition_id")
        except AttributeError:
            condition_id = None
    # Local import to avoid the chamber.envs.stage1_pickplace ↔
    # chamber.envs.stage1_obs_filter circular import that arises now
    # that make_stage1_pickplace_env applies this wrapper.
    from chamber.envs.stage1_pickplace import resolve_condition

    config = None
    if isinstance(condition_id, str):
        try:
            config = resolve_condition(condition_id)
        except ValueError:
            config = None
    self._active: bool = config is not None and not config.is_om_condition
    # Cache ego / partner uids when active so the per-step
    # ``observation()`` callable does not have to re-resolve.
    self._ego_uid: str | None = None
    self._partner_uid: str | None = None
    if self._active and config is not None:
        self._ego_uid, self._partner_uid = config.agent_uids
        self.observation_space = self._build_observation_space(env.observation_space)

observation

observation(observation: dict[str, Any]) -> dict[str, Any]

Inject the widened ego state (ADR-007 §Stage 1b Rev 12).

Source code in src/chamber/envs/stage1_obs_filter.py

def observation(self, observation: dict[str, Any]) -> dict[str, Any]:  # type: ignore[override]
    """Inject the widened ego ``state`` (ADR-007 §Stage 1b Rev 12)."""
    if not self._active:
        return observation
    agent = observation.get("agent")
    if not isinstance(agent, dict):
        return observation
    if self._ego_uid is None or self._partner_uid is None:  # pragma: no cover
        return observation
    extra = observation.get("extra")
    if not isinstance(extra, dict):
        msg = (
            "Stage1ASStateSynthesizer: runtime obs is missing the 'extra' "
            "sub-dict required by the widened ego state contract. "
            "Expected keys: cube_pose, goal_pos, tcp_pose. "
            "See ADR-007 §Stage 1b Rev 12."
        )
        raise TypeError(msg)
    partner_sub = agent.get(self._partner_uid)
    if (
        not isinstance(partner_sub, dict)
        or "qpos" not in partner_sub
        or "qvel" not in partner_sub
    ):
        msg = (
            f"Stage1ASStateSynthesizer: runtime obs missing partner uid "
            f"{self._partner_uid!r} with qpos+qvel keys. The widened ego "
            "state contract requires direct partner-pose observation "
            "(ADR-009 §Decision direct-observation-of-partner-pose). "
            "See ADR-007 §Stage 1b Rev 12."
        )
        raise TypeError(msg)
    task_arrays: dict[str, Any] = {}
    for field_name, _ in _AS_TASK_EXTRA_FIELDS:
        value = extra.get(field_name)
        if value is None:
            msg = (
                f"Stage1ASStateSynthesizer: runtime obs missing task field "
                f"'extra.{field_name}'. The widened ego state contract "
                "requires cube / goal / TCP pose. See ADR-007 §Stage 1b Rev 12."
            )
            raise TypeError(msg)
        task_arrays[field_name] = value

    new_agent: dict[str, Any] = {}
    for uid, sub in agent.items():
        if isinstance(sub, dict) and "qpos" in sub and "qvel" in sub:
            augmented = dict(sub)
            if uid == self._ego_uid:
                augmented["state"] = _flat_widened_state_concat(
                    sub["qpos"],
                    sub["qvel"],
                    partner_sub["qpos"],
                    partner_sub["qvel"],
                    task_arrays["cube_pose"],
                    task_arrays["goal_pos"],
                    task_arrays["tcp_pose"],
                )
            else:
                augmented["state"] = _flat_state_concat(sub["qpos"], sub["qvel"])
            new_agent[uid] = augmented
        else:
            new_agent[uid] = sub
    out = dict(observation)
    out["agent"] = new_agent
    return out

Stage1OMChannelFilter

Bases: ObservationWrapper

OM-axis per-condition channel filter (ADR-007 §Stage 1b).

Reads the inner env's condition_id at construction time and captures the resulting filter policy. The wrapper does not re-read condition_id on every step — Stage-1b envs are built once per (seed, condition) cell (see stage1_as.py:253-275) and the condition is fixed for the env's lifetime.

Parameters:

• env (Env[Any, Any]) –

  Inner env exposing a condition_id attribute. The :class:chamber.envs.stage1_pickplace.Stage1PickPlaceEnv class satisfies this; the wrapper falls back to a pass-through identity if condition_id is missing or not one of the two OM strings.

Raises:

• TypeError –

  If the inner env's observation space is not a :class:gym.spaces.Dict (the wrapper relies on dict-shaped obs).

Source code in src/chamber/envs/stage1_obs_filter.py

class Stage1OMChannelFilter(gym.ObservationWrapper):  # type: ignore[type-arg]
    """OM-axis per-condition channel filter (ADR-007 §Stage 1b).

    Reads the inner env's ``condition_id`` at construction time and
    captures the resulting filter policy. The wrapper does not re-read
    ``condition_id`` on every step — Stage-1b envs are built once per
    ``(seed, condition)`` cell (see ``stage1_as.py:253-275``) and the
    condition is fixed for the env's lifetime.

    Args:
        env: Inner env exposing a ``condition_id`` attribute. The
            :class:`chamber.envs.stage1_pickplace.Stage1PickPlaceEnv`
            class satisfies this; the wrapper falls back to a
            pass-through identity if ``condition_id`` is missing or
            not one of the two OM strings.

    Raises:
        TypeError: If the inner env's observation space is not a
            :class:`gym.spaces.Dict` (the wrapper relies on dict-shaped
            obs).
    """

    def __init__(self, env: gym.Env[Any, Any]) -> None:
        """Store the per-condition filter policy (ADR-007 §Stage 1b)."""
        super().__init__(env)
        if not isinstance(env.observation_space, gym.spaces.Dict):
            msg = (
                "Stage1OMChannelFilter requires a gym.spaces.Dict observation "
                f"space; got {type(env.observation_space).__name__}."
            )
            raise TypeError(msg)
        # Read condition_id once at construction; the env-per-cell
        # cadence makes this safe and saves a hot-path attr lookup.
        condition_id = getattr(env, "condition_id", None)
        if condition_id is None and hasattr(env, "get_wrapper_attr"):
            try:
                condition_id = env.get_wrapper_attr("condition_id")
            except AttributeError:
                condition_id = None
        self._condition_id: str | None = condition_id
        self._filter_active: bool = condition_id in _FILTERED_CONDITIONS

    @property
    def condition_id(self) -> str | None:
        """ADR-007 §Stage 1b OM axis: the condition_id resolved at construction."""
        return self._condition_id

    def observation(self, observation: dict[str, Any]) -> dict[str, Any]:  # type: ignore[override]
        """Apply the per-condition channel mask (ADR-007 §Stage 1b).

        OM-vision-only zero-masks the per-uid agent-proprio sub-dicts
        and the ``obs["extra"]["force_torque"]`` channel; keeps
        ``obs["extra"]["tcp_pose"]`` + ``obs["extra"]["goal_pos"]``
        (the minimal task-relevant fields) plus ``obs["sensor_data"]``
        (RGB-D camera) untouched. Other conditions pass through.
        """
        if not self._filter_active:
            return observation
        out = dict(observation)
        # Zero-mask per-uid agent proprio (the "no proprioception" half
        # of the vision-only condition_id semantics).
        agent = observation.get("agent")
        if isinstance(agent, dict):
            zeroed_agent: dict[str, Any] = {}
            for uid, sub in agent.items():
                if isinstance(sub, dict):
                    zeroed_agent[uid] = {
                        ch: _zeros_like_preserving_backend(val) for ch, val in sub.items()
                    }
                else:
                    zeroed_agent[uid] = sub
            out["agent"] = zeroed_agent
        # Zero-mask task extras NOT in the vision-only keep-set (the
        # "no force-torque" half of the vision-only semantics).
        extra = observation.get("extra")
        if isinstance(extra, dict):
            filtered_extra: dict[str, Any] = {}
            for ch, val in extra.items():
                if ch in _OM_VISION_ONLY_EXTRA_KEEP:
                    filtered_extra[ch] = val
                else:
                    filtered_extra[ch] = _zeros_like_preserving_backend(val)
            out["extra"] = filtered_extra
        return out

    def __getattr__(self, name: str) -> Any:  # noqa: ANN401 - mirrors Stage1ASStateSynthesizer's forwarding contract
        """Forward attribute access to the inner env (Tier-2 caller contract).

        Mirrors :meth:`Stage1ASStateSynthesizer.__getattr__`: Gymnasium 1.3
        removed :class:`gym.Wrapper`'s implicit forwarding, so callers of
        :func:`chamber.envs.stage1_pickplace.make_stage1_pickplace_env`
        — which now applies this wrapper on top of the AS synthesizer —
        would otherwise lose access to SAPIEN-env attributes such as
        ``env.agent``, ``env.obs_mode``, ``env.condition_config``.
        """
        if name == "env":
            raise AttributeError(name)
        return getattr(self.env, name)

condition_id property

condition_id: str | None

ADR-007 §Stage 1b OM axis: the condition_id resolved at construction.

__getattr__

__getattr__(name: str) -> Any

Forward attribute access to the inner env (Tier-2 caller contract).

Mirrors :meth:Stage1ASStateSynthesizer.__getattr__: Gymnasium 1.3 removed :class:gym.Wrapper's implicit forwarding, so callers of :func:chamber.envs.stage1_pickplace.make_stage1_pickplace_env — which now applies this wrapper on top of the AS synthesizer — would otherwise lose access to SAPIEN-env attributes such as env.agent, env.obs_mode, env.condition_config.

Source code in src/chamber/envs/stage1_obs_filter.py

def __getattr__(self, name: str) -> Any:  # noqa: ANN401 - mirrors Stage1ASStateSynthesizer's forwarding contract
    """Forward attribute access to the inner env (Tier-2 caller contract).

    Mirrors :meth:`Stage1ASStateSynthesizer.__getattr__`: Gymnasium 1.3
    removed :class:`gym.Wrapper`'s implicit forwarding, so callers of
    :func:`chamber.envs.stage1_pickplace.make_stage1_pickplace_env`
    — which now applies this wrapper on top of the AS synthesizer —
    would otherwise lose access to SAPIEN-env attributes such as
    ``env.agent``, ``env.obs_mode``, ``env.condition_config``.
    """
    if name == "env":
        raise AttributeError(name)
    return getattr(self.env, name)

__init__

__init__(env: Env[Any, Any]) -> None

Store the per-condition filter policy (ADR-007 §Stage 1b).

Source code in src/chamber/envs/stage1_obs_filter.py

def __init__(self, env: gym.Env[Any, Any]) -> None:
    """Store the per-condition filter policy (ADR-007 §Stage 1b)."""
    super().__init__(env)
    if not isinstance(env.observation_space, gym.spaces.Dict):
        msg = (
            "Stage1OMChannelFilter requires a gym.spaces.Dict observation "
            f"space; got {type(env.observation_space).__name__}."
        )
        raise TypeError(msg)
    # Read condition_id once at construction; the env-per-cell
    # cadence makes this safe and saves a hot-path attr lookup.
    condition_id = getattr(env, "condition_id", None)
    if condition_id is None and hasattr(env, "get_wrapper_attr"):
        try:
            condition_id = env.get_wrapper_attr("condition_id")
        except AttributeError:
            condition_id = None
    self._condition_id: str | None = condition_id
    self._filter_active: bool = condition_id in _FILTERED_CONDITIONS

observation

observation(observation: dict[str, Any]) -> dict[str, Any]

Apply the per-condition channel mask (ADR-007 §Stage 1b).

OM-vision-only zero-masks the per-uid agent-proprio sub-dicts and the obs["extra"]["force_torque"] channel; keeps obs["extra"]["tcp_pose"] + obs["extra"]["goal_pos"] (the minimal task-relevant fields) plus obs["sensor_data"] (RGB-D camera) untouched. Other conditions pass through.

Source code in src/chamber/envs/stage1_obs_filter.py

def observation(self, observation: dict[str, Any]) -> dict[str, Any]:  # type: ignore[override]
    """Apply the per-condition channel mask (ADR-007 §Stage 1b).

    OM-vision-only zero-masks the per-uid agent-proprio sub-dicts
    and the ``obs["extra"]["force_torque"]`` channel; keeps
    ``obs["extra"]["tcp_pose"]`` + ``obs["extra"]["goal_pos"]``
    (the minimal task-relevant fields) plus ``obs["sensor_data"]``
    (RGB-D camera) untouched. Other conditions pass through.
    """
    if not self._filter_active:
        return observation
    out = dict(observation)
    # Zero-mask per-uid agent proprio (the "no proprioception" half
    # of the vision-only condition_id semantics).
    agent = observation.get("agent")
    if isinstance(agent, dict):
        zeroed_agent: dict[str, Any] = {}
        for uid, sub in agent.items():
            if isinstance(sub, dict):
                zeroed_agent[uid] = {
                    ch: _zeros_like_preserving_backend(val) for ch, val in sub.items()
                }
            else:
                zeroed_agent[uid] = sub
        out["agent"] = zeroed_agent
    # Zero-mask task extras NOT in the vision-only keep-set (the
    # "no force-torque" half of the vision-only semantics).
    extra = observation.get("extra")
    if isinstance(extra, dict):
        filtered_extra: dict[str, Any] = {}
        for ch, val in extra.items():
            if ch in _OM_VISION_ONLY_EXTRA_KEEP:
                filtered_extra[ch] = val
            else:
                filtered_extra[ch] = _zeros_like_preserving_backend(val)
        out["extra"] = filtered_extra
    return out

Custom errors for CHAMBER environment wrappers.

ADR-001 §Risks — wrappers raise this error rather than silently falling back when a wrapped env does not satisfy the wrapper's structural assumptions.

ChamberEnvCompatibilityError

Bases: RuntimeError

Raised when a wrapped env does not satisfy CHAMBER wrapper assumptions.

ADR-001 §Risks: a silent fallback during a Stage-0 spike would invalidate the gate; failing loudly forces ADR re-review.

Source code in src/chamber/envs/errors.py

class ChamberEnvCompatibilityError(RuntimeError):
    """Raised when a wrapped env does not satisfy CHAMBER wrapper assumptions.

    ADR-001 §Risks: a silent fallback during a Stage-0 spike would invalidate
    the gate; failing loudly forces ADR re-review.
    """

chamber.agents

CHAMBER-side agent extensions (ADR-001 §Decision; ADR-007 §Stage 1b).

Hosts robot-agent classes the project needs in addition to ManiSkill v3's built-in registry. Currently:

• :class:PandaPartner — a 7-DOF Franka with uid="panda_partner", used by the Stage-1 AS-homogeneous condition pair (panda_wristcam, panda_partner) so the two-panda case resolves to distinct uid strings under the :func:chamber.envs._sapien_compat.load_agent_with_bare_uids strip- suffix path (otherwise ("panda_wristcam", "panda_wristcam") would collapse to a single dict entry post-strip).
• :class:PandaJacobianProvider — wraps :mod:pytorch_kinematics to expose the 3x7 linear end-effector Jacobian :math:J(q) \\in \\mathbb{R}^{3 \\times 7} that :class:concerto.safety.api.JacobianControlModel needs (ADR-004 §Decision; spike_004A §Per-agent control model).

Wrapper-only discipline (ADR-001 §Decision (wrapper-only)): :class:PandaPartner is registered via the public mani_skill.agents.registration.register_agent decorator. No mani_skill/ source patching; no _* private imports.

Tier-1 safety: this module's top-level imports tolerate missing ManiSkill/SAPIEN at module-load time. The :class:PandaPartner registration side-effect is deferred behind a try/except so python -c "import chamber.agents" succeeds on a Vulkan-less host — :class:chamber.envs.errors.ChamberEnvCompatibilityError only fires at env-construction time, never at module-import time (mirrors the stage0_smoke pattern; ADR-001 §Risks).

PandaJacobianProvider

Frozen URDF chain -> linear Jacobian callable (ADR-004 §Decision; §Stage 1b).

Parses the panda URDF once at construction (via :func:pytorch_kinematics.build_serial_chain_from_urdf) and caches the resulting :class:pytorch_kinematics.SerialChain. Each :meth:__call__ evaluates :math:J(q) on the cached chain.

Parameters:

• urdf_path (str | None, default: None ) –

  Absolute path to the panda URDF on disk. The default (None) selects the wristcam URDF ({PACKAGE_ASSET_DIR}/robots/panda/panda_v3.urdf) since the Stage-1b panda is by convention the wristcam variant; pass panda_v2.urdf to target the no-camera URDF used by :class:PandaPartner.

• ee_link (str, default: 'panda_hand_tcp' ) –

  Name of the end-effector link the chain terminates at. Defaults to "panda_hand_tcp" — the tool-center-point link the ManiSkill PickCube task uses for self.agent.tcp_pose (see mani_skill/envs/tasks/tabletop/pick_cube.py:136). The serial chain extracted with this end-link has exactly 7 joints (the 7 arm joints; the two gripper-finger joints are siblings of panda_hand, not in the chain).

Raises:

• FileNotFoundError –

  If urdf_path does not exist on disk.

• ValueError –

  If :func:pytorch_kinematics.build_serial_chain_from_urdf fails to extract a chain ending at ee_link.

Source code in src/chamber/agents/panda_jacobian.py

class PandaJacobianProvider:
    """Frozen URDF chain -> linear Jacobian callable (ADR-004 §Decision; §Stage 1b).

    Parses the panda URDF once at construction (via
    :func:`pytorch_kinematics.build_serial_chain_from_urdf`) and caches
    the resulting :class:`pytorch_kinematics.SerialChain`. Each
    :meth:`__call__` evaluates :math:`J(q)` on the cached chain.

    Args:
        urdf_path: Absolute path to the panda URDF on disk. The default
            (``None``) selects the wristcam URDF
            (``{PACKAGE_ASSET_DIR}/robots/panda/panda_v3.urdf``) since
            the Stage-1b panda is by convention the wristcam variant;
            pass ``panda_v2.urdf`` to target the no-camera URDF used by
            :class:`PandaPartner`.
        ee_link: Name of the end-effector link the chain terminates at.
            Defaults to ``"panda_hand_tcp"`` — the tool-center-point
            link the ManiSkill PickCube task uses for
            ``self.agent.tcp_pose`` (see
            ``mani_skill/envs/tasks/tabletop/pick_cube.py:136``). The
            serial chain extracted with this end-link has exactly 7
            joints (the 7 arm joints; the two gripper-finger joints are
            siblings of ``panda_hand``, not in the chain).

    Raises:
        FileNotFoundError: If ``urdf_path`` does not exist on disk.
        ValueError: If :func:`pytorch_kinematics.build_serial_chain_from_urdf`
            fails to extract a chain ending at ``ee_link``.
    """

    def __init__(
        self,
        urdf_path: str | None = None,
        *,
        ee_link: str = "panda_hand_tcp",
    ) -> None:
        """Parse the URDF and cache the serial chain (ADR-007 §Stage 1b)."""
        import pytorch_kinematics as pk

        if urdf_path is None:
            from mani_skill import PACKAGE_ASSET_DIR

            urdf_path = f"{PACKAGE_ASSET_DIR}/robots/panda/panda_v3.urdf"
        with open(urdf_path, "rb") as fh:
            urdf_blob = fh.read()
        self._chain = pk.build_serial_chain_from_urdf(urdf_blob, end_link_name=ee_link)
        self._ee_link: str = ee_link
        if self._chain.n_joints != PANDA_ARM_DOF:
            msg = (
                f"PandaJacobianProvider: expected {PANDA_ARM_DOF}-joint serial chain "
                f"to {ee_link!r}; pytorch_kinematics returned {self._chain.n_joints} "
                "joints. Check URDF integrity or pick a different end-effector link."
            )
            raise ValueError(msg)

    @property
    def ee_link(self) -> str:
        """The end-effector link the chain terminates at (read-only)."""
        return self._ee_link

    def fk_tcp_position(self, qpos_arm: NDArray[np.floating]) -> NDArray[np.float64]:
        """Forward-kinematics TCP position in the arm base frame (ADR-004 §Decision; ADR-026).

        Companion to :meth:`__call__`: evaluates the cached serial
        chain's forward kinematics at ``qpos_arm`` and returns the 3-D
        Cartesian position of :attr:`ee_link` in the panda base
        (``panda_link0``) frame — the same frame the Jacobian
        :meth:`__call__` returns, so a Cartesian error and its
        damped-pseudoinverse joint step compose consistently. Consumed
        by the co-carry matched impedance controller
        (:class:`chamber.partners.cocarry_impedance.CoCarryImpedancePartner`),
        which drives each held bar-end TCP to its cooperative target.

        Args:
            qpos_arm: Joint-angle vector for the 7 panda arm joints,
                shape ``(7,)``, in the same order as
                :attr:`mani_skill.agents.robots.panda.Panda.arm_joint_names`.

        Returns:
            TCP position in the base frame, shape ``(3,)``, dtype
            ``float64``.

        Raises:
            ValueError: If ``qpos_arm`` shape mismatches ``(7,)``.
        """
        import torch

        q = np.asarray(qpos_arm, dtype=np.float32)
        if q.shape != (PANDA_ARM_DOF,):
            msg = (
                f"PandaJacobianProvider.fk_tcp_position: qpos_arm shape {q.shape} "
                f"mismatches expected ({PANDA_ARM_DOF},) for the 7-DOF Panda chain."
            )
            raise ValueError(msg)
        q_torch = torch.from_numpy(q).unsqueeze(0)
        # forward_kinematics(end_only=True default) returns a Transform3d;
        # the pytorch_kinematics stub mistypes it as a dict.
        mat = self._chain.forward_kinematics(q_torch).get_matrix()  # type: ignore[union-attr]
        pos = mat[0, :CARTESIAN_POSITION_DIM, 3].detach().cpu().numpy()
        return np.ascontiguousarray(pos, dtype=np.float64)

    def fk_tcp_rotation(self, qpos_arm: NDArray[np.floating]) -> NDArray[np.float64]:
        """Forward-kinematics TCP rotation matrix in the base frame (ADR-026 §Decision 1; ADR-004).

        Companion to :meth:`fk_tcp_position`: the 3x3 orientation of
        :attr:`ee_link` in the panda base frame at ``qpos_arm``. Consumed by the
        co-insert controllers (:mod:`chamber.partners.coinsert_impedance`), which
        hold the gripper orientation fixed (so the welded peg / socket cannot
        tip under the insertion contact torque) — the 6-DOF orientation-hold
        term the 3x7 linear slice cannot express.

        Args:
            qpos_arm: Joint-angle vector for the 7 panda arm joints, shape ``(7,)``.

        Returns:
            TCP rotation matrix in the base frame, shape ``(3, 3)``, dtype ``float64``.

        Raises:
            ValueError: If ``qpos_arm`` shape mismatches ``(7,)``.
        """
        import torch

        q = np.asarray(qpos_arm, dtype=np.float32)
        if q.shape != (PANDA_ARM_DOF,):
            msg = (
                f"PandaJacobianProvider.fk_tcp_rotation: qpos_arm shape {q.shape} "
                f"mismatches expected ({PANDA_ARM_DOF},) for the 7-DOF Panda chain."
            )
            raise ValueError(msg)
        q_torch = torch.from_numpy(q).unsqueeze(0)
        mat = self._chain.forward_kinematics(q_torch).get_matrix()  # type: ignore[union-attr]
        rot = mat[0, :CARTESIAN_POSITION_DIM, :CARTESIAN_POSITION_DIM].detach().cpu().numpy()
        return np.ascontiguousarray(rot, dtype=np.float64)

    def jacobian_6x7(self, qpos_arm: NDArray[np.floating]) -> NDArray[np.float64]:
        """Full 6x7 SE(3) end-effector Jacobian at ``qpos_arm`` (ADR-026 §Decision 1; ADR-004).

        The linear (rows 0:3) AND angular (rows 3:6) parts of the base-frame
        end-effector Jacobian. The safety stack consumes only the 3x7 linear
        slice (:meth:`__call__`; ADR-004 §Decision — the pairwise distance
        barrier is orientation-free); this full Jacobian is for the co-insert
        controllers' 6-DOF orientation-hold step (:mod:`chamber.partners.
        coinsert_impedance`), which the linear slice cannot express. Same cached
        ``pytorch_kinematics`` chain; no safety-contract change.

        Args:
            qpos_arm: Joint-angle vector for the 7 panda arm joints, shape ``(7,)``.

        Returns:
            The 6x7 Jacobian, shape ``(6, 7)``, dtype ``float64``.

        Raises:
            ValueError: If ``qpos_arm`` shape mismatches ``(7,)``.
        """
        import torch

        q = np.asarray(qpos_arm, dtype=np.float32)
        if q.shape != (PANDA_ARM_DOF,):
            msg = (
                f"PandaJacobianProvider.jacobian_6x7: qpos_arm shape {q.shape} "
                f"mismatches expected ({PANDA_ARM_DOF},) for the 7-DOF Panda chain."
            )
            raise ValueError(msg)
        q_torch = torch.from_numpy(q).unsqueeze(0)
        jac_6x7 = self._chain.jacobian(q_torch)[0].detach().cpu().numpy()
        return np.ascontiguousarray(jac_6x7, dtype=np.float64)

    def __call__(
        self,
        snap: AgentSnapshot,
        qpos_arm: NDArray[np.floating],
    ) -> NDArray[np.float64]:
        """Compute the 3x7 linear end-effector Jacobian at ``qpos_arm`` (ADR-004 §Decision).

        Args:
            snap: Current :class:`AgentSnapshot` — unused at the
                provider level (the Jacobian is a function of joint
                state, not Cartesian state); accepted for Protocol
                conformance with
                :class:`concerto.safety.api.JacobianControlModel.jacobian_fn`.
                See module docstring for the closure-via-env-reference
                rationale and the contingent P1.05.5 follow-up that
                folds qpos into :class:`AgentSnapshot` directly.
            qpos_arm: Joint-angle vector for the 7 panda arm joints, in
                the same order as ``mani_skill.agents.robots.panda.Panda.arm_joint_names``.
                Shape ``(7,)``; dtype float-coercible to ``float32``.

        Returns:
            Linear Jacobian rows of the 6x7 SE(3) Jacobian at
            ``qpos_arm``, shape ``(3, 7)``, dtype ``float64`` (matches
            the :class:`JacobianControlModel` arithmetic contract at
            ``concerto/safety/api.py:560-561``).

        Raises:
            ValueError: If ``qpos_arm`` shape mismatches ``(7,)``.
        """
        del snap  # closure consumer reads qpos from env; see module docstring.
        import torch

        q = np.asarray(qpos_arm, dtype=np.float32)
        if q.shape != (PANDA_ARM_DOF,):
            msg = (
                f"PandaJacobianProvider: qpos_arm shape {q.shape} mismatches expected "
                f"({PANDA_ARM_DOF},) for the 7-DOF Panda chain."
            )
            raise ValueError(msg)
        q_torch = torch.from_numpy(q).unsqueeze(0)
        # pk.SerialChain.jacobian returns (N_batch, 6, n_dof); rows 0:3
        # are the linear part (d_pos / d_q), rows 3:6 are angular.
        # The CBF backbone consumes the linear part only — orientation
        # is out of scope for the pairwise distance barrier
        # (ADR-004 §Decision). See module docstring.
        jac_6x7 = self._chain.jacobian(q_torch)[0]
        jac_3x7 = jac_6x7[:CARTESIAN_POSITION_DIM].detach().cpu().numpy()
        return np.ascontiguousarray(jac_3x7, dtype=np.float64)

ee_link property

ee_link: str

The end-effector link the chain terminates at (read-only).

__call__

__call__(
    snap: AgentSnapshot, qpos_arm: NDArray[floating]
) -> NDArray[np.float64]

Compute the 3x7 linear end-effector Jacobian at qpos_arm (ADR-004 §Decision).

Parameters:

• snap (AgentSnapshot) –

  Current :class:AgentSnapshot — unused at the provider level (the Jacobian is a function of joint state, not Cartesian state); accepted for Protocol conformance with :class:concerto.safety.api.JacobianControlModel.jacobian_fn. See module docstring for the closure-via-env-reference rationale and the contingent P1.05.5 follow-up that folds qpos into :class:AgentSnapshot directly.

• qpos_arm (NDArray[floating]) –

  Joint-angle vector for the 7 panda arm joints, in the same order as mani_skill.agents.robots.panda.Panda.arm_joint_names. Shape (7,); dtype float-coercible to float32.

Returns:

• NDArray[float64] –

  Linear Jacobian rows of the 6x7 SE(3) Jacobian at

• NDArray[float64] –

  qpos_arm, shape (3, 7), dtype float64 (matches

• the ( NDArray[float64] ) –

  class:JacobianControlModel arithmetic contract at

• NDArray[float64] –

  concerto/safety/api.py:560-561).

Raises:

• ValueError –

  If qpos_arm shape mismatches (7,).

Source code in src/chamber/agents/panda_jacobian.py

def __call__(
    self,
    snap: AgentSnapshot,
    qpos_arm: NDArray[np.floating],
) -> NDArray[np.float64]:
    """Compute the 3x7 linear end-effector Jacobian at ``qpos_arm`` (ADR-004 §Decision).

    Args:
        snap: Current :class:`AgentSnapshot` — unused at the
            provider level (the Jacobian is a function of joint
            state, not Cartesian state); accepted for Protocol
            conformance with
            :class:`concerto.safety.api.JacobianControlModel.jacobian_fn`.
            See module docstring for the closure-via-env-reference
            rationale and the contingent P1.05.5 follow-up that
            folds qpos into :class:`AgentSnapshot` directly.
        qpos_arm: Joint-angle vector for the 7 panda arm joints, in
            the same order as ``mani_skill.agents.robots.panda.Panda.arm_joint_names``.
            Shape ``(7,)``; dtype float-coercible to ``float32``.

    Returns:
        Linear Jacobian rows of the 6x7 SE(3) Jacobian at
        ``qpos_arm``, shape ``(3, 7)``, dtype ``float64`` (matches
        the :class:`JacobianControlModel` arithmetic contract at
        ``concerto/safety/api.py:560-561``).

    Raises:
        ValueError: If ``qpos_arm`` shape mismatches ``(7,)``.
    """
    del snap  # closure consumer reads qpos from env; see module docstring.
    import torch

    q = np.asarray(qpos_arm, dtype=np.float32)
    if q.shape != (PANDA_ARM_DOF,):
        msg = (
            f"PandaJacobianProvider: qpos_arm shape {q.shape} mismatches expected "
            f"({PANDA_ARM_DOF},) for the 7-DOF Panda chain."
        )
        raise ValueError(msg)
    q_torch = torch.from_numpy(q).unsqueeze(0)
    # pk.SerialChain.jacobian returns (N_batch, 6, n_dof); rows 0:3
    # are the linear part (d_pos / d_q), rows 3:6 are angular.
    # The CBF backbone consumes the linear part only — orientation
    # is out of scope for the pairwise distance barrier
    # (ADR-004 §Decision). See module docstring.
    jac_6x7 = self._chain.jacobian(q_torch)[0]
    jac_3x7 = jac_6x7[:CARTESIAN_POSITION_DIM].detach().cpu().numpy()
    return np.ascontiguousarray(jac_3x7, dtype=np.float64)

__init__

__init__(
    urdf_path: str | None = None,
    *,
    ee_link: str = "panda_hand_tcp",
) -> None

Parse the URDF and cache the serial chain (ADR-007 §Stage 1b).

Source code in src/chamber/agents/panda_jacobian.py

def __init__(
    self,
    urdf_path: str | None = None,
    *,
    ee_link: str = "panda_hand_tcp",
) -> None:
    """Parse the URDF and cache the serial chain (ADR-007 §Stage 1b)."""
    import pytorch_kinematics as pk

    if urdf_path is None:
        from mani_skill import PACKAGE_ASSET_DIR

        urdf_path = f"{PACKAGE_ASSET_DIR}/robots/panda/panda_v3.urdf"
    with open(urdf_path, "rb") as fh:
        urdf_blob = fh.read()
    self._chain = pk.build_serial_chain_from_urdf(urdf_blob, end_link_name=ee_link)
    self._ee_link: str = ee_link
    if self._chain.n_joints != PANDA_ARM_DOF:
        msg = (
            f"PandaJacobianProvider: expected {PANDA_ARM_DOF}-joint serial chain "
            f"to {ee_link!r}; pytorch_kinematics returned {self._chain.n_joints} "
            "joints. Check URDF integrity or pick a different end-effector link."
        )
        raise ValueError(msg)

fk_tcp_position

fk_tcp_position(
    qpos_arm: NDArray[floating],
) -> NDArray[np.float64]

Forward-kinematics TCP position in the arm base frame (ADR-004 §Decision; ADR-026).

Companion to :meth:__call__: evaluates the cached serial chain's forward kinematics at qpos_arm and returns the 3-D Cartesian position of :attr:ee_link in the panda base (panda_link0) frame — the same frame the Jacobian :meth:__call__ returns, so a Cartesian error and its damped-pseudoinverse joint step compose consistently. Consumed by the co-carry matched impedance controller (:class:chamber.partners.cocarry_impedance.CoCarryImpedancePartner), which drives each held bar-end TCP to its cooperative target.

Parameters:

• qpos_arm (NDArray[floating]) –

  Joint-angle vector for the 7 panda arm joints, shape (7,), in the same order as :attr:mani_skill.agents.robots.panda.Panda.arm_joint_names.

Returns:

• NDArray[float64] –

  TCP position in the base frame, shape (3,), dtype

• NDArray[float64] –

  float64.

Raises:

• ValueError –

  If qpos_arm shape mismatches (7,).

Source code in src/chamber/agents/panda_jacobian.py

def fk_tcp_position(self, qpos_arm: NDArray[np.floating]) -> NDArray[np.float64]:
    """Forward-kinematics TCP position in the arm base frame (ADR-004 §Decision; ADR-026).

    Companion to :meth:`__call__`: evaluates the cached serial
    chain's forward kinematics at ``qpos_arm`` and returns the 3-D
    Cartesian position of :attr:`ee_link` in the panda base
    (``panda_link0``) frame — the same frame the Jacobian
    :meth:`__call__` returns, so a Cartesian error and its
    damped-pseudoinverse joint step compose consistently. Consumed
    by the co-carry matched impedance controller
    (:class:`chamber.partners.cocarry_impedance.CoCarryImpedancePartner`),
    which drives each held bar-end TCP to its cooperative target.

    Args:
        qpos_arm: Joint-angle vector for the 7 panda arm joints,
            shape ``(7,)``, in the same order as
            :attr:`mani_skill.agents.robots.panda.Panda.arm_joint_names`.

    Returns:
        TCP position in the base frame, shape ``(3,)``, dtype
        ``float64``.

    Raises:
        ValueError: If ``qpos_arm`` shape mismatches ``(7,)``.
    """
    import torch

    q = np.asarray(qpos_arm, dtype=np.float32)
    if q.shape != (PANDA_ARM_DOF,):
        msg = (
            f"PandaJacobianProvider.fk_tcp_position: qpos_arm shape {q.shape} "
            f"mismatches expected ({PANDA_ARM_DOF},) for the 7-DOF Panda chain."
        )
        raise ValueError(msg)
    q_torch = torch.from_numpy(q).unsqueeze(0)
    # forward_kinematics(end_only=True default) returns a Transform3d;
    # the pytorch_kinematics stub mistypes it as a dict.
    mat = self._chain.forward_kinematics(q_torch).get_matrix()  # type: ignore[union-attr]
    pos = mat[0, :CARTESIAN_POSITION_DIM, 3].detach().cpu().numpy()
    return np.ascontiguousarray(pos, dtype=np.float64)

fk_tcp_rotation

fk_tcp_rotation(
    qpos_arm: NDArray[floating],
) -> NDArray[np.float64]

Forward-kinematics TCP rotation matrix in the base frame (ADR-026 §Decision 1; ADR-004).

Companion to :meth:fk_tcp_position: the 3x3 orientation of :attr:ee_link in the panda base frame at qpos_arm. Consumed by the co-insert controllers (:mod:chamber.partners.coinsert_impedance), which hold the gripper orientation fixed (so the welded peg / socket cannot tip under the insertion contact torque) — the 6-DOF orientation-hold term the 3x7 linear slice cannot express.

Parameters:

• qpos_arm (NDArray[floating]) –

  Joint-angle vector for the 7 panda arm joints, shape (7,).

Returns:

• NDArray[float64] –

  TCP rotation matrix in the base frame, shape (3, 3), dtype float64.

Raises:

• ValueError –

  If qpos_arm shape mismatches (7,).

Source code in src/chamber/agents/panda_jacobian.py

def fk_tcp_rotation(self, qpos_arm: NDArray[np.floating]) -> NDArray[np.float64]:
    """Forward-kinematics TCP rotation matrix in the base frame (ADR-026 §Decision 1; ADR-004).

    Companion to :meth:`fk_tcp_position`: the 3x3 orientation of
    :attr:`ee_link` in the panda base frame at ``qpos_arm``. Consumed by the
    co-insert controllers (:mod:`chamber.partners.coinsert_impedance`), which
    hold the gripper orientation fixed (so the welded peg / socket cannot
    tip under the insertion contact torque) — the 6-DOF orientation-hold
    term the 3x7 linear slice cannot express.

    Args:
        qpos_arm: Joint-angle vector for the 7 panda arm joints, shape ``(7,)``.

    Returns:
        TCP rotation matrix in the base frame, shape ``(3, 3)``, dtype ``float64``.

    Raises:
        ValueError: If ``qpos_arm`` shape mismatches ``(7,)``.
    """
    import torch

    q = np.asarray(qpos_arm, dtype=np.float32)
    if q.shape != (PANDA_ARM_DOF,):
        msg = (
            f"PandaJacobianProvider.fk_tcp_rotation: qpos_arm shape {q.shape} "
            f"mismatches expected ({PANDA_ARM_DOF},) for the 7-DOF Panda chain."
        )
        raise ValueError(msg)
    q_torch = torch.from_numpy(q).unsqueeze(0)
    mat = self._chain.forward_kinematics(q_torch).get_matrix()  # type: ignore[union-attr]
    rot = mat[0, :CARTESIAN_POSITION_DIM, :CARTESIAN_POSITION_DIM].detach().cpu().numpy()
    return np.ascontiguousarray(rot, dtype=np.float64)

jacobian_6x7

jacobian_6x7(
    qpos_arm: NDArray[floating],
) -> NDArray[np.float64]

Full 6x7 SE(3) end-effector Jacobian at qpos_arm (ADR-026 §Decision 1; ADR-004).

The linear (rows 0:3) AND angular (rows 3:6) parts of the base-frame end-effector Jacobian. The safety stack consumes only the 3x7 linear slice (:meth:__call__; ADR-004 §Decision — the pairwise distance barrier is orientation-free); this full Jacobian is for the co-insert controllers' 6-DOF orientation-hold step (:mod:chamber.partners. coinsert_impedance), which the linear slice cannot express. Same cached pytorch_kinematics chain; no safety-contract change.

Parameters:

• qpos_arm (NDArray[floating]) –

  Joint-angle vector for the 7 panda arm joints, shape (7,).

Returns:

• NDArray[float64] –

  The 6x7 Jacobian, shape (6, 7), dtype float64.

Raises:

• ValueError –

  If qpos_arm shape mismatches (7,).

Source code in src/chamber/agents/panda_jacobian.py

def jacobian_6x7(self, qpos_arm: NDArray[np.floating]) -> NDArray[np.float64]:
    """Full 6x7 SE(3) end-effector Jacobian at ``qpos_arm`` (ADR-026 §Decision 1; ADR-004).

    The linear (rows 0:3) AND angular (rows 3:6) parts of the base-frame
    end-effector Jacobian. The safety stack consumes only the 3x7 linear
    slice (:meth:`__call__`; ADR-004 §Decision — the pairwise distance
    barrier is orientation-free); this full Jacobian is for the co-insert
    controllers' 6-DOF orientation-hold step (:mod:`chamber.partners.
    coinsert_impedance`), which the linear slice cannot express. Same cached
    ``pytorch_kinematics`` chain; no safety-contract change.

    Args:
        qpos_arm: Joint-angle vector for the 7 panda arm joints, shape ``(7,)``.

    Returns:
        The 6x7 Jacobian, shape ``(6, 7)``, dtype ``float64``.

    Raises:
        ValueError: If ``qpos_arm`` shape mismatches ``(7,)``.
    """
    import torch

    q = np.asarray(qpos_arm, dtype=np.float32)
    if q.shape != (PANDA_ARM_DOF,):
        msg = (
            f"PandaJacobianProvider.jacobian_6x7: qpos_arm shape {q.shape} "
            f"mismatches expected ({PANDA_ARM_DOF},) for the 7-DOF Panda chain."
        )
        raise ValueError(msg)
    q_torch = torch.from_numpy(q).unsqueeze(0)
    jac_6x7 = self._chain.jacobian(q_torch)[0].detach().cpu().numpy()
    return np.ascontiguousarray(jac_6x7, dtype=np.float64)

PandaPartner

Bases: Panda

Second-panda agent for the AS-homogeneous condition (ADR-007 §Stage 1b).

Inherits every Panda hook (arm joints, gripper joints, TCP pose, grasp / static predicates, controller configs) from :class:mani_skill.agents.robots.panda.panda.Panda. The only difference is the URDF: :class:PandaPartner uses panda_v2.urdf (no on-gripper camera mount), since the AS-homo partner is driven by the scripted-heuristic / trained policy rather than by camera-fed perception (the ego owns the camera via panda_wristcam).

Source code in src/chamber/agents/panda_partner.py

@register_agent()
class PandaPartner(Panda):
    """Second-panda agent for the AS-homogeneous condition (ADR-007 §Stage 1b).

    Inherits every Panda hook (arm joints, gripper joints, TCP pose,
    grasp / static predicates, controller configs) from
    :class:`mani_skill.agents.robots.panda.panda.Panda`. The only
    difference is the URDF: :class:`PandaPartner` uses ``panda_v2.urdf``
    (no on-gripper camera mount), since the AS-homo partner is driven by
    the scripted-heuristic / trained policy rather than by camera-fed
    perception (the ego owns the camera via ``panda_wristcam``).
    """

    uid = "panda_partner"
    urdf_path = f"{PACKAGE_ASSET_DIR}/robots/panda/panda_v2.urdf"

PandaPartner — second-panda agent for the AS-homogeneous condition (ADR-007 §Stage 1b).

The Stage-1 AS axis pre-registration (spikes/preregistration/AS.yaml, git tag prereg-stage1-AS-2026-05-15) names the homogeneous condition's agent tuple as ("panda_wristcam", "panda_partner"). ManiSkill v3.0.1's built-in agent registry covers panda, panda_wristcam, panda_stick, fetch, and the Allegro hands (see mani_skill.agents.registration.REGISTERED_AGENTS) — there is no panda_partner. The strip-suffix path in :func:chamber.envs._sapien_compat.load_agent_with_bare_uids would collapse two panda_wristcam entries to a single agents_dict key, so the AS-homo "two pandas" case needs a second, distinct uid.

This module defines that uid: a thin :class:Panda subclass mounted on the no-wristcam panda_v2.urdf (the AS-homo partner doesn't need its own perception — the ego owns the camera mount via panda_wristcam).

Wrapper-only discipline (ADR-001 §Decision (wrapper-only)): :class:PandaPartner is registered via the public @register_agent() decorator from mani_skill.agents.registration. No mani_skill/ source patching; no _* private imports. The base :class:Panda class's controller_configs, arm_joint_names, gripper_joint_names, tcp_pose property, is_grasping, and is_static are inherited unchanged — the only difference from panda_wristcam is the URDF choice (no on-gripper camera mount).

References: - ADR-007 §Stage 1b (P1.03 introduces the partner agent for the AS axis). - spikes/preregistration/AS.yaml (the pre-registration that names the ("panda_wristcam", "panda_partner") tuple). - mani_skill.agents.robots.panda.panda_wristcam.PandaWristCam (the parallel uid; pattern this class mirrors).

PandaPartner

Bases: Panda

Second-panda agent for the AS-homogeneous condition (ADR-007 §Stage 1b).

Inherits every Panda hook (arm joints, gripper joints, TCP pose, grasp / static predicates, controller configs) from :class:mani_skill.agents.robots.panda.panda.Panda. The only difference is the URDF: :class:PandaPartner uses panda_v2.urdf (no on-gripper camera mount), since the AS-homo partner is driven by the scripted-heuristic / trained policy rather than by camera-fed perception (the ego owns the camera via panda_wristcam).

Source code in src/chamber/agents/panda_partner.py

@register_agent()
class PandaPartner(Panda):
    """Second-panda agent for the AS-homogeneous condition (ADR-007 §Stage 1b).

    Inherits every Panda hook (arm joints, gripper joints, TCP pose,
    grasp / static predicates, controller configs) from
    :class:`mani_skill.agents.robots.panda.panda.Panda`. The only
    difference is the URDF: :class:`PandaPartner` uses ``panda_v2.urdf``
    (no on-gripper camera mount), since the AS-homo partner is driven by
    the scripted-heuristic / trained policy rather than by camera-fed
    perception (the ego owns the camera via ``panda_wristcam``).
    """

    uid = "panda_partner"
    urdf_path = f"{PACKAGE_ASSET_DIR}/robots/panda/panda_v2.urdf"

Panda 7-DOF end-effector Jacobian provider (ADR-004 §Decision; ADR-007 §Stage 1b).

Wraps :mod:pytorch_kinematics (already a transitive dep of mani-skill==3.0.1 — :mod:mani_skill.agents.controllers.utils.kinematics uses it for built-in IK; P1.03 promotes it to a load-bearing direct dep in pyproject.toml so :class:PandaJacobianProvider has a stable surface under wrapper-only discipline) to compute the analytical 3x7 linear end-effector Jacobian :math:J(q) \\in \\mathbb{R}^{3 \\times 7} the :class:concerto.safety.api.JacobianControlModel needs.

Why the 3x7 linear slice rather than the full 6x7 SE(3) Jacobian: :class:concerto.safety.cbf_qp.AgentSnapshot carries Cartesian position (shape (d,), typically d == 3) and velocity only — no orientation channel. The CBF backbone's pairwise barrier :math:h_{ij} is a Euclidean-distance constraint; angular Jacobian rows would be dimensionally orthogonal to it. The damped-pseudoinverse in :meth:JacobianControlModel.cartesian_accel_to_action (Nakamura & Hanafusa 1986) operates on the 3x7 slice; consistency with the safety-stack contract is the design constraint.

Note on the closure-via-env-reference workaround (Q3 mod 3 in the P1.03 design conversation): :class:AgentSnapshot does not carry qpos (extension is sequenced to slice P1.05.5 per ADR-004 §Open questions; the contingent trigger is Stage-1b λ-telemetry saturation). The :class:PandaJacobianProvider.__call__ signature therefore takes (snap, qpos_arm) — the env's :meth:chamber.envs.stage1_pickplace.Stage1PickPlaceEnv.build_control_models constructs a closure lambda snap: provider(snap, env._latest_qpos["panda_wristcam"]) that captures a fresh env reference per (seed, condition) cell (safe because :func:chamber.benchmarks.stage1_as._run_axis_with_factories builds the env once per cell and reuses it across the 20 evaluation episodes within the cell — the closure stays valid for the cell's lifetime; cited at stage1_as.py:253-275).

References: - ADR-004 §Decision (the JacobianControlModel contract). - ADR-004 §Open questions (the AgentSnapshot.qpos extension as the long-term fix; slice P1.05.5). - ADR-007 §Stage 1b (the slice introducing this provider). - :class:concerto.safety.api.JacobianControlModel (the consumer). - mani_skill.agents.controllers.utils.kinematics.Kinematics (the precedent for using pytorch_kinematics in ManiSkill's own IK).

PandaJacobianProvider

Frozen URDF chain -> linear Jacobian callable (ADR-004 §Decision; §Stage 1b).

Parses the panda URDF once at construction (via :func:pytorch_kinematics.build_serial_chain_from_urdf) and caches the resulting :class:pytorch_kinematics.SerialChain. Each :meth:__call__ evaluates :math:J(q) on the cached chain.

Parameters:

• urdf_path (str | None, default: None ) –

  Absolute path to the panda URDF on disk. The default (None) selects the wristcam URDF ({PACKAGE_ASSET_DIR}/robots/panda/panda_v3.urdf) since the Stage-1b panda is by convention the wristcam variant; pass panda_v2.urdf to target the no-camera URDF used by :class:PandaPartner.

• ee_link (str, default: 'panda_hand_tcp' ) –

  Name of the end-effector link the chain terminates at. Defaults to "panda_hand_tcp" — the tool-center-point link the ManiSkill PickCube task uses for self.agent.tcp_pose (see mani_skill/envs/tasks/tabletop/pick_cube.py:136). The serial chain extracted with this end-link has exactly 7 joints (the 7 arm joints; the two gripper-finger joints are siblings of panda_hand, not in the chain).

Raises:

• FileNotFoundError –

  If urdf_path does not exist on disk.

• ValueError –

  If :func:pytorch_kinematics.build_serial_chain_from_urdf fails to extract a chain ending at ee_link.

Source code in src/chamber/agents/panda_jacobian.py

class PandaJacobianProvider:
    """Frozen URDF chain -> linear Jacobian callable (ADR-004 §Decision; §Stage 1b).

    Parses the panda URDF once at construction (via
    :func:`pytorch_kinematics.build_serial_chain_from_urdf`) and caches
    the resulting :class:`pytorch_kinematics.SerialChain`. Each
    :meth:`__call__` evaluates :math:`J(q)` on the cached chain.

    Args:
        urdf_path: Absolute path to the panda URDF on disk. The default
            (``None``) selects the wristcam URDF
            (``{PACKAGE_ASSET_DIR}/robots/panda/panda_v3.urdf``) since
            the Stage-1b panda is by convention the wristcam variant;
            pass ``panda_v2.urdf`` to target the no-camera URDF used by
            :class:`PandaPartner`.
        ee_link: Name of the end-effector link the chain terminates at.
            Defaults to ``"panda_hand_tcp"`` — the tool-center-point
            link the ManiSkill PickCube task uses for
            ``self.agent.tcp_pose`` (see
            ``mani_skill/envs/tasks/tabletop/pick_cube.py:136``). The
            serial chain extracted with this end-link has exactly 7
            joints (the 7 arm joints; the two gripper-finger joints are
            siblings of ``panda_hand``, not in the chain).

    Raises:
        FileNotFoundError: If ``urdf_path`` does not exist on disk.
        ValueError: If :func:`pytorch_kinematics.build_serial_chain_from_urdf`
            fails to extract a chain ending at ``ee_link``.
    """

    def __init__(
        self,
        urdf_path: str | None = None,
        *,
        ee_link: str = "panda_hand_tcp",
    ) -> None:
        """Parse the URDF and cache the serial chain (ADR-007 §Stage 1b)."""
        import pytorch_kinematics as pk

        if urdf_path is None:
            from mani_skill import PACKAGE_ASSET_DIR

            urdf_path = f"{PACKAGE_ASSET_DIR}/robots/panda/panda_v3.urdf"
        with open(urdf_path, "rb") as fh:
            urdf_blob = fh.read()
        self._chain = pk.build_serial_chain_from_urdf(urdf_blob, end_link_name=ee_link)
        self._ee_link: str = ee_link
        if self._chain.n_joints != PANDA_ARM_DOF:
            msg = (
                f"PandaJacobianProvider: expected {PANDA_ARM_DOF}-joint serial chain "
                f"to {ee_link!r}; pytorch_kinematics returned {self._chain.n_joints} "
                "joints. Check URDF integrity or pick a different end-effector link."
            )
            raise ValueError(msg)

    @property
    def ee_link(self) -> str:
        """The end-effector link the chain terminates at (read-only)."""
        return self._ee_link

    def fk_tcp_position(self, qpos_arm: NDArray[np.floating]) -> NDArray[np.float64]:
        """Forward-kinematics TCP position in the arm base frame (ADR-004 §Decision; ADR-026).

        Companion to :meth:`__call__`: evaluates the cached serial
        chain's forward kinematics at ``qpos_arm`` and returns the 3-D
        Cartesian position of :attr:`ee_link` in the panda base
        (``panda_link0``) frame — the same frame the Jacobian
        :meth:`__call__` returns, so a Cartesian error and its
        damped-pseudoinverse joint step compose consistently. Consumed
        by the co-carry matched impedance controller
        (:class:`chamber.partners.cocarry_impedance.CoCarryImpedancePartner`),
        which drives each held bar-end TCP to its cooperative target.

        Args:
            qpos_arm: Joint-angle vector for the 7 panda arm joints,
                shape ``(7,)``, in the same order as
                :attr:`mani_skill.agents.robots.panda.Panda.arm_joint_names`.

        Returns:
            TCP position in the base frame, shape ``(3,)``, dtype
            ``float64``.

        Raises:
            ValueError: If ``qpos_arm`` shape mismatches ``(7,)``.
        """
        import torch

        q = np.asarray(qpos_arm, dtype=np.float32)
        if q.shape != (PANDA_ARM_DOF,):
            msg = (
                f"PandaJacobianProvider.fk_tcp_position: qpos_arm shape {q.shape} "
                f"mismatches expected ({PANDA_ARM_DOF},) for the 7-DOF Panda chain."
            )
            raise ValueError(msg)
        q_torch = torch.from_numpy(q).unsqueeze(0)
        # forward_kinematics(end_only=True default) returns a Transform3d;
        # the pytorch_kinematics stub mistypes it as a dict.
        mat = self._chain.forward_kinematics(q_torch).get_matrix()  # type: ignore[union-attr]
        pos = mat[0, :CARTESIAN_POSITION_DIM, 3].detach().cpu().numpy()
        return np.ascontiguousarray(pos, dtype=np.float64)

    def fk_tcp_rotation(self, qpos_arm: NDArray[np.floating]) -> NDArray[np.float64]:
        """Forward-kinematics TCP rotation matrix in the base frame (ADR-026 §Decision 1; ADR-004).

        Companion to :meth:`fk_tcp_position`: the 3x3 orientation of
        :attr:`ee_link` in the panda base frame at ``qpos_arm``. Consumed by the
        co-insert controllers (:mod:`chamber.partners.coinsert_impedance`), which
        hold the gripper orientation fixed (so the welded peg / socket cannot
        tip under the insertion contact torque) — the 6-DOF orientation-hold
        term the 3x7 linear slice cannot express.

        Args:
            qpos_arm: Joint-angle vector for the 7 panda arm joints, shape ``(7,)``.

        Returns:
            TCP rotation matrix in the base frame, shape ``(3, 3)``, dtype ``float64``.

        Raises:
            ValueError: If ``qpos_arm`` shape mismatches ``(7,)``.
        """
        import torch

        q = np.asarray(qpos_arm, dtype=np.float32)
        if q.shape != (PANDA_ARM_DOF,):
            msg = (
                f"PandaJacobianProvider.fk_tcp_rotation: qpos_arm shape {q.shape} "
                f"mismatches expected ({PANDA_ARM_DOF},) for the 7-DOF Panda chain."
            )
            raise ValueError(msg)
        q_torch = torch.from_numpy(q).unsqueeze(0)
        mat = self._chain.forward_kinematics(q_torch).get_matrix()  # type: ignore[union-attr]
        rot = mat[0, :CARTESIAN_POSITION_DIM, :CARTESIAN_POSITION_DIM].detach().cpu().numpy()
        return np.ascontiguousarray(rot, dtype=np.float64)

    def jacobian_6x7(self, qpos_arm: NDArray[np.floating]) -> NDArray[np.float64]:
        """Full 6x7 SE(3) end-effector Jacobian at ``qpos_arm`` (ADR-026 §Decision 1; ADR-004).

        The linear (rows 0:3) AND angular (rows 3:6) parts of the base-frame
        end-effector Jacobian. The safety stack consumes only the 3x7 linear
        slice (:meth:`__call__`; ADR-004 §Decision — the pairwise distance
        barrier is orientation-free); this full Jacobian is for the co-insert
        controllers' 6-DOF orientation-hold step (:mod:`chamber.partners.
        coinsert_impedance`), which the linear slice cannot express. Same cached
        ``pytorch_kinematics`` chain; no safety-contract change.

        Args:
            qpos_arm: Joint-angle vector for the 7 panda arm joints, shape ``(7,)``.

        Returns:
            The 6x7 Jacobian, shape ``(6, 7)``, dtype ``float64``.

        Raises:
            ValueError: If ``qpos_arm`` shape mismatches ``(7,)``.
        """
        import torch

        q = np.asarray(qpos_arm, dtype=np.float32)
        if q.shape != (PANDA_ARM_DOF,):
            msg = (
                f"PandaJacobianProvider.jacobian_6x7: qpos_arm shape {q.shape} "
                f"mismatches expected ({PANDA_ARM_DOF},) for the 7-DOF Panda chain."
            )
            raise ValueError(msg)
        q_torch = torch.from_numpy(q).unsqueeze(0)
        jac_6x7 = self._chain.jacobian(q_torch)[0].detach().cpu().numpy()
        return np.ascontiguousarray(jac_6x7, dtype=np.float64)

    def __call__(
        self,
        snap: AgentSnapshot,
        qpos_arm: NDArray[np.floating],
    ) -> NDArray[np.float64]:
        """Compute the 3x7 linear end-effector Jacobian at ``qpos_arm`` (ADR-004 §Decision).

        Args:
            snap: Current :class:`AgentSnapshot` — unused at the
                provider level (the Jacobian is a function of joint
                state, not Cartesian state); accepted for Protocol
                conformance with
                :class:`concerto.safety.api.JacobianControlModel.jacobian_fn`.
                See module docstring for the closure-via-env-reference
                rationale and the contingent P1.05.5 follow-up that
                folds qpos into :class:`AgentSnapshot` directly.
            qpos_arm: Joint-angle vector for the 7 panda arm joints, in
                the same order as ``mani_skill.agents.robots.panda.Panda.arm_joint_names``.
                Shape ``(7,)``; dtype float-coercible to ``float32``.

        Returns:
            Linear Jacobian rows of the 6x7 SE(3) Jacobian at
            ``qpos_arm``, shape ``(3, 7)``, dtype ``float64`` (matches
            the :class:`JacobianControlModel` arithmetic contract at
            ``concerto/safety/api.py:560-561``).

        Raises:
            ValueError: If ``qpos_arm`` shape mismatches ``(7,)``.
        """
        del snap  # closure consumer reads qpos from env; see module docstring.
        import torch

        q = np.asarray(qpos_arm, dtype=np.float32)
        if q.shape != (PANDA_ARM_DOF,):
            msg = (
                f"PandaJacobianProvider: qpos_arm shape {q.shape} mismatches expected "
                f"({PANDA_ARM_DOF},) for the 7-DOF Panda chain."
            )
            raise ValueError(msg)
        q_torch = torch.from_numpy(q).unsqueeze(0)
        # pk.SerialChain.jacobian returns (N_batch, 6, n_dof); rows 0:3
        # are the linear part (d_pos / d_q), rows 3:6 are angular.
        # The CBF backbone consumes the linear part only — orientation
        # is out of scope for the pairwise distance barrier
        # (ADR-004 §Decision). See module docstring.
        jac_6x7 = self._chain.jacobian(q_torch)[0]
        jac_3x7 = jac_6x7[:CARTESIAN_POSITION_DIM].detach().cpu().numpy()
        return np.ascontiguousarray(jac_3x7, dtype=np.float64)

ee_link property

ee_link: str

The end-effector link the chain terminates at (read-only).

__call__

__call__(
    snap: AgentSnapshot, qpos_arm: NDArray[floating]
) -> NDArray[np.float64]

Compute the 3x7 linear end-effector Jacobian at qpos_arm (ADR-004 §Decision).

Parameters:

• snap (AgentSnapshot) –

  Current :class:AgentSnapshot — unused at the provider level (the Jacobian is a function of joint state, not Cartesian state); accepted for Protocol conformance with :class:concerto.safety.api.JacobianControlModel.jacobian_fn. See module docstring for the closure-via-env-reference rationale and the contingent P1.05.5 follow-up that folds qpos into :class:AgentSnapshot directly.

• qpos_arm (NDArray[floating]) –

  Joint-angle vector for the 7 panda arm joints, in the same order as mani_skill.agents.robots.panda.Panda.arm_joint_names. Shape (7,); dtype float-coercible to float32.

Returns:

• NDArray[float64] –

  Linear Jacobian rows of the 6x7 SE(3) Jacobian at

• NDArray[float64] –

  qpos_arm, shape (3, 7), dtype float64 (matches

• the ( NDArray[float64] ) –

  class:JacobianControlModel arithmetic contract at

• NDArray[float64] –

  concerto/safety/api.py:560-561).

Raises:

• ValueError –

  If qpos_arm shape mismatches (7,).

Source code in src/chamber/agents/panda_jacobian.py

def __call__(
    self,
    snap: AgentSnapshot,
    qpos_arm: NDArray[np.floating],
) -> NDArray[np.float64]:
    """Compute the 3x7 linear end-effector Jacobian at ``qpos_arm`` (ADR-004 §Decision).

    Args:
        snap: Current :class:`AgentSnapshot` — unused at the
            provider level (the Jacobian is a function of joint
            state, not Cartesian state); accepted for Protocol
            conformance with
            :class:`concerto.safety.api.JacobianControlModel.jacobian_fn`.
            See module docstring for the closure-via-env-reference
            rationale and the contingent P1.05.5 follow-up that
            folds qpos into :class:`AgentSnapshot` directly.
        qpos_arm: Joint-angle vector for the 7 panda arm joints, in
            the same order as ``mani_skill.agents.robots.panda.Panda.arm_joint_names``.
            Shape ``(7,)``; dtype float-coercible to ``float32``.

    Returns:
        Linear Jacobian rows of the 6x7 SE(3) Jacobian at
        ``qpos_arm``, shape ``(3, 7)``, dtype ``float64`` (matches
        the :class:`JacobianControlModel` arithmetic contract at
        ``concerto/safety/api.py:560-561``).

    Raises:
        ValueError: If ``qpos_arm`` shape mismatches ``(7,)``.
    """
    del snap  # closure consumer reads qpos from env; see module docstring.
    import torch

    q = np.asarray(qpos_arm, dtype=np.float32)
    if q.shape != (PANDA_ARM_DOF,):
        msg = (
            f"PandaJacobianProvider: qpos_arm shape {q.shape} mismatches expected "
            f"({PANDA_ARM_DOF},) for the 7-DOF Panda chain."
        )
        raise ValueError(msg)
    q_torch = torch.from_numpy(q).unsqueeze(0)
    # pk.SerialChain.jacobian returns (N_batch, 6, n_dof); rows 0:3
    # are the linear part (d_pos / d_q), rows 3:6 are angular.
    # The CBF backbone consumes the linear part only — orientation
    # is out of scope for the pairwise distance barrier
    # (ADR-004 §Decision). See module docstring.
    jac_6x7 = self._chain.jacobian(q_torch)[0]
    jac_3x7 = jac_6x7[:CARTESIAN_POSITION_DIM].detach().cpu().numpy()
    return np.ascontiguousarray(jac_3x7, dtype=np.float64)

__init__

__init__(
    urdf_path: str | None = None,
    *,
    ee_link: str = "panda_hand_tcp",
) -> None

Parse the URDF and cache the serial chain (ADR-007 §Stage 1b).

Source code in src/chamber/agents/panda_jacobian.py

def __init__(
    self,
    urdf_path: str | None = None,
    *,
    ee_link: str = "panda_hand_tcp",
) -> None:
    """Parse the URDF and cache the serial chain (ADR-007 §Stage 1b)."""
    import pytorch_kinematics as pk

    if urdf_path is None:
        from mani_skill import PACKAGE_ASSET_DIR

        urdf_path = f"{PACKAGE_ASSET_DIR}/robots/panda/panda_v3.urdf"
    with open(urdf_path, "rb") as fh:
        urdf_blob = fh.read()
    self._chain = pk.build_serial_chain_from_urdf(urdf_blob, end_link_name=ee_link)
    self._ee_link: str = ee_link
    if self._chain.n_joints != PANDA_ARM_DOF:
        msg = (
            f"PandaJacobianProvider: expected {PANDA_ARM_DOF}-joint serial chain "
            f"to {ee_link!r}; pytorch_kinematics returned {self._chain.n_joints} "
            "joints. Check URDF integrity or pick a different end-effector link."
        )
        raise ValueError(msg)

fk_tcp_position

fk_tcp_position(
    qpos_arm: NDArray[floating],
) -> NDArray[np.float64]

Forward-kinematics TCP position in the arm base frame (ADR-004 §Decision; ADR-026).

Companion to :meth:__call__: evaluates the cached serial chain's forward kinematics at qpos_arm and returns the 3-D Cartesian position of :attr:ee_link in the panda base (panda_link0) frame — the same frame the Jacobian :meth:__call__ returns, so a Cartesian error and its damped-pseudoinverse joint step compose consistently. Consumed by the co-carry matched impedance controller (:class:chamber.partners.cocarry_impedance.CoCarryImpedancePartner), which drives each held bar-end TCP to its cooperative target.

Parameters:

• qpos_arm (NDArray[floating]) –

  Joint-angle vector for the 7 panda arm joints, shape (7,), in the same order as :attr:mani_skill.agents.robots.panda.Panda.arm_joint_names.

Returns:

• NDArray[float64] –

  TCP position in the base frame, shape (3,), dtype

• NDArray[float64] –

  float64.

Raises:

• ValueError –

  If qpos_arm shape mismatches (7,).

Source code in src/chamber/agents/panda_jacobian.py

def fk_tcp_position(self, qpos_arm: NDArray[np.floating]) -> NDArray[np.float64]:
    """Forward-kinematics TCP position in the arm base frame (ADR-004 §Decision; ADR-026).

    Companion to :meth:`__call__`: evaluates the cached serial
    chain's forward kinematics at ``qpos_arm`` and returns the 3-D
    Cartesian position of :attr:`ee_link` in the panda base
    (``panda_link0``) frame — the same frame the Jacobian
    :meth:`__call__` returns, so a Cartesian error and its
    damped-pseudoinverse joint step compose consistently. Consumed
    by the co-carry matched impedance controller
    (:class:`chamber.partners.cocarry_impedance.CoCarryImpedancePartner`),
    which drives each held bar-end TCP to its cooperative target.

    Args:
        qpos_arm: Joint-angle vector for the 7 panda arm joints,
            shape ``(7,)``, in the same order as
            :attr:`mani_skill.agents.robots.panda.Panda.arm_joint_names`.

    Returns:
        TCP position in the base frame, shape ``(3,)``, dtype
        ``float64``.

    Raises:
        ValueError: If ``qpos_arm`` shape mismatches ``(7,)``.
    """
    import torch

    q = np.asarray(qpos_arm, dtype=np.float32)
    if q.shape != (PANDA_ARM_DOF,):
        msg = (
            f"PandaJacobianProvider.fk_tcp_position: qpos_arm shape {q.shape} "
            f"mismatches expected ({PANDA_ARM_DOF},) for the 7-DOF Panda chain."
        )
        raise ValueError(msg)
    q_torch = torch.from_numpy(q).unsqueeze(0)
    # forward_kinematics(end_only=True default) returns a Transform3d;
    # the pytorch_kinematics stub mistypes it as a dict.
    mat = self._chain.forward_kinematics(q_torch).get_matrix()  # type: ignore[union-attr]
    pos = mat[0, :CARTESIAN_POSITION_DIM, 3].detach().cpu().numpy()
    return np.ascontiguousarray(pos, dtype=np.float64)

fk_tcp_rotation

fk_tcp_rotation(
    qpos_arm: NDArray[floating],
) -> NDArray[np.float64]

Forward-kinematics TCP rotation matrix in the base frame (ADR-026 §Decision 1; ADR-004).

Companion to :meth:fk_tcp_position: the 3x3 orientation of :attr:ee_link in the panda base frame at qpos_arm. Consumed by the co-insert controllers (:mod:chamber.partners.coinsert_impedance), which hold the gripper orientation fixed (so the welded peg / socket cannot tip under the insertion contact torque) — the 6-DOF orientation-hold term the 3x7 linear slice cannot express.

Parameters:

• qpos_arm (NDArray[floating]) –

  Joint-angle vector for the 7 panda arm joints, shape (7,).

Returns:

• NDArray[float64] –

  TCP rotation matrix in the base frame, shape (3, 3), dtype float64.

Raises:

• ValueError –

  If qpos_arm shape mismatches (7,).

Source code in src/chamber/agents/panda_jacobian.py

def fk_tcp_rotation(self, qpos_arm: NDArray[np.floating]) -> NDArray[np.float64]:
    """Forward-kinematics TCP rotation matrix in the base frame (ADR-026 §Decision 1; ADR-004).

    Companion to :meth:`fk_tcp_position`: the 3x3 orientation of
    :attr:`ee_link` in the panda base frame at ``qpos_arm``. Consumed by the
    co-insert controllers (:mod:`chamber.partners.coinsert_impedance`), which
    hold the gripper orientation fixed (so the welded peg / socket cannot
    tip under the insertion contact torque) — the 6-DOF orientation-hold
    term the 3x7 linear slice cannot express.

    Args:
        qpos_arm: Joint-angle vector for the 7 panda arm joints, shape ``(7,)``.

    Returns:
        TCP rotation matrix in the base frame, shape ``(3, 3)``, dtype ``float64``.

    Raises:
        ValueError: If ``qpos_arm`` shape mismatches ``(7,)``.
    """
    import torch

    q = np.asarray(qpos_arm, dtype=np.float32)
    if q.shape != (PANDA_ARM_DOF,):
        msg = (
            f"PandaJacobianProvider.fk_tcp_rotation: qpos_arm shape {q.shape} "
            f"mismatches expected ({PANDA_ARM_DOF},) for the 7-DOF Panda chain."
        )
        raise ValueError(msg)
    q_torch = torch.from_numpy(q).unsqueeze(0)
    mat = self._chain.forward_kinematics(q_torch).get_matrix()  # type: ignore[union-attr]
    rot = mat[0, :CARTESIAN_POSITION_DIM, :CARTESIAN_POSITION_DIM].detach().cpu().numpy()
    return np.ascontiguousarray(rot, dtype=np.float64)

jacobian_6x7

jacobian_6x7(
    qpos_arm: NDArray[floating],
) -> NDArray[np.float64]

Full 6x7 SE(3) end-effector Jacobian at qpos_arm (ADR-026 §Decision 1; ADR-004).

The linear (rows 0:3) AND angular (rows 3:6) parts of the base-frame end-effector Jacobian. The safety stack consumes only the 3x7 linear slice (:meth:__call__; ADR-004 §Decision — the pairwise distance barrier is orientation-free); this full Jacobian is for the co-insert controllers' 6-DOF orientation-hold step (:mod:chamber.partners. coinsert_impedance), which the linear slice cannot express. Same cached pytorch_kinematics chain; no safety-contract change.

Parameters:

• qpos_arm (NDArray[floating]) –

  Joint-angle vector for the 7 panda arm joints, shape (7,).

Returns:

• NDArray[float64] –

  The 6x7 Jacobian, shape (6, 7), dtype float64.

Raises:

• ValueError –

  If qpos_arm shape mismatches (7,).

Source code in src/chamber/agents/panda_jacobian.py

def jacobian_6x7(self, qpos_arm: NDArray[np.floating]) -> NDArray[np.float64]:
    """Full 6x7 SE(3) end-effector Jacobian at ``qpos_arm`` (ADR-026 §Decision 1; ADR-004).

    The linear (rows 0:3) AND angular (rows 3:6) parts of the base-frame
    end-effector Jacobian. The safety stack consumes only the 3x7 linear
    slice (:meth:`__call__`; ADR-004 §Decision — the pairwise distance
    barrier is orientation-free); this full Jacobian is for the co-insert
    controllers' 6-DOF orientation-hold step (:mod:`chamber.partners.
    coinsert_impedance`), which the linear slice cannot express. Same cached
    ``pytorch_kinematics`` chain; no safety-contract change.

    Args:
        qpos_arm: Joint-angle vector for the 7 panda arm joints, shape ``(7,)``.

    Returns:
        The 6x7 Jacobian, shape ``(6, 7)``, dtype ``float64``.

    Raises:
        ValueError: If ``qpos_arm`` shape mismatches ``(7,)``.
    """
    import torch

    q = np.asarray(qpos_arm, dtype=np.float32)
    if q.shape != (PANDA_ARM_DOF,):
        msg = (
            f"PandaJacobianProvider.jacobian_6x7: qpos_arm shape {q.shape} "
            f"mismatches expected ({PANDA_ARM_DOF},) for the 7-DOF Panda chain."
        )
        raise ValueError(msg)
    q_torch = torch.from_numpy(q).unsqueeze(0)
    jac_6x7 = self._chain.jacobian(q_torch)[0].detach().cpu().numpy()
    return np.ascontiguousarray(jac_6x7, dtype=np.float64)

chamber.comm

CHAMBER communication stack — fixed-format channel + URLLC degradation.

ADR-003 §Decision (mandatory fixed-format channel + opt-in learned overlay); ADR-006 §Decision (URLLC-anchored numeric bounds for latency, jitter, drop).

Public surface:

• :class:CommChannel — Protocol (re-exported from :mod:chamber.comm.api).
• :class:CommPacket, :class:Pose, :class:TaskStatePredicate, :data:SCHEMA_VERSION — wire format.
• :class:FixedFormatCommChannel — the mandatory fixed-format encoder/decoder.
• :class:AoIClock — per-uid Age-of-Information accounting.
• :class:ChamberCommError, :class:ChamberCommQPSaturationWarning — error and warning types.

Subsequent PRs (T2.4-T2.6) add the learned-overlay slot, the :class:CommDegradationWrapper, and the URLLC profile table.

AoIClock

Per-uid Age-of-Information accounting (ADR-003 §Decision; ADR-006 §Decision).

Usage::

clock = AoIClock()
clock.mark_fresh("panda")  # registers "panda" with AoI=0
clock.tick(0.01)  # +10 ms for every registered uid
clock.aoi("panda")  # -> 0.01

Uids are auto-registered on first :meth:mark_fresh. :meth:reset clears all registrations so a fresh episode begins from a clean slate.

Source code in src/chamber/comm/aoi.py

class AoIClock:
    """Per-uid Age-of-Information accounting (ADR-003 §Decision; ADR-006 §Decision).

    Usage::

        clock = AoIClock()
        clock.mark_fresh("panda")  # registers "panda" with AoI=0
        clock.tick(0.01)  # +10 ms for every registered uid
        clock.aoi("panda")  # -> 0.01

    Uids are auto-registered on first :meth:`mark_fresh`. :meth:`reset`
    clears all registrations so a fresh episode begins from a clean slate.
    """

    def __init__(self) -> None:
        """Create an empty clock with no uids registered (ADR-003 §Decision)."""
        self._aoi: dict[str, float] = {}

    def reset(self) -> None:
        """Clear every registered uid (ADR-003 §Decision; T2.2 acceptance criterion).

        After ``reset``, :meth:`aoi` raises ``KeyError`` for every uid until
        the next :meth:`mark_fresh`. This matches the channel's
        ``CommChannel.reset`` semantics: a new episode starts with no state.
        """
        self._aoi.clear()

    def mark_fresh(self, uid: str) -> None:
        """Mark ``uid`` as having received a fresh sample (AoI -> 0).

        ADR-003 §Decision: every fresh transmission zeroes that uid's AoI.
        Auto-registers ``uid`` on first call.
        """
        self._aoi[uid] = 0.0

    def tick(self, dt: float) -> None:
        """Advance time by ``dt`` for every registered uid (ADR-003 §Decision).

        Args:
            dt: Elapsed simulation time in seconds. Must be non-negative;
                AoI cannot run backwards (notes/tier2/41 §V definition).

        Raises:
            ValueError: when ``dt`` is negative.
        """
        if dt < 0.0:
            msg = f"tick dt must be non-negative; got {dt!r}"
            raise ValueError(msg)
        for uid in self._aoi:
            self._aoi[uid] += dt

    def aoi(self, uid: str) -> float:
        """Return the current AoI for ``uid`` (ADR-003 §Decision).

        Raises:
            KeyError: if ``uid`` is not registered (loud-fail per ADR-003).
        """
        return self._aoi[uid]

    def snapshot(self) -> dict[str, float]:
        """Return an independent copy of the per-uid AoI map (ADR-003 §Decision).

        The returned dict is decoupled from the clock's internal state, so
        callers may freely mutate it (typical use: pack into the next
        ``CommPacket["aoi"]`` field).
        """
        return dict(self._aoi)

__init__

__init__() -> None

Create an empty clock with no uids registered (ADR-003 §Decision).

Source code in src/chamber/comm/aoi.py

def __init__(self) -> None:
    """Create an empty clock with no uids registered (ADR-003 §Decision)."""
    self._aoi: dict[str, float] = {}

aoi

aoi(uid: str) -> float

Return the current AoI for uid (ADR-003 §Decision).

Raises:

• KeyError –

  if uid is not registered (loud-fail per ADR-003).

Source code in src/chamber/comm/aoi.py

def aoi(self, uid: str) -> float:
    """Return the current AoI for ``uid`` (ADR-003 §Decision).

    Raises:
        KeyError: if ``uid`` is not registered (loud-fail per ADR-003).
    """
    return self._aoi[uid]

mark_fresh

mark_fresh(uid: str) -> None

Mark uid as having received a fresh sample (AoI -> 0).

ADR-003 §Decision: every fresh transmission zeroes that uid's AoI. Auto-registers uid on first call.

Source code in src/chamber/comm/aoi.py

def mark_fresh(self, uid: str) -> None:
    """Mark ``uid`` as having received a fresh sample (AoI -> 0).

    ADR-003 §Decision: every fresh transmission zeroes that uid's AoI.
    Auto-registers ``uid`` on first call.
    """
    self._aoi[uid] = 0.0

reset

reset() -> None

Clear every registered uid (ADR-003 §Decision; T2.2 acceptance criterion).

After reset, :meth:aoi raises KeyError for every uid until the next :meth:mark_fresh. This matches the channel's CommChannel.reset semantics: a new episode starts with no state.

Source code in src/chamber/comm/aoi.py

def reset(self) -> None:
    """Clear every registered uid (ADR-003 §Decision; T2.2 acceptance criterion).

    After ``reset``, :meth:`aoi` raises ``KeyError`` for every uid until
    the next :meth:`mark_fresh`. This matches the channel's
    ``CommChannel.reset`` semantics: a new episode starts with no state.
    """
    self._aoi.clear()

snapshot

snapshot() -> dict[str, float]

Return an independent copy of the per-uid AoI map (ADR-003 §Decision).

The returned dict is decoupled from the clock's internal state, so callers may freely mutate it (typical use: pack into the next CommPacket["aoi"] field).

Source code in src/chamber/comm/aoi.py

def snapshot(self) -> dict[str, float]:
    """Return an independent copy of the per-uid AoI map (ADR-003 §Decision).

    The returned dict is decoupled from the clock's internal state, so
    callers may freely mutate it (typical use: pack into the next
    ``CommPacket["aoi"]`` field).
    """
    return dict(self._aoi)

tick

tick(dt: float) -> None

Advance time by dt for every registered uid (ADR-003 §Decision).

Parameters:

• dt (float) –

  Elapsed simulation time in seconds. Must be non-negative; AoI cannot run backwards (notes/tier2/41 §V definition).

Raises:

• ValueError –

  when dt is negative.

Source code in src/chamber/comm/aoi.py

def tick(self, dt: float) -> None:
    """Advance time by ``dt`` for every registered uid (ADR-003 §Decision).

    Args:
        dt: Elapsed simulation time in seconds. Must be non-negative;
            AoI cannot run backwards (notes/tier2/41 §V definition).

    Raises:
        ValueError: when ``dt`` is negative.
    """
    if dt < 0.0:
        msg = f"tick dt must be non-negative; got {dt!r}"
        raise ValueError(msg)
    for uid in self._aoi:
        self._aoi[uid] += dt

ChamberCommError

Bases: RuntimeError

Raised when a comm-channel contract is violated (ADR-003 §Decision).

Examples include malformed packets (missing schema_version, unrecognised packet keys), unsupported profile lookups, and channel state that cannot be reconciled (e.g., decoding a packet whose schema version differs from the channel's).

Source code in src/chamber/comm/errors.py

class ChamberCommError(RuntimeError):
    """Raised when a comm-channel contract is violated (ADR-003 §Decision).

    Examples include malformed packets (missing ``schema_version``,
    unrecognised packet keys), unsupported profile lookups, and channel
    state that cannot be reconciled (e.g., decoding a packet whose
    schema version differs from the channel's).
    """

ChamberCommQPSaturationWarning

Bases: UserWarning

Emitted when a degradation profile saturates the inner CBF QP (ADR-006 R5).

The QP-saturation guard test in tests/property/test_qp_saturation.py sweeps the :data:chamber.comm.profiles.URLLC_3GPP_R17 table and asserts that the inner CBF QP solve time stays below 1 ms (OSCBF target from ADR-004). If the most aggressive profile saturates, the wrapper raises this warning rather than silently allowing it (ADR-006 Risk register R5).

Source code in src/chamber/comm/errors.py

class ChamberCommQPSaturationWarning(UserWarning):
    """Emitted when a degradation profile saturates the inner CBF QP (ADR-006 R5).

    The QP-saturation guard test in
    ``tests/property/test_qp_saturation.py`` sweeps the
    :data:`chamber.comm.profiles.URLLC_3GPP_R17` table and asserts that
    the inner CBF QP solve time stays below 1 ms (OSCBF target from
    ADR-004). If the most aggressive profile saturates, the wrapper
    raises this warning rather than silently allowing it (ADR-006
    Risk register R5).
    """

CommChannel

Bases: Protocol

Contract for an inter-agent communication channel (ADR-003 §Decision).

Implementations encode the env-side state into a :class:CommPacket and decode it back into the dict subset that downstream consumers (safety filter M3, partner stack M4, evaluation harness M5) expect under obs["comm"]. ADR-006 §Decision: implementations honour the URLLC-anchored latency / jitter / drop bounds when composed with :class:chamber.comm.degradation.CommDegradationWrapper.

Source code in src/chamber/comm/api.py

@runtime_checkable
class CommChannel(Protocol):
    """Contract for an inter-agent communication channel (ADR-003 §Decision).

    Implementations encode the env-side state into a :class:`CommPacket` and
    decode it back into the dict subset that downstream consumers (safety
    filter M3, partner stack M4, evaluation harness M5) expect under
    ``obs["comm"]``. ADR-006 §Decision: implementations honour the
    URLLC-anchored latency / jitter / drop bounds when composed with
    :class:`chamber.comm.degradation.CommDegradationWrapper`.
    """

    def reset(self, *, seed: int | None = None) -> None:
        """Reset channel state at episode start (ADR-003 §Decision).

        Args:
            seed: Optional root seed for the channel's deterministic RNG
                substream (P6 reproducibility). Implementations route this
                through ``concerto.training.seeding.derive_substream``.
        """
        ...

    def encode(self, state: object) -> CommPacket:
        """Encode env state into a comm-channel packet (ADR-003 §Decision).

        Args:
            state: Env-side observation or raw physics state (impl-defined).

        Returns:
            A :class:`CommPacket` honouring :data:`SCHEMA_VERSION`.
        """
        ...

    def decode(self, packet: CommPacket) -> dict[str, object]:
        """Decode a comm-channel packet back into the typed state subset (ADR-003 §Decision).

        Args:
            packet: A :class:`CommPacket` previously produced by :meth:`encode`.

        Returns:
            The schema-typed subset of the env state expressible via the
            packet (pose / task-state predicate / AoI), keyed by uid.
        """
        ...

decode

decode(packet: CommPacket) -> dict[str, object]

Decode a comm-channel packet back into the typed state subset (ADR-003 §Decision).

Parameters:

• packet (CommPacket) –

  A :class:CommPacket previously produced by :meth:encode.

Returns:

• dict[str, object] –

  The schema-typed subset of the env state expressible via the

• dict[str, object] –

  packet (pose / task-state predicate / AoI), keyed by uid.

Source code in src/chamber/comm/api.py

def decode(self, packet: CommPacket) -> dict[str, object]:
    """Decode a comm-channel packet back into the typed state subset (ADR-003 §Decision).

    Args:
        packet: A :class:`CommPacket` previously produced by :meth:`encode`.

    Returns:
        The schema-typed subset of the env state expressible via the
        packet (pose / task-state predicate / AoI), keyed by uid.
    """
    ...

encode

encode(state: object) -> CommPacket

Encode env state into a comm-channel packet (ADR-003 §Decision).

Parameters:

• state (object) –

  Env-side observation or raw physics state (impl-defined).

Returns:

• A ( CommPacket ) –

  class:CommPacket honouring :data:SCHEMA_VERSION.

Source code in src/chamber/comm/api.py

def encode(self, state: object) -> CommPacket:
    """Encode env state into a comm-channel packet (ADR-003 §Decision).

    Args:
        state: Env-side observation or raw physics state (impl-defined).

    Returns:
        A :class:`CommPacket` honouring :data:`SCHEMA_VERSION`.
    """
    ...

reset

reset(*, seed: int | None = None) -> None

Reset channel state at episode start (ADR-003 §Decision).

Parameters:

• seed (int | None, default: None ) –

  Optional root seed for the channel's deterministic RNG substream (P6 reproducibility). Implementations route this through concerto.training.seeding.derive_substream.

Source code in src/chamber/comm/api.py

def reset(self, *, seed: int | None = None) -> None:
    """Reset channel state at episode start (ADR-003 §Decision).

    Args:
        seed: Optional root seed for the channel's deterministic RNG
            substream (P6 reproducibility). Implementations route this
            through ``concerto.training.seeding.derive_substream``.
    """
    ...

CommDegradationStats dataclass

Telemetry counters surfaced for the Stage-2 CM spike (ADR-006 §Decision).

Each delivered packet contributes one entry to latency_ticks (the in-queue dwell time, in ticks). Each dropped packet increments dropped without producing a latency entry.

Source code in src/chamber/comm/degradation.py

@dataclass(frozen=True)
class CommDegradationStats:
    """Telemetry counters surfaced for the Stage-2 CM spike (ADR-006 §Decision).

    Each delivered packet contributes one entry to ``latency_ticks``
    (the in-queue dwell time, in ticks). Each dropped packet increments
    ``dropped`` without producing a latency entry.
    """

    dropped: int = 0
    delivered: int = 0
    latency_ticks: tuple[int, ...] = field(default_factory=tuple)

CommDegradationWrapper

Compose-time degradation around a fixed-format channel (ADR-006 §Decision).

Wraps any :class:~chamber.comm.api.CommChannel and injects URLLC-anchored latency / jitter / drop semantics described above. The inner channel is unaware of degradation; the wrapper is itself a :class:CommChannel so it composes transparently with :class:chamber.envs.comm_shaping.CommShapingWrapper.

Parameters:

• channel (CommChannel) –

  The inner channel whose packets will be degraded.

• profile (DegradationProfile) –

  The degradation envelope (see :class:DegradationProfile).

• tick_period_ms (float, default: 1.0 ) –

  How many milliseconds each encode call represents. Defaults to 1.0 so the URLLC ms-denominated profiles map tick-for-millisecond.

• root_seed (int, default: 0 ) –

  Root seed for the wrapper's RNG (P6 determinism).

Source code in src/chamber/comm/degradation.py

class CommDegradationWrapper:
    """Compose-time degradation around a fixed-format channel (ADR-006 §Decision).

    Wraps any :class:`~chamber.comm.api.CommChannel` and injects
    URLLC-anchored latency / jitter / drop semantics described above. The
    inner channel is unaware of degradation; the wrapper is itself a
    :class:`CommChannel` so it composes transparently with
    :class:`chamber.envs.comm_shaping.CommShapingWrapper`.

    Args:
        channel: The inner channel whose packets will be degraded.
        profile: The degradation envelope (see :class:`DegradationProfile`).
        tick_period_ms: How many milliseconds each ``encode`` call represents.
            Defaults to ``1.0`` so the URLLC ms-denominated profiles map
            tick-for-millisecond.
        root_seed: Root seed for the wrapper's RNG (P6 determinism).
    """

    def __init__(
        self,
        channel: CommChannel,
        profile: DegradationProfile,
        *,
        tick_period_ms: float = 1.0,
        root_seed: int = 0,
    ) -> None:
        """Build the wrapper (ADR-006 §Decision)."""
        if tick_period_ms <= 0.0:
            msg = f"tick_period_ms must be positive; got {tick_period_ms!r}"
            raise ValueError(msg)
        self._channel = channel
        self._profile = profile
        self._tick_period_ms = tick_period_ms
        self._root_seed: int = root_seed
        self._rng = derive_substream(_SUBSTREAM_NAME, root_seed=self._root_seed).default_rng()
        self._tick: int = 0
        self._queue: list[_Queued] = []
        self._visible: CommPacket = _empty_packet()
        self._dropped: int = 0
        self._delivered: int = 0
        self._latency_ticks: list[int] = []

    @property
    def stats(self) -> CommDegradationStats:
        """Return a snapshot of telemetry counters (ADR-006 §Decision; ADR-007 Stage 2 CM)."""
        return CommDegradationStats(
            dropped=self._dropped,
            delivered=self._delivered,
            latency_ticks=tuple(self._latency_ticks),
        )

    def reset(self, *, seed: int | None = None) -> None:
        """Reset the wrapper, the inner channel, and the RNG (ADR-006 §Decision).

        Args:
            seed: Optional new root seed; otherwise the previously stored
                root seed is reused so episode resets stay reproducible.
        """
        if seed is not None:
            self._root_seed = seed
        self._channel.reset(seed=self._root_seed)
        self._rng = derive_substream(_SUBSTREAM_NAME, root_seed=self._root_seed).default_rng()
        self._tick = 0
        self._queue = []
        self._visible = _empty_packet()
        self._dropped = 0
        self._delivered = 0
        self._latency_ticks = []

    def encode(self, state: object) -> CommPacket:
        """Apply URLLC-anchored degradation to the inner channel's packet (ADR-006 §Decision).

        See module docstring for the per-step behaviour spec.
        """
        self._tick += 1
        fresh = self._channel.encode(state)
        if self._draw_drop():
            self._dropped += 1
            self._visible = self._age_packet(self._visible, by_ticks=1)
            return _copy_packet(self._visible)
        delay_ticks = self._draw_delay_ticks()
        self._queue.append(
            _Queued(release_tick=self._tick + delay_ticks, send_tick=self._tick, packet=fresh)
        )
        self._release_due()
        return _copy_packet(self._visible)

    def decode(self, packet: CommPacket) -> dict[str, object]:
        """Delegate decoding to the inner channel (ADR-003 §Decision)."""
        return self._channel.decode(packet)

    def _draw_drop(self) -> bool:
        """True iff the per-tick Bernoulli drop trial fires (P6 deterministic)."""
        if self._profile.drop_rate <= 0.0:
            return False
        return bool(self._rng.random() < self._profile.drop_rate)

    def _draw_delay_ticks(self) -> int:
        """Sample a clipped-Normal latency and convert to whole ticks (P6)."""
        mean = self._profile.latency_mean_ms
        std = self._profile.latency_std_ms
        upper = 2.0 * mean
        if std == 0.0:
            ms = max(0.0, min(mean, upper))
        else:
            rng_sample = float(self._rng.normal(loc=mean, scale=std))
            ms = max(0.0, min(rng_sample, upper))
        return round(ms / self._tick_period_ms)

    def _release_due(self) -> None:
        """Pop every queued packet whose release tick is <= now (ADR-006)."""
        if not self._queue:
            return
        due: list[_Queued] = [q for q in self._queue if q.release_tick <= self._tick]
        if not due:
            return
        self._queue = [q for q in self._queue if q.release_tick > self._tick]
        # The latest send_tick wins as the visible packet (most recent fresh sample).
        winner = max(due, key=lambda q: q.send_tick)
        for q in due:
            self._delivered += 1
            self._latency_ticks.append(q.release_tick - q.send_tick)
        dwell = self._tick - winner.send_tick
        self._visible = self._age_packet(winner.packet, by_ticks=dwell)

    @staticmethod
    def _age_packet(packet: CommPacket, *, by_ticks: int) -> CommPacket:
        """Return a copy of ``packet`` with all per-uid AoI advanced by ``by_ticks`` (ADR-003)."""
        if not packet["aoi"]:
            return packet
        aged_aoi = {uid: value + float(by_ticks) for uid, value in packet["aoi"].items()}
        aged: CommPacket = CommPacket(
            schema_version=packet["schema_version"],
            pose=dict(packet["pose"]),
            task_state=dict(packet["task_state"]),
            aoi=aged_aoi,
            learned_overlay=packet["learned_overlay"],
        )
        return aged

stats property

stats: CommDegradationStats

Return a snapshot of telemetry counters (ADR-006 §Decision; ADR-007 Stage 2 CM).

__init__

__init__(
    channel: CommChannel,
    profile: DegradationProfile,
    *,
    tick_period_ms: float = 1.0,
    root_seed: int = 0,
) -> None

Build the wrapper (ADR-006 §Decision).

Source code in src/chamber/comm/degradation.py

def __init__(
    self,
    channel: CommChannel,
    profile: DegradationProfile,
    *,
    tick_period_ms: float = 1.0,
    root_seed: int = 0,
) -> None:
    """Build the wrapper (ADR-006 §Decision)."""
    if tick_period_ms <= 0.0:
        msg = f"tick_period_ms must be positive; got {tick_period_ms!r}"
        raise ValueError(msg)
    self._channel = channel
    self._profile = profile
    self._tick_period_ms = tick_period_ms
    self._root_seed: int = root_seed
    self._rng = derive_substream(_SUBSTREAM_NAME, root_seed=self._root_seed).default_rng()
    self._tick: int = 0
    self._queue: list[_Queued] = []
    self._visible: CommPacket = _empty_packet()
    self._dropped: int = 0
    self._delivered: int = 0
    self._latency_ticks: list[int] = []

decode

decode(packet: CommPacket) -> dict[str, object]

Delegate decoding to the inner channel (ADR-003 §Decision).

Source code in src/chamber/comm/degradation.py

def decode(self, packet: CommPacket) -> dict[str, object]:
    """Delegate decoding to the inner channel (ADR-003 §Decision)."""
    return self._channel.decode(packet)

encode

encode(state: object) -> CommPacket

Apply URLLC-anchored degradation to the inner channel's packet (ADR-006 §Decision).

See module docstring for the per-step behaviour spec.

Source code in src/chamber/comm/degradation.py

def encode(self, state: object) -> CommPacket:
    """Apply URLLC-anchored degradation to the inner channel's packet (ADR-006 §Decision).

    See module docstring for the per-step behaviour spec.
    """
    self._tick += 1
    fresh = self._channel.encode(state)
    if self._draw_drop():
        self._dropped += 1
        self._visible = self._age_packet(self._visible, by_ticks=1)
        return _copy_packet(self._visible)
    delay_ticks = self._draw_delay_ticks()
    self._queue.append(
        _Queued(release_tick=self._tick + delay_ticks, send_tick=self._tick, packet=fresh)
    )
    self._release_due()
    return _copy_packet(self._visible)

reset

reset(*, seed: int | None = None) -> None

Reset the wrapper, the inner channel, and the RNG (ADR-006 §Decision).

Parameters:

• seed (int | None, default: None ) –

  Optional new root seed; otherwise the previously stored root seed is reused so episode resets stay reproducible.

Source code in src/chamber/comm/degradation.py

def reset(self, *, seed: int | None = None) -> None:
    """Reset the wrapper, the inner channel, and the RNG (ADR-006 §Decision).

    Args:
        seed: Optional new root seed; otherwise the previously stored
            root seed is reused so episode resets stay reproducible.
    """
    if seed is not None:
        self._root_seed = seed
    self._channel.reset(seed=self._root_seed)
    self._rng = derive_substream(_SUBSTREAM_NAME, root_seed=self._root_seed).default_rng()
    self._tick = 0
    self._queue = []
    self._visible = _empty_packet()
    self._dropped = 0
    self._delivered = 0
    self._latency_ticks = []

CommPacket

Bases: TypedDict

The mandatory fixed-format wire packet (ADR-003 §Decision).

Every concrete :class:CommChannel produces and consumes packets of exactly this shape. Downstream:

• The safety filter (M3) reads packet["pose"][uid] and packet["aoi"][uid] deterministically.
• The partner stack (M4) writes packet["pose"][uid] = self.last_pose.
• The evaluation harness (M5) logs from the same surface.

ADR-006 §Decision: AoI is the URLLC-anchored latency proxy.

Source code in src/chamber/comm/api.py

class CommPacket(TypedDict):
    """The mandatory fixed-format wire packet (ADR-003 §Decision).

    Every concrete :class:`CommChannel` produces and consumes packets of
    exactly this shape. Downstream:

    - The safety filter (M3) reads ``packet["pose"][uid]`` and
      ``packet["aoi"][uid]`` deterministically.
    - The partner stack (M4) writes ``packet["pose"][uid] = self.last_pose``.
    - The evaluation harness (M5) logs from the same surface.

    ADR-006 §Decision: AoI is the URLLC-anchored latency proxy.
    """

    schema_version: int
    pose: dict[str, Pose]
    task_state: dict[str, TaskStatePredicate]
    aoi: dict[str, float]
    learned_overlay: torch.Tensor | None

DegradationProfile dataclass

Latency / jitter / drop bounds for a single experimental condition.

ADR-006 §Decision: anchor values come from the URLLC + 3GPP R17 industrial trial corpus. The named profiles in :mod:chamber.comm.profiles cover the Phase-0 Stage-2 CM sweep table.

Parameters:

• latency_mean_ms (float) –

  Mean of the Gaussian latency draw (ms).

• latency_std_ms (float) –

  Std of the Gaussian latency draw (ms); the draw is clipped to [0, 2 * latency_mean_ms].

• drop_rate (float) –

  Bernoulli drop probability per packet (per encode call).

Source code in src/chamber/comm/degradation.py

@dataclass(frozen=True)
class DegradationProfile:
    """Latency / jitter / drop bounds for a single experimental condition.

    ADR-006 §Decision: anchor values come from the URLLC + 3GPP R17 industrial
    trial corpus. The named profiles in :mod:`chamber.comm.profiles` cover the
    Phase-0 Stage-2 CM sweep table.

    Args:
        latency_mean_ms: Mean of the Gaussian latency draw (ms).
        latency_std_ms: Std of the Gaussian latency draw (ms); the draw is
            clipped to ``[0, 2 * latency_mean_ms]``.
        drop_rate: Bernoulli drop probability per packet (per encode call).
    """

    latency_mean_ms: float
    latency_std_ms: float
    drop_rate: float

FixedFormatCommChannel

Mandatory fixed-format channel (ADR-003 §Decision).

On every :meth:encode call: 1. The internal :class:AoIClock advances by one env tick (+1.0). 2. Every uid present in state["pose"] / state["task_state"] is :meth:AoIClock.mark_fresh-ed (its AoI drops to zero). 3. The result is bundled into a :class:CommPacket carrying :data:~chamber.comm.api.SCHEMA_VERSION and a snapshot of every registered uid's AoI.

:meth:decode is the inverse projection: it returns the schema-typed subset of the state expressible via the packet (pose / task-state / AoI / learned overlay). A schema-version mismatch raises :class:~chamber.comm.errors.ChamberCommError.

Determinism: an internal numpy Generator is seeded via :func:concerto.training.seeding.derive_substream and re-seeded on :meth:reset. The encoder is currently fully deterministic from input; the RNG is held for future randomised-encoding features (e.g. dropout on optional fields) without changing the public surface.

Parameters:

• schema_version (int, default: SCHEMA_VERSION ) –

  Version stamp for emitted packets and the value decoders demand. Bumping it requires a new ADR (ADR-003 §"Schema evolution").

Source code in src/chamber/comm/fixed_format.py

class FixedFormatCommChannel:
    """Mandatory fixed-format channel (ADR-003 §Decision).

    On every :meth:`encode` call:
      1. The internal :class:`AoIClock` advances by one env tick (``+1.0``).
      2. Every uid present in ``state["pose"]`` / ``state["task_state"]`` is
         :meth:`AoIClock.mark_fresh`-ed (its AoI drops to zero).
      3. The result is bundled into a :class:`CommPacket` carrying
         :data:`~chamber.comm.api.SCHEMA_VERSION` and a snapshot of every
         registered uid's AoI.

    :meth:`decode` is the inverse projection: it returns the schema-typed
    subset of the state expressible via the packet (pose / task-state / AoI /
    learned overlay). A schema-version mismatch raises
    :class:`~chamber.comm.errors.ChamberCommError`.

    Determinism: an internal numpy ``Generator`` is seeded via
    :func:`concerto.training.seeding.derive_substream` and re-seeded on
    :meth:`reset`. The encoder is currently fully deterministic from input;
    the RNG is held for future randomised-encoding features (e.g. dropout on
    optional fields) without changing the public surface.

    Args:
        schema_version: Version stamp for emitted packets and the value
            decoders demand. Bumping it requires a new ADR
            (ADR-003 §"Schema evolution").
    """

    def __init__(self, *, schema_version: int = SCHEMA_VERSION) -> None:
        """Build a fixed-format channel (ADR-003 §Decision).

        Args:
            schema_version: Wire-format version stamp; defaults to the
                project-wide :data:`SCHEMA_VERSION`.
        """
        self._schema_version = schema_version
        self._aoi = AoIClock()
        self._root_seed: int = 0
        self._rng = derive_substream(_SUBSTREAM_NAME, root_seed=self._root_seed).default_rng()

    def reset(self, *, seed: int | None = None) -> None:
        """Reset the AoI clock and re-seed the channel RNG (ADR-003 §Decision).

        Args:
            seed: Optional new root seed for the channel substream (P6
                determinism). When provided, replaces the previously stored
                root seed; when omitted, the existing root seed is reused so
                episode resets remain reproducible without a fresh seed
                argument.
        """
        self._aoi.reset()
        if seed is not None:
            self._root_seed = seed
        self._rng = derive_substream(_SUBSTREAM_NAME, root_seed=self._root_seed).default_rng()

    def encode(self, state: object) -> CommPacket:
        """Encode env state into a :class:`CommPacket` (ADR-003 §Decision).

        Accepts any mapping with optional ``"pose"`` / ``"task_state"`` /
        ``"learned_overlay"`` keys; non-mapping inputs are treated as empty
        state (the channel simply ages every previously-registered uid).

        Args:
            state: Source state mapping. Recognised keys:

                - ``"pose"``: ``dict[str, Pose]`` — fresh pose per uid.
                - ``"task_state"``: ``dict[str, TaskStatePredicate]`` —
                  optional fresh predicate per uid.
                - ``"learned_overlay"``: optional ``torch.Tensor`` for
                  jointly-trained B6 partners; passed through unchanged.

        Returns:
            A :class:`CommPacket` carrying the current schema version, a
            shallow copy of pose / task-state, the AoI snapshot, and the
            opt-in learned overlay.
        """
        pose_in, task_state_in, learned = self._extract(state)
        self._aoi.tick(1.0)
        for uid in pose_in:
            self._aoi.mark_fresh(uid)
        for uid in task_state_in:
            self._aoi.mark_fresh(uid)
        return CommPacket(
            schema_version=self._schema_version,
            pose=dict(pose_in),
            task_state=dict(task_state_in),
            aoi=self._aoi.snapshot(),
            learned_overlay=learned,
        )

    def decode(self, packet: CommPacket) -> dict[str, object]:
        """Decode a :class:`CommPacket` back into the typed state subset (ADR-003 §Decision).

        Round-trip guarantee: ``decode(encode(state))`` reproduces every
        schema-typed field of ``state`` (pose / task-state / learned overlay)
        and adds the AoI snapshot the channel computed during encode.

        Args:
            packet: A packet previously emitted by :meth:`encode` (or another
                channel honouring the same :data:`SCHEMA_VERSION`).

        Returns:
            A dict with keys ``"pose"`` / ``"task_state"`` / ``"aoi"`` /
            ``"learned_overlay"`` (each a shallow copy where applicable).

        Raises:
            ChamberCommError: when ``packet["schema_version"]`` differs from
                this channel's schema version (ADR-003 §"Schema evolution").
        """
        if packet["schema_version"] != self._schema_version:
            msg = (
                f"comm packet schema_version mismatch: "
                f"channel expects {self._schema_version}, packet carries "
                f"{packet['schema_version']}"
            )
            raise ChamberCommError(msg)
        return {
            "pose": dict(packet["pose"]),
            "task_state": dict(packet["task_state"]),
            "aoi": dict(packet["aoi"]),
            "learned_overlay": packet["learned_overlay"],
        }

    @staticmethod
    def _extract(
        state: object,
    ) -> tuple[Mapping[str, Pose], Mapping[str, TaskStatePredicate], Any]:
        """Pluck the recognised sub-keys from a state-shaped mapping (ADR-003 §Decision)."""
        if not isinstance(state, Mapping):
            return {}, {}, None
        state_map = cast("Mapping[str, Any]", state)
        pose: Mapping[str, Pose] = state_map.get("pose") or {}
        task_state: Mapping[str, TaskStatePredicate] = state_map.get("task_state") or {}
        learned: Any = state_map.get("learned_overlay")
        return pose, task_state, learned

__init__

__init__(*, schema_version: int = SCHEMA_VERSION) -> None

Build a fixed-format channel (ADR-003 §Decision).

Parameters:

• schema_version (int, default: SCHEMA_VERSION ) –

  Wire-format version stamp; defaults to the project-wide :data:SCHEMA_VERSION.

Source code in src/chamber/comm/fixed_format.py

def __init__(self, *, schema_version: int = SCHEMA_VERSION) -> None:
    """Build a fixed-format channel (ADR-003 §Decision).

    Args:
        schema_version: Wire-format version stamp; defaults to the
            project-wide :data:`SCHEMA_VERSION`.
    """
    self._schema_version = schema_version
    self._aoi = AoIClock()
    self._root_seed: int = 0
    self._rng = derive_substream(_SUBSTREAM_NAME, root_seed=self._root_seed).default_rng()

decode

decode(packet: CommPacket) -> dict[str, object]

Decode a :class:CommPacket back into the typed state subset (ADR-003 §Decision).

Round-trip guarantee: decode(encode(state)) reproduces every schema-typed field of state (pose / task-state / learned overlay) and adds the AoI snapshot the channel computed during encode.

Parameters:

• packet (CommPacket) –

  A packet previously emitted by :meth:encode (or another channel honouring the same :data:SCHEMA_VERSION).

Returns:

• dict[str, object] –

  A dict with keys "pose" / "task_state" / "aoi" /

• dict[str, object] –

  "learned_overlay" (each a shallow copy where applicable).

Raises:

• ChamberCommError –

  when packet["schema_version"] differs from this channel's schema version (ADR-003 §"Schema evolution").

Source code in src/chamber/comm/fixed_format.py

def decode(self, packet: CommPacket) -> dict[str, object]:
    """Decode a :class:`CommPacket` back into the typed state subset (ADR-003 §Decision).

    Round-trip guarantee: ``decode(encode(state))`` reproduces every
    schema-typed field of ``state`` (pose / task-state / learned overlay)
    and adds the AoI snapshot the channel computed during encode.

    Args:
        packet: A packet previously emitted by :meth:`encode` (or another
            channel honouring the same :data:`SCHEMA_VERSION`).

    Returns:
        A dict with keys ``"pose"`` / ``"task_state"`` / ``"aoi"`` /
        ``"learned_overlay"`` (each a shallow copy where applicable).

    Raises:
        ChamberCommError: when ``packet["schema_version"]`` differs from
            this channel's schema version (ADR-003 §"Schema evolution").
    """
    if packet["schema_version"] != self._schema_version:
        msg = (
            f"comm packet schema_version mismatch: "
            f"channel expects {self._schema_version}, packet carries "
            f"{packet['schema_version']}"
        )
        raise ChamberCommError(msg)
    return {
        "pose": dict(packet["pose"]),
        "task_state": dict(packet["task_state"]),
        "aoi": dict(packet["aoi"]),
        "learned_overlay": packet["learned_overlay"],
    }

encode

encode(state: object) -> CommPacket

Encode env state into a :class:CommPacket (ADR-003 §Decision).

Accepts any mapping with optional "pose" / "task_state" / "learned_overlay" keys; non-mapping inputs are treated as empty state (the channel simply ages every previously-registered uid).

Parameters:

• state (object) –

  Source state mapping. Recognised keys:

  • "pose": dict[str, Pose] — fresh pose per uid.
  • "task_state": dict[str, TaskStatePredicate] — optional fresh predicate per uid.
  • "learned_overlay": optional torch.Tensor for jointly-trained B6 partners; passed through unchanged.

Returns:

• A ( CommPacket ) –

  class:CommPacket carrying the current schema version, a

• CommPacket –

  shallow copy of pose / task-state, the AoI snapshot, and the

• CommPacket –

  opt-in learned overlay.

Source code in src/chamber/comm/fixed_format.py

def encode(self, state: object) -> CommPacket:
    """Encode env state into a :class:`CommPacket` (ADR-003 §Decision).

    Accepts any mapping with optional ``"pose"`` / ``"task_state"`` /
    ``"learned_overlay"`` keys; non-mapping inputs are treated as empty
    state (the channel simply ages every previously-registered uid).

    Args:
        state: Source state mapping. Recognised keys:

            - ``"pose"``: ``dict[str, Pose]`` — fresh pose per uid.
            - ``"task_state"``: ``dict[str, TaskStatePredicate]`` —
              optional fresh predicate per uid.
            - ``"learned_overlay"``: optional ``torch.Tensor`` for
              jointly-trained B6 partners; passed through unchanged.

    Returns:
        A :class:`CommPacket` carrying the current schema version, a
        shallow copy of pose / task-state, the AoI snapshot, and the
        opt-in learned overlay.
    """
    pose_in, task_state_in, learned = self._extract(state)
    self._aoi.tick(1.0)
    for uid in pose_in:
        self._aoi.mark_fresh(uid)
    for uid in task_state_in:
        self._aoi.mark_fresh(uid)
    return CommPacket(
        schema_version=self._schema_version,
        pose=dict(pose_in),
        task_state=dict(task_state_in),
        aoi=self._aoi.snapshot(),
        learned_overlay=learned,
    )

reset

reset(*, seed: int | None = None) -> None

Reset the AoI clock and re-seed the channel RNG (ADR-003 §Decision).

Parameters:

• seed (int | None, default: None ) –

  Optional new root seed for the channel substream (P6 determinism). When provided, replaces the previously stored root seed; when omitted, the existing root seed is reused so episode resets remain reproducible without a fresh seed argument.

Source code in src/chamber/comm/fixed_format.py

def reset(self, *, seed: int | None = None) -> None:
    """Reset the AoI clock and re-seed the channel RNG (ADR-003 §Decision).

    Args:
        seed: Optional new root seed for the channel substream (P6
            determinism). When provided, replaces the previously stored
            root seed; when omitted, the existing root seed is reused so
            episode resets remain reproducible without a fresh seed
            argument.
    """
    self._aoi.reset()
    if seed is not None:
        self._root_seed = seed
    self._rng = derive_substream(_SUBSTREAM_NAME, root_seed=self._root_seed).default_rng()

LearnedOverlay

Holds an optional learned-message tensor (ADR-003 §Decision).

The class is a thin slot wrapper: encode returns whatever tensor a jointly-trained partner has set (or None), and decode is null-safe so black-box consumers can call it unconditionally.

Parameters:

• tensor (Tensor | None, default: None ) –

  Initial overlay value. Defaults to None so the slot is interoperable with the black-box partner contract out of the box.

Source code in src/chamber/comm/learned_overlay.py

class LearnedOverlay:
    """Holds an optional learned-message tensor (ADR-003 §Decision).

    The class is a thin slot wrapper: ``encode`` returns whatever tensor a
    jointly-trained partner has set (or ``None``), and ``decode`` is
    null-safe so black-box consumers can call it unconditionally.

    Args:
        tensor: Initial overlay value. Defaults to ``None`` so the slot is
            interoperable with the black-box partner contract out of the box.
    """

    def __init__(self, tensor: torch.Tensor | None = None) -> None:
        """Build an overlay slot, optionally pre-populated (ADR-003 §Decision)."""
        self._tensor: torch.Tensor | None = tensor

    @property
    def tensor(self) -> torch.Tensor | None:
        """Return the currently held tensor, or ``None`` (ADR-003 §Decision)."""
        return self._tensor

    def set(self, tensor: torch.Tensor | None) -> None:
        """Replace the held tensor (ADR-003 §Decision).

        Jointly-trained partners call this from their forward pass; black-box
        partners never invoke it (or invoke it with ``None``), preserving the
        null-safety guarantee.
        """
        self._tensor = tensor

    def reset(self) -> None:
        """Clear the overlay (ADR-003 §Decision; episode boundary).

        Called by the channel on env reset so cross-episode message tensors
        do not leak across episode boundaries.
        """
        self._tensor = None

    def encode(self) -> torch.Tensor | None:
        """No-op encoder: returns the held tensor (ADR-003 §Decision).

        Phase-1 will replace this with the message GNN forward pass; for
        Phase-0 the slot semantics are sufficient for the
        :class:`~chamber.comm.api.CommPacket` ``learned_overlay`` field.
        """
        return self._tensor

    @staticmethod
    def decode(packet_overlay: torch.Tensor | None) -> torch.Tensor | None:
        """Null-safe decoder for the packet's learned overlay (ADR-003 §Decision).

        Black-box partners receive a packet whose ``learned_overlay`` is
        ``None``; jointly-trained partners receive the producer's tensor
        unchanged. Either path returns without raising.
        """
        return packet_overlay

tensor property

tensor: Tensor | None

Return the currently held tensor, or None (ADR-003 §Decision).

__init__

__init__(tensor: Tensor | None = None) -> None

Build an overlay slot, optionally pre-populated (ADR-003 §Decision).

Source code in src/chamber/comm/learned_overlay.py

def __init__(self, tensor: torch.Tensor | None = None) -> None:
    """Build an overlay slot, optionally pre-populated (ADR-003 §Decision)."""
    self._tensor: torch.Tensor | None = tensor

decode staticmethod

decode(
    packet_overlay: Tensor | None,
) -> torch.Tensor | None

Null-safe decoder for the packet's learned overlay (ADR-003 §Decision).

Black-box partners receive a packet whose learned_overlay is None; jointly-trained partners receive the producer's tensor unchanged. Either path returns without raising.

Source code in src/chamber/comm/learned_overlay.py

@staticmethod
def decode(packet_overlay: torch.Tensor | None) -> torch.Tensor | None:
    """Null-safe decoder for the packet's learned overlay (ADR-003 §Decision).

    Black-box partners receive a packet whose ``learned_overlay`` is
    ``None``; jointly-trained partners receive the producer's tensor
    unchanged. Either path returns without raising.
    """
    return packet_overlay

encode

encode() -> torch.Tensor | None

No-op encoder: returns the held tensor (ADR-003 §Decision).

Phase-1 will replace this with the message GNN forward pass; for Phase-0 the slot semantics are sufficient for the :class:~chamber.comm.api.CommPacket learned_overlay field.

Source code in src/chamber/comm/learned_overlay.py

def encode(self) -> torch.Tensor | None:
    """No-op encoder: returns the held tensor (ADR-003 §Decision).

    Phase-1 will replace this with the message GNN forward pass; for
    Phase-0 the slot semantics are sufficient for the
    :class:`~chamber.comm.api.CommPacket` ``learned_overlay`` field.
    """
    return self._tensor

reset

reset() -> None

Clear the overlay (ADR-003 §Decision; episode boundary).

Called by the channel on env reset so cross-episode message tensors do not leak across episode boundaries.

Source code in src/chamber/comm/learned_overlay.py

def reset(self) -> None:
    """Clear the overlay (ADR-003 §Decision; episode boundary).

    Called by the channel on env reset so cross-episode message tensors
    do not leak across episode boundaries.
    """
    self._tensor = None

set

set(tensor: Tensor | None) -> None

Replace the held tensor (ADR-003 §Decision).

Jointly-trained partners call this from their forward pass; black-box partners never invoke it (or invoke it with None), preserving the null-safety guarantee.

Source code in src/chamber/comm/learned_overlay.py

def set(self, tensor: torch.Tensor | None) -> None:
    """Replace the held tensor (ADR-003 §Decision).

    Jointly-trained partners call this from their forward pass; black-box
    partners never invoke it (or invoke it with ``None``), preserving the
    null-safety guarantee.
    """
    self._tensor = tensor

Pose

Bases: TypedDict

SE(3) pose in the env's base frame (ADR-003 §Decision).

The fixed-format channel ships pose as the minimum every black-box partner can produce. Quaternion convention is wxyz (real part first), matching SAPIEN / ManiSkill v3.

Source code in src/chamber/comm/api.py

class Pose(TypedDict):
    """SE(3) pose in the env's base frame (ADR-003 §Decision).

    The fixed-format channel ships pose as the minimum every black-box
    partner can produce. Quaternion convention is wxyz (real part first),
    matching SAPIEN / ManiSkill v3.
    """

    xyz: tuple[float, float, float]
    quat_wxyz: tuple[float, float, float, float]

TaskStatePredicate

Bases: TypedDict

Typed task-state predicates for richer coordination (ADR-003 §Decision).

The fixed-format extension field; all keys are optional so partners that do not produce them remain interoperable. Adding a new key is a schema bump.

Source code in src/chamber/comm/api.py

class TaskStatePredicate(TypedDict, total=False):
    """Typed task-state predicates for richer coordination (ADR-003 §Decision).

    The fixed-format extension field; all keys are optional so partners that
    do not produce them remain interoperable. Adding a new key is a
    schema bump.
    """

    grasp_side: str
    object_class: str
    contact_force: float

saturation_guard

saturation_guard(
    profile: DegradationProfile,
    qp_solve_fn: Callable[
        ..., tuple[float, float]
    ] = solve_qp_stub,
    *,
    qp_time_budget_ms: float = _QP_TIME_BUDGET_MS,
) -> None

Check the inner CBF QP solver's headroom under profile (ADR-006 §Risks R5).

Two conditions trigger :class:~chamber.comm.errors.ChamberCommQPSaturationWarning:

1. The measured QP solve time exceeds qp_time_budget_ms (M3 enforces this on the real solver; the M2 stub returns immediately).
2. The profile is in the saturation regime per ADR-006 R5 — drop rate >= 10 % or latency mean >= 100 ms — even when timing is fine. The regime check exists so the test exists from M2 and M3 cannot regress it.

Parameters:

• profile (DegradationProfile) –

  The :class:DegradationProfile whose feasibility against the inner CBF QP we are testing.

• qp_solve_fn (Callable[..., tuple[float, float]], default: solve_qp_stub ) –

  The QP solver under test. Defaults to :func:concerto.safety.solve_qp_stub; M3 swaps in the real solver. Must return a (decision, elapsed_seconds) pair.

• qp_time_budget_ms (float, default: _QP_TIME_BUDGET_MS ) –

  Solve-time budget. Defaults to the OSCBF target from ADR-004 (1 ms).

Source code in src/chamber/comm/degradation.py

def saturation_guard(
    profile: DegradationProfile,
    qp_solve_fn: Callable[..., tuple[float, float]] = solve_qp_stub,
    *,
    qp_time_budget_ms: float = _QP_TIME_BUDGET_MS,
) -> None:
    """Check the inner CBF QP solver's headroom under ``profile`` (ADR-006 §Risks R5).

    Two conditions trigger :class:`~chamber.comm.errors.ChamberCommQPSaturationWarning`:

      1. The measured QP solve time exceeds ``qp_time_budget_ms`` (M3 enforces
         this on the real solver; the M2 stub returns immediately).
      2. The profile is in the saturation regime per ADR-006 R5 — drop rate
         >= 10 % or latency mean >= 100 ms — even when timing is fine. The
         regime check exists so the test exists from M2 and M3 cannot regress
         it.

    Args:
        profile: The :class:`DegradationProfile` whose feasibility against the
            inner CBF QP we are testing.
        qp_solve_fn: The QP solver under test. Defaults to
            :func:`concerto.safety.solve_qp_stub`; M3 swaps in the real
            solver. Must return a ``(decision, elapsed_seconds)`` pair.
        qp_time_budget_ms: Solve-time budget. Defaults to the OSCBF target
            from ADR-004 (1 ms).
    """
    start = time.perf_counter()
    qp_solve_fn()
    elapsed_ms = (time.perf_counter() - start) * 1000.0
    timing_saturated = elapsed_ms > qp_time_budget_ms
    regime_saturated = _profile_in_saturation_regime(profile)
    if not (timing_saturated or regime_saturated):
        return
    reasons: list[str] = []
    if timing_saturated:
        reasons.append(f"QP solve {elapsed_ms:.4f} ms exceeds {qp_time_budget_ms:.4f} ms budget")
    if regime_saturated:
        reasons.append(
            "profile in ADR-006 R5 saturation regime "
            f"(drop_rate={profile.drop_rate}, latency_mean_ms={profile.latency_mean_ms})"
        )
    warnings.warn(
        "ChamberCommQPSaturationWarning: " + "; ".join(reasons),
        ChamberCommQPSaturationWarning,
        stacklevel=2,
    )

Public API for the CHAMBER comm stack — Protocol + packet shape + schema.

ADR-003 §Decision: defines the canonical wire format of the mandatory fixed-format channel (pose per uid, task-state predicate per uid, AoI per uid) plus an opt-in learned-overlay tensor field, and the :class:CommChannel Protocol that every concrete channel implements.

ADR-006 §Decision: schema versioning protects the URLLC-anchored numeric bounds against silent drift; bumping :data:SCHEMA_VERSION requires a new ADR.

The Protocol lives on the benchmark side (this module) rather than under concerto.api because its signatures reference :class:CommPacket, which is the benchmark's wire format. The dependency-direction rule (plan/10 §2) forbids concerto.* from importing chamber.*; placing the Protocol here keeps the rule intact.

CommChannel

Bases: Protocol

Contract for an inter-agent communication channel (ADR-003 §Decision).

Implementations encode the env-side state into a :class:CommPacket and decode it back into the dict subset that downstream consumers (safety filter M3, partner stack M4, evaluation harness M5) expect under obs["comm"]. ADR-006 §Decision: implementations honour the URLLC-anchored latency / jitter / drop bounds when composed with :class:chamber.comm.degradation.CommDegradationWrapper.

Source code in src/chamber/comm/api.py

@runtime_checkable
class CommChannel(Protocol):
    """Contract for an inter-agent communication channel (ADR-003 §Decision).

    Implementations encode the env-side state into a :class:`CommPacket` and
    decode it back into the dict subset that downstream consumers (safety
    filter M3, partner stack M4, evaluation harness M5) expect under
    ``obs["comm"]``. ADR-006 §Decision: implementations honour the
    URLLC-anchored latency / jitter / drop bounds when composed with
    :class:`chamber.comm.degradation.CommDegradationWrapper`.
    """

    def reset(self, *, seed: int | None = None) -> None:
        """Reset channel state at episode start (ADR-003 §Decision).

        Args:
            seed: Optional root seed for the channel's deterministic RNG
                substream (P6 reproducibility). Implementations route this
                through ``concerto.training.seeding.derive_substream``.
        """
        ...

    def encode(self, state: object) -> CommPacket:
        """Encode env state into a comm-channel packet (ADR-003 §Decision).

        Args:
            state: Env-side observation or raw physics state (impl-defined).

        Returns:
            A :class:`CommPacket` honouring :data:`SCHEMA_VERSION`.
        """
        ...

    def decode(self, packet: CommPacket) -> dict[str, object]:
        """Decode a comm-channel packet back into the typed state subset (ADR-003 §Decision).

        Args:
            packet: A :class:`CommPacket` previously produced by :meth:`encode`.

        Returns:
            The schema-typed subset of the env state expressible via the
            packet (pose / task-state predicate / AoI), keyed by uid.
        """
        ...

decode

decode(packet: CommPacket) -> dict[str, object]

Decode a comm-channel packet back into the typed state subset (ADR-003 §Decision).

Parameters:

• packet (CommPacket) –

  A :class:CommPacket previously produced by :meth:encode.

Returns:

• dict[str, object] –

  The schema-typed subset of the env state expressible via the

• dict[str, object] –

  packet (pose / task-state predicate / AoI), keyed by uid.

Source code in src/chamber/comm/api.py

def decode(self, packet: CommPacket) -> dict[str, object]:
    """Decode a comm-channel packet back into the typed state subset (ADR-003 §Decision).

    Args:
        packet: A :class:`CommPacket` previously produced by :meth:`encode`.

    Returns:
        The schema-typed subset of the env state expressible via the
        packet (pose / task-state predicate / AoI), keyed by uid.
    """
    ...

encode

encode(state: object) -> CommPacket

Encode env state into a comm-channel packet (ADR-003 §Decision).

Parameters:

• state (object) –

  Env-side observation or raw physics state (impl-defined).

Returns:

• A ( CommPacket ) –

  class:CommPacket honouring :data:SCHEMA_VERSION.

Source code in src/chamber/comm/api.py

def encode(self, state: object) -> CommPacket:
    """Encode env state into a comm-channel packet (ADR-003 §Decision).

    Args:
        state: Env-side observation or raw physics state (impl-defined).

    Returns:
        A :class:`CommPacket` honouring :data:`SCHEMA_VERSION`.
    """
    ...

reset

reset(*, seed: int | None = None) -> None

Reset channel state at episode start (ADR-003 §Decision).

Parameters:

• seed (int | None, default: None ) –

  Optional root seed for the channel's deterministic RNG substream (P6 reproducibility). Implementations route this through concerto.training.seeding.derive_substream.

Source code in src/chamber/comm/api.py

def reset(self, *, seed: int | None = None) -> None:
    """Reset channel state at episode start (ADR-003 §Decision).

    Args:
        seed: Optional root seed for the channel's deterministic RNG
            substream (P6 reproducibility). Implementations route this
            through ``concerto.training.seeding.derive_substream``.
    """
    ...

CommPacket

Bases: TypedDict

The mandatory fixed-format wire packet (ADR-003 §Decision).

Every concrete :class:CommChannel produces and consumes packets of exactly this shape. Downstream:

• The safety filter (M3) reads packet["pose"][uid] and packet["aoi"][uid] deterministically.
• The partner stack (M4) writes packet["pose"][uid] = self.last_pose.
• The evaluation harness (M5) logs from the same surface.

ADR-006 §Decision: AoI is the URLLC-anchored latency proxy.

Source code in src/chamber/comm/api.py

class CommPacket(TypedDict):
    """The mandatory fixed-format wire packet (ADR-003 §Decision).

    Every concrete :class:`CommChannel` produces and consumes packets of
    exactly this shape. Downstream:

    - The safety filter (M3) reads ``packet["pose"][uid]`` and
      ``packet["aoi"][uid]`` deterministically.
    - The partner stack (M4) writes ``packet["pose"][uid] = self.last_pose``.
    - The evaluation harness (M5) logs from the same surface.

    ADR-006 §Decision: AoI is the URLLC-anchored latency proxy.
    """

    schema_version: int
    pose: dict[str, Pose]
    task_state: dict[str, TaskStatePredicate]
    aoi: dict[str, float]
    learned_overlay: torch.Tensor | None

Pose

Bases: TypedDict

SE(3) pose in the env's base frame (ADR-003 §Decision).

The fixed-format channel ships pose as the minimum every black-box partner can produce. Quaternion convention is wxyz (real part first), matching SAPIEN / ManiSkill v3.

Source code in src/chamber/comm/api.py

class Pose(TypedDict):
    """SE(3) pose in the env's base frame (ADR-003 §Decision).

    The fixed-format channel ships pose as the minimum every black-box
    partner can produce. Quaternion convention is wxyz (real part first),
    matching SAPIEN / ManiSkill v3.
    """

    xyz: tuple[float, float, float]
    quat_wxyz: tuple[float, float, float, float]

TaskStatePredicate

Bases: TypedDict

Typed task-state predicates for richer coordination (ADR-003 §Decision).

The fixed-format extension field; all keys are optional so partners that do not produce them remain interoperable. Adding a new key is a schema bump.

Source code in src/chamber/comm/api.py

class TaskStatePredicate(TypedDict, total=False):
    """Typed task-state predicates for richer coordination (ADR-003 §Decision).

    The fixed-format extension field; all keys are optional so partners that
    do not produce them remain interoperable. Adding a new key is a
    schema bump.
    """

    grasp_side: str
    object_class: str
    contact_force: float

Per-uid Age-of-Information clock (T2.2).

ADR-003 §Decision: AoI is the latency proxy carried in every :class:~chamber.comm.api.CommPacket. ADR-006 §Decision: AoI is the URLLC-anchored latency-axis instrumentation for the ADR-007 Stage-2 CM spike.

Semantics follow notes/tier2/41 (Ballotta & Talak 2024): for each uid, AoI is the elapsed simulation time since the last fresh sample arrived. mark_fresh(uid) resets that uid to zero; tick(dt) advances every registered uid by dt. The clock holds no env-side dependency — wall time is supplied by the caller (typically the env tick) so the class remains pure-Python and trivially deterministic (P6).

AoIClock

Per-uid Age-of-Information accounting (ADR-003 §Decision; ADR-006 §Decision).

Usage::

clock = AoIClock()
clock.mark_fresh("panda")  # registers "panda" with AoI=0
clock.tick(0.01)  # +10 ms for every registered uid
clock.aoi("panda")  # -> 0.01

Uids are auto-registered on first :meth:mark_fresh. :meth:reset clears all registrations so a fresh episode begins from a clean slate.

Source code in src/chamber/comm/aoi.py

class AoIClock:
    """Per-uid Age-of-Information accounting (ADR-003 §Decision; ADR-006 §Decision).

    Usage::

        clock = AoIClock()
        clock.mark_fresh("panda")  # registers "panda" with AoI=0
        clock.tick(0.01)  # +10 ms for every registered uid
        clock.aoi("panda")  # -> 0.01

    Uids are auto-registered on first :meth:`mark_fresh`. :meth:`reset`
    clears all registrations so a fresh episode begins from a clean slate.
    """

    def __init__(self) -> None:
        """Create an empty clock with no uids registered (ADR-003 §Decision)."""
        self._aoi: dict[str, float] = {}

    def reset(self) -> None:
        """Clear every registered uid (ADR-003 §Decision; T2.2 acceptance criterion).

        After ``reset``, :meth:`aoi` raises ``KeyError`` for every uid until
        the next :meth:`mark_fresh`. This matches the channel's
        ``CommChannel.reset`` semantics: a new episode starts with no state.
        """
        self._aoi.clear()

    def mark_fresh(self, uid: str) -> None:
        """Mark ``uid`` as having received a fresh sample (AoI -> 0).

        ADR-003 §Decision: every fresh transmission zeroes that uid's AoI.
        Auto-registers ``uid`` on first call.
        """
        self._aoi[uid] = 0.0

    def tick(self, dt: float) -> None:
        """Advance time by ``dt`` for every registered uid (ADR-003 §Decision).

        Args:
            dt: Elapsed simulation time in seconds. Must be non-negative;
                AoI cannot run backwards (notes/tier2/41 §V definition).

        Raises:
            ValueError: when ``dt`` is negative.
        """
        if dt < 0.0:
            msg = f"tick dt must be non-negative; got {dt!r}"
            raise ValueError(msg)
        for uid in self._aoi:
            self._aoi[uid] += dt

    def aoi(self, uid: str) -> float:
        """Return the current AoI for ``uid`` (ADR-003 §Decision).

        Raises:
            KeyError: if ``uid`` is not registered (loud-fail per ADR-003).
        """
        return self._aoi[uid]

    def snapshot(self) -> dict[str, float]:
        """Return an independent copy of the per-uid AoI map (ADR-003 §Decision).

        The returned dict is decoupled from the clock's internal state, so
        callers may freely mutate it (typical use: pack into the next
        ``CommPacket["aoi"]`` field).
        """
        return dict(self._aoi)

__init__

__init__() -> None

Create an empty clock with no uids registered (ADR-003 §Decision).

Source code in src/chamber/comm/aoi.py

def __init__(self) -> None:
    """Create an empty clock with no uids registered (ADR-003 §Decision)."""
    self._aoi: dict[str, float] = {}

aoi

aoi(uid: str) -> float

Return the current AoI for uid (ADR-003 §Decision).

Raises:

• KeyError –

  if uid is not registered (loud-fail per ADR-003).

Source code in src/chamber/comm/aoi.py

def aoi(self, uid: str) -> float:
    """Return the current AoI for ``uid`` (ADR-003 §Decision).

    Raises:
        KeyError: if ``uid`` is not registered (loud-fail per ADR-003).
    """
    return self._aoi[uid]

mark_fresh

mark_fresh(uid: str) -> None

Mark uid as having received a fresh sample (AoI -> 0).

ADR-003 §Decision: every fresh transmission zeroes that uid's AoI. Auto-registers uid on first call.

Source code in src/chamber/comm/aoi.py

def mark_fresh(self, uid: str) -> None:
    """Mark ``uid`` as having received a fresh sample (AoI -> 0).

    ADR-003 §Decision: every fresh transmission zeroes that uid's AoI.
    Auto-registers ``uid`` on first call.
    """
    self._aoi[uid] = 0.0

reset

reset() -> None

Clear every registered uid (ADR-003 §Decision; T2.2 acceptance criterion).

After reset, :meth:aoi raises KeyError for every uid until the next :meth:mark_fresh. This matches the channel's CommChannel.reset semantics: a new episode starts with no state.

Source code in src/chamber/comm/aoi.py

def reset(self) -> None:
    """Clear every registered uid (ADR-003 §Decision; T2.2 acceptance criterion).

    After ``reset``, :meth:`aoi` raises ``KeyError`` for every uid until
    the next :meth:`mark_fresh`. This matches the channel's
    ``CommChannel.reset`` semantics: a new episode starts with no state.
    """
    self._aoi.clear()

snapshot

snapshot() -> dict[str, float]

Return an independent copy of the per-uid AoI map (ADR-003 §Decision).

The returned dict is decoupled from the clock's internal state, so callers may freely mutate it (typical use: pack into the next CommPacket["aoi"] field).

Source code in src/chamber/comm/aoi.py

def snapshot(self) -> dict[str, float]:
    """Return an independent copy of the per-uid AoI map (ADR-003 §Decision).

    The returned dict is decoupled from the clock's internal state, so
    callers may freely mutate it (typical use: pack into the next
    ``CommPacket["aoi"]`` field).
    """
    return dict(self._aoi)

tick

tick(dt: float) -> None

Advance time by dt for every registered uid (ADR-003 §Decision).

Parameters:

• dt (float) –

  Elapsed simulation time in seconds. Must be non-negative; AoI cannot run backwards (notes/tier2/41 §V definition).

Raises:

• ValueError –

  when dt is negative.

Source code in src/chamber/comm/aoi.py

def tick(self, dt: float) -> None:
    """Advance time by ``dt`` for every registered uid (ADR-003 §Decision).

    Args:
        dt: Elapsed simulation time in seconds. Must be non-negative;
            AoI cannot run backwards (notes/tier2/41 §V definition).

    Raises:
        ValueError: when ``dt`` is negative.
    """
    if dt < 0.0:
        msg = f"tick dt must be non-negative; got {dt!r}"
        raise ValueError(msg)
    for uid in self._aoi:
        self._aoi[uid] += dt

Fixed-format communication channel — encoder + decoder (T2.3).

ADR-003 §Decision: this channel is the mandatory baseline every black-box partner can speak. It encodes pose + task-state predicates + AoI per uid into a schema-versioned :class:~chamber.comm.api.CommPacket, with an opt-in learned_overlay slot that jointly-trained partners may fill.

ADR-006 §Decision: the channel itself ships no degradation. URLLC-anchored latency / jitter / drop is composed externally via :class:chamber.comm.degradation.CommDegradationWrapper (T2.5) so that the encoding logic stays pure, deterministic, and trivially testable.

FixedFormatCommChannel

Mandatory fixed-format channel (ADR-003 §Decision).

On every :meth:encode call: 1. The internal :class:AoIClock advances by one env tick (+1.0). 2. Every uid present in state["pose"] / state["task_state"] is :meth:AoIClock.mark_fresh-ed (its AoI drops to zero). 3. The result is bundled into a :class:CommPacket carrying :data:~chamber.comm.api.SCHEMA_VERSION and a snapshot of every registered uid's AoI.

:meth:decode is the inverse projection: it returns the schema-typed subset of the state expressible via the packet (pose / task-state / AoI / learned overlay). A schema-version mismatch raises :class:~chamber.comm.errors.ChamberCommError.

Determinism: an internal numpy Generator is seeded via :func:concerto.training.seeding.derive_substream and re-seeded on :meth:reset. The encoder is currently fully deterministic from input; the RNG is held for future randomised-encoding features (e.g. dropout on optional fields) without changing the public surface.

Parameters:

• schema_version (int, default: SCHEMA_VERSION ) –

  Version stamp for emitted packets and the value decoders demand. Bumping it requires a new ADR (ADR-003 §"Schema evolution").

Source code in src/chamber/comm/fixed_format.py

class FixedFormatCommChannel:
    """Mandatory fixed-format channel (ADR-003 §Decision).

    On every :meth:`encode` call:
      1. The internal :class:`AoIClock` advances by one env tick (``+1.0``).
      2. Every uid present in ``state["pose"]`` / ``state["task_state"]`` is
         :meth:`AoIClock.mark_fresh`-ed (its AoI drops to zero).
      3. The result is bundled into a :class:`CommPacket` carrying
         :data:`~chamber.comm.api.SCHEMA_VERSION` and a snapshot of every
         registered uid's AoI.

    :meth:`decode` is the inverse projection: it returns the schema-typed
    subset of the state expressible via the packet (pose / task-state / AoI /
    learned overlay). A schema-version mismatch raises
    :class:`~chamber.comm.errors.ChamberCommError`.

    Determinism: an internal numpy ``Generator`` is seeded via
    :func:`concerto.training.seeding.derive_substream` and re-seeded on
    :meth:`reset`. The encoder is currently fully deterministic from input;
    the RNG is held for future randomised-encoding features (e.g. dropout on
    optional fields) without changing the public surface.

    Args:
        schema_version: Version stamp for emitted packets and the value
            decoders demand. Bumping it requires a new ADR
            (ADR-003 §"Schema evolution").
    """

    def __init__(self, *, schema_version: int = SCHEMA_VERSION) -> None:
        """Build a fixed-format channel (ADR-003 §Decision).

        Args:
            schema_version: Wire-format version stamp; defaults to the
                project-wide :data:`SCHEMA_VERSION`.
        """
        self._schema_version = schema_version
        self._aoi = AoIClock()
        self._root_seed: int = 0
        self._rng = derive_substream(_SUBSTREAM_NAME, root_seed=self._root_seed).default_rng()

    def reset(self, *, seed: int | None = None) -> None:
        """Reset the AoI clock and re-seed the channel RNG (ADR-003 §Decision).

        Args:
            seed: Optional new root seed for the channel substream (P6
                determinism). When provided, replaces the previously stored
                root seed; when omitted, the existing root seed is reused so
                episode resets remain reproducible without a fresh seed
                argument.
        """
        self._aoi.reset()
        if seed is not None:
            self._root_seed = seed
        self._rng = derive_substream(_SUBSTREAM_NAME, root_seed=self._root_seed).default_rng()

    def encode(self, state: object) -> CommPacket:
        """Encode env state into a :class:`CommPacket` (ADR-003 §Decision).

        Accepts any mapping with optional ``"pose"`` / ``"task_state"`` /
        ``"learned_overlay"`` keys; non-mapping inputs are treated as empty
        state (the channel simply ages every previously-registered uid).

        Args:
            state: Source state mapping. Recognised keys:

                - ``"pose"``: ``dict[str, Pose]`` — fresh pose per uid.
                - ``"task_state"``: ``dict[str, TaskStatePredicate]`` —
                  optional fresh predicate per uid.
                - ``"learned_overlay"``: optional ``torch.Tensor`` for
                  jointly-trained B6 partners; passed through unchanged.

        Returns:
            A :class:`CommPacket` carrying the current schema version, a
            shallow copy of pose / task-state, the AoI snapshot, and the
            opt-in learned overlay.
        """
        pose_in, task_state_in, learned = self._extract(state)
        self._aoi.tick(1.0)
        for uid in pose_in:
            self._aoi.mark_fresh(uid)
        for uid in task_state_in:
            self._aoi.mark_fresh(uid)
        return CommPacket(
            schema_version=self._schema_version,
            pose=dict(pose_in),
            task_state=dict(task_state_in),
            aoi=self._aoi.snapshot(),
            learned_overlay=learned,
        )

    def decode(self, packet: CommPacket) -> dict[str, object]:
        """Decode a :class:`CommPacket` back into the typed state subset (ADR-003 §Decision).

        Round-trip guarantee: ``decode(encode(state))`` reproduces every
        schema-typed field of ``state`` (pose / task-state / learned overlay)
        and adds the AoI snapshot the channel computed during encode.

        Args:
            packet: A packet previously emitted by :meth:`encode` (or another
                channel honouring the same :data:`SCHEMA_VERSION`).

        Returns:
            A dict with keys ``"pose"`` / ``"task_state"`` / ``"aoi"`` /
            ``"learned_overlay"`` (each a shallow copy where applicable).

        Raises:
            ChamberCommError: when ``packet["schema_version"]`` differs from
                this channel's schema version (ADR-003 §"Schema evolution").
        """
        if packet["schema_version"] != self._schema_version:
            msg = (
                f"comm packet schema_version mismatch: "
                f"channel expects {self._schema_version}, packet carries "
                f"{packet['schema_version']}"
            )
            raise ChamberCommError(msg)
        return {
            "pose": dict(packet["pose"]),
            "task_state": dict(packet["task_state"]),
            "aoi": dict(packet["aoi"]),
            "learned_overlay": packet["learned_overlay"],
        }

    @staticmethod
    def _extract(
        state: object,
    ) -> tuple[Mapping[str, Pose], Mapping[str, TaskStatePredicate], Any]:
        """Pluck the recognised sub-keys from a state-shaped mapping (ADR-003 §Decision)."""
        if not isinstance(state, Mapping):
            return {}, {}, None
        state_map = cast("Mapping[str, Any]", state)
        pose: Mapping[str, Pose] = state_map.get("pose") or {}
        task_state: Mapping[str, TaskStatePredicate] = state_map.get("task_state") or {}
        learned: Any = state_map.get("learned_overlay")
        return pose, task_state, learned

__init__

__init__(*, schema_version: int = SCHEMA_VERSION) -> None

Build a fixed-format channel (ADR-003 §Decision).

Parameters:

• schema_version (int, default: SCHEMA_VERSION ) –

  Wire-format version stamp; defaults to the project-wide :data:SCHEMA_VERSION.

Source code in src/chamber/comm/fixed_format.py

def __init__(self, *, schema_version: int = SCHEMA_VERSION) -> None:
    """Build a fixed-format channel (ADR-003 §Decision).

    Args:
        schema_version: Wire-format version stamp; defaults to the
            project-wide :data:`SCHEMA_VERSION`.
    """
    self._schema_version = schema_version
    self._aoi = AoIClock()
    self._root_seed: int = 0
    self._rng = derive_substream(_SUBSTREAM_NAME, root_seed=self._root_seed).default_rng()

decode

decode(packet: CommPacket) -> dict[str, object]

Decode a :class:CommPacket back into the typed state subset (ADR-003 §Decision).

Round-trip guarantee: decode(encode(state)) reproduces every schema-typed field of state (pose / task-state / learned overlay) and adds the AoI snapshot the channel computed during encode.

Parameters:

• packet (CommPacket) –

  A packet previously emitted by :meth:encode (or another channel honouring the same :data:SCHEMA_VERSION).

Returns:

• dict[str, object] –

  A dict with keys "pose" / "task_state" / "aoi" /

• dict[str, object] –

  "learned_overlay" (each a shallow copy where applicable).

Raises:

• ChamberCommError –

  when packet["schema_version"] differs from this channel's schema version (ADR-003 §"Schema evolution").

Source code in src/chamber/comm/fixed_format.py

def decode(self, packet: CommPacket) -> dict[str, object]:
    """Decode a :class:`CommPacket` back into the typed state subset (ADR-003 §Decision).

    Round-trip guarantee: ``decode(encode(state))`` reproduces every
    schema-typed field of ``state`` (pose / task-state / learned overlay)
    and adds the AoI snapshot the channel computed during encode.

    Args:
        packet: A packet previously emitted by :meth:`encode` (or another
            channel honouring the same :data:`SCHEMA_VERSION`).

    Returns:
        A dict with keys ``"pose"`` / ``"task_state"`` / ``"aoi"`` /
        ``"learned_overlay"`` (each a shallow copy where applicable).

    Raises:
        ChamberCommError: when ``packet["schema_version"]`` differs from
            this channel's schema version (ADR-003 §"Schema evolution").
    """
    if packet["schema_version"] != self._schema_version:
        msg = (
            f"comm packet schema_version mismatch: "
            f"channel expects {self._schema_version}, packet carries "
            f"{packet['schema_version']}"
        )
        raise ChamberCommError(msg)
    return {
        "pose": dict(packet["pose"]),
        "task_state": dict(packet["task_state"]),
        "aoi": dict(packet["aoi"]),
        "learned_overlay": packet["learned_overlay"],
    }

encode

encode(state: object) -> CommPacket

Encode env state into a :class:CommPacket (ADR-003 §Decision).

Accepts any mapping with optional "pose" / "task_state" / "learned_overlay" keys; non-mapping inputs are treated as empty state (the channel simply ages every previously-registered uid).

Parameters:

• state (object) –

  Source state mapping. Recognised keys:

  • "pose": dict[str, Pose] — fresh pose per uid.
  • "task_state": dict[str, TaskStatePredicate] — optional fresh predicate per uid.
  • "learned_overlay": optional torch.Tensor for jointly-trained B6 partners; passed through unchanged.

Returns:

• A ( CommPacket ) –

  class:CommPacket carrying the current schema version, a

• CommPacket –

  shallow copy of pose / task-state, the AoI snapshot, and the

• CommPacket –

  opt-in learned overlay.

Source code in src/chamber/comm/fixed_format.py

def encode(self, state: object) -> CommPacket:
    """Encode env state into a :class:`CommPacket` (ADR-003 §Decision).

    Accepts any mapping with optional ``"pose"`` / ``"task_state"`` /
    ``"learned_overlay"`` keys; non-mapping inputs are treated as empty
    state (the channel simply ages every previously-registered uid).

    Args:
        state: Source state mapping. Recognised keys:

            - ``"pose"``: ``dict[str, Pose]`` — fresh pose per uid.
            - ``"task_state"``: ``dict[str, TaskStatePredicate]`` —
              optional fresh predicate per uid.
            - ``"learned_overlay"``: optional ``torch.Tensor`` for
              jointly-trained B6 partners; passed through unchanged.

    Returns:
        A :class:`CommPacket` carrying the current schema version, a
        shallow copy of pose / task-state, the AoI snapshot, and the
        opt-in learned overlay.
    """
    pose_in, task_state_in, learned = self._extract(state)
    self._aoi.tick(1.0)
    for uid in pose_in:
        self._aoi.mark_fresh(uid)
    for uid in task_state_in:
        self._aoi.mark_fresh(uid)
    return CommPacket(
        schema_version=self._schema_version,
        pose=dict(pose_in),
        task_state=dict(task_state_in),
        aoi=self._aoi.snapshot(),
        learned_overlay=learned,
    )

reset

reset(*, seed: int | None = None) -> None

Reset the AoI clock and re-seed the channel RNG (ADR-003 §Decision).

Parameters:

• seed (int | None, default: None ) –

  Optional new root seed for the channel substream (P6 determinism). When provided, replaces the previously stored root seed; when omitted, the existing root seed is reused so episode resets remain reproducible without a fresh seed argument.

Source code in src/chamber/comm/fixed_format.py

def reset(self, *, seed: int | None = None) -> None:
    """Reset the AoI clock and re-seed the channel RNG (ADR-003 §Decision).

    Args:
        seed: Optional new root seed for the channel substream (P6
            determinism). When provided, replaces the previously stored
            root seed; when omitted, the existing root seed is reused so
            episode resets remain reproducible without a fresh seed
            argument.
    """
    self._aoi.reset()
    if seed is not None:
        self._root_seed = seed
    self._rng = derive_substream(_SUBSTREAM_NAME, root_seed=self._root_seed).default_rng()

Opt-in learned-message overlay slot (T2.4).

ADR-003 §Decision (the second of the two channels — opt-in, null-safe); ADR-003 §Risks risk-mitigation 1: black-box partners leave this slot as None so the fixed-format channel alone is sufficient for ad-hoc deployment. Jointly-trained partners (HetGPPO, CommFormer) populate it with a message tensor.

Phase-0 ships only the slot itself plus a no-op encoder; the real learned-comm machinery (HetGPPO message GNN) is a Phase-1 concern.

LearnedOverlay

Holds an optional learned-message tensor (ADR-003 §Decision).

The class is a thin slot wrapper: encode returns whatever tensor a jointly-trained partner has set (or None), and decode is null-safe so black-box consumers can call it unconditionally.

Parameters:

• tensor (Tensor | None, default: None ) –

  Initial overlay value. Defaults to None so the slot is interoperable with the black-box partner contract out of the box.

Source code in src/chamber/comm/learned_overlay.py

class LearnedOverlay:
    """Holds an optional learned-message tensor (ADR-003 §Decision).

    The class is a thin slot wrapper: ``encode`` returns whatever tensor a
    jointly-trained partner has set (or ``None``), and ``decode`` is
    null-safe so black-box consumers can call it unconditionally.

    Args:
        tensor: Initial overlay value. Defaults to ``None`` so the slot is
            interoperable with the black-box partner contract out of the box.
    """

    def __init__(self, tensor: torch.Tensor | None = None) -> None:
        """Build an overlay slot, optionally pre-populated (ADR-003 §Decision)."""
        self._tensor: torch.Tensor | None = tensor

    @property
    def tensor(self) -> torch.Tensor | None:
        """Return the currently held tensor, or ``None`` (ADR-003 §Decision)."""
        return self._tensor

    def set(self, tensor: torch.Tensor | None) -> None:
        """Replace the held tensor (ADR-003 §Decision).

        Jointly-trained partners call this from their forward pass; black-box
        partners never invoke it (or invoke it with ``None``), preserving the
        null-safety guarantee.
        """
        self._tensor = tensor

    def reset(self) -> None:
        """Clear the overlay (ADR-003 §Decision; episode boundary).

        Called by the channel on env reset so cross-episode message tensors
        do not leak across episode boundaries.
        """
        self._tensor = None

    def encode(self) -> torch.Tensor | None:
        """No-op encoder: returns the held tensor (ADR-003 §Decision).

        Phase-1 will replace this with the message GNN forward pass; for
        Phase-0 the slot semantics are sufficient for the
        :class:`~chamber.comm.api.CommPacket` ``learned_overlay`` field.
        """
        return self._tensor

    @staticmethod
    def decode(packet_overlay: torch.Tensor | None) -> torch.Tensor | None:
        """Null-safe decoder for the packet's learned overlay (ADR-003 §Decision).

        Black-box partners receive a packet whose ``learned_overlay`` is
        ``None``; jointly-trained partners receive the producer's tensor
        unchanged. Either path returns without raising.
        """
        return packet_overlay

tensor property

tensor: Tensor | None

Return the currently held tensor, or None (ADR-003 §Decision).

__init__

__init__(tensor: Tensor | None = None) -> None

Build an overlay slot, optionally pre-populated (ADR-003 §Decision).

Source code in src/chamber/comm/learned_overlay.py

def __init__(self, tensor: torch.Tensor | None = None) -> None:
    """Build an overlay slot, optionally pre-populated (ADR-003 §Decision)."""
    self._tensor: torch.Tensor | None = tensor

decode staticmethod

decode(
    packet_overlay: Tensor | None,
) -> torch.Tensor | None

Null-safe decoder for the packet's learned overlay (ADR-003 §Decision).

Black-box partners receive a packet whose learned_overlay is None; jointly-trained partners receive the producer's tensor unchanged. Either path returns without raising.

Source code in src/chamber/comm/learned_overlay.py

@staticmethod
def decode(packet_overlay: torch.Tensor | None) -> torch.Tensor | None:
    """Null-safe decoder for the packet's learned overlay (ADR-003 §Decision).

    Black-box partners receive a packet whose ``learned_overlay`` is
    ``None``; jointly-trained partners receive the producer's tensor
    unchanged. Either path returns without raising.
    """
    return packet_overlay

encode

encode() -> torch.Tensor | None

No-op encoder: returns the held tensor (ADR-003 §Decision).

Phase-1 will replace this with the message GNN forward pass; for Phase-0 the slot semantics are sufficient for the :class:~chamber.comm.api.CommPacket learned_overlay field.

Source code in src/chamber/comm/learned_overlay.py

def encode(self) -> torch.Tensor | None:
    """No-op encoder: returns the held tensor (ADR-003 §Decision).

    Phase-1 will replace this with the message GNN forward pass; for
    Phase-0 the slot semantics are sufficient for the
    :class:`~chamber.comm.api.CommPacket` ``learned_overlay`` field.
    """
    return self._tensor

reset

reset() -> None

Clear the overlay (ADR-003 §Decision; episode boundary).

Called by the channel on env reset so cross-episode message tensors do not leak across episode boundaries.

Source code in src/chamber/comm/learned_overlay.py

def reset(self) -> None:
    """Clear the overlay (ADR-003 §Decision; episode boundary).

    Called by the channel on env reset so cross-episode message tensors
    do not leak across episode boundaries.
    """
    self._tensor = None

set

set(tensor: Tensor | None) -> None

Replace the held tensor (ADR-003 §Decision).

Jointly-trained partners call this from their forward pass; black-box partners never invoke it (or invoke it with None), preserving the null-safety guarantee.

Source code in src/chamber/comm/learned_overlay.py

def set(self, tensor: torch.Tensor | None) -> None:
    """Replace the held tensor (ADR-003 §Decision).

    Jointly-trained partners call this from their forward pass; black-box
    partners never invoke it (or invoke it with ``None``), preserving the
    null-safety guarantee.
    """
    self._tensor = tensor

URLLC-anchored comm degradation wrapper (T2.5).

ADR-006 §Decision: URLLC-anchored numeric bounds — latency 1-100 ms, jitter μs-10 ms, drop 10⁻⁶ to 10⁻² — are applied externally by this wrapper rather than by the channel itself, so the encoding logic in :class:chamber.comm.fixed_format.FixedFormatCommChannel stays pure and testable. ADR-007 Stage-2 CM sweep ranges are exposed via :data:chamber.comm.profiles.URLLC_3GPP_R17.

Behaviour (plan/02 §3.5):

1. With probability profile.drop_rate, the freshly-encoded packet is dropped; the wrapper returns the previous visible packet with all per-uid AoI values incremented by one tick.
2. Otherwise the packet is queued with a delay drawn from Normal(latency_mean_ms, latency_std_ms) clipped to [0, 2 * latency_mean_ms]. Packets due at or before the current tick are released; the most-recently-due packet becomes the visible one, with its per-uid AoI incremented by the time it spent in queue.

Determinism (P6): every random draw is seeded via concerto.training.seeding.derive_substream("comm.degrade", ...) so two wrappers reset with the same seed produce byte-identical traces.

CommDegradationStats dataclass

Telemetry counters surfaced for the Stage-2 CM spike (ADR-006 §Decision).

Each delivered packet contributes one entry to latency_ticks (the in-queue dwell time, in ticks). Each dropped packet increments dropped without producing a latency entry.

Source code in src/chamber/comm/degradation.py

@dataclass(frozen=True)
class CommDegradationStats:
    """Telemetry counters surfaced for the Stage-2 CM spike (ADR-006 §Decision).

    Each delivered packet contributes one entry to ``latency_ticks``
    (the in-queue dwell time, in ticks). Each dropped packet increments
    ``dropped`` without producing a latency entry.
    """

    dropped: int = 0
    delivered: int = 0
    latency_ticks: tuple[int, ...] = field(default_factory=tuple)

CommDegradationWrapper

Compose-time degradation around a fixed-format channel (ADR-006 §Decision).

Wraps any :class:~chamber.comm.api.CommChannel and injects URLLC-anchored latency / jitter / drop semantics described above. The inner channel is unaware of degradation; the wrapper is itself a :class:CommChannel so it composes transparently with :class:chamber.envs.comm_shaping.CommShapingWrapper.

Parameters:

• channel (CommChannel) –

  The inner channel whose packets will be degraded.

• profile (DegradationProfile) –

  The degradation envelope (see :class:DegradationProfile).

• tick_period_ms (float, default: 1.0 ) –

  How many milliseconds each encode call represents. Defaults to 1.0 so the URLLC ms-denominated profiles map tick-for-millisecond.

• root_seed (int, default: 0 ) –

  Root seed for the wrapper's RNG (P6 determinism).

Source code in src/chamber/comm/degradation.py

class CommDegradationWrapper:
    """Compose-time degradation around a fixed-format channel (ADR-006 §Decision).

    Wraps any :class:`~chamber.comm.api.CommChannel` and injects
    URLLC-anchored latency / jitter / drop semantics described above. The
    inner channel is unaware of degradation; the wrapper is itself a
    :class:`CommChannel` so it composes transparently with
    :class:`chamber.envs.comm_shaping.CommShapingWrapper`.

    Args:
        channel: The inner channel whose packets will be degraded.
        profile: The degradation envelope (see :class:`DegradationProfile`).
        tick_period_ms: How many milliseconds each ``encode`` call represents.
            Defaults to ``1.0`` so the URLLC ms-denominated profiles map
            tick-for-millisecond.
        root_seed: Root seed for the wrapper's RNG (P6 determinism).
    """

    def __init__(
        self,
        channel: CommChannel,
        profile: DegradationProfile,
        *,
        tick_period_ms: float = 1.0,
        root_seed: int = 0,
    ) -> None:
        """Build the wrapper (ADR-006 §Decision)."""
        if tick_period_ms <= 0.0:
            msg = f"tick_period_ms must be positive; got {tick_period_ms!r}"
            raise ValueError(msg)
        self._channel = channel
        self._profile = profile
        self._tick_period_ms = tick_period_ms
        self._root_seed: int = root_seed
        self._rng = derive_substream(_SUBSTREAM_NAME, root_seed=self._root_seed).default_rng()
        self._tick: int = 0
        self._queue: list[_Queued] = []
        self._visible: CommPacket = _empty_packet()
        self._dropped: int = 0
        self._delivered: int = 0
        self._latency_ticks: list[int] = []

    @property
    def stats(self) -> CommDegradationStats:
        """Return a snapshot of telemetry counters (ADR-006 §Decision; ADR-007 Stage 2 CM)."""
        return CommDegradationStats(
            dropped=self._dropped,
            delivered=self._delivered,
            latency_ticks=tuple(self._latency_ticks),
        )

    def reset(self, *, seed: int | None = None) -> None:
        """Reset the wrapper, the inner channel, and the RNG (ADR-006 §Decision).

        Args:
            seed: Optional new root seed; otherwise the previously stored
                root seed is reused so episode resets stay reproducible.
        """
        if seed is not None:
            self._root_seed = seed
        self._channel.reset(seed=self._root_seed)
        self._rng = derive_substream(_SUBSTREAM_NAME, root_seed=self._root_seed).default_rng()
        self._tick = 0
        self._queue = []
        self._visible = _empty_packet()
        self._dropped = 0
        self._delivered = 0
        self._latency_ticks = []

    def encode(self, state: object) -> CommPacket:
        """Apply URLLC-anchored degradation to the inner channel's packet (ADR-006 §Decision).

        See module docstring for the per-step behaviour spec.
        """
        self._tick += 1
        fresh = self._channel.encode(state)
        if self._draw_drop():
            self._dropped += 1
            self._visible = self._age_packet(self._visible, by_ticks=1)
            return _copy_packet(self._visible)
        delay_ticks = self._draw_delay_ticks()
        self._queue.append(
            _Queued(release_tick=self._tick + delay_ticks, send_tick=self._tick, packet=fresh)
        )
        self._release_due()
        return _copy_packet(self._visible)

    def decode(self, packet: CommPacket) -> dict[str, object]:
        """Delegate decoding to the inner channel (ADR-003 §Decision)."""
        return self._channel.decode(packet)

    def _draw_drop(self) -> bool:
        """True iff the per-tick Bernoulli drop trial fires (P6 deterministic)."""
        if self._profile.drop_rate <= 0.0:
            return False
        return bool(self._rng.random() < self._profile.drop_rate)

    def _draw_delay_ticks(self) -> int:
        """Sample a clipped-Normal latency and convert to whole ticks (P6)."""
        mean = self._profile.latency_mean_ms
        std = self._profile.latency_std_ms
        upper = 2.0 * mean
        if std == 0.0:
            ms = max(0.0, min(mean, upper))
        else:
            rng_sample = float(self._rng.normal(loc=mean, scale=std))
            ms = max(0.0, min(rng_sample, upper))
        return round(ms / self._tick_period_ms)

    def _release_due(self) -> None:
        """Pop every queued packet whose release tick is <= now (ADR-006)."""
        if not self._queue:
            return
        due: list[_Queued] = [q for q in self._queue if q.release_tick <= self._tick]
        if not due:
            return
        self._queue = [q for q in self._queue if q.release_tick > self._tick]
        # The latest send_tick wins as the visible packet (most recent fresh sample).
        winner = max(due, key=lambda q: q.send_tick)
        for q in due:
            self._delivered += 1
            self._latency_ticks.append(q.release_tick - q.send_tick)
        dwell = self._tick - winner.send_tick
        self._visible = self._age_packet(winner.packet, by_ticks=dwell)

    @staticmethod
    def _age_packet(packet: CommPacket, *, by_ticks: int) -> CommPacket:
        """Return a copy of ``packet`` with all per-uid AoI advanced by ``by_ticks`` (ADR-003)."""
        if not packet["aoi"]:
            return packet
        aged_aoi = {uid: value + float(by_ticks) for uid, value in packet["aoi"].items()}
        aged: CommPacket = CommPacket(
            schema_version=packet["schema_version"],
            pose=dict(packet["pose"]),
            task_state=dict(packet["task_state"]),
            aoi=aged_aoi,
            learned_overlay=packet["learned_overlay"],
        )
        return aged

stats property

stats: CommDegradationStats

Return a snapshot of telemetry counters (ADR-006 §Decision; ADR-007 Stage 2 CM).

__init__

__init__(
    channel: CommChannel,
    profile: DegradationProfile,
    *,
    tick_period_ms: float = 1.0,
    root_seed: int = 0,
) -> None

Build the wrapper (ADR-006 §Decision).

Source code in src/chamber/comm/degradation.py

def __init__(
    self,
    channel: CommChannel,
    profile: DegradationProfile,
    *,
    tick_period_ms: float = 1.0,
    root_seed: int = 0,
) -> None:
    """Build the wrapper (ADR-006 §Decision)."""
    if tick_period_ms <= 0.0:
        msg = f"tick_period_ms must be positive; got {tick_period_ms!r}"
        raise ValueError(msg)
    self._channel = channel
    self._profile = profile
    self._tick_period_ms = tick_period_ms
    self._root_seed: int = root_seed
    self._rng = derive_substream(_SUBSTREAM_NAME, root_seed=self._root_seed).default_rng()
    self._tick: int = 0
    self._queue: list[_Queued] = []
    self._visible: CommPacket = _empty_packet()
    self._dropped: int = 0
    self._delivered: int = 0
    self._latency_ticks: list[int] = []

decode

decode(packet: CommPacket) -> dict[str, object]

Delegate decoding to the inner channel (ADR-003 §Decision).

Source code in src/chamber/comm/degradation.py

def decode(self, packet: CommPacket) -> dict[str, object]:
    """Delegate decoding to the inner channel (ADR-003 §Decision)."""
    return self._channel.decode(packet)

encode

encode(state: object) -> CommPacket

Apply URLLC-anchored degradation to the inner channel's packet (ADR-006 §Decision).

See module docstring for the per-step behaviour spec.

Source code in src/chamber/comm/degradation.py

def encode(self, state: object) -> CommPacket:
    """Apply URLLC-anchored degradation to the inner channel's packet (ADR-006 §Decision).

    See module docstring for the per-step behaviour spec.
    """
    self._tick += 1
    fresh = self._channel.encode(state)
    if self._draw_drop():
        self._dropped += 1
        self._visible = self._age_packet(self._visible, by_ticks=1)
        return _copy_packet(self._visible)
    delay_ticks = self._draw_delay_ticks()
    self._queue.append(
        _Queued(release_tick=self._tick + delay_ticks, send_tick=self._tick, packet=fresh)
    )
    self._release_due()
    return _copy_packet(self._visible)

reset

reset(*, seed: int | None = None) -> None

Reset the wrapper, the inner channel, and the RNG (ADR-006 §Decision).

Parameters:

• seed (int | None, default: None ) –

  Optional new root seed; otherwise the previously stored root seed is reused so episode resets stay reproducible.

Source code in src/chamber/comm/degradation.py

def reset(self, *, seed: int | None = None) -> None:
    """Reset the wrapper, the inner channel, and the RNG (ADR-006 §Decision).

    Args:
        seed: Optional new root seed; otherwise the previously stored
            root seed is reused so episode resets stay reproducible.
    """
    if seed is not None:
        self._root_seed = seed
    self._channel.reset(seed=self._root_seed)
    self._rng = derive_substream(_SUBSTREAM_NAME, root_seed=self._root_seed).default_rng()
    self._tick = 0
    self._queue = []
    self._visible = _empty_packet()
    self._dropped = 0
    self._delivered = 0
    self._latency_ticks = []

DegradationProfile dataclass

Latency / jitter / drop bounds for a single experimental condition.

ADR-006 §Decision: anchor values come from the URLLC + 3GPP R17 industrial trial corpus. The named profiles in :mod:chamber.comm.profiles cover the Phase-0 Stage-2 CM sweep table.

Parameters:

• latency_mean_ms (float) –

  Mean of the Gaussian latency draw (ms).

• latency_std_ms (float) –

  Std of the Gaussian latency draw (ms); the draw is clipped to [0, 2 * latency_mean_ms].

• drop_rate (float) –

  Bernoulli drop probability per packet (per encode call).

Source code in src/chamber/comm/degradation.py

@dataclass(frozen=True)
class DegradationProfile:
    """Latency / jitter / drop bounds for a single experimental condition.

    ADR-006 §Decision: anchor values come from the URLLC + 3GPP R17 industrial
    trial corpus. The named profiles in :mod:`chamber.comm.profiles` cover the
    Phase-0 Stage-2 CM sweep table.

    Args:
        latency_mean_ms: Mean of the Gaussian latency draw (ms).
        latency_std_ms: Std of the Gaussian latency draw (ms); the draw is
            clipped to ``[0, 2 * latency_mean_ms]``.
        drop_rate: Bernoulli drop probability per packet (per encode call).
    """

    latency_mean_ms: float
    latency_std_ms: float
    drop_rate: float

saturation_guard

saturation_guard(
    profile: DegradationProfile,
    qp_solve_fn: Callable[
        ..., tuple[float, float]
    ] = solve_qp_stub,
    *,
    qp_time_budget_ms: float = _QP_TIME_BUDGET_MS,
) -> None

Check the inner CBF QP solver's headroom under profile (ADR-006 §Risks R5).

Two conditions trigger :class:~chamber.comm.errors.ChamberCommQPSaturationWarning:

1. The measured QP solve time exceeds qp_time_budget_ms (M3 enforces this on the real solver; the M2 stub returns immediately).
2. The profile is in the saturation regime per ADR-006 R5 — drop rate >= 10 % or latency mean >= 100 ms — even when timing is fine. The regime check exists so the test exists from M2 and M3 cannot regress it.

Parameters:

• profile (DegradationProfile) –

  The :class:DegradationProfile whose feasibility against the inner CBF QP we are testing.

• qp_solve_fn (Callable[..., tuple[float, float]], default: solve_qp_stub ) –

  The QP solver under test. Defaults to :func:concerto.safety.solve_qp_stub; M3 swaps in the real solver. Must return a (decision, elapsed_seconds) pair.

• qp_time_budget_ms (float, default: _QP_TIME_BUDGET_MS ) –

  Solve-time budget. Defaults to the OSCBF target from ADR-004 (1 ms).

Source code in src/chamber/comm/degradation.py

def saturation_guard(
    profile: DegradationProfile,
    qp_solve_fn: Callable[..., tuple[float, float]] = solve_qp_stub,
    *,
    qp_time_budget_ms: float = _QP_TIME_BUDGET_MS,
) -> None:
    """Check the inner CBF QP solver's headroom under ``profile`` (ADR-006 §Risks R5).

    Two conditions trigger :class:`~chamber.comm.errors.ChamberCommQPSaturationWarning`:

      1. The measured QP solve time exceeds ``qp_time_budget_ms`` (M3 enforces
         this on the real solver; the M2 stub returns immediately).
      2. The profile is in the saturation regime per ADR-006 R5 — drop rate
         >= 10 % or latency mean >= 100 ms — even when timing is fine. The
         regime check exists so the test exists from M2 and M3 cannot regress
         it.

    Args:
        profile: The :class:`DegradationProfile` whose feasibility against the
            inner CBF QP we are testing.
        qp_solve_fn: The QP solver under test. Defaults to
            :func:`concerto.safety.solve_qp_stub`; M3 swaps in the real
            solver. Must return a ``(decision, elapsed_seconds)`` pair.
        qp_time_budget_ms: Solve-time budget. Defaults to the OSCBF target
            from ADR-004 (1 ms).
    """
    start = time.perf_counter()
    qp_solve_fn()
    elapsed_ms = (time.perf_counter() - start) * 1000.0
    timing_saturated = elapsed_ms > qp_time_budget_ms
    regime_saturated = _profile_in_saturation_regime(profile)
    if not (timing_saturated or regime_saturated):
        return
    reasons: list[str] = []
    if timing_saturated:
        reasons.append(f"QP solve {elapsed_ms:.4f} ms exceeds {qp_time_budget_ms:.4f} ms budget")
    if regime_saturated:
        reasons.append(
            "profile in ADR-006 R5 saturation regime "
            f"(drop_rate={profile.drop_rate}, latency_mean_ms={profile.latency_mean_ms})"
        )
    warnings.warn(
        "ChamberCommQPSaturationWarning: " + "; ".join(reasons),
        ChamberCommQPSaturationWarning,
        stacklevel=2,
    )

URLLC-anchored degradation sweep profiles (T2.6).

ADR-006 §Decision: latency 1-100 ms, jitter μs-10 ms, drop 10⁻⁶ to 10⁻² (URLLC + 3GPP Release 17 + arXiv 2501.12792 industrial-trial anchors). The six named profiles below cover the sweep range the ADR-007 Stage-2 CM spike will reproduce; the saturation row is held aside so the QP-saturation property test (T2.7) can prove or refute ADR-006 risk #5 (R5).

Profiles are evaluated in production by composition with :class:chamber.comm.degradation.CommDegradationWrapper; the channel itself ships no degradation (ADR-003 §Decision).

Comm-stack error and warning types.

ADR-003 §Decision (every concrete channel raises :class:ChamberCommError on contract violations, never silently degrades). ADR-006 §Risks #5 / Risk register R5 (the QP-saturation guard fires :class:ChamberCommQPSaturationWarning when the URLLC sweep saturates the inner CBF QP solver).

ChamberCommError

Bases: RuntimeError

Raised when a comm-channel contract is violated (ADR-003 §Decision).

Examples include malformed packets (missing schema_version, unrecognised packet keys), unsupported profile lookups, and channel state that cannot be reconciled (e.g., decoding a packet whose schema version differs from the channel's).

Source code in src/chamber/comm/errors.py

class ChamberCommError(RuntimeError):
    """Raised when a comm-channel contract is violated (ADR-003 §Decision).

    Examples include malformed packets (missing ``schema_version``,
    unrecognised packet keys), unsupported profile lookups, and channel
    state that cannot be reconciled (e.g., decoding a packet whose
    schema version differs from the channel's).
    """

ChamberCommQPSaturationWarning

Bases: UserWarning

Emitted when a degradation profile saturates the inner CBF QP (ADR-006 R5).

The QP-saturation guard test in tests/property/test_qp_saturation.py sweeps the :data:chamber.comm.profiles.URLLC_3GPP_R17 table and asserts that the inner CBF QP solve time stays below 1 ms (OSCBF target from ADR-004). If the most aggressive profile saturates, the wrapper raises this warning rather than silently allowing it (ADR-006 Risk register R5).

Source code in src/chamber/comm/errors.py

class ChamberCommQPSaturationWarning(UserWarning):
    """Emitted when a degradation profile saturates the inner CBF QP (ADR-006 R5).

    The QP-saturation guard test in
    ``tests/property/test_qp_saturation.py`` sweeps the
    :data:`chamber.comm.profiles.URLLC_3GPP_R17` table and asserts that
    the inner CBF QP solve time stays below 1 ms (OSCBF target from
    ADR-004). If the most aggressive profile saturates, the wrapper
    raises this warning rather than silently allowing it (ADR-006
    Risk register R5).
    """

chamber.partners

CHAMBER partner zoo — concrete implementations of the FrozenPartner Protocol.

ADR-009 §Decision (zoo construction); ADR-010 §Decision (FM partner selection); plan/04 §3 (architecture). Phase-0 ships:

• The :class:FrozenPartner Protocol + :class:PartnerSpec dataclass (:mod:chamber.partners.api).
• The plug-in :func:register_partner decorator + :func:load_partner factory + :func:list_registered (:mod:chamber.partners.registry).
• :class:PartnerBase with the _FORBIDDEN_ATTRS shield enforcing the black-box AHT no-joint-training constraint at runtime (:mod:chamber.partners.interface).
• :class:ScriptedHeuristicPartner — Stage-3 draft-zoo entry #1 (:mod:chamber.partners.heuristic).
• :class:FrozenMAPPOPartner — Stage-3 draft-zoo entry #2 (T4.5; :mod:chamber.partners.frozen_mappo). Loads a torch state-dict via :func:concerto.training.checkpoints.load_checkpoint, freezes every parameter, runs inference under :func:torch.no_grad.
• :class:FrozenHARLPartner — Stage-3 draft-zoo entry #3 (T4.6; :mod:chamber.partners.frozen_harl). Loads the HARL HAPPO actor checkpoint produced by :class:chamber.benchmarks.ego_ppo_trainer.EgoPPOTrainer, rebuilds the :class:StochasticPolicy with the same args, freezes every parameter, runs deterministic=True inference under :func:torch.no_grad.
• :class:CoCarryImpedancePartner — the matched hand-written co-carry controller (:mod:chamber.partners.cocarry_impedance; ADR-026 §Decision 1). The frozen teammate the Rung-2 learned incumbent trains against (R-2026-06-B §15); imported here so it registers package-wide.
• :class:OpenVLAPartner and :class:CrossFormerPartner Phase-1 stubs (:mod:chamber.partners.stubs) — ADR-010 §Decision Option B; both raise :class:NotImplementedError referencing the Phase-1 ticket.
• The Phase-0 :func:make_phase0_draft_zoo (real) and the Phase-1 :func:select_zoo stub (:mod:chamber.partners.selection).

The M4-gate integration test (T4.9) lands in a follow-up PR (plan/04 §1).

CoCarryBlindImpedancePartner

Bases: CoCarryImpedancePartner

The matched co-carry controller minus the coupling channel (ADR-027 §Admission A3).

spec.extra keys are those of :class:chamber.partners.cocarry_impedance.CoCarryImpedancePartner; a ki override is ignored — the integral is the coupling-feedback term and is forced to zero (see module docstring).

Source code in src/chamber/partners/cocarry_blind.py

@register_partner(COCARRY_BLIND_IMPEDANCE_CLASS)
class CoCarryBlindImpedancePartner(CoCarryImpedancePartner):
    """The matched co-carry controller minus the coupling channel (ADR-027 §Admission A3).

    ``spec.extra`` keys are those of
    :class:`chamber.partners.cocarry_impedance.CoCarryImpedancePartner`;
    a ``ki`` override is ignored — the integral is the coupling-feedback
    term and is forced to zero (see module docstring).
    """

    def __init__(self, spec: PartnerSpec) -> None:
        """Bind the reference gains with ``ki`` forced to zero (ADR-027 §Admission protocol A3)."""
        super().__init__(spec)
        self._ki = 0.0
        # Dead-reckoned arm joint estimate; booted on the first act() of
        # each episode from the measured ready pose.
        self._q_hat: NDArray[np.float64] | None = None

    def reset(self, *, seed: int | None = None) -> None:
        """Clear the dead-reckoned joint estimate (ADR-009 §Decision; stateless across episodes)."""
        super().reset(seed=seed)
        self._q_hat = None

    def act(
        self,
        obs: Mapping[str, object],
        *,
        deterministic: bool = True,
    ) -> NDArray[np.floating]:
        """Return the blind ``pd_joint_delta_pos`` action (ADR-027 §Admission protocol A3).

        Reads the world goal (task specification) and — on the first
        step of the episode only — the measured joint angles (the
        published ready pose). Thereafter the joint state is
        dead-reckoned from the controller's own emitted commands, so no
        partner- or load-induced deviation is ever observed.

        Args:
            obs: Gymnasium observation mapping (see the reference
                controller); the ``qpos`` leaf is consumed only at the
                episode's first step.
            deterministic: Ignored — the controller is deterministic.

        Returns:
            Float32 action of length 8 (7 normalised joint deltas +
            gripper-open); a gripper-only action if the obs lacks the
            required keys (defensive, mirrors the reference).
        """
        del deterministic
        goal = self._read_goal(obs)
        action = np.zeros(_PANDA_ARM_DOF + 1, dtype=np.float32)
        action[_PANDA_ARM_DOF] = 1.0  # gripper open, mirrors the reference
        if self._q_hat is None:
            boot = self._read_qpos(obs)
            if boot is None:
                return action
            self._q_hat = np.asarray(boot[:_PANDA_ARM_DOF], dtype=np.float64).copy()
        if goal is None:
            return action
        # Reference control law evaluated at the dead-reckoned joints,
        # P-only (the integral is the coupling channel; forced to 0).
        target_world = goal + np.asarray([self._end_sign * self._bar_half_len, 0.0, 0.0])
        target_base = self._base_rot_t @ (target_world - self._base_xyz)
        tcp_base = self._provider.fk_tcp_position(self._q_hat)
        error = target_base - tcp_base
        v_cmd = np.clip(self._kp * error, -self._step_max, self._step_max)
        jac = self._provider(None, self._q_hat)  # type: ignore[arg-type]  # (3, 7), base frame
        jjt = jac @ jac.T + (self._damping**2) * np.eye(_XYZ)
        dq = jac.T @ np.linalg.solve(jjt, v_cmd)
        normalised = np.clip(dq / _ACTION_DELTA_SCALE, -1.0, 1.0)
        # Dead-reckon forward by the command actually emitted.
        self._q_hat = self._q_hat + normalised * _ACTION_DELTA_SCALE
        action[:_PANDA_ARM_DOF] = normalised.astype(np.float32)
        return action

__init__

__init__(spec: PartnerSpec) -> None

Bind the reference gains with ki forced to zero (ADR-027 §Admission protocol A3).

Source code in src/chamber/partners/cocarry_blind.py

def __init__(self, spec: PartnerSpec) -> None:
    """Bind the reference gains with ``ki`` forced to zero (ADR-027 §Admission protocol A3)."""
    super().__init__(spec)
    self._ki = 0.0
    # Dead-reckoned arm joint estimate; booted on the first act() of
    # each episode from the measured ready pose.
    self._q_hat: NDArray[np.float64] | None = None

act

act(
    obs: Mapping[str, object], *, deterministic: bool = True
) -> NDArray[np.floating]

Return the blind pd_joint_delta_pos action (ADR-027 §Admission protocol A3).

Reads the world goal (task specification) and — on the first step of the episode only — the measured joint angles (the published ready pose). Thereafter the joint state is dead-reckoned from the controller's own emitted commands, so no partner- or load-induced deviation is ever observed.

Parameters:

• obs (Mapping[str, object]) –

  Gymnasium observation mapping (see the reference controller); the qpos leaf is consumed only at the episode's first step.

• deterministic (bool, default: True ) –

  Ignored — the controller is deterministic.

Returns:

• NDArray[floating] –

  Float32 action of length 8 (7 normalised joint deltas +

• NDArray[floating] –

  gripper-open); a gripper-only action if the obs lacks the

• NDArray[floating] –

  required keys (defensive, mirrors the reference).

Source code in src/chamber/partners/cocarry_blind.py

def act(
    self,
    obs: Mapping[str, object],
    *,
    deterministic: bool = True,
) -> NDArray[np.floating]:
    """Return the blind ``pd_joint_delta_pos`` action (ADR-027 §Admission protocol A3).

    Reads the world goal (task specification) and — on the first
    step of the episode only — the measured joint angles (the
    published ready pose). Thereafter the joint state is
    dead-reckoned from the controller's own emitted commands, so no
    partner- or load-induced deviation is ever observed.

    Args:
        obs: Gymnasium observation mapping (see the reference
            controller); the ``qpos`` leaf is consumed only at the
            episode's first step.
        deterministic: Ignored — the controller is deterministic.

    Returns:
        Float32 action of length 8 (7 normalised joint deltas +
        gripper-open); a gripper-only action if the obs lacks the
        required keys (defensive, mirrors the reference).
    """
    del deterministic
    goal = self._read_goal(obs)
    action = np.zeros(_PANDA_ARM_DOF + 1, dtype=np.float32)
    action[_PANDA_ARM_DOF] = 1.0  # gripper open, mirrors the reference
    if self._q_hat is None:
        boot = self._read_qpos(obs)
        if boot is None:
            return action
        self._q_hat = np.asarray(boot[:_PANDA_ARM_DOF], dtype=np.float64).copy()
    if goal is None:
        return action
    # Reference control law evaluated at the dead-reckoned joints,
    # P-only (the integral is the coupling channel; forced to 0).
    target_world = goal + np.asarray([self._end_sign * self._bar_half_len, 0.0, 0.0])
    target_base = self._base_rot_t @ (target_world - self._base_xyz)
    tcp_base = self._provider.fk_tcp_position(self._q_hat)
    error = target_base - tcp_base
    v_cmd = np.clip(self._kp * error, -self._step_max, self._step_max)
    jac = self._provider(None, self._q_hat)  # type: ignore[arg-type]  # (3, 7), base frame
    jjt = jac @ jac.T + (self._damping**2) * np.eye(_XYZ)
    dq = jac.T @ np.linalg.solve(jjt, v_cmd)
    normalised = np.clip(dq / _ACTION_DELTA_SCALE, -1.0, 1.0)
    # Dead-reckon forward by the command actually emitted.
    self._q_hat = self._q_hat + normalised * _ACTION_DELTA_SCALE
    action[:_PANDA_ARM_DOF] = normalised.astype(np.float32)
    return action

reset

reset(*, seed: int | None = None) -> None

Clear the dead-reckoned joint estimate (ADR-009 §Decision; stateless across episodes).

Source code in src/chamber/partners/cocarry_blind.py

def reset(self, *, seed: int | None = None) -> None:
    """Clear the dead-reckoned joint estimate (ADR-009 §Decision; stateless across episodes)."""
    super().reset(seed=seed)
    self._q_hat = None

CoCarryImpedancePartner

Bases: PartnerBase

EE-space impedance controller for one co-carry arm (ADR-026 §Decision 1; ADR-009 §Decision).

Reads obs["extra"]["goal_pos"] (the world goal centroid) and obs["agent"][uid]["qpos"] (the arm's joint angles), computes the cooperative TCP target, and returns the pd_joint_delta_pos action that steps the TCP toward it via the damped-pseudoinverse Jacobian.

spec.extra keys:

• uid — the arm this controller drives (panda_wristcam / panda_partner).
• base_xyz — the arm's base position "x,y,z" (world).
• base_yaw_deg — the arm's base yaw about z, degrees ("0" ego, "180" partner).
• end_sign — "+1" if the arm holds the bar's +x end, "-1" for the -x end.
• bar_half_len — half the bar length, metres.
• urdf_path — optional; defaults to the wristcam URDF (panda_partner shares the kinematic chain, so the default is correct for both).
• kp / ki / step_max / damping — optional gain overrides.
• lag_steps — optional bounded transport lag in control steps (default "0" = the historical byte-identical path). A positive lag makes the controller emit the arm command it computed lag_steps steps ago (holding still during the warm-up), i.e. a "sluggish but competent" member: delayed but convergent tracking, since the target is quasi-static and the PI law keeps integrating on the fresh error (ADR-009 §Decision, v1.0 right-sizing amendment 2026-07-05 — the bounded-lag scripted-family member).

Source code in src/chamber/partners/cocarry_impedance.py

@register_partner("cocarry_impedance")
class CoCarryImpedancePartner(PartnerBase):
    """EE-space impedance controller for one co-carry arm (ADR-026 §Decision 1; ADR-009 §Decision).

    Reads ``obs["extra"]["goal_pos"]`` (the world goal centroid) and
    ``obs["agent"][uid]["qpos"]`` (the arm's joint angles), computes the
    cooperative TCP target, and returns the ``pd_joint_delta_pos`` action
    that steps the TCP toward it via the damped-pseudoinverse Jacobian.

    ``spec.extra`` keys:

    - ``uid`` — the arm this controller drives (``panda_wristcam`` /
      ``panda_partner``).
    - ``base_xyz`` — the arm's base position ``"x,y,z"`` (world).
    - ``base_yaw_deg`` — the arm's base yaw about z, degrees
      (``"0"`` ego, ``"180"`` partner).
    - ``end_sign`` — ``"+1"`` if the arm holds the bar's ``+x`` end,
      ``"-1"`` for the ``-x`` end.
    - ``bar_half_len`` — half the bar length, metres.
    - ``urdf_path`` — optional; defaults to the wristcam URDF
      (``panda_partner`` shares the kinematic chain, so the default is
      correct for both).
    - ``kp`` / ``ki`` / ``step_max`` / ``damping`` — optional gain overrides.
    - ``lag_steps`` — optional bounded transport lag in control steps
      (default ``"0"`` = the historical byte-identical path). A positive
      lag makes the controller emit the arm command it computed
      ``lag_steps`` steps ago (holding still during the warm-up), i.e. a
      "sluggish but competent" member: delayed but convergent tracking,
      since the target is quasi-static and the PI law keeps integrating
      on the fresh error (ADR-009 §Decision, v1.0 right-sizing amendment
      2026-07-05 — the bounded-lag scripted-family member).
    """

    def __init__(self, spec: PartnerSpec) -> None:
        """Bind the spec and build the Jacobian/FK provider (ADR-026 §Decision 1)."""
        super().__init__(spec)
        from chamber.agents.panda_jacobian import PandaJacobianProvider

        extra = spec.extra
        self._uid: str = extra.get("uid", "panda_wristcam")
        self._base_xyz: NDArray[np.float64] = _parse_vec3(extra.get("base_xyz", "0,0,0"))
        self._base_rot_t: NDArray[np.float64] = _rot_z(float(extra.get("base_yaw_deg", "0"))).T
        self._end_sign: float = float(extra.get("end_sign", "1"))
        self._bar_half_len: float = float(extra.get("bar_half_len", "0.115"))
        self._kp: float = float(extra.get("kp", str(_DEFAULT_KP)))
        self._ki: float = float(extra.get("ki", str(_DEFAULT_KI)))
        self._step_max: float = float(extra.get("step_max", str(_DEFAULT_STEP_MAX_M)))
        self._damping: float = float(extra.get("damping", str(_DEFAULT_DAMPING)))
        lag_raw = extra.get("lag_steps", "0")
        try:
            self._lag_steps: int = int(lag_raw)
        except ValueError as exc:
            raise ValueError(f"lag_steps must be an int in [0, {_LAG_STEPS_MAX}]") from exc
        if not 0 <= self._lag_steps <= _LAG_STEPS_MAX:
            raise ValueError(
                f"lag_steps must be an int in [0, {_LAG_STEPS_MAX}]; got {self._lag_steps}"
            )
        urdf_path = extra.get("urdf_path")
        self._provider = PandaJacobianProvider(urdf_path)
        # Within-episode Cartesian integral (base frame); cleared in reset.
        self._integral: NDArray[np.float64] = np.zeros(_XYZ, dtype=np.float64)
        # Within-episode bounded-lag buffer of past arm commands; cleared in
        # reset. Empty list when lag_steps == 0 (the byte-identical path).
        self._lag_buffer: list[NDArray[np.float32]] = []

    def reset(self, *, seed: int | None = None) -> None:
        """Clear the within-episode integral + lag buffer (ADR-009 §Decision; stateless).

        The control law is a deterministic function of ``obs`` + ``spec``
        plus within-episode state (the Cartesian integral and the
        bounded-lag command buffer) that is zeroed here, so the partner
        carries no state across episodes (ADR-009 §Decision; plan/04 §2).
        The seed is accepted only for
        :class:`~chamber.partners.api.FrozenPartner` Protocol conformance.
        """
        del seed
        self._integral = np.zeros(_XYZ, dtype=np.float64)
        self._lag_buffer = []

    def act(
        self,
        obs: Mapping[str, object],
        *,
        deterministic: bool = True,
    ) -> NDArray[np.floating]:
        """Return the ``pd_joint_delta_pos`` action toward the target (ADR-026 §Decision 1).

        Args:
            obs: Gymnasium observation mapping with ``obs["extra"]
                ["goal_pos"]`` (world goal centroid) and
                ``obs["agent"][uid]["qpos"]`` (the arm's joint angles).
            deterministic: Ignored — the controller is deterministic.

        Returns:
            Float32 action of length ``_PANDA_ARM_DOF + 1`` (7 normalised
            joint deltas + gripper-open); a gripper-only action if the obs
            lacks the required keys (defensive — keeps the rollout shape
            stable).
        """
        del deterministic
        goal = self._read_goal(obs)
        qpos = self._read_qpos(obs)
        action = np.zeros(_PANDA_ARM_DOF + 1, dtype=np.float32)
        action[_PANDA_ARM_DOF] = _GRIPPER_ACTION_OPEN
        if goal is None or qpos is None:
            return action
        # Cooperative TCP target (world) -> arm base frame.
        target_world = goal + np.asarray([self._end_sign * self._bar_half_len, 0.0, 0.0])
        target_base = self._base_rot_t @ (target_world - self._base_xyz)
        tcp_base = self._provider.fk_tcp_position(qpos)
        error = target_base - tcp_base
        # PI law: the deadzone-gated, anti-windup-clamped integral closes
        # the load-induced steady-state offset of the delta-from-measured
        # joint controller, engaging only once the TCP is near its target.
        if float(np.linalg.norm(error)) < _INTEGRAL_ENGAGE_M:
            self._integral = np.clip(
                self._integral + error * _CONTROL_DT, -_INTEGRAL_CLAMP_MS, _INTEGRAL_CLAMP_MS
            )
        v_cmd = np.clip(
            self._kp * error + self._ki * self._integral, -self._step_max, self._step_max
        )
        jac = self._provider(None, qpos)  # type: ignore[arg-type]  # (3, 7), base frame
        # Damped pseudo-inverse joint step: dq = J^T (J J^T + l^2 I)^-1 v.
        jjt = jac @ jac.T + (self._damping**2) * np.eye(_XYZ)
        dq = jac.T @ np.linalg.solve(jjt, v_cmd)
        action[:_PANDA_ARM_DOF] = np.clip(dq / _ACTION_DELTA_SCALE, -1.0, 1.0).astype(np.float32)
        if self._lag_steps == 0:
            return action
        # Bounded lag (ADR-009 §Decision, 2026-07-05 amendment): emit the arm
        # command computed lag_steps steps ago, holding still through the
        # warm-up. Convergent because the target is quasi-static and the PI
        # law keeps integrating on the fresh error.
        self._lag_buffer.append(action[:_PANDA_ARM_DOF].copy())
        delayed = np.zeros(_PANDA_ARM_DOF + 1, dtype=np.float32)
        delayed[_PANDA_ARM_DOF] = _GRIPPER_ACTION_OPEN
        if len(self._lag_buffer) > self._lag_steps:
            delayed[:_PANDA_ARM_DOF] = self._lag_buffer.pop(0)
        return delayed

    def _read_goal(self, obs: Mapping[str, object]) -> NDArray[np.float64] | None:
        """Read the world goal centroid from ``obs["extra"]["goal_pos"]``."""
        extra = obs.get("extra")
        if not isinstance(extra, Mapping) or "goal_pos" not in extra:
            return None
        goal = _to_numpy_flat(extra["goal_pos"])
        if goal.shape[0] < _XYZ:
            return None
        return goal[:_XYZ]

    def _read_qpos(self, obs: Mapping[str, object]) -> NDArray[np.float64] | None:
        """Read the arm's 7 joint angles from ``obs["agent"][uid]["qpos"]``."""
        agent = obs.get("agent")
        if not isinstance(agent, Mapping) or self._uid not in agent:
            return None
        entry = agent[self._uid]
        if not isinstance(entry, Mapping) or "qpos" not in entry:
            return None
        qpos = _to_numpy_flat(entry["qpos"])
        if qpos.shape[0] < _PANDA_ARM_DOF:
            return None
        return qpos[:_PANDA_ARM_DOF]

__init__

__init__(spec: PartnerSpec) -> None

Bind the spec and build the Jacobian/FK provider (ADR-026 §Decision 1).

Source code in src/chamber/partners/cocarry_impedance.py

def __init__(self, spec: PartnerSpec) -> None:
    """Bind the spec and build the Jacobian/FK provider (ADR-026 §Decision 1)."""
    super().__init__(spec)
    from chamber.agents.panda_jacobian import PandaJacobianProvider

    extra = spec.extra
    self._uid: str = extra.get("uid", "panda_wristcam")
    self._base_xyz: NDArray[np.float64] = _parse_vec3(extra.get("base_xyz", "0,0,0"))
    self._base_rot_t: NDArray[np.float64] = _rot_z(float(extra.get("base_yaw_deg", "0"))).T
    self._end_sign: float = float(extra.get("end_sign", "1"))
    self._bar_half_len: float = float(extra.get("bar_half_len", "0.115"))
    self._kp: float = float(extra.get("kp", str(_DEFAULT_KP)))
    self._ki: float = float(extra.get("ki", str(_DEFAULT_KI)))
    self._step_max: float = float(extra.get("step_max", str(_DEFAULT_STEP_MAX_M)))
    self._damping: float = float(extra.get("damping", str(_DEFAULT_DAMPING)))
    lag_raw = extra.get("lag_steps", "0")
    try:
        self._lag_steps: int = int(lag_raw)
    except ValueError as exc:
        raise ValueError(f"lag_steps must be an int in [0, {_LAG_STEPS_MAX}]") from exc
    if not 0 <= self._lag_steps <= _LAG_STEPS_MAX:
        raise ValueError(
            f"lag_steps must be an int in [0, {_LAG_STEPS_MAX}]; got {self._lag_steps}"
        )
    urdf_path = extra.get("urdf_path")
    self._provider = PandaJacobianProvider(urdf_path)
    # Within-episode Cartesian integral (base frame); cleared in reset.
    self._integral: NDArray[np.float64] = np.zeros(_XYZ, dtype=np.float64)
    # Within-episode bounded-lag buffer of past arm commands; cleared in
    # reset. Empty list when lag_steps == 0 (the byte-identical path).
    self._lag_buffer: list[NDArray[np.float32]] = []

act

act(
    obs: Mapping[str, object], *, deterministic: bool = True
) -> NDArray[np.floating]

Return the pd_joint_delta_pos action toward the target (ADR-026 §Decision 1).

Parameters:

• obs (Mapping[str, object]) –

  Gymnasium observation mapping with obs["extra"] ["goal_pos"] (world goal centroid) and obs["agent"][uid]["qpos"] (the arm's joint angles).

• deterministic (bool, default: True ) –

  Ignored — the controller is deterministic.

Returns:

• NDArray[floating] –

  Float32 action of length _PANDA_ARM_DOF + 1 (7 normalised

• NDArray[floating] –

  joint deltas + gripper-open); a gripper-only action if the obs

• NDArray[floating] –

  lacks the required keys (defensive — keeps the rollout shape

• NDArray[floating] –

  stable).

Source code in src/chamber/partners/cocarry_impedance.py

def act(
    self,
    obs: Mapping[str, object],
    *,
    deterministic: bool = True,
) -> NDArray[np.floating]:
    """Return the ``pd_joint_delta_pos`` action toward the target (ADR-026 §Decision 1).

    Args:
        obs: Gymnasium observation mapping with ``obs["extra"]
            ["goal_pos"]`` (world goal centroid) and
            ``obs["agent"][uid]["qpos"]`` (the arm's joint angles).
        deterministic: Ignored — the controller is deterministic.

    Returns:
        Float32 action of length ``_PANDA_ARM_DOF + 1`` (7 normalised
        joint deltas + gripper-open); a gripper-only action if the obs
        lacks the required keys (defensive — keeps the rollout shape
        stable).
    """
    del deterministic
    goal = self._read_goal(obs)
    qpos = self._read_qpos(obs)
    action = np.zeros(_PANDA_ARM_DOF + 1, dtype=np.float32)
    action[_PANDA_ARM_DOF] = _GRIPPER_ACTION_OPEN
    if goal is None or qpos is None:
        return action
    # Cooperative TCP target (world) -> arm base frame.
    target_world = goal + np.asarray([self._end_sign * self._bar_half_len, 0.0, 0.0])
    target_base = self._base_rot_t @ (target_world - self._base_xyz)
    tcp_base = self._provider.fk_tcp_position(qpos)
    error = target_base - tcp_base
    # PI law: the deadzone-gated, anti-windup-clamped integral closes
    # the load-induced steady-state offset of the delta-from-measured
    # joint controller, engaging only once the TCP is near its target.
    if float(np.linalg.norm(error)) < _INTEGRAL_ENGAGE_M:
        self._integral = np.clip(
            self._integral + error * _CONTROL_DT, -_INTEGRAL_CLAMP_MS, _INTEGRAL_CLAMP_MS
        )
    v_cmd = np.clip(
        self._kp * error + self._ki * self._integral, -self._step_max, self._step_max
    )
    jac = self._provider(None, qpos)  # type: ignore[arg-type]  # (3, 7), base frame
    # Damped pseudo-inverse joint step: dq = J^T (J J^T + l^2 I)^-1 v.
    jjt = jac @ jac.T + (self._damping**2) * np.eye(_XYZ)
    dq = jac.T @ np.linalg.solve(jjt, v_cmd)
    action[:_PANDA_ARM_DOF] = np.clip(dq / _ACTION_DELTA_SCALE, -1.0, 1.0).astype(np.float32)
    if self._lag_steps == 0:
        return action
    # Bounded lag (ADR-009 §Decision, 2026-07-05 amendment): emit the arm
    # command computed lag_steps steps ago, holding still through the
    # warm-up. Convergent because the target is quasi-static and the PI
    # law keeps integrating on the fresh error.
    self._lag_buffer.append(action[:_PANDA_ARM_DOF].copy())
    delayed = np.zeros(_PANDA_ARM_DOF + 1, dtype=np.float32)
    delayed[_PANDA_ARM_DOF] = _GRIPPER_ACTION_OPEN
    if len(self._lag_buffer) > self._lag_steps:
        delayed[:_PANDA_ARM_DOF] = self._lag_buffer.pop(0)
    return delayed

reset

reset(*, seed: int | None = None) -> None

Clear the within-episode integral + lag buffer (ADR-009 §Decision; stateless).

The control law is a deterministic function of obs + spec plus within-episode state (the Cartesian integral and the bounded-lag command buffer) that is zeroed here, so the partner carries no state across episodes (ADR-009 §Decision; plan/04 §2). The seed is accepted only for :class:~chamber.partners.api.FrozenPartner Protocol conformance.

Source code in src/chamber/partners/cocarry_impedance.py

def reset(self, *, seed: int | None = None) -> None:
    """Clear the within-episode integral + lag buffer (ADR-009 §Decision; stateless).

    The control law is a deterministic function of ``obs`` + ``spec``
    plus within-episode state (the Cartesian integral and the
    bounded-lag command buffer) that is zeroed here, so the partner
    carries no state across episodes (ADR-009 §Decision; plan/04 §2).
    The seed is accepted only for
    :class:`~chamber.partners.api.FrozenPartner` Protocol conformance.
    """
    del seed
    self._integral = np.zeros(_XYZ, dtype=np.float64)
    self._lag_buffer = []

CoInsertBaseInserter

Bases: _CoInsertControllerBase

Structured base inserter — impedance approach + spiral-search press (ADR-026 §Decision 1).

The base_policy + impedance_overlay term of the ADR-026 ego decomposition, with no learned residual. Reads the observed peg pose and socket (receptacle) pose, computes the vertical insertion target, and drives the ego arm's TCP — and hence the rigidly-welded peg — toward it via the damped-pseudoinverse Jacobian step.

Two-phase control:

1. Approach. While the peg tip is above the socket mouth or laterally misaligned beyond :data:_BASE_ALIGN_TOL_M, drive the tip to :data:_BASE_APPROACH_STANDOFF_M above the mouth along the socket axis while nulling the lateral offset — so the descent begins pre-aligned.
2. Insertion press + lead-in search. Once aligned, advance the target depth by :data:_BASE_DESCEND_STEP_M per step (a quasi-static seat, not a slam), adding a shrinking spiral lateral offset of initial radius :data:_BASE_SPIRAL_AMPLITUDE_M to find the hole at the chamfer capture edge. The spiral radius decays to zero as the peg seats.

The base's holder-dependence boundary is the physical insertion envelope = chamfer capture radius + :data:_BASE_SPIRAL_AMPLITUDE_M. The base attempts insertion for any receptacle pose error within that envelope and does NOT re-acquire a receptacle the holder has let drift outside it (it keeps pressing toward the last-seen socket pose; it has no global re-search). The envelope numbers are emitted into the S2 artifact and frozen at S3 (:mod:chamber.envs.coinsert gate0.base_controller_holder_dependence) — a property of the controller's physics, not a degree of freedom tuned to make Gate 0 resolve a chosen way.

spec.extra keys: uid / base_xyz / base_yaw_deg (the ego arm geometry), peg_half_len, optional kp / ki / step_max / damping / spiral_amp / descend_step overrides.

Source code in src/chamber/partners/coinsert_impedance.py

@register_partner("coinsert_base_inserter")
class CoInsertBaseInserter(_CoInsertControllerBase):
    """Structured base inserter — impedance approach + spiral-search press (ADR-026 §Decision 1).

    The ``base_policy`` + ``impedance_overlay`` term of the ADR-026 ego
    decomposition, with **no learned residual**. Reads the observed peg pose and
    socket (receptacle) pose, computes the vertical insertion target, and drives
    the ego arm's TCP — and hence the rigidly-welded peg — toward it via the
    damped-pseudoinverse Jacobian step.

    Two-phase control:

    1. **Approach.** While the peg tip is above the socket mouth or laterally
       misaligned beyond :data:`_BASE_ALIGN_TOL_M`, drive the tip to
       :data:`_BASE_APPROACH_STANDOFF_M` above the mouth along the socket axis
       while nulling the lateral offset — so the descent begins pre-aligned.
    2. **Insertion press + lead-in search.** Once aligned, advance the target
       depth by :data:`_BASE_DESCEND_STEP_M` per step (a quasi-static seat, not a
       slam), adding a shrinking spiral lateral offset of initial radius
       :data:`_BASE_SPIRAL_AMPLITUDE_M` to find the hole at the chamfer capture
       edge. The spiral radius decays to zero as the peg seats.

    The base's **holder-dependence boundary** is the physical *insertion
    envelope* = chamfer capture radius + :data:`_BASE_SPIRAL_AMPLITUDE_M`. The
    base attempts insertion for any receptacle pose error within that envelope
    and does NOT re-acquire a receptacle the holder has let drift outside it (it
    keeps pressing toward the last-seen socket pose; it has no global re-search).
    The envelope numbers are emitted into the S2 artifact and frozen at S3
    (:mod:`chamber.envs.coinsert` gate0.base_controller_holder_dependence) — a
    property of the controller's physics, not a degree of freedom tuned to make
    Gate 0 resolve a chosen way.

    ``spec.extra`` keys: ``uid`` / ``base_xyz`` / ``base_yaw_deg`` (the ego arm
    geometry), ``peg_half_len``, optional ``kp`` / ``ki`` / ``step_max`` /
    ``damping`` / ``spiral_amp`` / ``descend_step`` overrides.
    """

    def __init__(self, spec: PartnerSpec) -> None:
        """Bind base-inserter gains (ADR-026 §Decision 1)."""
        super().__init__(spec)
        extra = spec.extra
        self._kp: float = float(extra.get("kp", str(_BASE_KP)))
        self._ki: float = float(extra.get("ki", str(_BASE_KI)))
        self._spiral_amp: float = float(extra.get("spiral_amp", str(_BASE_SPIRAL_AMPLITUDE_M)))
        self._descend_step: float = float(extra.get("descend_step", str(_BASE_DESCEND_STEP_M)))
        self._depth_target: float = float(extra.get("depth_target", "0.040"))
        # Within-episode stall / unjam state for the lead-in search (zeroed in reset).
        self._stall_count: int = 0
        self._retract_count: int = 0
        self._last_depth: float = -1.0

    def _default_damping(self) -> float:
        return _BASE_DAMPING

    def _default_step_max(self) -> float:
        return _BASE_STEP_MAX_M

    def reset(self, *, seed: int | None = None) -> None:
        """Clear within-episode state including the lead-in-search stall clock (ADR-009)."""
        super().reset(seed=seed)
        self._stall_count = 0
        self._retract_count = 0
        self._last_depth = -1.0

    def assert_episode_state_clear(self) -> None:
        """Assert the within-episode state — including the stall clock — was cleared (ADR-009)."""
        super().assert_episode_state_clear()
        if self._stall_count != 0 or self._retract_count != 0:
            msg = (
                f"{type(self).__name__}: stall clock not cleared after reset. "
                "ADR-009 §Decision: partners are stateless across episodes."
            )
            raise AssertionError(msg)

    @property
    def insertion_envelope_m(self) -> dict[str, float]:
        """The frozen-at-S3 insertion-envelope numbers (ADR-026 gate0 base-controller dependence).

        Returns the two physical numbers that define the base's holder-dependence
        boundary: the declared spiral-search amplitude and the chamfer capture
        radius (the env's :data:`chamber.envs.coinsert.COINSERT_CHAMFER_M`), plus
        their sum (the envelope). Auditable; emitted into the S2 artifact.
        """
        from chamber.envs.coinsert import COINSERT_CHAMFER_M

        return {
            "spiral_search_amplitude_m": self._spiral_amp,
            "chamfer_capture_radius_m": float(COINSERT_CHAMFER_M),
            "insertion_envelope_m": self._spiral_amp + float(COINSERT_CHAMFER_M),
        }

    def act(  # noqa: PLR0915 - the approach/press/seated phase machine + unjam is one cohesive step
        self, obs: Mapping[str, object], *, deterministic: bool = True
    ) -> NDArray[np.floating]:
        """Return the ego ``pd_joint_delta_pos`` insertion action (ADR-026 §Decision 1)."""
        del deterministic
        self._step += 1
        gripper_only = np.zeros(_PANDA_ARM_DOF + 1, dtype=np.float32)
        gripper_only[_PANDA_ARM_DOF] = _GRIPPER_ACTION
        qpos = self._read_qpos(obs)
        peg = self._read_pose(obs, "peg_pose")
        sock = self._read_pose(obs, "receptacle_pose")
        if qpos is None or peg is None or sock is None:
            return gripper_only
        peg_p, peg_r = peg
        sock_p, sock_r = sock
        tip = self._peg_tip_world(peg_p, peg_r)
        mouth = sock_p  # socket opening sits at the receptacle local origin
        axis = sock_r[:, 2]  # socket axis (points out of the mouth)
        axis = axis / max(float(np.linalg.norm(axis)), 1e-12)

        rel = tip - mouth
        depth = -float(rel @ axis)  # >0 once the tip is below the mouth (inserted)
        lateral_vec = rel - (rel @ axis) * axis
        lateral_mag = float(np.linalg.norm(lateral_vec))

        e1, e2 = _lateral_basis(axis)
        if depth >= (self._depth_target - 0.002):
            # Seated: hold (command ~zero velocity) so both arms go static and the
            # receptacle settles — the success ``static`` ∧ ``settled`` conjuncts
            # need the press to stop once depth is reached.
            self._stall_count = 0
            self._integral = np.zeros(_XYZ, dtype=np.float64)
            v_cmd = np.zeros(_XYZ, dtype=np.float64)
        elif depth < -_BASE_APPROACH_STANDOFF_M or lateral_mag > _BASE_ALIGN_TOL_M:
            # Approach / centre: STIFFLY drive the tip to a standoff above the
            # mouth while nulling the lateral offset, so the descent begins tightly
            # centred. The integral closes the steady-state lateral offset.
            self._stall_count = 0
            self._last_depth = depth
            target = mouth + _BASE_APPROACH_STANDOFF_M * axis
            error = target - tip
            if float(np.linalg.norm(error)) < _BASE_INTEGRAL_ENGAGE_M:
                self._integral = np.clip(
                    self._integral + error * _CONTROL_DT,
                    -_BASE_INTEGRAL_CLAMP_MS,
                    _BASE_INTEGRAL_CLAMP_MS,
                )
            v_cmd = np.clip(
                self._kp * error + self._ki * self._integral, -self._step_max, self._step_max
            )
        else:
            # Insertion press toward the target depth (centred on the mouth +
            # advancing depth). If the press makes no depth progress the peg has
            # friction-wedged on a slight cock; a stiff press only locks it harder
            # and drags the whole free assembly down — so run the UNJAM maneuver:
            # briefly RETRACT (back the peg up, relieving the wedge normal force)
            # while spiral-searching, then re-press. Repeated, it walks the peg
            # past the wedge depth (the FROZEN insertion envelope = the spiral
            # amplitude + the chamfer capture).
            if self._retract_count > 0:
                self._retract_count -= 1
                target_depth = max(depth - _BASE_RETRACT_M, -0.005)
            else:
                if depth <= self._last_depth + 1e-4:
                    self._stall_count += 1
                else:
                    self._stall_count = 0
                if self._stall_count >= _BASE_STALL_STEPS:
                    self._retract_count = _BASE_RETRACT_STEPS
                    self._stall_count = 0
                target_depth = min(depth + self._descend_step, self._depth_target + 0.005)
            self._last_depth = depth
            target = mouth - target_depth * axis
            if self._retract_count > 0:
                ang = _BASE_SPIRAL_OMEGA_RAD * self._step
                target = target + self._spiral_amp * (np.cos(ang) * e1 + np.sin(ang) * e2)
            error = target - tip
            if float(np.linalg.norm(error)) < _BASE_INTEGRAL_ENGAGE_M:
                self._integral = np.clip(
                    self._integral + error * _CONTROL_DT,
                    -_BASE_INTEGRAL_CLAMP_MS,
                    _BASE_INTEGRAL_CLAMP_MS,
                )
            v_cmd = np.clip(
                self._kp * error + self._ki * self._integral, -self._step_max, self._step_max
            )

        return self._joint_step_action(qpos, v_cmd)

insertion_envelope_m property

insertion_envelope_m: dict[str, float]

The frozen-at-S3 insertion-envelope numbers (ADR-026 gate0 base-controller dependence).

Returns the two physical numbers that define the base's holder-dependence boundary: the declared spiral-search amplitude and the chamfer capture radius (the env's :data:chamber.envs.coinsert.COINSERT_CHAMFER_M), plus their sum (the envelope). Auditable; emitted into the S2 artifact.

__init__

__init__(spec: PartnerSpec) -> None

Bind base-inserter gains (ADR-026 §Decision 1).

Source code in src/chamber/partners/coinsert_impedance.py

def __init__(self, spec: PartnerSpec) -> None:
    """Bind base-inserter gains (ADR-026 §Decision 1)."""
    super().__init__(spec)
    extra = spec.extra
    self._kp: float = float(extra.get("kp", str(_BASE_KP)))
    self._ki: float = float(extra.get("ki", str(_BASE_KI)))
    self._spiral_amp: float = float(extra.get("spiral_amp", str(_BASE_SPIRAL_AMPLITUDE_M)))
    self._descend_step: float = float(extra.get("descend_step", str(_BASE_DESCEND_STEP_M)))
    self._depth_target: float = float(extra.get("depth_target", "0.040"))
    # Within-episode stall / unjam state for the lead-in search (zeroed in reset).
    self._stall_count: int = 0
    self._retract_count: int = 0
    self._last_depth: float = -1.0

act

act(
    obs: Mapping[str, object], *, deterministic: bool = True
) -> NDArray[np.floating]

Return the ego pd_joint_delta_pos insertion action (ADR-026 §Decision 1).

Source code in src/chamber/partners/coinsert_impedance.py

def act(  # noqa: PLR0915 - the approach/press/seated phase machine + unjam is one cohesive step
    self, obs: Mapping[str, object], *, deterministic: bool = True
) -> NDArray[np.floating]:
    """Return the ego ``pd_joint_delta_pos`` insertion action (ADR-026 §Decision 1)."""
    del deterministic
    self._step += 1
    gripper_only = np.zeros(_PANDA_ARM_DOF + 1, dtype=np.float32)
    gripper_only[_PANDA_ARM_DOF] = _GRIPPER_ACTION
    qpos = self._read_qpos(obs)
    peg = self._read_pose(obs, "peg_pose")
    sock = self._read_pose(obs, "receptacle_pose")
    if qpos is None or peg is None or sock is None:
        return gripper_only
    peg_p, peg_r = peg
    sock_p, sock_r = sock
    tip = self._peg_tip_world(peg_p, peg_r)
    mouth = sock_p  # socket opening sits at the receptacle local origin
    axis = sock_r[:, 2]  # socket axis (points out of the mouth)
    axis = axis / max(float(np.linalg.norm(axis)), 1e-12)

    rel = tip - mouth
    depth = -float(rel @ axis)  # >0 once the tip is below the mouth (inserted)
    lateral_vec = rel - (rel @ axis) * axis
    lateral_mag = float(np.linalg.norm(lateral_vec))

    e1, e2 = _lateral_basis(axis)
    if depth >= (self._depth_target - 0.002):
        # Seated: hold (command ~zero velocity) so both arms go static and the
        # receptacle settles — the success ``static`` ∧ ``settled`` conjuncts
        # need the press to stop once depth is reached.
        self._stall_count = 0
        self._integral = np.zeros(_XYZ, dtype=np.float64)
        v_cmd = np.zeros(_XYZ, dtype=np.float64)
    elif depth < -_BASE_APPROACH_STANDOFF_M or lateral_mag > _BASE_ALIGN_TOL_M:
        # Approach / centre: STIFFLY drive the tip to a standoff above the
        # mouth while nulling the lateral offset, so the descent begins tightly
        # centred. The integral closes the steady-state lateral offset.
        self._stall_count = 0
        self._last_depth = depth
        target = mouth + _BASE_APPROACH_STANDOFF_M * axis
        error = target - tip
        if float(np.linalg.norm(error)) < _BASE_INTEGRAL_ENGAGE_M:
            self._integral = np.clip(
                self._integral + error * _CONTROL_DT,
                -_BASE_INTEGRAL_CLAMP_MS,
                _BASE_INTEGRAL_CLAMP_MS,
            )
        v_cmd = np.clip(
            self._kp * error + self._ki * self._integral, -self._step_max, self._step_max
        )
    else:
        # Insertion press toward the target depth (centred on the mouth +
        # advancing depth). If the press makes no depth progress the peg has
        # friction-wedged on a slight cock; a stiff press only locks it harder
        # and drags the whole free assembly down — so run the UNJAM maneuver:
        # briefly RETRACT (back the peg up, relieving the wedge normal force)
        # while spiral-searching, then re-press. Repeated, it walks the peg
        # past the wedge depth (the FROZEN insertion envelope = the spiral
        # amplitude + the chamfer capture).
        if self._retract_count > 0:
            self._retract_count -= 1
            target_depth = max(depth - _BASE_RETRACT_M, -0.005)
        else:
            if depth <= self._last_depth + 1e-4:
                self._stall_count += 1
            else:
                self._stall_count = 0
            if self._stall_count >= _BASE_STALL_STEPS:
                self._retract_count = _BASE_RETRACT_STEPS
                self._stall_count = 0
            target_depth = min(depth + self._descend_step, self._depth_target + 0.005)
        self._last_depth = depth
        target = mouth - target_depth * axis
        if self._retract_count > 0:
            ang = _BASE_SPIRAL_OMEGA_RAD * self._step
            target = target + self._spiral_amp * (np.cos(ang) * e1 + np.sin(ang) * e2)
        error = target - tip
        if float(np.linalg.norm(error)) < _BASE_INTEGRAL_ENGAGE_M:
            self._integral = np.clip(
                self._integral + error * _CONTROL_DT,
                -_BASE_INTEGRAL_CLAMP_MS,
                _BASE_INTEGRAL_CLAMP_MS,
            )
        v_cmd = np.clip(
            self._kp * error + self._ki * self._integral, -self._step_max, self._step_max
        )

    return self._joint_step_action(qpos, v_cmd)

assert_episode_state_clear

assert_episode_state_clear() -> None

Assert the within-episode state — including the stall clock — was cleared (ADR-009).

Source code in src/chamber/partners/coinsert_impedance.py

def assert_episode_state_clear(self) -> None:
    """Assert the within-episode state — including the stall clock — was cleared (ADR-009)."""
    super().assert_episode_state_clear()
    if self._stall_count != 0 or self._retract_count != 0:
        msg = (
            f"{type(self).__name__}: stall clock not cleared after reset. "
            "ADR-009 §Decision: partners are stateless across episodes."
        )
        raise AssertionError(msg)

reset

reset(*, seed: int | None = None) -> None

Clear within-episode state including the lead-in-search stall clock (ADR-009).

Source code in src/chamber/partners/coinsert_impedance.py

def reset(self, *, seed: int | None = None) -> None:
    """Clear within-episode state including the lead-in-search stall clock (ADR-009)."""
    super().reset(seed=seed)
    self._stall_count = 0
    self._retract_count = 0
    self._last_depth = -1.0

CoInsertReferenceHolder

Bases: _CoInsertControllerBase

Cooperative reference holder — tracks the socket, yields compliantly (ADR-026 §Decision 1).

The co-designed calibration anchor (the cocarry_impedance analogue for the holder seat). It reads the observed peg + socket poses and drives the holder arm so the free receptacle's mouth stays under the descending peg tip (a moderately stiff lateral track) while holding the nominal mouth height with a deliberately soft axial gain — so it yields compliantly to the insertion reaction force rather than fighting it (a stiff holder would spike the coupling wrench and read as un-cooperative). Paired with :class:CoInsertBaseInserter, the matched pair seats the peg reliably — the honest high reference and the Δ_min dynamic-range anchor (ADR-026 §Decision 2; the S2 precondition reference_success_min ≥ 0.9).

The nominal mouth height is captured on the FIRST :meth:act of each episode (the warm-started socket height), so the holder defends the height the env initialised — not a hard-coded constant — keeping it robust to the S3 freeze.

spec.extra keys: uid / base_xyz / base_yaw_deg (the holder arm geometry; base_yaw_deg = 180 for the mirrored partner seat), peg_half_len, optional gain overrides kp_lateral / kp_axial / ki / step_max / damping.

Source code in src/chamber/partners/coinsert_impedance.py

@register_partner("coinsert_reference_holder")
class CoInsertReferenceHolder(_CoInsertControllerBase):
    """Cooperative reference holder — tracks the socket, yields compliantly (ADR-026 §Decision 1).

    The co-designed calibration anchor (the ``cocarry_impedance`` analogue for
    the holder seat). It reads the observed peg + socket poses and drives the
    holder arm so the **free** receptacle's mouth stays under the descending peg
    tip (a moderately stiff lateral track) while holding the nominal mouth height
    with a deliberately **soft** axial gain — so it yields compliantly to the
    insertion reaction force rather than fighting it (a stiff holder would spike
    the coupling wrench and read as un-cooperative). Paired with
    :class:`CoInsertBaseInserter`, the matched pair seats the peg reliably — the
    honest high reference and the Δ_min dynamic-range anchor (ADR-026 §Decision
    2; the S2 precondition reference_success_min ≥ 0.9).

    The nominal mouth height is captured on the FIRST :meth:`act` of each episode
    (the warm-started socket height), so the holder defends the height the env
    initialised — not a hard-coded constant — keeping it robust to the S3 freeze.

    ``spec.extra`` keys: ``uid`` / ``base_xyz`` / ``base_yaw_deg`` (the holder arm
    geometry; ``base_yaw_deg`` = 180 for the mirrored partner seat),
    ``peg_half_len``, optional gain overrides ``kp_lateral`` / ``kp_axial`` /
    ``ki`` / ``step_max`` / ``damping``.
    """

    def __init__(self, spec: PartnerSpec) -> None:
        """Bind reference-holder gains (ADR-026 §Decision 1)."""
        super().__init__(spec)
        extra = spec.extra
        self._kp_lateral: float = float(extra.get("kp_lateral", str(_HOLDER_KP_LATERAL)))
        self._kp_axial: float = float(extra.get("kp_axial", str(_HOLDER_KP_AXIAL)))
        self._ki: float = float(extra.get("ki", str(_HOLDER_KI)))
        self._nominal_mouth: NDArray[np.float64] | None = None

    def _default_damping(self) -> float:
        return _HOLDER_DAMPING

    def _default_step_max(self) -> float:
        return _HOLDER_STEP_MAX_M

    def reset(self, *, seed: int | None = None) -> None:
        """Clear within-episode state including the captured nominal mouth pose (ADR-009)."""
        super().reset(seed=seed)
        self._nominal_mouth = None

    def assert_episode_state_clear(self) -> None:
        """Assert within-episode state — incl. the nominal mouth pose — was cleared (ADR-009)."""
        super().assert_episode_state_clear()
        if self._nominal_mouth is not None:
            msg = (
                f"{type(self).__name__}: nominal mouth pose not cleared after reset. "
                "ADR-009 §Decision: partners are stateless across episodes."
            )
            raise AssertionError(msg)

    def act(self, obs: Mapping[str, object], *, deterministic: bool = True) -> NDArray[np.floating]:
        """Return the holder ``pd_joint_delta_pos`` cooperative-hold action (ADR-026 §Decision 1).

        Cooperative reference behaviour: hold the socket steady at the
        warm-started insertion pose (captured on the first act), giving the base
        inserter a fixed, well-posed target to centre on, with a moderately stiff
        LATERAL gain (keep the mouth under the peg) and a deliberately SOFT AXIAL
        gain so the holder yields compliantly to the insertion reaction force
        rather than fighting it. Orientation is held by :meth:`_joint_step_action`
        (the socket cannot tip / spill the part).
        """
        del deterministic
        self._step += 1
        gripper_only = np.zeros(_PANDA_ARM_DOF + 1, dtype=np.float32)
        gripper_only[_PANDA_ARM_DOF] = _GRIPPER_ACTION
        qpos = self._read_qpos(obs)
        sock = self._read_pose(obs, "receptacle_pose")
        if qpos is None or sock is None:
            return gripper_only
        sock_p, sock_r = sock
        mouth = sock_p
        axis = sock_r[:, 2]
        axis = axis / max(float(np.linalg.norm(axis)), 1e-12)

        # Capture the warm-started mouth pose once; hold it.
        if self._nominal_mouth is None:
            self._nominal_mouth = mouth.copy()

        err_vec = self._nominal_mouth - mouth
        axial_err = float(err_vec @ axis) * axis
        lateral_err = err_vec - axial_err
        # Stiff lateral hold + soft axial yield (the cooperative compliance).
        error = self._kp_lateral * lateral_err + self._kp_axial * axial_err
        if float(np.linalg.norm(err_vec)) < _HOLDER_INTEGRAL_ENGAGE_M:
            self._integral = np.clip(
                self._integral + axial_err * _CONTROL_DT,
                -_HOLDER_INTEGRAL_CLAMP_MS,
                _HOLDER_INTEGRAL_CLAMP_MS,
            )
        v_cmd = np.clip(error + self._ki * self._integral, -self._step_max, self._step_max)
        return self._joint_step_action(qpos, v_cmd)

__init__

__init__(spec: PartnerSpec) -> None

Bind reference-holder gains (ADR-026 §Decision 1).

Source code in src/chamber/partners/coinsert_impedance.py

def __init__(self, spec: PartnerSpec) -> None:
    """Bind reference-holder gains (ADR-026 §Decision 1)."""
    super().__init__(spec)
    extra = spec.extra
    self._kp_lateral: float = float(extra.get("kp_lateral", str(_HOLDER_KP_LATERAL)))
    self._kp_axial: float = float(extra.get("kp_axial", str(_HOLDER_KP_AXIAL)))
    self._ki: float = float(extra.get("ki", str(_HOLDER_KI)))
    self._nominal_mouth: NDArray[np.float64] | None = None

act

act(
    obs: Mapping[str, object], *, deterministic: bool = True
) -> NDArray[np.floating]

Return the holder pd_joint_delta_pos cooperative-hold action (ADR-026 §Decision 1).

Cooperative reference behaviour: hold the socket steady at the warm-started insertion pose (captured on the first act), giving the base inserter a fixed, well-posed target to centre on, with a moderately stiff LATERAL gain (keep the mouth under the peg) and a deliberately SOFT AXIAL gain so the holder yields compliantly to the insertion reaction force rather than fighting it. Orientation is held by :meth:_joint_step_action (the socket cannot tip / spill the part).

Source code in src/chamber/partners/coinsert_impedance.py

def act(self, obs: Mapping[str, object], *, deterministic: bool = True) -> NDArray[np.floating]:
    """Return the holder ``pd_joint_delta_pos`` cooperative-hold action (ADR-026 §Decision 1).

    Cooperative reference behaviour: hold the socket steady at the
    warm-started insertion pose (captured on the first act), giving the base
    inserter a fixed, well-posed target to centre on, with a moderately stiff
    LATERAL gain (keep the mouth under the peg) and a deliberately SOFT AXIAL
    gain so the holder yields compliantly to the insertion reaction force
    rather than fighting it. Orientation is held by :meth:`_joint_step_action`
    (the socket cannot tip / spill the part).
    """
    del deterministic
    self._step += 1
    gripper_only = np.zeros(_PANDA_ARM_DOF + 1, dtype=np.float32)
    gripper_only[_PANDA_ARM_DOF] = _GRIPPER_ACTION
    qpos = self._read_qpos(obs)
    sock = self._read_pose(obs, "receptacle_pose")
    if qpos is None or sock is None:
        return gripper_only
    sock_p, sock_r = sock
    mouth = sock_p
    axis = sock_r[:, 2]
    axis = axis / max(float(np.linalg.norm(axis)), 1e-12)

    # Capture the warm-started mouth pose once; hold it.
    if self._nominal_mouth is None:
        self._nominal_mouth = mouth.copy()

    err_vec = self._nominal_mouth - mouth
    axial_err = float(err_vec @ axis) * axis
    lateral_err = err_vec - axial_err
    # Stiff lateral hold + soft axial yield (the cooperative compliance).
    error = self._kp_lateral * lateral_err + self._kp_axial * axial_err
    if float(np.linalg.norm(err_vec)) < _HOLDER_INTEGRAL_ENGAGE_M:
        self._integral = np.clip(
            self._integral + axial_err * _CONTROL_DT,
            -_HOLDER_INTEGRAL_CLAMP_MS,
            _HOLDER_INTEGRAL_CLAMP_MS,
        )
    v_cmd = np.clip(error + self._ki * self._integral, -self._step_max, self._step_max)
    return self._joint_step_action(qpos, v_cmd)

assert_episode_state_clear

assert_episode_state_clear() -> None

Assert within-episode state — incl. the nominal mouth pose — was cleared (ADR-009).

Source code in src/chamber/partners/coinsert_impedance.py

def assert_episode_state_clear(self) -> None:
    """Assert within-episode state — incl. the nominal mouth pose — was cleared (ADR-009)."""
    super().assert_episode_state_clear()
    if self._nominal_mouth is not None:
        msg = (
            f"{type(self).__name__}: nominal mouth pose not cleared after reset. "
            "ADR-009 §Decision: partners are stateless across episodes."
        )
        raise AssertionError(msg)

reset

reset(*, seed: int | None = None) -> None

Clear within-episode state including the captured nominal mouth pose (ADR-009).

Source code in src/chamber/partners/coinsert_impedance.py

def reset(self, *, seed: int | None = None) -> None:
    """Clear within-episode state including the captured nominal mouth pose (ADR-009)."""
    super().reset(seed=seed)
    self._nominal_mouth = None

CrossFormerPartner

Bases: PartnerBase

CrossFormer frozen zero-shot generalist — Phase-1 stub (ADR-010 §Decision Option B).

Frozen across all 20 cross-embodiment classes; no per-task LoRA budget (ADR-010 §Decision: zero fine-tuning cost). Per ADR-010 §Risks the zero-shot deployment must pass a per-task ablation before use as a primary partner; the stub does not bypass that gate.

Source code in src/chamber/partners/stubs/crossformer.py

@register_partner("crossformer_zero_shot")
class CrossFormerPartner(PartnerBase):
    """CrossFormer frozen zero-shot generalist — Phase-1 stub (ADR-010 §Decision Option B).

    Frozen across all 20 cross-embodiment classes; no per-task LoRA budget
    (ADR-010 §Decision: zero fine-tuning cost). Per ADR-010 §Risks the
    zero-shot deployment must pass a per-task ablation before use as a
    primary partner; the stub does not bypass that gate.
    """

    def reset(self, *, seed: int | None = None) -> NoReturn:
        """Phase-1 stub — raises (ADR-010 §Decision Option B).

        Args:
            seed: Accepted for Protocol conformance only.

        Raises:
            NotImplementedError: Always; the real zero-shot inference
                harness is Phase-1 work.
        """
        del seed
        raise NotImplementedError(
            f"CrossFormerPartner.reset is Phase-1 work; see ADR-010 §Decision and {_PHASE1_TICKET}."
        )

    def act(
        self,
        obs: Mapping[str, object],
        *,
        deterministic: bool = True,
    ) -> NDArray[np.floating]:
        """Phase-1 stub — raises (ADR-010 §Decision Option B).

        Args:
            obs: Gymnasium observation mapping.
            deterministic: Accepted for Protocol conformance only.

        Raises:
            NotImplementedError: Always; the real action-chunk inference
                is Phase-1 work.
        """
        del obs, deterministic
        raise NotImplementedError(
            f"CrossFormerPartner.act is Phase-1 work; see ADR-010 §Decision and {_PHASE1_TICKET}."
        )

act

act(
    obs: Mapping[str, object], *, deterministic: bool = True
) -> NDArray[np.floating]

Phase-1 stub — raises (ADR-010 §Decision Option B).

Parameters:

• obs (Mapping[str, object]) –

  Gymnasium observation mapping.

• deterministic (bool, default: True ) –

  Accepted for Protocol conformance only.

Raises:

• NotImplementedError –

  Always; the real action-chunk inference is Phase-1 work.

Source code in src/chamber/partners/stubs/crossformer.py

def act(
    self,
    obs: Mapping[str, object],
    *,
    deterministic: bool = True,
) -> NDArray[np.floating]:
    """Phase-1 stub — raises (ADR-010 §Decision Option B).

    Args:
        obs: Gymnasium observation mapping.
        deterministic: Accepted for Protocol conformance only.

    Raises:
        NotImplementedError: Always; the real action-chunk inference
            is Phase-1 work.
    """
    del obs, deterministic
    raise NotImplementedError(
        f"CrossFormerPartner.act is Phase-1 work; see ADR-010 §Decision and {_PHASE1_TICKET}."
    )

reset

reset(*, seed: int | None = None) -> NoReturn

Phase-1 stub — raises (ADR-010 §Decision Option B).

Parameters:

• seed (int | None, default: None ) –

  Accepted for Protocol conformance only.

Raises:

• NotImplementedError –

  Always; the real zero-shot inference harness is Phase-1 work.

Source code in src/chamber/partners/stubs/crossformer.py

def reset(self, *, seed: int | None = None) -> NoReturn:
    """Phase-1 stub — raises (ADR-010 §Decision Option B).

    Args:
        seed: Accepted for Protocol conformance only.

    Raises:
        NotImplementedError: Always; the real zero-shot inference
            harness is Phase-1 work.
    """
    del seed
    raise NotImplementedError(
        f"CrossFormerPartner.reset is Phase-1 work; see ADR-010 §Decision and {_PHASE1_TICKET}."
    )

FrozenCoCarryJointPartner

Bases: PartnerBase

Frozen joint-MAPPO co-carry seat (ADR-011 §Decision as amended; ADR-018/I3).

Spec contract:

• spec.class_name == "frozen_cocarry_joint".
• spec.weights_uri — the local://artifacts/<pair>.pt pair checkpoint URI (SHA-256 sidecar verified at load).
• spec.extra["uid"] — the env-side seat this policy acts on.
• spec.extra["other_uid"] — the opposite seat (needed to assemble the symmetric full state from raw leaves).
• spec.extra["actor_key"] — optional pair-checkpoint sub-key; defaults to :data:DEFAULT_ACTOR_KEY (the partner-side actor).

Statefulness: stateless across episodes; :meth:reset only ensures the checkpoint is loaded (mirrors :class:~chamber.partners.frozen_harl.FrozenHARLPartner).

Source code in src/chamber/partners/frozen_cocarry_joint.py

@register_partner(FROZEN_COCARRY_JOINT_CLASS)
class FrozenCoCarryJointPartner(PartnerBase):
    """Frozen joint-MAPPO co-carry seat (ADR-011 §Decision as amended; ADR-018/I3).

    Spec contract:

    - ``spec.class_name == "frozen_cocarry_joint"``.
    - ``spec.weights_uri`` — the ``local://artifacts/<pair>.pt`` pair
      checkpoint URI (SHA-256 sidecar verified at load).
    - ``spec.extra["uid"]`` — the env-side seat this policy acts on.
    - ``spec.extra["other_uid"]`` — the opposite seat (needed to
      assemble the symmetric full state from raw leaves).
    - ``spec.extra["actor_key"]`` — optional pair-checkpoint sub-key;
      defaults to :data:`DEFAULT_ACTOR_KEY` (the partner-side actor).

    Statefulness: stateless across episodes; :meth:`reset` only ensures
    the checkpoint is loaded (mirrors
    :class:`~chamber.partners.frozen_harl.FrozenHARLPartner`).
    """

    def __init__(self, spec: PartnerSpec) -> None:
        """Bind the spec; defer checkpoint I/O (ADR-009 §Decision; ADR-018/I3).

        Raises:
            ValueError: If ``spec.weights_uri`` is ``None`` or
                ``spec.extra`` lacks ``uid`` / ``other_uid``.
        """
        super().__init__(spec)
        if spec.weights_uri is None:
            msg = (
                "FrozenCoCarryJointPartner requires spec.weights_uri (the pair "
                "checkpoint; ADR-011 §Decision as amended); got None."
            )
            raise ValueError(msg)
        uid = spec.extra.get("uid", "")
        other_uid = spec.extra.get("other_uid", "")
        if not uid or not other_uid:
            msg = (
                "FrozenCoCarryJointPartner requires spec.extra['uid'] and "
                "spec.extra['other_uid'] (the two co-carry seats; ADR-011 "
                "§Decision as amended)."
            )
            raise ValueError(msg)
        self._uid: str = uid
        self._other_uid: str = other_uid
        self._actor_key: str = spec.extra.get("actor_key", DEFAULT_ACTOR_KEY)
        self._weights_uri: str = spec.weights_uri
        self._actor: StochasticPolicy | None = None
        self._obs_dim: int = 0
        self._hidden_dim: int = 0

    def reset(self, *, seed: int | None = None) -> None:
        """Ensure the checkpoint is loaded; no per-episode state (ADR-009 §Decision)."""
        del seed
        self._ensure_loaded()

    def act(
        self,
        obs: Mapping[str, object],
        *,
        deterministic: bool = True,
    ) -> NDArray[np.floating]:
        """Deterministic actor forward pass on the symmetric full state (ADR-011; ADR-018).

        Args:
            obs: Gymnasium observation mapping; raw co-carry leaves are
                read via :func:`joint_partner_full_state`.
            deterministic: Accepted for Protocol conformance but pinned
                to ``True`` (the frozen-partner global-RNG decoupling
                rationale, :mod:`chamber.partners.frozen_harl`).

        Returns:
            ``np.float32`` action vector for this seat.

        Raises:
            ValueError: When the assembled state width disagrees with
                the loaded actor's input dimension.
        """
        del deterministic
        actor = self._ensure_loaded()
        state = joint_partner_full_state(obs, own_uid=self._uid, other_uid=self._other_uid)
        if state.shape != (self._obs_dim,):
            msg = (
                f"FrozenCoCarryJointPartner: assembled full state has shape "
                f"{tuple(state.shape)}, expected ({self._obs_dim},) matching the "
                f"loaded {self._actor_key!r} actor's input dim."
            )
            raise ValueError(msg)
        obs_t = state.reshape(1, -1)
        rnn_states = np.zeros((1, 1, self._hidden_dim), dtype=np.float32)
        masks = np.ones((1, 1), dtype=np.float32)
        with torch.no_grad():
            action_t, _, _ = actor(obs_t, rnn_states, masks, None, True)
        return action_t.detach().cpu().numpy().squeeze(0).astype(np.float32)

    def _ensure_loaded(self) -> StochasticPolicy:
        """Load + freeze the named actor sub-dict on first use; idempotent (ADR-018/I3).

        Raises:
            CheckpointError: Propagated from
                :func:`concerto.training.checkpoints.load_checkpoint`.
            ValueError: When the pair checkpoint lacks the named actor
                sub-key or its layout is not the HARL StochasticPolicy.
        """
        if self._actor is not None:
            return self._actor
        loaded, _ = load_checkpoint(uri=self._weights_uri, artifacts_root=_resolve_artifacts_root())
        inner = loaded.get(self._actor_key)
        if not isinstance(inner, dict):
            msg = (
                f"FrozenCoCarryJointPartner: pair checkpoint has no dict under "
                f"{self._actor_key!r}. Got top-level keys: {sorted(loaded.keys())}. "
                "Expected the joint_mappo_trainer pair layout (ADR-011 as amended)."
            )
            raise ValueError(msg)
        obs_dim, hidden_dim, _action_dim = _infer_shape(inner)
        args = dict(_HARL_INFERENCE_ARGS)
        args["hidden_sizes"] = [hidden_dim, hidden_dim]
        obs_space = gym.spaces.Box(low=-np.inf, high=np.inf, shape=(obs_dim,), dtype=np.float32)
        act_space = gym.spaces.Box(low=-1.0, high=1.0, shape=(_action_dim,), dtype=np.float32)
        actor = StochasticPolicy(args, obs_space, act_space, torch.device("cpu"))
        try:
            actor.load_state_dict(dict(inner))
        except RuntimeError as exc:
            msg = (
                f"FrozenCoCarryJointPartner: load_state_dict failed for "
                f"{self._weights_uri!r}[{self._actor_key!r}]: {exc}"
            )
            raise ValueError(msg) from exc
        for param in actor.parameters():
            param.requires_grad = False
        actor.eval()
        self._actor = actor
        self._obs_dim = obs_dim
        self._hidden_dim = hidden_dim
        return actor

__init__

__init__(spec: PartnerSpec) -> None

Bind the spec; defer checkpoint I/O (ADR-009 §Decision; ADR-018/I3).

Raises:

• ValueError –

  If spec.weights_uri is None or spec.extra lacks uid / other_uid.

Source code in src/chamber/partners/frozen_cocarry_joint.py

def __init__(self, spec: PartnerSpec) -> None:
    """Bind the spec; defer checkpoint I/O (ADR-009 §Decision; ADR-018/I3).

    Raises:
        ValueError: If ``spec.weights_uri`` is ``None`` or
            ``spec.extra`` lacks ``uid`` / ``other_uid``.
    """
    super().__init__(spec)
    if spec.weights_uri is None:
        msg = (
            "FrozenCoCarryJointPartner requires spec.weights_uri (the pair "
            "checkpoint; ADR-011 §Decision as amended); got None."
        )
        raise ValueError(msg)
    uid = spec.extra.get("uid", "")
    other_uid = spec.extra.get("other_uid", "")
    if not uid or not other_uid:
        msg = (
            "FrozenCoCarryJointPartner requires spec.extra['uid'] and "
            "spec.extra['other_uid'] (the two co-carry seats; ADR-011 "
            "§Decision as amended)."
        )
        raise ValueError(msg)
    self._uid: str = uid
    self._other_uid: str = other_uid
    self._actor_key: str = spec.extra.get("actor_key", DEFAULT_ACTOR_KEY)
    self._weights_uri: str = spec.weights_uri
    self._actor: StochasticPolicy | None = None
    self._obs_dim: int = 0
    self._hidden_dim: int = 0

act

act(
    obs: Mapping[str, object], *, deterministic: bool = True
) -> NDArray[np.floating]

Deterministic actor forward pass on the symmetric full state (ADR-011; ADR-018).

Parameters:

• obs (Mapping[str, object]) –

  Gymnasium observation mapping; raw co-carry leaves are read via :func:joint_partner_full_state.

• deterministic (bool, default: True ) –

  Accepted for Protocol conformance but pinned to True (the frozen-partner global-RNG decoupling rationale, :mod:chamber.partners.frozen_harl).

Returns:

• NDArray[floating] –

  np.float32 action vector for this seat.

Raises:

• ValueError –

  When the assembled state width disagrees with the loaded actor's input dimension.

Source code in src/chamber/partners/frozen_cocarry_joint.py

def act(
    self,
    obs: Mapping[str, object],
    *,
    deterministic: bool = True,
) -> NDArray[np.floating]:
    """Deterministic actor forward pass on the symmetric full state (ADR-011; ADR-018).

    Args:
        obs: Gymnasium observation mapping; raw co-carry leaves are
            read via :func:`joint_partner_full_state`.
        deterministic: Accepted for Protocol conformance but pinned
            to ``True`` (the frozen-partner global-RNG decoupling
            rationale, :mod:`chamber.partners.frozen_harl`).

    Returns:
        ``np.float32`` action vector for this seat.

    Raises:
        ValueError: When the assembled state width disagrees with
            the loaded actor's input dimension.
    """
    del deterministic
    actor = self._ensure_loaded()
    state = joint_partner_full_state(obs, own_uid=self._uid, other_uid=self._other_uid)
    if state.shape != (self._obs_dim,):
        msg = (
            f"FrozenCoCarryJointPartner: assembled full state has shape "
            f"{tuple(state.shape)}, expected ({self._obs_dim},) matching the "
            f"loaded {self._actor_key!r} actor's input dim."
        )
        raise ValueError(msg)
    obs_t = state.reshape(1, -1)
    rnn_states = np.zeros((1, 1, self._hidden_dim), dtype=np.float32)
    masks = np.ones((1, 1), dtype=np.float32)
    with torch.no_grad():
        action_t, _, _ = actor(obs_t, rnn_states, masks, None, True)
    return action_t.detach().cpu().numpy().squeeze(0).astype(np.float32)

reset

reset(*, seed: int | None = None) -> None

Ensure the checkpoint is loaded; no per-episode state (ADR-009 §Decision).

Source code in src/chamber/partners/frozen_cocarry_joint.py

def reset(self, *, seed: int | None = None) -> None:
    """Ensure the checkpoint is loaded; no per-episode state (ADR-009 §Decision)."""
    del seed
    self._ensure_loaded()

FrozenHARLPartner

Bases: PartnerBase

Frozen HARL HAPPO partner (ADR-009 §Decision; plan/04 §3.6).

Loads a HARL :class:StochasticPolicy checkpoint via :func:concerto.training.checkpoints.load_checkpoint (which verifies the sidecar SHA-256), freezes every parameter (requires_grad=False), and runs inference under :func:torch.no_grad with deterministic=True. The actor's layer widths are inferred from the loaded state-dict tensor shapes.

Spec contract (plan/04 §3.6; ADR-009 §Decision):

• spec.class_name == "frozen_harl".
• spec.weights_uri is the local://artifacts/<name>.pt URI.
• spec.extra["uid"] is the env-side uid the partner acts on; it indexes obs["agent"][uid]["state"] at action time.

Statefulness (plan/04 §2): the partner is stateless across episodes; :meth:reset is a no-op once the checkpoint is loaded. Loading is deferred to the first :meth:reset / :meth:act call so the registry lookup in :func:chamber.partners.registry.load_partner stays cheap.

Device placement (Phase-0): inference runs on CPU. HAPPO actor forward passes are microseconds-scale and not the project's throughput bottleneck (the OpenVLA partner stratum is); partner-side GPU placement is deferred to a future partner-config plane and would need its own ADR amendment.

Source code in src/chamber/partners/frozen_harl.py

@register_partner("frozen_harl")
class FrozenHARLPartner(PartnerBase):
    """Frozen HARL HAPPO partner (ADR-009 §Decision; plan/04 §3.6).

    Loads a HARL :class:`StochasticPolicy` checkpoint via
    :func:`concerto.training.checkpoints.load_checkpoint` (which verifies
    the sidecar SHA-256), freezes every parameter
    (``requires_grad=False``), and runs inference under
    :func:`torch.no_grad` with ``deterministic=True``. The actor's layer
    widths are inferred from the loaded state-dict tensor shapes.

    Spec contract (plan/04 §3.6; ADR-009 §Decision):

    - ``spec.class_name == "frozen_harl"``.
    - ``spec.weights_uri`` is the ``local://artifacts/<name>.pt`` URI.
    - ``spec.extra["uid"]`` is the env-side uid the partner acts on;
      it indexes ``obs["agent"][uid]["state"]`` at action time.

    Statefulness (plan/04 §2): the partner is stateless across episodes;
    :meth:`reset` is a no-op once the checkpoint is loaded. Loading is
    deferred to the first :meth:`reset` / :meth:`act` call so the
    registry lookup in :func:`chamber.partners.registry.load_partner`
    stays cheap.

    Device placement (Phase-0): inference runs on CPU. HAPPO actor
    forward passes are microseconds-scale and not the project's
    throughput bottleneck (the OpenVLA partner stratum is); partner-side
    GPU placement is deferred to a future partner-config plane and would
    need its own ADR amendment.
    """

    def __init__(self, spec: PartnerSpec) -> None:
        """Bind the spec; defer checkpoint I/O (ADR-009 §Decision; plan/04 §3.3).

        Args:
            spec: Identity-bearing handle. Reads ``spec.extra["uid"]``
                for the env-side agent uid and ``spec.weights_uri`` for
                the checkpoint URI. Construction does not touch disk.

        Raises:
            ValueError: If ``spec.weights_uri`` is ``None`` or
                ``spec.extra["uid"]`` is missing / empty.
        """
        super().__init__(spec)
        if spec.weights_uri is None:
            msg = (
                f"FrozenHARLPartner requires spec.weights_uri (ADR-009 §Decision); "
                f"got None on spec {spec.class_name!r}."
            )
            raise ValueError(msg)
        uid = spec.extra.get("uid", "")
        if not uid:
            msg = (
                "FrozenHARLPartner requires spec.extra['uid'] (the env-side agent uid; "
                "plan/04 §3.6)."
            )
            raise ValueError(msg)
        self._uid: str = uid
        self._weights_uri: str = spec.weights_uri
        self._actor: StochasticPolicy | None = None
        self._obs_dim: int = 0
        self._action_dim: int = 0
        self._hidden_dim: int = 0

    def reset(self, *, seed: int | None = None) -> None:
        """Ensure the checkpoint is loaded; no per-episode state (ADR-009 §Decision; plan/04 §2).

        Args:
            seed: Accepted for
                :class:`~chamber.partners.api.FrozenPartner` Protocol
                conformance. The partner is fully deterministic given
                the loaded weights and ``obs``; seed is ignored.
        """
        del seed
        self._ensure_loaded()

    def act(
        self,
        obs: Mapping[str, object],
        *,
        deterministic: bool = True,
    ) -> NDArray[np.floating]:
        """Greedy HARL-actor forward pass under no-grad (ADR-009 §Decision).

        Args:
            obs: Gymnasium observation mapping. Reads the ego's flat state
                from ``obs["agent"][uid]["state"]`` (plan/04 §3.4); other
                keys are ignored.
            deterministic: Accepted for Protocol conformance but ignored.
                Phase-0 pins the partner to the distribution mode so a
                frozen partner's actions stay decoupled from torch's
                global RNG (see module docstring).

        Returns:
            ``np.float32`` action vector of length ``action_dim`` (the
            mean head's output dimension, inferred from the loaded
            checkpoint).

        Raises:
            ValueError: If ``obs["agent"][uid]["state"]`` is missing or
                its length disagrees with the loaded actor's input
                dimension.
        """
        del deterministic
        actor = self._ensure_loaded()
        state = _read_flat_state(obs, self._uid)
        if state.shape != (self._obs_dim,):
            msg = (
                f"FrozenHARLPartner: obs['agent'][{self._uid!r}]['state'] has shape "
                f"{tuple(state.shape)}, expected ({self._obs_dim},) matching the loaded "
                f"actor's input dim."
            )
            raise ValueError(msg)
        # HARL's StochasticPolicy.forward signature is
        # ``(obs, rnn_states, masks, available_actions, deterministic)``.
        # rnn_states + masks are placeholders since use_recurrent_policy=False;
        # we pass shape-correct zeros / ones so HARL's internal ``check`` call
        # accepts them. Mirrors EgoPPOTrainer.act's call site.
        obs_t = state.reshape(1, -1)
        rnn_states = np.zeros((1, 1, self._hidden_dim), dtype=np.float32)
        masks = np.ones((1, 1), dtype=np.float32)
        with torch.no_grad():
            action_t, _, _ = actor(obs_t, rnn_states, masks, None, True)
        return action_t.detach().cpu().numpy().squeeze(0).astype(np.float32)

    def _ensure_loaded(self) -> StochasticPolicy:
        """Load + freeze the HARL actor on first use; idempotent (plan/04 §3.3).

        Returns:
            The loaded :class:`StochasticPolicy` (cached after first call).

        Raises:
            CheckpointError: Propagated from
                :func:`concerto.training.checkpoints.load_checkpoint`
                when the sidecar is missing, malformed, or the SHA-256
                disagrees with the on-disk payload.
            ValueError: When the loaded state-dict does not match the
                expected HARL HAPPO actor layout.
        """
        if self._actor is not None:
            return self._actor
        artifacts_root = _resolve_artifacts_root()
        loaded, _meta = load_checkpoint(uri=self._weights_uri, artifacts_root=artifacts_root)
        actor_sd = _extract_actor_state_dict(loaded)
        obs_dim, hidden_dim, action_dim = _infer_shape(actor_sd)
        args = dict(_HARL_INFERENCE_ARGS)
        args["hidden_sizes"] = [hidden_dim, hidden_dim]
        obs_space = gym.spaces.Box(low=-np.inf, high=np.inf, shape=(obs_dim,), dtype=np.float32)
        act_space = gym.spaces.Box(low=-1.0, high=1.0, shape=(action_dim,), dtype=np.float32)
        actor = StochasticPolicy(args, obs_space, act_space, torch.device("cpu"))
        try:
            actor.load_state_dict(dict(actor_sd))
        except RuntimeError as exc:
            msg = f"FrozenHARLPartner: load_state_dict failed for {self._weights_uri!r}: {exc}"
            raise ValueError(msg) from exc
        for param in actor.parameters():
            param.requires_grad = False
        actor.eval()
        self._actor = actor
        self._obs_dim = obs_dim
        self._action_dim = action_dim
        self._hidden_dim = hidden_dim
        return actor

__init__

__init__(spec: PartnerSpec) -> None

Bind the spec; defer checkpoint I/O (ADR-009 §Decision; plan/04 §3.3).

Parameters:

• spec (PartnerSpec) –

  Identity-bearing handle. Reads spec.extra["uid"] for the env-side agent uid and spec.weights_uri for the checkpoint URI. Construction does not touch disk.

Raises:

• ValueError –

  If spec.weights_uri is None or spec.extra["uid"] is missing / empty.

Source code in src/chamber/partners/frozen_harl.py

def __init__(self, spec: PartnerSpec) -> None:
    """Bind the spec; defer checkpoint I/O (ADR-009 §Decision; plan/04 §3.3).

    Args:
        spec: Identity-bearing handle. Reads ``spec.extra["uid"]``
            for the env-side agent uid and ``spec.weights_uri`` for
            the checkpoint URI. Construction does not touch disk.

    Raises:
        ValueError: If ``spec.weights_uri`` is ``None`` or
            ``spec.extra["uid"]`` is missing / empty.
    """
    super().__init__(spec)
    if spec.weights_uri is None:
        msg = (
            f"FrozenHARLPartner requires spec.weights_uri (ADR-009 §Decision); "
            f"got None on spec {spec.class_name!r}."
        )
        raise ValueError(msg)
    uid = spec.extra.get("uid", "")
    if not uid:
        msg = (
            "FrozenHARLPartner requires spec.extra['uid'] (the env-side agent uid; "
            "plan/04 §3.6)."
        )
        raise ValueError(msg)
    self._uid: str = uid
    self._weights_uri: str = spec.weights_uri
    self._actor: StochasticPolicy | None = None
    self._obs_dim: int = 0
    self._action_dim: int = 0
    self._hidden_dim: int = 0

act

act(
    obs: Mapping[str, object], *, deterministic: bool = True
) -> NDArray[np.floating]

Greedy HARL-actor forward pass under no-grad (ADR-009 §Decision).

Parameters:

• obs (Mapping[str, object]) –

  Gymnasium observation mapping. Reads the ego's flat state from obs["agent"][uid]["state"] (plan/04 §3.4); other keys are ignored.

• deterministic (bool, default: True ) –

  Accepted for Protocol conformance but ignored. Phase-0 pins the partner to the distribution mode so a frozen partner's actions stay decoupled from torch's global RNG (see module docstring).

Returns:

• NDArray[floating] –

  np.float32 action vector of length action_dim (the

• NDArray[floating] –

  mean head's output dimension, inferred from the loaded

• NDArray[floating] –

  checkpoint).

Raises:

• ValueError –

  If obs["agent"][uid]["state"] is missing or its length disagrees with the loaded actor's input dimension.

Source code in src/chamber/partners/frozen_harl.py

def act(
    self,
    obs: Mapping[str, object],
    *,
    deterministic: bool = True,
) -> NDArray[np.floating]:
    """Greedy HARL-actor forward pass under no-grad (ADR-009 §Decision).

    Args:
        obs: Gymnasium observation mapping. Reads the ego's flat state
            from ``obs["agent"][uid]["state"]`` (plan/04 §3.4); other
            keys are ignored.
        deterministic: Accepted for Protocol conformance but ignored.
            Phase-0 pins the partner to the distribution mode so a
            frozen partner's actions stay decoupled from torch's
            global RNG (see module docstring).

    Returns:
        ``np.float32`` action vector of length ``action_dim`` (the
        mean head's output dimension, inferred from the loaded
        checkpoint).

    Raises:
        ValueError: If ``obs["agent"][uid]["state"]`` is missing or
            its length disagrees with the loaded actor's input
            dimension.
    """
    del deterministic
    actor = self._ensure_loaded()
    state = _read_flat_state(obs, self._uid)
    if state.shape != (self._obs_dim,):
        msg = (
            f"FrozenHARLPartner: obs['agent'][{self._uid!r}]['state'] has shape "
            f"{tuple(state.shape)}, expected ({self._obs_dim},) matching the loaded "
            f"actor's input dim."
        )
        raise ValueError(msg)
    # HARL's StochasticPolicy.forward signature is
    # ``(obs, rnn_states, masks, available_actions, deterministic)``.
    # rnn_states + masks are placeholders since use_recurrent_policy=False;
    # we pass shape-correct zeros / ones so HARL's internal ``check`` call
    # accepts them. Mirrors EgoPPOTrainer.act's call site.
    obs_t = state.reshape(1, -1)
    rnn_states = np.zeros((1, 1, self._hidden_dim), dtype=np.float32)
    masks = np.ones((1, 1), dtype=np.float32)
    with torch.no_grad():
        action_t, _, _ = actor(obs_t, rnn_states, masks, None, True)
    return action_t.detach().cpu().numpy().squeeze(0).astype(np.float32)

reset

reset(*, seed: int | None = None) -> None

Ensure the checkpoint is loaded; no per-episode state (ADR-009 §Decision; plan/04 §2).

Parameters:

• seed (int | None, default: None ) –

  Accepted for :class:~chamber.partners.api.FrozenPartner Protocol conformance. The partner is fully deterministic given the loaded weights and obs; seed is ignored.

Source code in src/chamber/partners/frozen_harl.py

def reset(self, *, seed: int | None = None) -> None:
    """Ensure the checkpoint is loaded; no per-episode state (ADR-009 §Decision; plan/04 §2).

    Args:
        seed: Accepted for
            :class:`~chamber.partners.api.FrozenPartner` Protocol
            conformance. The partner is fully deterministic given
            the loaded weights and ``obs``; seed is ignored.
    """
    del seed
    self._ensure_loaded()

FrozenMAPPOPartner

Bases: PartnerBase

Frozen shared-parameter MAPPO partner (ADR-009 §Decision; plan/04 §3.5).

Loads a :class:_MAPPOActor checkpoint via :func:concerto.training.checkpoints.load_checkpoint (which verifies the sidecar SHA-256), freezes every parameter (requires_grad=False), and runs inference under :func:torch.no_grad. The actor's layer widths are inferred from the loaded state-dict tensor shapes — no architecture-metadata sidecar is required (ADR-002 §Decisions: provenance lives on the sidecar; shape lives in the tensors).

Spec contract (plan/04 §3.5; ADR-009 §Decision):

• spec.class_name == "frozen_mappo".
• spec.weights_uri is the local://artifacts/<name>.pt URI.
• spec.extra["uid"] is the env-side uid the partner acts on; it indexes obs["agent"][uid]["state"] at action time.

Statefulness (plan/04 §2): the partner is stateless across episodes; :meth:reset is a no-op once the checkpoint is loaded. Loading is deferred to the first :meth:reset / :meth:act call so the registry lookup in :func:chamber.partners.registry.load_partner stays cheap and so test fixtures can construct + monkey-patch the env var before any I/O happens.

Source code in src/chamber/partners/frozen_mappo.py

@register_partner("frozen_mappo")
class FrozenMAPPOPartner(PartnerBase):
    """Frozen shared-parameter MAPPO partner (ADR-009 §Decision; plan/04 §3.5).

    Loads a :class:`_MAPPOActor` checkpoint via
    :func:`concerto.training.checkpoints.load_checkpoint` (which verifies
    the sidecar SHA-256), freezes every parameter
    (``requires_grad=False``), and runs inference under
    :func:`torch.no_grad`. The actor's layer widths are inferred from the
    loaded state-dict tensor shapes — no architecture-metadata sidecar is
    required (ADR-002 §Decisions: provenance lives on the sidecar; shape
    lives in the tensors).

    Spec contract (plan/04 §3.5; ADR-009 §Decision):

    - ``spec.class_name == "frozen_mappo"``.
    - ``spec.weights_uri`` is the ``local://artifacts/<name>.pt`` URI.
    - ``spec.extra["uid"]`` is the env-side uid the partner acts on;
      it indexes ``obs["agent"][uid]["state"]`` at action time.

    Statefulness (plan/04 §2): the partner is stateless across episodes;
    :meth:`reset` is a no-op once the checkpoint is loaded. Loading is
    deferred to the first :meth:`reset` / :meth:`act` call so the
    registry lookup in :func:`chamber.partners.registry.load_partner`
    stays cheap and so test fixtures can construct + monkey-patch the
    env var before any I/O happens.
    """

    def __init__(self, spec: PartnerSpec) -> None:
        """Bind the spec; defer checkpoint I/O (ADR-009 §Decision; plan/04 §3.3).

        Args:
            spec: Identity-bearing handle. Reads ``spec.extra["uid"]``
                for the env-side agent uid and ``spec.weights_uri`` for
                the checkpoint URI. Construction does not touch disk —
                the checkpoint is loaded lazily on first action / reset.

        Raises:
            ValueError: If ``spec.weights_uri`` is ``None`` or
                ``spec.extra["uid"]`` is missing / empty.
        """
        super().__init__(spec)
        if spec.weights_uri is None:
            msg = (
                f"FrozenMAPPOPartner requires spec.weights_uri (ADR-009 §Decision); "
                f"got None on spec {spec.class_name!r}."
            )
            raise ValueError(msg)
        uid = spec.extra.get("uid", "")
        if not uid:
            msg = (
                "FrozenMAPPOPartner requires spec.extra['uid'] (the env-side agent uid; "
                "plan/04 §3.5)."
            )
            raise ValueError(msg)
        self._uid: str = uid
        self._weights_uri: str = spec.weights_uri
        self._actor: _MAPPOActor | None = None

    def reset(self, *, seed: int | None = None) -> None:
        """Ensure the checkpoint is loaded; no per-episode state (ADR-009 §Decision; plan/04 §2).

        Args:
            seed: Accepted for :class:`~chamber.partners.api.FrozenPartner`
                Protocol conformance. The partner is fully deterministic
                given the loaded weights and ``obs``; seed is ignored.
        """
        del seed
        self._ensure_loaded()

    def act(
        self,
        obs: Mapping[str, object],
        *,
        deterministic: bool = True,
    ) -> NDArray[np.floating]:
        """Greedy MAPPO-actor forward pass under no-grad (ADR-009 §Decision).

        Args:
            obs: Gymnasium observation mapping. Reads the ego's flat state
                from ``obs["agent"][uid]["state"]`` (plan/04 §3.4); other
                keys are ignored.
            deterministic: Accepted for Protocol conformance. The
                Phase-0 actor head is a deterministic linear layer with
                no sampled noise, so this kwarg has no effect.

        Returns:
            ``np.float32`` action vector of length ``action_dim`` (the
            head's output dimension, inferred from the loaded
            checkpoint).

        Raises:
            ValueError: If ``obs["agent"][uid]["state"]`` is missing or
                its length disagrees with the loaded actor's input
                dimension.
        """
        del deterministic
        actor = self._ensure_loaded()
        state = _read_flat_state(obs, self._uid)
        expected = actor.fc1.in_features
        if state.shape != (expected,):
            msg = (
                f"FrozenMAPPOPartner: obs['agent'][{self._uid!r}]['state'] has shape "
                f"{tuple(state.shape)}, expected ({expected},) matching the loaded "
                f"actor's fc1 input dim."
            )
            raise ValueError(msg)
        with torch.no_grad():
            input_t = torch.from_numpy(state).unsqueeze(0)
            action_t = actor(input_t)
        return action_t.squeeze(0).detach().cpu().numpy().astype(np.float32)

    def _ensure_loaded(self) -> _MAPPOActor:
        """Load + freeze the actor on first use; idempotent (plan/04 §3.3).

        Returns:
            The loaded :class:`_MAPPOActor` (cached after first call).

        Raises:
            CheckpointError: Propagated from
                :func:`concerto.training.checkpoints.load_checkpoint`
                when the sidecar is missing, malformed, or the SHA-256
                disagrees with the on-disk payload.
            ValueError: When the loaded state-dict does not match the
                expected MAPPO actor layout.
        """
        if self._actor is not None:
            return self._actor
        artifacts_root = _resolve_artifacts_root()
        loaded, _meta = load_checkpoint(uri=self._weights_uri, artifacts_root=artifacts_root)
        actor = self._build_actor_from_state_dict(loaded)
        for param in actor.parameters():
            param.requires_grad = False
        actor.eval()
        self._actor = actor
        return actor

    def _build_actor_from_state_dict(self, loaded: Mapping[str, object]) -> _MAPPOActor:
        """Reconstruct the MLP actor from a loaded checkpoint dict (plan/04 §3.5).

        Accepts both nested (``{"actor": <flat_state_dict>}``) and flat
        layouts. The nested layout is the canonical Phase-0 format
        produced by :meth:`chamber.benchmarks.ego_ppo_trainer.EgoPPOTrainer.state_dict`
        (the ``"actor"`` sub-key); the flat layout is the convenience
        format the unit tests + manual reproduction scripts use.

        Args:
            loaded: The dict :func:`load_checkpoint` returned.

        Returns:
            A fresh :class:`_MAPPOActor` with weights copied from
            ``loaded``.

        Raises:
            ValueError: When required layer keys are missing or shapes
                disagree.
        """
        state_dict = _extract_actor_state_dict(loaded)
        try:
            fc1_weight = state_dict[_FC1_WEIGHT_KEY]
            fc2_weight = state_dict[_FC2_WEIGHT_KEY]
            head_weight = state_dict[_HEAD_WEIGHT_KEY]
        except KeyError as exc:
            msg = (
                f"FrozenMAPPOPartner: loaded actor state-dict is missing required "
                f"layer key {exc.args[0]!r}; expected the fc1/fc2/head MLP layout "
                f"(plan/04 §3.5). Got keys: {sorted(state_dict.keys())}."
            )
            raise ValueError(msg) from exc
        if not (
            isinstance(fc1_weight, torch.Tensor)
            and isinstance(fc2_weight, torch.Tensor)
            and isinstance(head_weight, torch.Tensor)
        ):
            msg = (
                "FrozenMAPPOPartner: actor state-dict layer values must be "
                "torch.Tensor; got non-tensor entries."
            )
            raise ValueError(msg)
        hidden_dim, obs_dim = int(fc1_weight.shape[0]), int(fc1_weight.shape[1])
        action_dim = int(head_weight.shape[0])
        if fc2_weight.shape != (hidden_dim, hidden_dim):
            msg = (
                f"FrozenMAPPOPartner: fc2 shape {tuple(fc2_weight.shape)} disagrees "
                f"with inferred hidden_dim {hidden_dim} (plan/04 §3.5)."
            )
            raise ValueError(msg)
        if head_weight.shape[1] != hidden_dim:
            msg = (
                f"FrozenMAPPOPartner: head input dim {head_weight.shape[1]} disagrees "
                f"with inferred hidden_dim {hidden_dim} (plan/04 §3.5)."
            )
            raise ValueError(msg)
        actor = _MAPPOActor(obs_dim=obs_dim, hidden_dim=hidden_dim, action_dim=action_dim)
        try:
            actor.load_state_dict(dict(state_dict))
        except RuntimeError as exc:
            msg = f"FrozenMAPPOPartner: load_state_dict failed for {self._weights_uri!r}: {exc}"
            raise ValueError(msg) from exc
        return actor

__init__

__init__(spec: PartnerSpec) -> None

Bind the spec; defer checkpoint I/O (ADR-009 §Decision; plan/04 §3.3).

Parameters:

• spec (PartnerSpec) –

  Identity-bearing handle. Reads spec.extra["uid"] for the env-side agent uid and spec.weights_uri for the checkpoint URI. Construction does not touch disk — the checkpoint is loaded lazily on first action / reset.

Raises:

• ValueError –

  If spec.weights_uri is None or spec.extra["uid"] is missing / empty.

Source code in src/chamber/partners/frozen_mappo.py

def __init__(self, spec: PartnerSpec) -> None:
    """Bind the spec; defer checkpoint I/O (ADR-009 §Decision; plan/04 §3.3).

    Args:
        spec: Identity-bearing handle. Reads ``spec.extra["uid"]``
            for the env-side agent uid and ``spec.weights_uri`` for
            the checkpoint URI. Construction does not touch disk —
            the checkpoint is loaded lazily on first action / reset.

    Raises:
        ValueError: If ``spec.weights_uri`` is ``None`` or
            ``spec.extra["uid"]`` is missing / empty.
    """
    super().__init__(spec)
    if spec.weights_uri is None:
        msg = (
            f"FrozenMAPPOPartner requires spec.weights_uri (ADR-009 §Decision); "
            f"got None on spec {spec.class_name!r}."
        )
        raise ValueError(msg)
    uid = spec.extra.get("uid", "")
    if not uid:
        msg = (
            "FrozenMAPPOPartner requires spec.extra['uid'] (the env-side agent uid; "
            "plan/04 §3.5)."
        )
        raise ValueError(msg)
    self._uid: str = uid
    self._weights_uri: str = spec.weights_uri
    self._actor: _MAPPOActor | None = None

act

act(
    obs: Mapping[str, object], *, deterministic: bool = True
) -> NDArray[np.floating]

Greedy MAPPO-actor forward pass under no-grad (ADR-009 §Decision).

Parameters:

• obs (Mapping[str, object]) –

  Gymnasium observation mapping. Reads the ego's flat state from obs["agent"][uid]["state"] (plan/04 §3.4); other keys are ignored.

• deterministic (bool, default: True ) –

  Accepted for Protocol conformance. The Phase-0 actor head is a deterministic linear layer with no sampled noise, so this kwarg has no effect.

Returns:

• NDArray[floating] –

  np.float32 action vector of length action_dim (the

• NDArray[floating] –

  head's output dimension, inferred from the loaded

• NDArray[floating] –

  checkpoint).

Raises:

• ValueError –

  If obs["agent"][uid]["state"] is missing or its length disagrees with the loaded actor's input dimension.

Source code in src/chamber/partners/frozen_mappo.py

def act(
    self,
    obs: Mapping[str, object],
    *,
    deterministic: bool = True,
) -> NDArray[np.floating]:
    """Greedy MAPPO-actor forward pass under no-grad (ADR-009 §Decision).

    Args:
        obs: Gymnasium observation mapping. Reads the ego's flat state
            from ``obs["agent"][uid]["state"]`` (plan/04 §3.4); other
            keys are ignored.
        deterministic: Accepted for Protocol conformance. The
            Phase-0 actor head is a deterministic linear layer with
            no sampled noise, so this kwarg has no effect.

    Returns:
        ``np.float32`` action vector of length ``action_dim`` (the
        head's output dimension, inferred from the loaded
        checkpoint).

    Raises:
        ValueError: If ``obs["agent"][uid]["state"]`` is missing or
            its length disagrees with the loaded actor's input
            dimension.
    """
    del deterministic
    actor = self._ensure_loaded()
    state = _read_flat_state(obs, self._uid)
    expected = actor.fc1.in_features
    if state.shape != (expected,):
        msg = (
            f"FrozenMAPPOPartner: obs['agent'][{self._uid!r}]['state'] has shape "
            f"{tuple(state.shape)}, expected ({expected},) matching the loaded "
            f"actor's fc1 input dim."
        )
        raise ValueError(msg)
    with torch.no_grad():
        input_t = torch.from_numpy(state).unsqueeze(0)
        action_t = actor(input_t)
    return action_t.squeeze(0).detach().cpu().numpy().astype(np.float32)

reset

reset(*, seed: int | None = None) -> None

Ensure the checkpoint is loaded; no per-episode state (ADR-009 §Decision; plan/04 §2).

Parameters:

• seed (int | None, default: None ) –

  Accepted for :class:~chamber.partners.api.FrozenPartner Protocol conformance. The partner is fully deterministic given the loaded weights and obs; seed is ignored.

Source code in src/chamber/partners/frozen_mappo.py

def reset(self, *, seed: int | None = None) -> None:
    """Ensure the checkpoint is loaded; no per-episode state (ADR-009 §Decision; plan/04 §2).

    Args:
        seed: Accepted for :class:`~chamber.partners.api.FrozenPartner`
            Protocol conformance. The partner is fully deterministic
            given the loaded weights and ``obs``; seed is ignored.
    """
    del seed
    self._ensure_loaded()

FrozenPartner

Bases: Protocol

A partner the ego agent treats as a black box (ADR-009 §Decision).

Implementations MUST NOT expose any update / train / learn methods at runtime. The base class :class:chamber.partners.interface.PartnerBase enforces this via a __getattr__ shield over _FORBIDDEN_ATTRS. Type checkers reject Protocol-typed access to train / learn / update_params because those names are not part of this Protocol.

Stateless across episodes: reset(*, seed) clears every internal cache (plan/04 §2 "Partner state" — Phase-0 deliberately excludes recurrent partner policies; if Phase 1 needs them, ADR amendment).

Source code in src/chamber/partners/api.py

@runtime_checkable
class FrozenPartner(Protocol):
    """A partner the ego agent treats as a black box (ADR-009 §Decision).

    Implementations MUST NOT expose any update / train / learn methods at
    runtime. The base class :class:`chamber.partners.interface.PartnerBase`
    enforces this via a ``__getattr__`` shield over ``_FORBIDDEN_ATTRS``.
    Type checkers reject Protocol-typed access to ``train`` / ``learn`` /
    ``update_params`` because those names are not part of this Protocol.

    Stateless across episodes: ``reset(*, seed)`` clears every internal
    cache (plan/04 §2 "Partner state" — Phase-0 deliberately excludes
    recurrent partner policies; if Phase 1 needs them, ADR amendment).
    """

    spec: PartnerSpec

    def reset(self, *, seed: int | None = None) -> None:
        """Reset internal episode state (ADR-009 §Decision; P6 reproducibility).

        Args:
            seed: Optional root seed for the partner's deterministic RNG
                substream. Implementations route this through
                :func:`concerto.training.seeding.derive_substream`.
        """
        ...  # pragma: no cover

    def act(
        self,
        obs: Mapping[str, object],
        *,
        deterministic: bool = True,
    ) -> NDArray[np.floating]:
        """Map observation to action (ADR-009 §Decision; ADR-003 §Decision).

        The observation mapping is the Gymnasium-conformant
        ``{"agent": {uid: proprio}, "comm": CommPacket, "meta": {...}}``
        produced by :mod:`chamber.envs` wrappers. Partners read
        ``obs["agent"][uid]`` for proprioception and ``obs["comm"]`` for the
        ADR-003 fixed-format channel; they MUST NOT touch any other key.

        The accepted type is :class:`~collections.abc.Mapping` rather than
        :class:`dict` so that callers can pass concrete nested dicts without
        running into Mapping-vs-dict invariance issues at the call site.

        Args:
            obs: Gymnasium observation dict.
            deterministic: Whether to sample greedily (default ``True``);
                stochastic policies pass ``False``. Scripted partners ignore.

        Returns:
            Action vector for the partner's own uid, shape and dtype defined
            by the env's action space slice for that uid.
        """
        ...  # pragma: no cover

act

act(
    obs: Mapping[str, object], *, deterministic: bool = True
) -> NDArray[np.floating]

Map observation to action (ADR-009 §Decision; ADR-003 §Decision).

The observation mapping is the Gymnasium-conformant {"agent": {uid: proprio}, "comm": CommPacket, "meta": {...}} produced by :mod:chamber.envs wrappers. Partners read obs["agent"][uid] for proprioception and obs["comm"] for the ADR-003 fixed-format channel; they MUST NOT touch any other key.

The accepted type is :class:~collections.abc.Mapping rather than :class:dict so that callers can pass concrete nested dicts without running into Mapping-vs-dict invariance issues at the call site.

Parameters:

• obs (Mapping[str, object]) –

  Gymnasium observation dict.

• deterministic (bool, default: True ) –

  Whether to sample greedily (default True); stochastic policies pass False. Scripted partners ignore.

Returns:

• NDArray[floating] –

  Action vector for the partner's own uid, shape and dtype defined

• NDArray[floating] –

  by the env's action space slice for that uid.

Source code in src/chamber/partners/api.py

def act(
    self,
    obs: Mapping[str, object],
    *,
    deterministic: bool = True,
) -> NDArray[np.floating]:
    """Map observation to action (ADR-009 §Decision; ADR-003 §Decision).

    The observation mapping is the Gymnasium-conformant
    ``{"agent": {uid: proprio}, "comm": CommPacket, "meta": {...}}``
    produced by :mod:`chamber.envs` wrappers. Partners read
    ``obs["agent"][uid]`` for proprioception and ``obs["comm"]`` for the
    ADR-003 fixed-format channel; they MUST NOT touch any other key.

    The accepted type is :class:`~collections.abc.Mapping` rather than
    :class:`dict` so that callers can pass concrete nested dicts without
    running into Mapping-vs-dict invariance issues at the call site.

    Args:
        obs: Gymnasium observation dict.
        deterministic: Whether to sample greedily (default ``True``);
            stochastic policies pass ``False``. Scripted partners ignore.

    Returns:
        Action vector for the partner's own uid, shape and dtype defined
        by the env's action space slice for that uid.
    """
    ...  # pragma: no cover

reset

reset(*, seed: int | None = None) -> None

Reset internal episode state (ADR-009 §Decision; P6 reproducibility).

Parameters:

• seed (int | None, default: None ) –

  Optional root seed for the partner's deterministic RNG substream. Implementations route this through :func:concerto.training.seeding.derive_substream.

Source code in src/chamber/partners/api.py

def reset(self, *, seed: int | None = None) -> None:
    """Reset internal episode state (ADR-009 §Decision; P6 reproducibility).

    Args:
        seed: Optional root seed for the partner's deterministic RNG
            substream. Implementations route this through
            :func:`concerto.training.seeding.derive_substream`.
    """
    ...  # pragma: no cover

HandoverPresenterPartner

Bases: PartnerBase

Scripted black-box presenter for handover-and-place (ADR-009; ADR-026 §Decision).

Emits a presentation action [lat_offset_x, lat_offset_y, grasp_pose_error_deg, timing_skew_s] drawn from its distribution; the matched/mismatched split lives in the grasp-pose term only. Frozen: implements reset/act only; PartnerBase blocks every _FORBIDDEN_ATTRS lookup so the AHT no-joint-training constraint holds at runtime (ADR-009 §Consequences).

Source code in src/chamber/partners/handover_presenter.py

@register_partner(HANDOVER_PRESENTER_CLASS)
class HandoverPresenterPartner(PartnerBase):
    """Scripted black-box presenter for handover-and-place (ADR-009; ADR-026 §Decision).

    Emits a presentation action ``[lat_offset_x, lat_offset_y, grasp_pose_error_deg,
    timing_skew_s]`` drawn from its distribution; the matched/mismatched split lives in
    the grasp-pose term only. Frozen: implements ``reset``/``act`` only;
    ``PartnerBase`` blocks every ``_FORBIDDEN_ATTRS`` lookup so the AHT
    no-joint-training constraint holds at runtime (ADR-009 §Consequences).
    """

    def __init__(self, spec: PartnerSpec) -> None:
        """Bind the variant label and presentation params from ``spec`` (ADR-009)."""
        super().__init__(spec)
        self.variant: str = spec.extra.get("variant", "matched")
        self._params: dict[str, float] = {
            key: float(spec.extra[key]) for key in _PARAM_KEYS if key in spec.extra
        }
        self._rng: np.random.Generator | None = None

    def reset(self, *, seed: int | None = None) -> None:
        """Seed the per-episode presentation RNG (P6 / ADR-002; FrozenPartner contract).

        Builds a fresh deterministic generator so the presentation is a pure function
        of ``seed``; clears any prior episode state.
        """
        episode_seed = 0 if seed is None else int(seed)
        self._rng = derive_substream(
            f"partner.handover_presenter.{self.variant}", root_seed=episode_seed
        ).default_rng()

    def act(self, obs: Mapping[str, Any], *, deterministic: bool = True) -> NDArray[np.floating]:
        """Draw the presentation handed to the ego (ADR-026 §Decision; ADR-009).

        A one-shot draw from the variant's distribution; ``obs`` is unused (the
        presenter conditions on nothing the ego controls). ``deterministic`` is
        accepted for the FrozenPartner Protocol; the draw is fully seed-determined, so
        the flag does not change behaviour.
        """
        del obs, deterministic
        if self._rng is None:
            raise RuntimeError("HandoverPresenterPartner.act called before reset()")
        rng = self._rng
        p = self._params
        lateral_sigma = p.get("lateral_sigma_m", 0.0)
        lat_x = p.get("lateral_offset_x_m", 0.0) + float(rng.normal(0.0, lateral_sigma))
        lat_y = p.get("lateral_offset_y_m", 0.0) + float(rng.normal(0.0, lateral_sigma))
        grasp_pose_error = p.get("grasp_pose_bias_deg", 0.0) + float(
            rng.normal(0.0, p.get("grasp_pose_sigma_deg", 0.0))
        )
        timing_skew = max(
            0.0,
            p.get("timing_skew_bias_s", 0.0)
            + float(rng.normal(0.0, p.get("timing_skew_sigma_s", 0.0))),
        )
        action = np.zeros(HANDOVER_PRESENTATION_DIM, dtype=np.float64)
        action[:] = (lat_x, lat_y, grasp_pose_error, timing_skew)
        return action

__init__

__init__(spec: PartnerSpec) -> None

Bind the variant label and presentation params from spec (ADR-009).

Source code in src/chamber/partners/handover_presenter.py

def __init__(self, spec: PartnerSpec) -> None:
    """Bind the variant label and presentation params from ``spec`` (ADR-009)."""
    super().__init__(spec)
    self.variant: str = spec.extra.get("variant", "matched")
    self._params: dict[str, float] = {
        key: float(spec.extra[key]) for key in _PARAM_KEYS if key in spec.extra
    }
    self._rng: np.random.Generator | None = None

act

act(
    obs: Mapping[str, Any], *, deterministic: bool = True
) -> NDArray[np.floating]

Draw the presentation handed to the ego (ADR-026 §Decision; ADR-009).

A one-shot draw from the variant's distribution; obs is unused (the presenter conditions on nothing the ego controls). deterministic is accepted for the FrozenPartner Protocol; the draw is fully seed-determined, so the flag does not change behaviour.

Source code in src/chamber/partners/handover_presenter.py

def act(self, obs: Mapping[str, Any], *, deterministic: bool = True) -> NDArray[np.floating]:
    """Draw the presentation handed to the ego (ADR-026 §Decision; ADR-009).

    A one-shot draw from the variant's distribution; ``obs`` is unused (the
    presenter conditions on nothing the ego controls). ``deterministic`` is
    accepted for the FrozenPartner Protocol; the draw is fully seed-determined, so
    the flag does not change behaviour.
    """
    del obs, deterministic
    if self._rng is None:
        raise RuntimeError("HandoverPresenterPartner.act called before reset()")
    rng = self._rng
    p = self._params
    lateral_sigma = p.get("lateral_sigma_m", 0.0)
    lat_x = p.get("lateral_offset_x_m", 0.0) + float(rng.normal(0.0, lateral_sigma))
    lat_y = p.get("lateral_offset_y_m", 0.0) + float(rng.normal(0.0, lateral_sigma))
    grasp_pose_error = p.get("grasp_pose_bias_deg", 0.0) + float(
        rng.normal(0.0, p.get("grasp_pose_sigma_deg", 0.0))
    )
    timing_skew = max(
        0.0,
        p.get("timing_skew_bias_s", 0.0)
        + float(rng.normal(0.0, p.get("timing_skew_sigma_s", 0.0))),
    )
    action = np.zeros(HANDOVER_PRESENTATION_DIM, dtype=np.float64)
    action[:] = (lat_x, lat_y, grasp_pose_error, timing_skew)
    return action

reset

reset(*, seed: int | None = None) -> None

Seed the per-episode presentation RNG (P6 / ADR-002; FrozenPartner contract).

Builds a fresh deterministic generator so the presentation is a pure function of seed; clears any prior episode state.

Source code in src/chamber/partners/handover_presenter.py

def reset(self, *, seed: int | None = None) -> None:
    """Seed the per-episode presentation RNG (P6 / ADR-002; FrozenPartner contract).

    Builds a fresh deterministic generator so the presentation is a pure function
    of ``seed``; clears any prior episode state.
    """
    episode_seed = 0 if seed is None else int(seed)
    self._rng = derive_substream(
        f"partner.handover_presenter.{self.variant}", root_seed=episode_seed
    ).default_rng()

OpenVLAPartner

Bases: PartnerBase

OpenVLA LoRA-adapted specialist — Phase-1 stub (ADR-010 §Decision Option B).

LoRA fine-tune protocol (ADR-010 §Decision; ADR-009 §Decision): 10-150 demos, single GPU at ≤7.0 GB VRAM, 256-bin-per-DoF action tokenisation. The 5-15 Hz throughput ceiling is enforced at the env wrapper layer (chamber.envs.action_repeat), not here.

Source code in src/chamber/partners/stubs/openvla.py

@register_partner("openvla_lora_specialist")
class OpenVLAPartner(PartnerBase):
    """OpenVLA LoRA-adapted specialist — Phase-1 stub (ADR-010 §Decision Option B).

    LoRA fine-tune protocol (ADR-010 §Decision; ADR-009 §Decision):
    10-150 demos, single GPU at ≤7.0 GB VRAM, 256-bin-per-DoF action
    tokenisation. The 5-15 Hz throughput ceiling is enforced at the env
    wrapper layer (``chamber.envs.action_repeat``), not here.
    """

    def reset(self, *, seed: int | None = None) -> NoReturn:
        """Phase-1 stub — raises (ADR-010 §Decision Option B).

        Args:
            seed: Accepted for Protocol conformance only.

        Raises:
            NotImplementedError: Always; the real LoRA inference harness is
                Phase-1 work.
        """
        del seed
        raise NotImplementedError(
            f"OpenVLAPartner.reset is Phase-1 work; see ADR-010 §Decision and {_PHASE1_TICKET}."
        )

    def act(
        self,
        obs: Mapping[str, object],
        *,
        deterministic: bool = True,
    ) -> NDArray[np.floating]:
        """Phase-1 stub — raises (ADR-010 §Decision Option B).

        Args:
            obs: Gymnasium observation mapping.
            deterministic: Accepted for Protocol conformance only.

        Raises:
            NotImplementedError: Always; the real 256-bin action-token
                inference is Phase-1 work.
        """
        del obs, deterministic
        raise NotImplementedError(
            f"OpenVLAPartner.act is Phase-1 work; see ADR-010 §Decision and {_PHASE1_TICKET}."
        )

act

act(
    obs: Mapping[str, object], *, deterministic: bool = True
) -> NDArray[np.floating]

Phase-1 stub — raises (ADR-010 §Decision Option B).

Parameters:

• obs (Mapping[str, object]) –

  Gymnasium observation mapping.

• deterministic (bool, default: True ) –

  Accepted for Protocol conformance only.

Raises:

• NotImplementedError –

  Always; the real 256-bin action-token inference is Phase-1 work.

Source code in src/chamber/partners/stubs/openvla.py

def act(
    self,
    obs: Mapping[str, object],
    *,
    deterministic: bool = True,
) -> NDArray[np.floating]:
    """Phase-1 stub — raises (ADR-010 §Decision Option B).

    Args:
        obs: Gymnasium observation mapping.
        deterministic: Accepted for Protocol conformance only.

    Raises:
        NotImplementedError: Always; the real 256-bin action-token
            inference is Phase-1 work.
    """
    del obs, deterministic
    raise NotImplementedError(
        f"OpenVLAPartner.act is Phase-1 work; see ADR-010 §Decision and {_PHASE1_TICKET}."
    )

reset

reset(*, seed: int | None = None) -> NoReturn

Phase-1 stub — raises (ADR-010 §Decision Option B).

Parameters:

• seed (int | None, default: None ) –

  Accepted for Protocol conformance only.

Raises:

• NotImplementedError –

  Always; the real LoRA inference harness is Phase-1 work.

Source code in src/chamber/partners/stubs/openvla.py

def reset(self, *, seed: int | None = None) -> NoReturn:
    """Phase-1 stub — raises (ADR-010 §Decision Option B).

    Args:
        seed: Accepted for Protocol conformance only.

    Raises:
        NotImplementedError: Always; the real LoRA inference harness is
            Phase-1 work.
    """
    del seed
    raise NotImplementedError(
        f"OpenVLAPartner.reset is Phase-1 work; see ADR-010 §Decision and {_PHASE1_TICKET}."
    )

PartnerAblatedZero

Bases: PartnerBase

Zero-action partner seat for A2 partner-ablated cells (ADR-027 §Admission protocol).

Emits an all-zero action of length spec.extra["action_dim"] regardless of the observation — the partner is physically removed / zeroed in the task's own terms (ADR-026 §Decision 2's single-robot side of the coupling positive-control). Deterministic and stateless (ADR-009 §Decision).

Source code in src/chamber/partners/ablation.py

@register_partner(PARTNER_ABLATED_ZERO_CLASS)
class PartnerAblatedZero(PartnerBase):
    """Zero-action partner seat for A2 partner-ablated cells (ADR-027 §Admission protocol).

    Emits an all-zero action of length ``spec.extra["action_dim"]``
    regardless of the observation — the partner is physically removed /
    zeroed in the task's own terms (ADR-026 §Decision 2's single-robot
    side of the coupling positive-control). Deterministic and stateless
    (ADR-009 §Decision).
    """

    def __init__(self, spec: PartnerSpec) -> None:
        """Bind the action dimensionality from ``spec.extra`` (ADR-027 §Admission protocol).

        Raises:
            ValueError: When ``spec.extra["action_dim"]`` is missing or
                not a positive integer.
        """
        super().__init__(spec)
        raw = spec.extra.get("action_dim")
        try:
            action_dim = int(raw) if raw is not None else 0
        except ValueError as exc:
            msg = f"action_dim must be a positive int; got {raw!r}"
            raise ValueError(msg) from exc
        if action_dim < 1:
            msg = f"action_dim must be a positive int; got {raw!r}"
            raise ValueError(msg)
        self._action_dim: int = action_dim

    def reset(self, *, seed: int | None = None) -> None:
        """No-op — the instrument is stateless (ADR-009 §Decision)."""
        del seed

    def act(
        self,
        obs: Mapping[str, object],
        *,
        deterministic: bool = True,
    ) -> NDArray[np.floating]:
        """Return the all-zero action (ADR-027 §Admission protocol A2).

        Args:
            obs: Ignored — the ablated seat observes nothing.
            deterministic: Ignored — zeros are zeros.

        Returns:
            Float32 zeros of the bound ``action_dim``.
        """
        del obs, deterministic
        return np.zeros(self._action_dim, dtype=np.float32)

__init__

__init__(spec: PartnerSpec) -> None

Bind the action dimensionality from spec.extra (ADR-027 §Admission protocol).

Raises:

• ValueError –

  When spec.extra["action_dim"] is missing or not a positive integer.

Source code in src/chamber/partners/ablation.py

def __init__(self, spec: PartnerSpec) -> None:
    """Bind the action dimensionality from ``spec.extra`` (ADR-027 §Admission protocol).

    Raises:
        ValueError: When ``spec.extra["action_dim"]`` is missing or
            not a positive integer.
    """
    super().__init__(spec)
    raw = spec.extra.get("action_dim")
    try:
        action_dim = int(raw) if raw is not None else 0
    except ValueError as exc:
        msg = f"action_dim must be a positive int; got {raw!r}"
        raise ValueError(msg) from exc
    if action_dim < 1:
        msg = f"action_dim must be a positive int; got {raw!r}"
        raise ValueError(msg)
    self._action_dim: int = action_dim

act

act(
    obs: Mapping[str, object], *, deterministic: bool = True
) -> NDArray[np.floating]

Return the all-zero action (ADR-027 §Admission protocol A2).

Parameters:

• obs (Mapping[str, object]) –

  Ignored — the ablated seat observes nothing.

• deterministic (bool, default: True ) –

  Ignored — zeros are zeros.

Returns:

• NDArray[floating] –

  Float32 zeros of the bound action_dim.

Source code in src/chamber/partners/ablation.py

def act(
    self,
    obs: Mapping[str, object],
    *,
    deterministic: bool = True,
) -> NDArray[np.floating]:
    """Return the all-zero action (ADR-027 §Admission protocol A2).

    Args:
        obs: Ignored — the ablated seat observes nothing.
        deterministic: Ignored — zeros are zeros.

    Returns:
        Float32 zeros of the bound ``action_dim``.
    """
    del obs, deterministic
    return np.zeros(self._action_dim, dtype=np.float32)

reset

reset(*, seed: int | None = None) -> None

No-op — the instrument is stateless (ADR-009 §Decision).

Source code in src/chamber/partners/ablation.py

def reset(self, *, seed: int | None = None) -> None:
    """No-op — the instrument is stateless (ADR-009 §Decision)."""
    del seed

PartnerBase

Common base class for every concrete partner (ADR-009 §Consequences).

Subclasses MUST implement reset(*, seed) and act(obs, *, deterministic) per the :class:~chamber.partners.api.FrozenPartner Protocol. The base class blocks any attribute lookup in :data:_FORBIDDEN_ATTRS so the AHT no-joint-training constraint is enforced even when a careless caller imports the underlying torch module directly.

Attributes:

• spec (PartnerSpec) –

  The :class:~chamber.partners.api.PartnerSpec the partner was constructed from. Read-only by convention; the registry assumes Class(spec) is the only constructor signature.

Source code in src/chamber/partners/interface.py

class PartnerBase:
    """Common base class for every concrete partner (ADR-009 §Consequences).

    Subclasses MUST implement ``reset(*, seed)`` and
    ``act(obs, *, deterministic)`` per the
    :class:`~chamber.partners.api.FrozenPartner` Protocol. The base class
    blocks any attribute lookup in :data:`_FORBIDDEN_ATTRS` so the AHT
    no-joint-training constraint is enforced even when a careless caller
    imports the underlying torch module directly.

    Attributes:
        spec: The :class:`~chamber.partners.api.PartnerSpec` the partner was
            constructed from. Read-only by convention; the registry assumes
            ``Class(spec)`` is the only constructor signature.
    """

    spec: PartnerSpec

    def __init__(self, spec: PartnerSpec) -> None:
        """Bind the partner spec (ADR-009 §Decision).

        Args:
            spec: Identity-bearing handle from
                :class:`~chamber.partners.api.PartnerSpec`. The constructor
                does no checkpoint I/O so subclasses can defer heavy loads
                until :meth:`reset`.
        """
        self.spec = spec

    def __getattr__(self, name: str) -> NoReturn:
        """Block forbidden attribute lookups (ADR-009 §Consequences).

        ``__getattr__`` is only invoked for names not found via the normal
        attribute lookup path, so this method does not interfere with
        legitimate methods defined on subclasses or with ``self.spec``.

        Args:
            name: Attribute name being looked up.

        Raises:
            AttributeError: Always — either with the ADR-009 message for
                forbidden names, or with the Pythonic-default message for
                anything else (so ``hasattr`` works as expected).
        """
        if name in _FORBIDDEN_ATTRS:
            raise AttributeError(
                f"FrozenPartner of class {type(self).__name__!r} forbids attribute "
                f"{name!r} (ADR-009 §Consequences: black-box AHT — no joint training)."
            )
        raise AttributeError(name)

__getattr__

__getattr__(name: str) -> NoReturn

Block forbidden attribute lookups (ADR-009 §Consequences).

__getattr__ is only invoked for names not found via the normal attribute lookup path, so this method does not interfere with legitimate methods defined on subclasses or with self.spec.

Parameters:

• name (str) –

  Attribute name being looked up.

Raises:

• AttributeError –

  Always — either with the ADR-009 message for forbidden names, or with the Pythonic-default message for anything else (so hasattr works as expected).

Source code in src/chamber/partners/interface.py

def __getattr__(self, name: str) -> NoReturn:
    """Block forbidden attribute lookups (ADR-009 §Consequences).

    ``__getattr__`` is only invoked for names not found via the normal
    attribute lookup path, so this method does not interfere with
    legitimate methods defined on subclasses or with ``self.spec``.

    Args:
        name: Attribute name being looked up.

    Raises:
        AttributeError: Always — either with the ADR-009 message for
            forbidden names, or with the Pythonic-default message for
            anything else (so ``hasattr`` works as expected).
    """
    if name in _FORBIDDEN_ATTRS:
        raise AttributeError(
            f"FrozenPartner of class {type(self).__name__!r} forbids attribute "
            f"{name!r} (ADR-009 §Consequences: black-box AHT — no joint training)."
        )
    raise AttributeError(name)

__init__

__init__(spec: PartnerSpec) -> None

Bind the partner spec (ADR-009 §Decision).

Parameters:

• spec (PartnerSpec) –

  Identity-bearing handle from :class:~chamber.partners.api.PartnerSpec. The constructor does no checkpoint I/O so subclasses can defer heavy loads until :meth:reset.

Source code in src/chamber/partners/interface.py

def __init__(self, spec: PartnerSpec) -> None:
    """Bind the partner spec (ADR-009 §Decision).

    Args:
        spec: Identity-bearing handle from
            :class:`~chamber.partners.api.PartnerSpec`. The constructor
            does no checkpoint I/O so subclasses can defer heavy loads
            until :meth:`reset`.
    """
    self.spec = spec

PartnerMemberSpec

Bases: BaseModel

One named member of a versioned partner set (ADR-009 §Decision as amended 2026-07-05).

Attributes:

• member_name (str) –

  Set-unique name (card file name, roster key, partners.json member key).

• registry_class (str) –

  The :func:chamber.partners.registry.register_partner key the member is built from (the scripted stratum parameterizes one class into many members).

• role (str) –

  Seat the member plays where the task is asymmetric (partner_arm / presenter / partner).

• split (SplitLabel) –

  Committed split assignment — validated against the recomputed :func:compute_split rule at set registration (no hand-picking).

• seed (int) –

  :class:~chamber.partners.api.PartnerSpec seed identity field (0 for scripted members; CB-06 learned members carry their training seed).

• checkpoint_step (int | None) –

  Checkpoint identity field (None scripted).

• param_box (dict[str, ParamRange]) –

  Committed per-parameter draw boxes (public for every member — the capability-matching statement).

• params (dict[str, str] | None) –

  Exact behavioural parameters — committed literals for public members, None (withheld) for private members.

• params_sha256 (str) –

  SHA-256 custody digest of the exact parameters (:func:params_sha256) — committed for every member; the verification anchor for private reconstructions (I4-adjacent discipline; ADR-018 §Decision custody style).

• checkpoint_uri (str | None) –

  The learned stratum (CB-06 / ADR-027 §Versioning): the real local://artifacts/... payload URI of a frozen trained policy. When set, it IS the member's identity-bearing :attr:weights_uri (the member:// parameter-digest URI is a scripted-stratum device), the loading wrapper verifies the SHA-256 sidecar at load, and :attr:checkpoint_sha256 commits the payload digest here for roster-level custody. None for the scripted stratum.

• checkpoint_sha256 (str | None) –

  Committed SHA-256 of the checkpoint payload (must match the ADR-002 sidecar); required iff checkpoint_uri is set.

• provenance (str) –

  Free-text provenance line rendered on the member's card — mandatory content for jointly-trained members ("trained jointly with "; ADR-011 §Decision as amended).

Source code in src/chamber/partners/sets.py

class PartnerMemberSpec(BaseModel):
    """One named member of a versioned partner set (ADR-009 §Decision as amended 2026-07-05).

    Attributes:
        member_name: Set-unique name (card file name, roster key,
            ``partners.json`` member key).
        registry_class: The :func:`chamber.partners.registry.register_partner`
            key the member is built from (the scripted stratum
            parameterizes one class into many members).
        role: Seat the member plays where the task is asymmetric
            (``partner_arm`` / ``presenter`` / ``partner``).
        split: Committed split assignment — validated against the
            recomputed :func:`compute_split` rule at set registration
            (no hand-picking).
        seed: :class:`~chamber.partners.api.PartnerSpec` seed identity
            field (``0`` for scripted members; CB-06 learned members
            carry their training seed).
        checkpoint_step: Checkpoint identity field (``None`` scripted).
        param_box: Committed per-parameter draw boxes (public for every
            member — the capability-matching statement).
        params: Exact behavioural parameters — committed literals for
            public members, ``None`` (withheld) for private members.
        params_sha256: SHA-256 custody digest of the exact parameters
            (:func:`params_sha256`) — committed for every member; the
            verification anchor for private reconstructions (I4-adjacent
            discipline; ADR-018 §Decision custody style).
        checkpoint_uri: The learned stratum (CB-06 / ADR-027
            §Versioning): the real ``local://artifacts/...`` payload
            URI of a frozen trained policy. When set, it IS the
            member's identity-bearing :attr:`weights_uri` (the
            ``member://`` parameter-digest URI is a scripted-stratum
            device), the loading wrapper verifies the SHA-256 sidecar
            at load, and :attr:`checkpoint_sha256` commits the payload
            digest here for roster-level custody. ``None`` for the
            scripted stratum.
        checkpoint_sha256: Committed SHA-256 of the checkpoint payload
            (must match the ADR-002 sidecar); required iff
            ``checkpoint_uri`` is set.
        provenance: Free-text provenance line rendered on the member's
            card — mandatory content for jointly-trained members
            ("trained jointly with <ego hash>"; ADR-011 §Decision as
            amended).
    """

    model_config = ConfigDict(frozen=True, extra="forbid")

    member_name: str
    registry_class: str
    role: str
    split: SplitLabel
    seed: int = 0
    checkpoint_step: int | None = None
    param_box: dict[str, ParamRange]
    params: dict[str, str] | None
    params_sha256: str = Field(min_length=64, max_length=64)
    checkpoint_uri: str | None = None
    checkpoint_sha256: str | None = None
    provenance: str = ""

    @model_validator(mode="after")
    def _check_checkpoint(self) -> PartnerMemberSpec:
        """Enforce the learned-stratum custody invariants (ADR-027 §Versioning; ADR-018).

        A checkpoint-bearing member must commit the payload digest and
        its checkpoint step (both identity/custody anchors); a
        checkpoint digest without a URI is unanchored and refused.
        """
        if self.checkpoint_uri is not None:
            if self.checkpoint_sha256 is None or len(self.checkpoint_sha256) != 64:  # noqa: PLR2004 - SHA-256 hex length
                msg = (
                    f"member {self.member_name!r}: checkpoint_uri requires a 64-hex "
                    "checkpoint_sha256 (the committed payload digest; ADR-018 custody)"
                )
                raise ValueError(msg)
            if self.checkpoint_step is None:
                msg = (
                    f"member {self.member_name!r}: checkpoint_uri requires "
                    "checkpoint_step (the identity field; ADR-002 §Decisions)"
                )
                raise ValueError(msg)
        elif self.checkpoint_sha256 is not None:
            msg = (
                f"member {self.member_name!r}: checkpoint_sha256 without "
                "checkpoint_uri is unanchored custody"
            )
            raise ValueError(msg)
        return self

    @model_validator(mode="after")
    def _check_params(self) -> PartnerMemberSpec:
        """Enforce the split/withholding invariants (ADR-009 as amended; ADR-018)."""
        if self.split == "private":
            if self.params is not None:
                msg = (
                    f"member {self.member_name!r} is private but carries committed "
                    "parameter values — private parameters are withheld (I4 discipline)"
                )
                raise ValueError(msg)
            return self
        if self.params is None:
            msg = f"member {self.member_name!r} is public but carries no parameter values"
            raise ValueError(msg)
        if set(self.params) != set(self.param_box):
            msg = (
                f"member {self.member_name!r}: params keys {sorted(self.params)} != "
                f"param_box keys {sorted(self.param_box)}"
            )
            raise ValueError(msg)
        for key, raw in self.params.items():
            if not self.param_box[key].contains(raw):
                edge = self.param_box[key]
                msg = (
                    f"member {self.member_name!r}: params[{key!r}] = {raw!r} outside "
                    f"the committed box [{edge.lo}, {edge.hi}]"
                )
                raise ValueError(msg)
        digest = params_sha256(self.params)
        if digest != self.params_sha256:
            msg = (
                f"member {self.member_name!r}: committed params_sha256 "
                f"{self.params_sha256} != recomputed {digest}"
            )
            raise ValueError(msg)
        return self

    @property
    def weights_uri(self) -> str:
        """The identity-bearing URI (ADR-009 as amended; ADR-027 §Versioning).

        Scripted members ride on the ``member://`` parameter-digest URI;
        learned members ride on their real checkpoint URI (the loading
        wrapper dereferences it and verifies the sidecar SHA-256).
        """
        if self.checkpoint_uri is not None:
            return self.checkpoint_uri
        return member_weights_uri(self.registry_class, self.params_sha256)

    @property
    def partner_id(self) -> str:
        """The member's :attr:`~chamber.partners.api.PartnerSpec.partner_id` (ADR-006 risk #3).

        Computable for private members without their withheld
        parameters — identity rides on the committed digest, so the
        split rule, cards, and bundle custody hashes never need the
        parameter values themselves.
        """
        return self._identity_spec().partner_id

    def _identity_spec(self, extra: dict[str, str] | None = None) -> PartnerSpec:
        return PartnerSpec(
            class_name=self.registry_class,
            seed=self.seed,
            checkpoint_step=self.checkpoint_step,
            weights_uri=self.weights_uri,
            extra=extra or {},
        )

    def partner_spec(
        self,
        *,
        params: Mapping[str, str],
        seat_extra: Mapping[str, str] | None = None,
    ) -> PartnerSpec:
        """Build the loadable :class:`~chamber.partners.api.PartnerSpec` (ADR-009 §Decision).

        Args:
            params: The member's exact behavioural parameters — the
                committed literals for public members, or a
                digest-verified private reconstruction from
                :func:`resolve_member_params`. Verified against
                :attr:`params_sha256` here as well (defence in depth).
            seat_extra: Task-seat metadata (uid, base pose, action_dim
                …) supplied by the runner; identity-inert (``extra`` is
                excluded from the hash by design, plan/04 §3.1).

        Raises:
            WithheldParametersError: On a digest mismatch.
        """
        digest = params_sha256(params)
        if digest != self.params_sha256:
            msg = (
                f"member {self.member_name!r}: supplied parameters hash {digest}, "
                f"committed digest {self.params_sha256} — refusing to build a "
                "behaviourally-unverified member (ADR-018 custody)"
            )
            raise WithheldParametersError(msg)
        extra = dict(seat_extra or {})
        extra.update(compose_member_extra(self.registry_class, params))
        return self._identity_spec(extra)

partner_id property

partner_id: str

The member's :attr:~chamber.partners.api.PartnerSpec.partner_id (ADR-006 risk #3).

Computable for private members without their withheld parameters — identity rides on the committed digest, so the split rule, cards, and bundle custody hashes never need the parameter values themselves.

weights_uri property

weights_uri: str

The identity-bearing URI (ADR-009 as amended; ADR-027 §Versioning).

Scripted members ride on the member:// parameter-digest URI; learned members ride on their real checkpoint URI (the loading wrapper dereferences it and verifies the sidecar SHA-256).

partner_spec

partner_spec(
    *,
    params: Mapping[str, str],
    seat_extra: Mapping[str, str] | None = None,
) -> PartnerSpec

Build the loadable :class:~chamber.partners.api.PartnerSpec (ADR-009 §Decision).

Parameters:

• params (Mapping[str, str]) –

  The member's exact behavioural parameters — the committed literals for public members, or a digest-verified private reconstruction from :func:resolve_member_params. Verified against :attr:params_sha256 here as well (defence in depth).

• seat_extra (Mapping[str, str] | None, default: None ) –

  Task-seat metadata (uid, base pose, action_dim …) supplied by the runner; identity-inert (extra is excluded from the hash by design, plan/04 §3.1).

Raises:

• WithheldParametersError –

  On a digest mismatch.

Source code in src/chamber/partners/sets.py

def partner_spec(
    self,
    *,
    params: Mapping[str, str],
    seat_extra: Mapping[str, str] | None = None,
) -> PartnerSpec:
    """Build the loadable :class:`~chamber.partners.api.PartnerSpec` (ADR-009 §Decision).

    Args:
        params: The member's exact behavioural parameters — the
            committed literals for public members, or a
            digest-verified private reconstruction from
            :func:`resolve_member_params`. Verified against
            :attr:`params_sha256` here as well (defence in depth).
        seat_extra: Task-seat metadata (uid, base pose, action_dim
            …) supplied by the runner; identity-inert (``extra`` is
            excluded from the hash by design, plan/04 §3.1).

    Raises:
        WithheldParametersError: On a digest mismatch.
    """
    digest = params_sha256(params)
    if digest != self.params_sha256:
        msg = (
            f"member {self.member_name!r}: supplied parameters hash {digest}, "
            f"committed digest {self.params_sha256} — refusing to build a "
            "behaviourally-unverified member (ADR-018 custody)"
        )
        raise WithheldParametersError(msg)
    extra = dict(seat_extra or {})
    extra.update(compose_member_extra(self.registry_class, params))
    return self._identity_spec(extra)

PartnerSetSpec

Bases: BaseModel

A versioned per-task partner set (ADR-009 §Decision as amended; ADR-027 §Versioning).

Attributes:

• set_id (str) –

  Stable set identity (<task_id>_partners).

• version (int) –

  Set version; any membership or parameter change bumps it (ADR-027 §Versioning — CB-06's frozen learned members join as version+1; old bundles keep referencing the version they ran against).

• task_id (str) –

  The ADR-027 task the set serves.

• task_version (int) –

  The task version the set was built for.

• members (list[PartnerMemberSpec]) –

  The roster. Split assignments are validated against :func:compute_split at construction.

• floor (float) –

  Committed matched-pair success floor every member must clear with the reference ego on the floor probe before admission to the set (a member no ego can work with measures nothing — the co-insert Gate-0 lesson: a member that freezes is a wall, not a partner).

• floor_probe (Literal['fingerprint', 'free_regrasp']) –

  Which probe the floor is evaluated on. "fingerprint" — the fingerprint probe itself (co-carry, pick-place). "free_regrasp" — the same probe with the re-grasp budget removed (handover-place: the canonical-cell probe intentionally degrades mismatch members — that gap is the measured coupling, not incompetence — so competence is judged at the Gate-0 free-re-grasp endpoint where budget pressure is off and only a wall scores low).

• probe_seeds (list[int]) –

  Committed probe-suite cluster seeds (ADR-002 P6).

• probe_episodes_per_seed (int) –

  Episodes per probe seed (~20 total).

• notes (str) –

  Free-text provenance.

Source code in src/chamber/partners/sets.py

class PartnerSetSpec(BaseModel):
    """A versioned per-task partner set (ADR-009 §Decision as amended; ADR-027 §Versioning).

    Attributes:
        set_id: Stable set identity (``<task_id>_partners``).
        version: Set version; **any** membership or parameter change
            bumps it (ADR-027 §Versioning — CB-06's frozen learned
            members join as ``version+1``; old bundles keep referencing
            the version they ran against).
        task_id: The ADR-027 task the set serves.
        task_version: The task version the set was built for.
        members: The roster. Split assignments are validated against
            :func:`compute_split` at construction.
        floor: Committed matched-pair success floor every member must
            clear with the reference ego on the floor probe before
            admission to the set (a member no ego can work with
            measures nothing — the co-insert Gate-0 lesson: a member
            that freezes is a wall, not a partner).
        floor_probe: Which probe the floor is evaluated on.
            ``"fingerprint"`` — the fingerprint probe itself (co-carry,
            pick-place). ``"free_regrasp"`` — the same probe with the
            re-grasp budget removed (handover-place: the canonical-cell
            probe *intentionally* degrades mismatch members — that gap
            is the measured coupling, not incompetence — so competence
            is judged at the Gate-0 free-re-grasp endpoint where budget
            pressure is off and only a wall scores low).
        probe_seeds: Committed probe-suite cluster seeds (ADR-002 P6).
        probe_episodes_per_seed: Episodes per probe seed (~20 total).
        notes: Free-text provenance.
    """

    model_config = ConfigDict(frozen=True, extra="forbid")

    set_id: str
    version: int = Field(ge=1)
    task_id: str
    task_version: int
    members: list[PartnerMemberSpec] = Field(min_length=1)
    floor: float = Field(ge=0.0, le=1.0)
    floor_probe: Literal["fingerprint", "free_regrasp"] = "fingerprint"
    probe_seeds: list[int] = Field(min_length=1)
    probe_episodes_per_seed: int = Field(ge=1)
    notes: str = ""

    @model_validator(mode="after")
    def _check_roster(self) -> PartnerSetSpec:
        """Recompute the split rule and reject drift (ADR-009 as amended: no hand-picking)."""
        names = [m.member_name for m in self.members]
        if len(set(names)) != len(names):
            msg = f"set {self.set_id!r}: duplicate member_name in roster"
            raise ValueError(msg)
        expected = compute_split([m.partner_id for m in self.members])
        for member in self.members:
            if member.split != expected[member.partner_id]:
                msg = (
                    f"set {self.set_id!r}: member {member.member_name!r} committed as "
                    f"{member.split!r} but the deterministic split rule assigns "
                    f"{expected[member.partner_id]!r} (ADR-009 as amended: order by "
                    "partner_id, first ⌈0.7·N⌉ public — no hand-picking)"
                )
                raise ValueError(msg)
        return self

    @property
    def slug(self) -> str:
        """``set_id@vN`` — the versioned set handle (ADR-027 §Versioning)."""
        return f"{self.set_id}@v{self.version}"

    @property
    def public_members(self) -> list[PartnerMemberSpec]:
        """Roster order, public split only (ADR-009 as amended)."""
        return [m for m in self.members if m.split == "public"]

    @property
    def private_members(self) -> list[PartnerMemberSpec]:
        """Roster order, private split only (ADR-009 as amended)."""
        return [m for m in self.members if m.split == "private"]

private_members property

private_members: list[PartnerMemberSpec]

Roster order, private split only (ADR-009 as amended).

public_members property

public_members: list[PartnerMemberSpec]

Roster order, public split only (ADR-009 as amended).

slug property

slug: str

set_id@vN — the versioned set handle (ADR-027 §Versioning).

PartnerSpec dataclass

Identity-bearing spec used to build, load, and address a partner (ADR-009 §Decision).

The :attr:partner_id property is the stable hash that the M3 conformal filter reads on every step (ADR-004 §risk-mitigation #2; ADR-006 risk #3). Two specs that hash the same partner_id refer to the same logical partner; a partner-set change between steps re-initialises the conformal lambda.

Attributes:

• class_name (str) –

  Registry key — the string passed to :func:chamber.partners.registry.register_partner.

• seed (int) –

  Training-time seed; for scripted partners use 0.

• checkpoint_step (int | None) –

  Training step at which the checkpoint was taken; None for scripted partners or for stubs.

• weights_uri (str | None) –

  local:// or remote URI pointing at the frozen checkpoint; None for scripted partners.

• extra (dict[str, str]) –

  Free-form string→string dict for task / embodiment / uid metadata. Read by the partner implementation, NOT by the hash.

Source code in src/chamber/partners/api.py

@dataclass(frozen=True)
class PartnerSpec:
    """Identity-bearing spec used to build, load, and address a partner (ADR-009 §Decision).

    The :attr:`partner_id` property is the stable hash that the M3 conformal
    filter reads on every step (ADR-004 §risk-mitigation #2; ADR-006 risk #3).
    Two specs that hash the same partner_id refer to the same logical partner;
    a partner-set change between steps re-initialises the conformal ``lambda``.

    Attributes:
        class_name: Registry key — the string passed to
            :func:`chamber.partners.registry.register_partner`.
        seed: Training-time seed; for scripted partners use ``0``.
        checkpoint_step: Training step at which the checkpoint was taken;
            ``None`` for scripted partners or for stubs.
        weights_uri: ``local://`` or remote URI pointing at the frozen
            checkpoint; ``None`` for scripted partners.
        extra: Free-form string→string dict for task / embodiment / uid
            metadata. Read by the partner implementation, NOT by the hash.
    """

    class_name: str
    seed: int
    checkpoint_step: int | None
    weights_uri: str | None
    extra: dict[str, str] = field(default_factory=dict)

    @property
    def partner_id(self) -> str:
        """Stable 16-hex-char hash of ``(class_name, seed, checkpoint_step, weights_uri)``.

        ADR-004 §risk-mitigation #2 / ADR-006 risk #3: surfaced on
        ``obs["meta"]["partner_id"]`` so the conformal filter can re-initialise
        ``lambda`` on partner identity change. The 16-char (64-bit) keyspace
        is sufficient for the Phase-1 zoo target of 144 partners with vast
        margin (plan/04 §8 Notes).

        The hash material uses :func:`repr` of a tuple of the four identity
        fields (in this fixed order) rather than f-string interpolation so
        ``None`` cannot collide with the literal string ``"None"`` — a real
        risk if a Phase-1 partner ever ships with ``weights_uri="None"``
        (ADR-006 risk #3 swap-detection contract). Reordering the fields
        in :class:`PartnerSpec` would silently change every existing
        partner_id; do not reorder without a new ADR.

        Returns:
            Lowercase 16-character hex digest of the SHA-256 of
            ``repr((class_name, seed, checkpoint_step, weights_uri))``.
            ``extra`` is intentionally excluded so per-task / per-embodiment
            metadata does not collide with the conformal filter's
            swap-detection contract (plan/04 §3.1).
        """
        material = repr((self.class_name, self.seed, self.checkpoint_step, self.weights_uri))
        return hashlib.sha256(material.encode("utf-8")).hexdigest()[:16]

partner_id property

partner_id: str

Stable 16-hex-char hash of (class_name, seed, checkpoint_step, weights_uri).

ADR-004 §risk-mitigation #2 / ADR-006 risk #3: surfaced on obs["meta"]["partner_id"] so the conformal filter can re-initialise lambda on partner identity change. The 16-char (64-bit) keyspace is sufficient for the Phase-1 zoo target of 144 partners with vast margin (plan/04 §8 Notes).

The hash material uses :func:repr of a tuple of the four identity fields (in this fixed order) rather than f-string interpolation so None cannot collide with the literal string "None" — a real risk if a Phase-1 partner ever ships with weights_uri="None" (ADR-006 risk #3 swap-detection contract). Reordering the fields in :class:PartnerSpec would silently change every existing partner_id; do not reorder without a new ADR.

Returns:

• str –

  Lowercase 16-character hex digest of the SHA-256 of

• str –

  repr((class_name, seed, checkpoint_step, weights_uri)).

• str –

  extra is intentionally excluded so per-task / per-embodiment

• str –

  metadata does not collide with the conformal filter's

• str –

  swap-detection contract (plan/04 §3.1).

ScriptedHeuristicPartner

Bases: PartnerBase

Greedy planar-reach heuristic partner (ADR-009 §Consequences; plan/04 §3.4).

Reads the partner's own xy from obs["comm"]["pose"][uid]["xyz"] (ADR-003 §Decision) when available, else from obs["agent"][uid]["state"][:2]. Outputs a unit-clipped xy velocity toward the configured target xy.

The partner's own uid is read from spec.extra["uid"] and the target from spec.extra["target_xy"] (default "0.0,0.0"). Action dim is set via spec.extra["action_dim"] (default "2"); components beyond the planar xy are zeroed.

Source code in src/chamber/partners/heuristic.py

@register_partner("scripted_heuristic")
class ScriptedHeuristicPartner(PartnerBase):
    """Greedy planar-reach heuristic partner (ADR-009 §Consequences; plan/04 §3.4).

    Reads the partner's own xy from ``obs["comm"]["pose"][uid]["xyz"]`` (ADR-003
    §Decision) when available, else from ``obs["agent"][uid]["state"][:2]``.
    Outputs a unit-clipped xy velocity toward the configured target xy.

    The partner's own uid is read from ``spec.extra["uid"]`` and the target
    from ``spec.extra["target_xy"]`` (default ``"0.0,0.0"``). Action dim is
    set via ``spec.extra["action_dim"]`` (default ``"2"``); components beyond
    the planar xy are zeroed.
    """

    def __init__(self, spec: PartnerSpec) -> None:
        """Bind the spec and parse the heuristic's tunables (ADR-009 §Decision).

        Args:
            spec: Partner identity. ``spec.extra`` controls the policy:
                ``uid`` selects the env-side agent, ``target_xy`` the goal,
                ``action_dim`` the output vector length.

        Raises:
            ValueError: If ``spec.extra["target_xy"]`` is malformed or
                ``action_dim`` is not a positive integer ≥ 2.
        """
        super().__init__(spec)
        self._uid: str = spec.extra.get("uid", "")
        self._target_xy: tuple[float, float] = _parse_xy(spec.extra.get("target_xy", "0.0,0.0"))
        action_dim_raw = spec.extra.get("action_dim", "2")
        try:
            action_dim = int(action_dim_raw)
        except ValueError as exc:
            raise ValueError(
                f"action_dim must be a positive int ≥ 2; got {action_dim_raw!r}"
            ) from exc
        if action_dim < _MIN_ACTION_DIM:
            raise ValueError(f"action_dim must be a positive int ≥ 2; got {action_dim}")
        self._action_dim: int = action_dim

    def reset(self, *, seed: int | None = None) -> None:
        """No-op reset (ADR-009 §Decision; plan/04 §2 stateless across episodes).

        Phase-0 heuristic carries no episode state. The seed is ignored
        deliberately; the policy is fully deterministic from ``obs``.

        Args:
            seed: Accepted for Protocol conformance only.
        """
        del seed

    def act(
        self,
        obs: Mapping[str, object],
        *,
        deterministic: bool = True,
    ) -> NDArray[np.floating]:
        """Greedy planar-reach action toward ``spec.extra["target_xy"]`` (ADR-009 §Consequences).

        Args:
            obs: Gymnasium observation mapping keyed by ``"agent"`` and
                optionally ``"comm"``. ADR-003 §Decision: when ``"comm"`` is
                present, pose is read from ``obs["comm"]["pose"][uid]``.
            deterministic: Ignored; the heuristic is deterministic regardless.

        Returns:
            Float32 action vector of length ``spec.extra["action_dim"]``;
            components 0/1 hold the unit-clipped xy velocity toward target,
            remaining components are zero.
        """
        del deterministic
        batched_xy = self._read_agent_xy_batched(obs)
        if batched_xy is not None:
            # P1.05.10 (ADR-007 §Stage 1b regime-alignment): vectorised
            # cells emit per-uid state as (num_envs, dim); the heuristic
            # returns (num_envs, action_dim) so the batched env step
            # receives one planar-reach command per env. The policy per
            # env is identical to the single-env path.
            tx, ty = self._target_xy
            n = batched_xy.shape[0]
            action_b = np.zeros((n, self._action_dim), dtype=np.float32)
            action_b[:, 0] = np.clip(tx - batched_xy[:, 0], -_ACTION_CLIP, _ACTION_CLIP)
            action_b[:, 1] = np.clip(ty - batched_xy[:, 1], -_ACTION_CLIP, _ACTION_CLIP)
            return action_b
        x, y = self._read_agent_xy(obs)
        tx, ty = self._target_xy
        dx = float(np.clip(tx - x, -_ACTION_CLIP, _ACTION_CLIP))
        dy = float(np.clip(ty - y, -_ACTION_CLIP, _ACTION_CLIP))
        action = np.zeros(self._action_dim, dtype=np.float32)
        action[0] = dx
        action[1] = dy
        return action

    def _read_agent_xy_batched(self, obs: Mapping[str, object]) -> NDArray[np.floating] | None:
        """Return the partner's planar xy as ``(num_envs, 2)``, or ``None`` (ADR-007 §Stage 1b).

        P1.05.10: detects the vectorised-cell obs layout — a 2-D
        ``obs["agent"][uid]["state"]`` of shape ``(num_envs, dim)``
        with ``num_envs > 1`` — and returns its first two columns.
        Returns ``None`` for the single-env layout (1-D state or
        ``shape[0] == 1`` is still routed through the historical
        scalar path so pre-P1.05.10 behaviour is byte-identical).
        Torch tensors are accepted (ManiSkill GPU obs) and moved to
        numpy.
        """
        agent = obs.get("agent")
        if not isinstance(agent, Mapping) or self._uid not in agent:
            return None
        entry = agent[self._uid]
        if not isinstance(entry, Mapping):
            return None
        state = entry.get("state")
        if state is None:
            return None
        if hasattr(state, "detach"):
            state = state.detach().cpu().numpy()  # type: ignore[union-attr]
        if not isinstance(state, np.ndarray):
            return None
        if state.ndim == 2 and state.shape[0] > 1 and state.shape[1] >= _XY_DIMS:  # noqa: PLR2004 - rank-2 is the (batch, dim) layout
            return state[:, :_XY_DIMS].astype(np.float64)
        return None

    def _read_agent_xy(self, obs: Mapping[str, object]) -> tuple[float, float]:
        """Extract the partner's planar xy from ``obs`` (ADR-003 §Decision).

        Reads ``obs["comm"]["pose"][uid]["xyz"]`` when present (the M2
        fixed-format channel surface), falling back to
        ``obs["agent"][uid]["state"][:2]`` for envs without comm wired up
        (e.g. the unit-test :class:`tests.fakes.FakeMultiAgentEnv`).

        Args:
            obs: Gymnasium observation mapping.

        Returns:
            ``(x, y)`` tuple of Python floats.
        """
        comm = obs.get("comm")
        if isinstance(comm, Mapping):
            pose_table = comm.get("pose")
            if isinstance(pose_table, Mapping) and self._uid in pose_table:
                pose = pose_table[self._uid]
                if isinstance(pose, Mapping):
                    xyz = pose.get("xyz")
                    if isinstance(xyz, (tuple, list)) and len(xyz) >= _XY_DIMS:
                        return float(xyz[0]), float(xyz[1])
        agent = obs.get("agent")
        if isinstance(agent, Mapping) and self._uid in agent:
            entry = agent[self._uid]
            if isinstance(entry, Mapping):
                state = entry.get("state")
                if isinstance(state, np.ndarray) and state.shape[0] >= _XY_DIMS:
                    arr = cast("NDArray[np.floating]", state)
                    return float(arr[0]), float(arr[1])
        return 0.0, 0.0

__init__

__init__(spec: PartnerSpec) -> None

Bind the spec and parse the heuristic's tunables (ADR-009 §Decision).

Parameters:

• spec (PartnerSpec) –

  Partner identity. spec.extra controls the policy: uid selects the env-side agent, target_xy the goal, action_dim the output vector length.

Raises:

• ValueError –

  If spec.extra["target_xy"] is malformed or action_dim is not a positive integer ≥ 2.

Source code in src/chamber/partners/heuristic.py

def __init__(self, spec: PartnerSpec) -> None:
    """Bind the spec and parse the heuristic's tunables (ADR-009 §Decision).

    Args:
        spec: Partner identity. ``spec.extra`` controls the policy:
            ``uid`` selects the env-side agent, ``target_xy`` the goal,
            ``action_dim`` the output vector length.

    Raises:
        ValueError: If ``spec.extra["target_xy"]`` is malformed or
            ``action_dim`` is not a positive integer ≥ 2.
    """
    super().__init__(spec)
    self._uid: str = spec.extra.get("uid", "")
    self._target_xy: tuple[float, float] = _parse_xy(spec.extra.get("target_xy", "0.0,0.0"))
    action_dim_raw = spec.extra.get("action_dim", "2")
    try:
        action_dim = int(action_dim_raw)
    except ValueError as exc:
        raise ValueError(
            f"action_dim must be a positive int ≥ 2; got {action_dim_raw!r}"
        ) from exc
    if action_dim < _MIN_ACTION_DIM:
        raise ValueError(f"action_dim must be a positive int ≥ 2; got {action_dim}")
    self._action_dim: int = action_dim

act

act(
    obs: Mapping[str, object], *, deterministic: bool = True
) -> NDArray[np.floating]

Greedy planar-reach action toward spec.extra["target_xy"] (ADR-009 §Consequences).

Parameters:

• obs (Mapping[str, object]) –

  Gymnasium observation mapping keyed by "agent" and optionally "comm". ADR-003 §Decision: when "comm" is present, pose is read from obs["comm"]["pose"][uid].

• deterministic (bool, default: True ) –

  Ignored; the heuristic is deterministic regardless.

Returns:

• NDArray[floating] –

  Float32 action vector of length spec.extra["action_dim"];

• NDArray[floating] –

  components 0/1 hold the unit-clipped xy velocity toward target,

• NDArray[floating] –

  remaining components are zero.

Source code in src/chamber/partners/heuristic.py

def act(
    self,
    obs: Mapping[str, object],
    *,
    deterministic: bool = True,
) -> NDArray[np.floating]:
    """Greedy planar-reach action toward ``spec.extra["target_xy"]`` (ADR-009 §Consequences).

    Args:
        obs: Gymnasium observation mapping keyed by ``"agent"`` and
            optionally ``"comm"``. ADR-003 §Decision: when ``"comm"`` is
            present, pose is read from ``obs["comm"]["pose"][uid]``.
        deterministic: Ignored; the heuristic is deterministic regardless.

    Returns:
        Float32 action vector of length ``spec.extra["action_dim"]``;
        components 0/1 hold the unit-clipped xy velocity toward target,
        remaining components are zero.
    """
    del deterministic
    batched_xy = self._read_agent_xy_batched(obs)
    if batched_xy is not None:
        # P1.05.10 (ADR-007 §Stage 1b regime-alignment): vectorised
        # cells emit per-uid state as (num_envs, dim); the heuristic
        # returns (num_envs, action_dim) so the batched env step
        # receives one planar-reach command per env. The policy per
        # env is identical to the single-env path.
        tx, ty = self._target_xy
        n = batched_xy.shape[0]
        action_b = np.zeros((n, self._action_dim), dtype=np.float32)
        action_b[:, 0] = np.clip(tx - batched_xy[:, 0], -_ACTION_CLIP, _ACTION_CLIP)
        action_b[:, 1] = np.clip(ty - batched_xy[:, 1], -_ACTION_CLIP, _ACTION_CLIP)
        return action_b
    x, y = self._read_agent_xy(obs)
    tx, ty = self._target_xy
    dx = float(np.clip(tx - x, -_ACTION_CLIP, _ACTION_CLIP))
    dy = float(np.clip(ty - y, -_ACTION_CLIP, _ACTION_CLIP))
    action = np.zeros(self._action_dim, dtype=np.float32)
    action[0] = dx
    action[1] = dy
    return action

reset

reset(*, seed: int | None = None) -> None

No-op reset (ADR-009 §Decision; plan/04 §2 stateless across episodes).

Phase-0 heuristic carries no episode state. The seed is ignored deliberately; the policy is fully deterministic from obs.

Parameters:

• seed (int | None, default: None ) –

  Accepted for Protocol conformance only.

Source code in src/chamber/partners/heuristic.py

def reset(self, *, seed: int | None = None) -> None:
    """No-op reset (ADR-009 §Decision; plan/04 §2 stateless across episodes).

    Phase-0 heuristic carries no episode state. The seed is ignored
    deliberately; the policy is fully deterministic from ``obs``.

    Args:
        seed: Accepted for Protocol conformance only.
    """
    del seed

WithheldParametersError

Bases: RuntimeError

Private-member parameters requested but not available/verified (ADR-009 as amended).

Raised when the maintainer-held seed (:data:PRIVATE_PARAMS_ENV) is absent or malformed, or when a locally-derived reconstruction fails its committed SHA-256 digest check (wrong seed — never silently build a behaviourally-wrong private member).

Source code in src/chamber/partners/sets.py

class WithheldParametersError(RuntimeError):
    """Private-member parameters requested but not available/verified (ADR-009 as amended).

    Raised when the maintainer-held seed (:data:`PRIVATE_PARAMS_ENV`) is
    absent or malformed, or when a locally-derived reconstruction fails
    its committed SHA-256 digest check (wrong seed — never silently
    build a behaviourally-wrong private member).
    """

compute_split

compute_split(
    partner_ids: Sequence[str],
) -> dict[str, SplitLabel]

The deterministic public/private split rule (ADR-009 §Decision as amended 2026-07-05).

Order members by partner_id hash (ascending lexicographic) and assign the first ⌈0.7·N⌉ to public — no hand-picking. Pure function of the committed hashes, so anyone can recompute the split from a set's published roster; registration enforces agreement.

Raises:

• ValueError –

  On duplicate partner_id hashes (two members may not share an identity).

Source code in src/chamber/partners/sets.py

def compute_split(partner_ids: Sequence[str]) -> dict[str, SplitLabel]:
    """The deterministic public/private split rule (ADR-009 §Decision as amended 2026-07-05).

    Order members by ``partner_id`` hash (ascending lexicographic) and
    assign the first ``⌈0.7·N⌉`` to public — no hand-picking. Pure
    function of the committed hashes, so anyone can recompute the split
    from a set's published roster; registration enforces agreement.

    Raises:
        ValueError: On duplicate ``partner_id`` hashes (two members may
            not share an identity).
    """
    ids = list(partner_ids)
    if len(set(ids)) != len(ids):
        msg = "compute_split requires distinct partner_id hashes"
        raise ValueError(msg)
    n_public = public_member_count(len(ids))
    ordered = sorted(ids)
    return {pid: ("public" if i < n_public else "private") for i, pid in enumerate(ordered)}

get_partner_set

get_partner_set(
    set_id: str, version: int | None = None
) -> PartnerSetSpec

Look up a registered set (ADR-027 §Versioning; ADR-009 §Decision error style).

version=None resolves to the latest registered version. Unknown ids/versions raise KeyError listing the known keys.

Source code in src/chamber/partners/sets.py

def get_partner_set(set_id: str, version: int | None = None) -> PartnerSetSpec:
    """Look up a registered set (ADR-027 §Versioning; ADR-009 §Decision error style).

    ``version=None`` resolves to the latest registered version. Unknown
    ids/versions raise ``KeyError`` listing the known keys.
    """
    versions = _SET_REGISTRY.get(set_id)
    if versions is None:
        known = ", ".join(sorted(_SET_REGISTRY)) or "<none>"
        msg = f"unknown partner-set id {set_id!r}; registered set ids: {known}"
        raise KeyError(msg)
    if version is None:
        version = max(versions)
    if version not in versions:
        known_versions = ", ".join(str(v) for v in sorted(versions))
        msg = (
            f"unknown version {version} for partner set {set_id!r}; "
            f"registered versions: {known_versions}"
        )
        raise KeyError(msg)
    return versions[version]

list_partner_sets

list_partner_sets() -> list[str]

Sorted set_id@vN slugs of every registered set version (ADR-027 §Versioning).

Source code in src/chamber/partners/sets.py

def list_partner_sets() -> list[str]:
    """Sorted ``set_id@vN`` slugs of every registered set version (ADR-027 §Versioning)."""
    return sorted(spec.slug for versions in _SET_REGISTRY.values() for spec in versions.values())

list_registered

list_registered() -> list[str]

Return the sorted list of registered partner class names (ADR-009 §Decision).

Used by the eval CLI to enumerate the available zoo strata and by tests to assert the Phase-0 draft zoo classes are wired up.

Returns:

• list[str] –

  A new list, freshly sorted on every call.

Source code in src/chamber/partners/registry.py

def list_registered() -> list[str]:
    """Return the sorted list of registered partner class names (ADR-009 §Decision).

    Used by the eval CLI to enumerate the available zoo strata and by tests
    to assert the Phase-0 draft zoo classes are wired up.

    Returns:
        A new list, freshly sorted on every call.
    """
    return sorted(_REGISTRY.keys())

load_partner

load_partner(spec: PartnerSpec) -> FrozenPartner

Build a partner instance from its spec via the registry (ADR-009 §Decision).

Parameters:

• spec (PartnerSpec) –

  The :class:~chamber.partners.api.PartnerSpec whose :attr:~chamber.partners.api.PartnerSpec.class_name selects the registered class.

Returns:

• FrozenPartner –

  A fresh :class:~chamber.partners.api.FrozenPartner instance built

• FrozenPartner –

  by Class(spec).

Raises:

• KeyError –

  If spec.class_name is not registered. The error message lists the currently-registered keys to make typos easy to fix.

Source code in src/chamber/partners/registry.py

def load_partner(spec: PartnerSpec) -> FrozenPartner:
    """Build a partner instance from its spec via the registry (ADR-009 §Decision).

    Args:
        spec: The :class:`~chamber.partners.api.PartnerSpec` whose
            :attr:`~chamber.partners.api.PartnerSpec.class_name` selects the
            registered class.

    Returns:
        A fresh :class:`~chamber.partners.api.FrozenPartner` instance built
        by ``Class(spec)``.

    Raises:
        KeyError: If ``spec.class_name`` is not registered. The error message
            lists the currently-registered keys to make typos easy to fix.
    """
    if spec.class_name not in _REGISTRY:
        known = ", ".join(sorted(_REGISTRY.keys())) or "<none>"
        raise KeyError(f"No partner class registered as {spec.class_name!r}; known: {known}")
    cls = _REGISTRY[spec.class_name]
    # ``FrozenPartner`` is a Protocol without a constructor signature, so
    # pyright cannot prove ``cls(spec)`` is well-typed. The registry's
    # contract (plan/04 §3.2) is that every registered class accepts
    # ``__init__(self, spec: PartnerSpec)`` — :class:`PartnerBase` enforces
    # this. Do NOT widen the Protocol with ``__init__`` to silence this.
    return cls(spec)  # type: ignore[call-arg]

make_phase0_draft_zoo

make_phase0_draft_zoo() -> list[PartnerSpec]

Return the 3-partner Stage-3 draft zoo (ADR-009 §Consequences "draft-zoo scoping").

The draft zoo is the minimum viable zoo that lets the ADR-007 rev-3 Stage-3 PF spike measure trained-with vs frozen-novel ≥20pp gap and instrument the partner-swap λ-reset transient (ADR-006 risk #3 / ADR-004 §risk-mitigation #2). All three specs target the Stage-0 smoke task so they share an env shape; the per-partner uid matches the ADR-001 smoke robot tuple (panda_wristcam / fetch / allegro_hand_right).

The frozen-RL checkpoint URIs (local://artifacts/...) are produced by M4b training runs. Both :class:~chamber.partners.frozen_mappo.FrozenMAPPOPartner (T4.5, registered as frozen_mappo) and :class:~chamber.partners.frozen_harl.FrozenHARLPartner (T4.6, registered as frozen_harl) load their specs via :func:chamber.partners.registry.load_partner. The full M4 gate (plan/04 §6 #1, T4.9 draft-zoo round-trip integration test) lands in a follow-up PR.

Returns:

• list[PartnerSpec] –

  A fresh list of 3 :class:~chamber.partners.api.PartnerSpec

• list[PartnerSpec] –

  instances. Callers may append to the list freely; the function

• list[PartnerSpec] –

  rebuilds it every time so the canonical zoo is immutable.

Source code in src/chamber/partners/selection.py

def make_phase0_draft_zoo() -> list[PartnerSpec]:
    """Return the 3-partner Stage-3 draft zoo (ADR-009 §Consequences "draft-zoo scoping").

    The draft zoo is the minimum viable zoo that lets the ADR-007 rev-3
    Stage-3 PF spike measure trained-with vs frozen-novel ≥20pp gap and
    instrument the partner-swap λ-reset transient (ADR-006 risk #3 / ADR-004
    §risk-mitigation #2). All three specs target the Stage-0 smoke task so
    they share an env shape; the per-partner ``uid`` matches the ADR-001
    smoke robot tuple (panda_wristcam / fetch / allegro_hand_right).

    The frozen-RL checkpoint URIs (``local://artifacts/...``) are produced
    by M4b training runs. Both
    :class:`~chamber.partners.frozen_mappo.FrozenMAPPOPartner` (T4.5,
    registered as ``frozen_mappo``) and
    :class:`~chamber.partners.frozen_harl.FrozenHARLPartner` (T4.6,
    registered as ``frozen_harl``) load their specs via
    :func:`chamber.partners.registry.load_partner`. The full M4 gate
    (plan/04 §6 #1, T4.9 draft-zoo round-trip integration test) lands in
    a follow-up PR.

    Returns:
        A fresh list of 3 :class:`~chamber.partners.api.PartnerSpec`
        instances. Callers may append to the list freely; the function
        rebuilds it every time so the canonical zoo is immutable.
    """
    return [
        PartnerSpec(
            class_name="scripted_heuristic",
            seed=0,
            checkpoint_step=None,
            weights_uri=None,
            extra={
                "uid": "fetch",
                "task": "stage0_smoke",
                "target_xy": "0.0,0.0",
                "action_dim": "2",
            },
        ),
        PartnerSpec(
            class_name="frozen_mappo",
            seed=42,
            checkpoint_step=100_000,
            weights_uri="local://artifacts/mappo_seed42_step100k.pt",
            extra={
                "uid": "panda_wristcam",
                "task": "stage0_smoke",
            },
        ),
        PartnerSpec(
            class_name="frozen_harl",
            seed=7,
            checkpoint_step=50_000,
            weights_uri="local://artifacts/happo_seed7_step50k.pt",
            extra={
                "uid": "allegro_hand_right",
                "task": "stage0_smoke",
                "checkpoint_tier": "50pct_reward",
            },
        ),
    ]

register_partner

register_partner(
    class_name: str,
) -> Callable[[type[T]], type[T]]

Register a partner class by name (ADR-009 §Decision; plan/04 §3.2).

Used as a class decorator:

.. code-block:: python

@register_partner("scripted_heuristic")
class ScriptedHeuristicPartner(PartnerBase): ...

Parameters:

• class_name (str) –

  Registry key. Must be unique process-wide; re-registering the same key raises :class:ValueError so name collisions are caught at import time.

Returns:

• Callable[[type[T]], type[T]] –

  A decorator that records the class against class_name and returns

• Callable[[type[T]], type[T]] –

  the class unchanged.

Raises:

• ValueError –

  If class_name is already registered.

Source code in src/chamber/partners/registry.py

def register_partner(class_name: str) -> Callable[[type[T]], type[T]]:
    """Register a partner class by name (ADR-009 §Decision; plan/04 §3.2).

    Used as a class decorator:

    .. code-block:: python

        @register_partner("scripted_heuristic")
        class ScriptedHeuristicPartner(PartnerBase): ...

    Args:
        class_name: Registry key. Must be unique process-wide; re-registering
            the same key raises :class:`ValueError` so name collisions are
            caught at import time.

    Returns:
        A decorator that records the class against ``class_name`` and returns
        the class unchanged.

    Raises:
        ValueError: If ``class_name`` is already registered.
    """

    def _decorator(cls: type[T]) -> type[T]:
        if class_name in _REGISTRY:
            raise ValueError(f"Partner class {class_name!r} is already registered")
        _REGISTRY[class_name] = cls
        return cls

    return _decorator

register_partner_set

register_partner_set(
    builder: Callable[[], PartnerSetSpec],
) -> Callable[[], PartnerSetSpec]

Register the set returned by builder (ADR-027 §Versioning; ADR-009 registry style).

Decorator over a zero-argument builder; the spec is built (running the split-rule validation) and registered eagerly. Re-registering an existing set_id@vN raises ValueError — a changed set must bump its version, never overwrite (ADR-027 §Versioning).

Source code in src/chamber/partners/sets.py

def register_partner_set(
    builder: Callable[[], PartnerSetSpec],
) -> Callable[[], PartnerSetSpec]:
    """Register the set returned by ``builder`` (ADR-027 §Versioning; ADR-009 registry style).

    Decorator over a zero-argument builder; the spec is built (running
    the split-rule validation) and registered eagerly. Re-registering an
    existing ``set_id@vN`` raises ``ValueError`` — a changed set must
    bump its version, never overwrite (ADR-027 §Versioning).
    """
    spec = builder()
    versions = _SET_REGISTRY.setdefault(spec.set_id, {})
    if spec.version in versions:
        msg = f"partner set {spec.slug!r} is already registered"
        raise ValueError(msg)
    versions[spec.version] = spec
    return builder

resolve_set_members

resolve_set_members(
    set_spec: PartnerSetSpec,
    *,
    include_private: bool = False,
) -> list[tuple[PartnerMemberSpec, dict[str, str]]]

Resolve the runnable roster with exact parameters (ADR-009 as amended).

Public members only by default (the shipped evaluation surface); include_private=True adds private members and therefore requires the withheld parameters to be derivable locally (:func:resolve_member_params).

Returns:

• list[tuple[PartnerMemberSpec, dict[str, str]]] –

  (member, params) pairs in roster order.

Raises:

• WithheldParametersError –

  include_private without the maintainer-held seed, or on any digest mismatch.

Source code in src/chamber/partners/sets.py

def resolve_set_members(
    set_spec: PartnerSetSpec,
    *,
    include_private: bool = False,
) -> list[tuple[PartnerMemberSpec, dict[str, str]]]:
    """Resolve the runnable roster with exact parameters (ADR-009 as amended).

    Public members only by default (the shipped evaluation surface);
    ``include_private=True`` adds private members and therefore
    requires the withheld parameters to be derivable locally
    (:func:`resolve_member_params`).

    Returns:
        ``(member, params)`` pairs in roster order.

    Raises:
        WithheldParametersError: ``include_private`` without the
            maintainer-held seed, or on any digest mismatch.
    """
    selected = set_spec.members if include_private else set_spec.public_members
    return [(member, resolve_member_params(set_spec, member)) for member in selected]

select_zoo

select_zoo(*args: object, **kwargs: object) -> NoReturn

FCP/MEP-style zoo construction — Phase-1 stub (ADR-009 §Decision).

The Phase-1 implementation is the three-axis pipeline (policy class x seed x checkpoint) with MEP Population Entropy as the per-stratum admission filter (ADR-009 §Validation criteria "By Phase-1 end").

Parameters:

• *args (object, default: () ) –

  Reserved for the Phase-1 signature.

• **kwargs (object, default: {} ) –

  Reserved for the Phase-1 signature.

Raises:

• NotImplementedError –

  Always. Phase-0 callers must use :func:make_phase0_draft_zoo instead.

Source code in src/chamber/partners/selection.py

def select_zoo(*args: object, **kwargs: object) -> NoReturn:
    """FCP/MEP-style zoo construction — Phase-1 stub (ADR-009 §Decision).

    The Phase-1 implementation is the three-axis pipeline (policy class x
    seed x checkpoint) with MEP Population Entropy as the per-stratum
    admission filter (ADR-009 §Validation criteria "By Phase-1 end").

    Args:
        *args: Reserved for the Phase-1 signature.
        **kwargs: Reserved for the Phase-1 signature.

    Raises:
        NotImplementedError: Always. Phase-0 callers must use
            :func:`make_phase0_draft_zoo` instead.
    """
    del args, kwargs
    raise NotImplementedError(
        "Phase-1 work; see ADR-009 §Validation criteria 'By Phase-1 end' for "
        "the FCP/MEP-style construction protocol with Population Entropy "
        "admission filter. Phase-0 callers should use make_phase0_draft_zoo()."
    )

chamber.evaluation

CHAMBER evaluation harness — HRS bundle, leaderboard, safety reports.

Implements the HRS bundle composition (Option D, axis-survival rule) from ADR-008 and consumes the three-table safety reporting format from ADR-014. Statistical tooling (cluster + paired-cluster bootstrap) and the pre-registration discipline (ADR-007 §Discipline) live in sub-modules of this package.

Public modules:

• :mod:chamber.evaluation.results — Pydantic schema for spike runs and leaderboard entries (ADR-008 §Decision).
• :mod:chamber.evaluation.prereg — YAML loader + git-tag SHA verification (ADR-007 §Discipline).
• :mod:chamber.evaluation.bootstrap — cluster + paired-cluster bootstrap with rliable-compatible aggregate metrics (ADR-008 §Decision; reviewer P1-9).
• :mod:chamber.evaluation.hrs — HRS vector + scalar (ADR-008 §Decision; reviewer P1-8).
• :mod:chamber.evaluation.render — three-table safety report + leaderboard renderers (ADR-014 §Decision, ADR-008 §Decision).

AdmissionCellSpec

Bases: BaseModel

One measured admission cell — a policy/partner configuration (ADR-027 §Admission protocol).

Attributes:

• cell_id (str) –

  Archive-stable cell name (becomes the bundle directory name, e.g. a1_reference).

• runner (str) –

  Key into the cell-runner registry (:data:chamber.benchmarks.admission_cells.CELL_RUNNERS); resolved lazily so this module stays Tier-1-importable (ADR-001 §Risks / P2).

• policy_id (str) –

  Ego policy identity recorded in the cell's bundle (ADR-011 baseline ids; e.g. ref_script, b_blind).

• partner_name (str) –

  Partner registry name for the partner seat (ADR-009 §Decision; recorded with its identity hash, ADR-028 §Decision 1).

• params (dict[str, Any]) –

  Runner-specific committed parameters (condition ids, env overrides). Frozen by the prereg tag blob.

Source code in src/chamber/evaluation/admission.py

class AdmissionCellSpec(BaseModel):
    """One measured admission cell — a policy/partner configuration (ADR-027 §Admission protocol).

    Attributes:
        cell_id: Archive-stable cell name (becomes the bundle directory
            name, e.g. ``a1_reference``).
        runner: Key into the cell-runner registry
            (:data:`chamber.benchmarks.admission_cells.CELL_RUNNERS`);
            resolved lazily so this module stays Tier-1-importable
            (ADR-001 §Risks / P2).
        policy_id: Ego policy identity recorded in the cell's bundle
            (ADR-011 baseline ids; e.g. ``ref_script``, ``b_blind``).
        partner_name: Partner registry name for the partner seat
            (ADR-009 §Decision; recorded with its identity hash,
            ADR-028 §Decision 1).
        params: Runner-specific committed parameters (condition ids,
            env overrides). Frozen by the prereg tag blob.
    """

    model_config = ConfigDict(frozen=True, extra="forbid")

    cell_id: str
    runner: str
    policy_id: str
    partner_name: str
    params: dict[str, Any] = Field(default_factory=dict)

AdmissionError

Bases: RuntimeError

Raised when an admission run cannot proceed (ADR-027 §Admission protocol).

Source code in src/chamber/evaluation/admission.py

class AdmissionError(RuntimeError):
    """Raised when an admission run cannot proceed (ADR-027 §Admission protocol)."""

AdmissionReport

Bases: BaseModel

The committed admission report — the Tier-2 entry evidence (ADR-027 §Admission protocol).

Attributes:

• schema_version (int) –

  :data:ADMISSION_REPORT_SCHEMA_VERSION.

• task_id (str) –

  Task under admission.

• task_version (int) –

  Task version.

• prereg_git_tag (str) –

  Verified pre-registration tag (ADR-007 §Discipline).

• prereg_blob_sha (str) –

  Verified prereg blob SHA at the tag.

• git_sha (str) –

  Launch commit (ADR-028 §Decision 1 provenance).

• dirty (bool) –

  Whether the working tree was dirty at run time (a dirty report is never registry-flip evidence — mirrors ADR-028 §Rev 2026-07-05).

• date_stamp (str) –

  Caller-supplied date label of the archive (<task_id>-<date>); passed in, never sampled, so the report stays deterministic (ADR-002 P6).

• checks (list[CheckReport]) –

  Per-check reports in A1/A2/A3/A4 order (A4 present only for instrument-based contrasts); a NOT_SOLVABLE short-circuit records A1 only.

• verdict (AdmissionVerdict) –

  Overall verdict (ADR-027 §Admission protocol).

• seed_extension_used (bool) –

  Whether any check consumed the single pre-committed extension.

• binding_evidence (dict[str, float]) –

  The A2 coupling-binding evidence — the stress distribution on matched successful episodes (ADR-026 §Decision 2 positive-control).

• ego_robustness_profile (dict[str, dict[str, float]] | None) –

  The A4 mandatory reported artifact (ADR-027 §Admission A4): admitted-set member name → the instrument's success point + CI + stress percentiles with that partner. None for plain A1/A2/A3 admissions — additive and optional, so schema-1 reports written before A4 existed still validate unchanged.

• notes (str) –

  Free-text caveats.

Source code in src/chamber/evaluation/admission.py

class AdmissionReport(BaseModel):
    """The committed admission report — the Tier-2 entry evidence (ADR-027 §Admission protocol).

    Attributes:
        schema_version: :data:`ADMISSION_REPORT_SCHEMA_VERSION`.
        task_id: Task under admission.
        task_version: Task version.
        prereg_git_tag: Verified pre-registration tag (ADR-007
            §Discipline).
        prereg_blob_sha: Verified prereg blob SHA at the tag.
        git_sha: Launch commit (ADR-028 §Decision 1 provenance).
        dirty: Whether the working tree was dirty at run time (a dirty
            report is never registry-flip evidence — mirrors ADR-028
            §Rev 2026-07-05).
        date_stamp: Caller-supplied date label of the archive
            (``<task_id>-<date>``); passed in, never sampled, so the
            report stays deterministic (ADR-002 P6).
        checks: Per-check reports in A1/A2/A3/A4 order (A4 present only
            for instrument-based contrasts); a NOT_SOLVABLE
            short-circuit records A1 only.
        verdict: Overall verdict (ADR-027 §Admission protocol).
        seed_extension_used: Whether any check consumed the single
            pre-committed extension.
        binding_evidence: The A2 coupling-binding evidence — the stress
            distribution on matched successful episodes (ADR-026
            §Decision 2 positive-control).
        ego_robustness_profile: The A4 mandatory reported artifact
            (ADR-027 §Admission A4): admitted-set member name → the
            instrument's success point + CI + stress percentiles with
            that partner. ``None`` for plain A1/A2/A3 admissions —
            additive and optional, so schema-1 reports written before
            A4 existed still validate unchanged.
        notes: Free-text caveats.
    """

    model_config = ConfigDict(frozen=True, extra="forbid")

    schema_version: int = ADMISSION_REPORT_SCHEMA_VERSION
    task_id: str
    task_version: int
    prereg_git_tag: str
    prereg_blob_sha: str
    git_sha: str
    dirty: bool
    date_stamp: str
    checks: list[CheckReport]
    verdict: AdmissionVerdict
    seed_extension_used: bool
    binding_evidence: dict[str, float]
    ego_robustness_profile: dict[str, dict[str, float]] | None = None
    notes: str = ""

AdmissionSpec

Bases: BaseModel

The preregistered admission-protocol specification (ADR-027 §Admission protocol).

Thresholds are committed before results exist and are never tuned afterward (ADR-007 §Discipline); the spec is carried inside a document-form pre-registration (PreregDocument.parameters ["admission"]) locked to git_tag.

Attributes:

• task_id (str) –

  ADR-027 task under admission.

• task_version (int) –

  ADR-027 task version (task_id@vN).

• tau_solv (float) –

  A1 success floor (on the CI lower bound).

• stress_limit (float | None) –

  A1 stress ceiling on successful episodes' force_peak (the task's canonical stress instrument, ADR-027 §Versioning); None for tasks with no stress channel.

• tau_infeasible (float) –

  A2 success ceiling (on the CI upper bound) for the partner-ablated variant.

• delta_min (float) –

  A3 margin the coupling-aware reference must hold over the partner-blind ego (CI lower bound of the gap).

• seeds (list[int]) –

  Committed cluster-seed list per measured cell.

• episodes_per_seed (PositiveInt) –

  Episode budget per (cell, seed).

• extension_seeds (list[int]) –

  The single pre-committed seed extension used to resolve an INDETERMINATE check, then final (ADR-027 §Admission protocol).

• n_resamples (PositiveInt) –

  Bootstrap resample count (ADR-008 default 2000).

• root_seed (int) –

  Run-level root seed for episode + bootstrap substreams (ADR-002 P6).

• a1 (AdmissionCellSpec | WrappedEvidenceSpec) –

  The A1 reference cell (measured, or wrapped committed evidence).

• a2 (AdmissionCellSpec | WrappedEvidenceSpec) –

  The A2 partner-ablated cell (measured — the genuinely new, cheap cell for wrap-first tasks — or wrapped committed evidence when a committed ablated-cell bundle already exists, e.g. a retrospective re-issue over an earlier admission archive's cells).

• a3 (AdmissionCellSpec | WrappedEvidenceSpec) –

  The A3 partner-blind cell (measured; compared against the A1 reference cell on matched initial states), or wrapped committed gap evidence.

• c_min_ego (float | None) –

  A4 ego-robustness floor (ADR-027 §Admission A4) — the measuring instrument's per-partner success CI lower bound must clear it across the admitted partner set. It inherits the admitted set's capability floor C_min (never the aggregate tau_solv — ADR-027 §Revision history 2026-07-15 disambiguation), with episode success judged by the task's per-episode success+stress predicate. None (the default) for plain task admissions: A4 is skipped and the A1/A2/A3 semantics are unchanged.

• a4 (AdmissionCellSpec | WrappedEvidenceSpec | None) –

  The A4 instrument cell: measured (policy_id names the instrument under test and partner_name the admitted partner set it sweeps — an ADR-009 set slug, e.g. cocarry_partners@v1; the runner stamps each episode's metadata["member"] with the set-member name, the leaderboard per-partner convention), or wrapped committed per-partner evidence (I8: the profile is re-extracted from the SHA-verified bundle episodes by a profile extractor; a wrapped straddle is final — FAIL). Committed iff c_min_ego is.

• git_tag (str) –

  Pre-registration tag the spec is locked to (ADR-007 §Discipline).

Source code in src/chamber/evaluation/admission.py

class AdmissionSpec(BaseModel):
    """The preregistered admission-protocol specification (ADR-027 §Admission protocol).

    Thresholds are committed before results exist and are never tuned
    afterward (ADR-007 §Discipline); the spec is carried inside a
    document-form pre-registration (``PreregDocument.parameters
    ["admission"]``) locked to ``git_tag``.

    Attributes:
        task_id: ADR-027 task under admission.
        task_version: ADR-027 task version (``task_id@vN``).
        tau_solv: A1 success floor (on the CI lower bound).
        stress_limit: A1 stress ceiling on successful episodes'
            ``force_peak`` (the task's canonical stress instrument,
            ADR-027 §Versioning); ``None`` for tasks with no stress
            channel.
        tau_infeasible: A2 success ceiling (on the CI upper bound) for
            the partner-ablated variant.
        delta_min: A3 margin the coupling-aware reference must hold
            over the partner-blind ego (CI lower bound of the gap).
        seeds: Committed cluster-seed list per measured cell.
        episodes_per_seed: Episode budget per ``(cell, seed)``.
        extension_seeds: The single pre-committed seed extension used
            to resolve an INDETERMINATE check, then final (ADR-027
            §Admission protocol).
        n_resamples: Bootstrap resample count (ADR-008 default 2000).
        root_seed: Run-level root seed for episode + bootstrap
            substreams (ADR-002 P6).
        a1: The A1 reference cell (measured, or wrapped committed
            evidence).
        a2: The A2 partner-ablated cell (measured — the genuinely new,
            cheap cell for wrap-first tasks — or wrapped committed
            evidence when a committed ablated-cell bundle already
            exists, e.g. a retrospective re-issue over an earlier
            admission archive's cells).
        a3: The A3 partner-blind cell (measured; compared against the
            A1 reference cell on matched initial states), or wrapped
            committed gap evidence.
        c_min_ego: A4 ego-robustness floor (ADR-027 §Admission A4) —
            the measuring instrument's per-partner success CI lower
            bound must clear it across the admitted partner set. It
            inherits the admitted set's capability floor ``C_min``
            (never the aggregate ``tau_solv`` — ADR-027 §Revision
            history 2026-07-15 disambiguation), with episode success
            judged by the task's per-episode success+stress predicate.
            ``None`` (the default) for plain task admissions: A4 is
            skipped and the A1/A2/A3 semantics are unchanged.
        a4: The A4 instrument cell: measured (``policy_id`` names the
            instrument under test and ``partner_name`` the admitted
            partner set it sweeps — an ADR-009 set slug, e.g.
            ``cocarry_partners@v1``; the runner stamps each episode's
            ``metadata["member"]`` with the set-member name, the
            leaderboard per-partner convention), or wrapped committed
            per-partner evidence (I8: the profile is re-extracted from
            the SHA-verified bundle episodes by a profile extractor;
            a wrapped straddle is final — FAIL). Committed iff
            ``c_min_ego`` is.
        git_tag: Pre-registration tag the spec is locked to
            (ADR-007 §Discipline).
    """

    model_config = ConfigDict(frozen=True, extra="forbid")

    task_id: str
    task_version: int
    tau_solv: float
    stress_limit: float | None
    tau_infeasible: float
    delta_min: float
    seeds: list[int]
    episodes_per_seed: PositiveInt
    extension_seeds: list[int]
    n_resamples: PositiveInt = 2000
    root_seed: int = 0
    a1: AdmissionCellSpec | WrappedEvidenceSpec
    a2: AdmissionCellSpec | WrappedEvidenceSpec
    a3: AdmissionCellSpec | WrappedEvidenceSpec
    c_min_ego: float | None = None
    a4: AdmissionCellSpec | WrappedEvidenceSpec | None = None
    git_tag: str

    @model_validator(mode="after")
    def _a4_fields_travel_together(self) -> AdmissionSpec:
        """A4 needs both the floor and the cell (ADR-027 §Admission A4); loud otherwise."""
        if (self.c_min_ego is None) != (self.a4 is None):
            msg = (
                "c_min_ego and a4 commit the A4 ego-robustness gate together "
                "(ADR-027 §Admission A4): set both for an instrument-based "
                "contrast, neither for a plain task admission"
            )
            raise ValueError(msg)
        return self

BootstrapCI dataclass

Bootstrap point estimate + 95% CI (ADR-008 §Decision).

Attributes:

• iqm (float) –

  Interquartile mean of the resampled point estimates.

• mean (float) –

  Plain arithmetic mean of the resampled point estimates.

• ci_low (float) –

  2.5th percentile of the resampled estimates (lower bound of the 95% CI).

• ci_high (float) –

  97.5th percentile of the resampled estimates (upper bound of the 95% CI).

• n_resamples (int) –

  Number of bootstrap resamples that produced the interval.

Source code in src/chamber/evaluation/bootstrap.py

@dataclass(frozen=True)
class BootstrapCI:
    """Bootstrap point estimate + 95% CI (ADR-008 §Decision).

    Attributes:
        iqm: Interquartile mean of the resampled point estimates.
        mean: Plain arithmetic mean of the resampled point estimates.
        ci_low: 2.5th percentile of the resampled estimates (lower
            bound of the 95% CI).
        ci_high: 97.5th percentile of the resampled estimates (upper
            bound of the 95% CI).
        n_resamples: Number of bootstrap resamples that produced the
            interval.
    """

    iqm: float
    mean: float
    ci_low: float
    ci_high: float
    n_resamples: int

BundleSummary

Bases: BaseModel

Recomputable summary statistics of a result bundle (ADR-028 §Decision 3).

chamber-eval verify recomputes these from the bundle's raw per-seed episode records and compares within tolerance — so every field here must be a pure function of the episode records plus the pinned bootstrap parameters (n_resamples + bootstrap_root_seed routed through derive_substream, so the recomputation is byte-reproducible per ADR-002 P6).

Attributes:

• n_episodes (NonNegativeInt) –

  Total episode count across all seeds.

• success_mean (float) –

  Plain mean success over all episodes.

• success_iqm (float) –

  Interquartile-mean success from the seed-cluster bootstrap (ADR-008 reporting discipline).

• success_ci_low (float) –

  2.5th percentile of the cluster bootstrap.

• success_ci_high (float) –

  97.5th percentile of the cluster bootstrap.

• n_resamples (NonNegativeInt) –

  Bootstrap resample count used.

• bootstrap_root_seed (int) –

  Root seed of the bootstrap substream.

Source code in src/chamber/evaluation/results.py

class BundleSummary(BaseModel):
    """Recomputable summary statistics of a result bundle (ADR-028 §Decision 3).

    ``chamber-eval verify`` recomputes these from the bundle's raw
    per-seed episode records and compares within tolerance — so every
    field here must be a pure function of the episode records plus the
    pinned bootstrap parameters (``n_resamples`` +
    ``bootstrap_root_seed`` routed through ``derive_substream``, so
    the recomputation is byte-reproducible per ADR-002 P6).

    Attributes:
        n_episodes: Total episode count across all seeds.
        success_mean: Plain mean success over all episodes.
        success_iqm: Interquartile-mean success from the seed-cluster
            bootstrap (ADR-008 reporting discipline).
        success_ci_low: 2.5th percentile of the cluster bootstrap.
        success_ci_high: 97.5th percentile of the cluster bootstrap.
        n_resamples: Bootstrap resample count used.
        bootstrap_root_seed: Root seed of the bootstrap substream.
    """

    model_config = ConfigDict(extra="forbid", frozen=True)

    n_episodes: NonNegativeInt
    success_mean: float
    success_iqm: float
    success_ci_low: float
    success_ci_high: float
    n_resamples: NonNegativeInt
    bootstrap_root_seed: int

CheckReport

Bases: BaseModel

One admission check's result (ADR-027 §Admission protocol).

Attributes:

• check (AdmissionCheckId) –

  A1 / A2 / A3 / A4.

• outcome (CheckOutcome) –

  Final outcome after any pre-committed extension.

• criterion (str) –

  The pre-committed rule, verbatim, as applied.

• statistics (dict[str, float]) –

  The numbers the outcome was computed from (IQM, CI bounds, stress percentiles, paired-gap CI).

• bundles (list[str]) –

  Bundle directory names (relative to the admission archive) contributing to this check; empty for wrapped checks.

• evidence (dict[str, str]) –

  Evidence file → SHA-256 (bundle bundle.json hashes, or the wrapped archive files).

• extended (bool) –

  Whether the pre-committed seed extension was used.

• notes (str) –

  Free-text caveats.

Source code in src/chamber/evaluation/admission.py

class CheckReport(BaseModel):
    """One admission check's result (ADR-027 §Admission protocol).

    Attributes:
        check: ``A1`` / ``A2`` / ``A3`` / ``A4``.
        outcome: Final outcome after any pre-committed extension.
        criterion: The pre-committed rule, verbatim, as applied.
        statistics: The numbers the outcome was computed from (IQM,
            CI bounds, stress percentiles, paired-gap CI).
        bundles: Bundle directory names (relative to the admission
            archive) contributing to this check; empty for wrapped
            checks.
        evidence: Evidence file → SHA-256 (bundle ``bundle.json``
            hashes, or the wrapped archive files).
        extended: Whether the pre-committed seed extension was used.
        notes: Free-text caveats.
    """

    model_config = ConfigDict(frozen=True, extra="forbid")

    check: AdmissionCheckId
    outcome: CheckOutcome
    criterion: str
    statistics: dict[str, float]
    bundles: list[str]
    evidence: dict[str, str]
    extended: bool = False
    notes: str = ""

ConditionPair

Bases: BaseModel

Pre-registered homogeneous-vs-heterogeneous baseline pair (ADR-007 §Validation criteria).

Each Phase-0 spike runs at least one homogeneous baseline (the "control" side of the ≥20pp test) and at least one heterogeneous condition (the "treatment" side). Identifiers are free-form but must match the labels in the pre-registration YAML.

Attributes:

• homogeneous_id (str) –

  Identifier of the homogeneous baseline.

• heterogeneous_id (str) –

  Identifier of the heterogeneous condition.

Source code in src/chamber/evaluation/results.py

class ConditionPair(BaseModel):
    """Pre-registered homogeneous-vs-heterogeneous baseline pair (ADR-007 §Validation criteria).

    Each Phase-0 spike runs at least one homogeneous baseline (the
    "control" side of the ≥20pp test) and at least one heterogeneous
    condition (the "treatment" side). Identifiers are free-form but
    must match the labels in the pre-registration YAML.

    Attributes:
        homogeneous_id: Identifier of the homogeneous baseline.
        heterogeneous_id: Identifier of the heterogeneous condition.
    """

    model_config = ConfigDict(extra="forbid", frozen=True)

    homogeneous_id: str
    heterogeneous_id: str

ConditionResult

Bases: BaseModel

Aggregated result for one ADR-007 axis (ADR-008 §Decision).

Carries the homogeneous-vs-heterogeneous success-rate gap and the safety signals that feed the HRS-vector entry for this axis. gap_pp is the ≥20pp gap statistic from ADR-007 §Validation criteria; ci_low_pp / ci_high_pp are the cluster-bootstrap 95% bounds from :mod:chamber.evaluation.bootstrap.

Attributes:

• axis (str) –

  ADR-007 axis name.

• n_episodes (NonNegativeInt) –

  Total episodes contributing to this row.

• homogeneous_success (NonNegativeFloat) –

  IQM success rate on the homogeneous side.

• heterogeneous_success (NonNegativeFloat) –

  IQM success rate on the heterogeneous side.

• gap_pp (float) –

  (homogeneous_success - heterogeneous_success) * 100 — the percentage-point gap (ADR-007 §Validation criteria).

• ci_low_pp (float) –

  Lower bound of the 95% cluster-bootstrap CI on gap_pp.

• ci_high_pp (float) –

  Upper bound of the 95% cluster-bootstrap CI on gap_pp.

• violation_rate (NonNegativeFloat) –

  Per-step CBF-constraint violation rate across episodes (ADR-014 §Decision Table 2).

• fallback_rate (NonNegativeFloat) –

  Fraction of episodes in which the braking fallback fired at least once (separate from violation_rate per reviewer P0).

Source code in src/chamber/evaluation/results.py

class ConditionResult(BaseModel):
    """Aggregated result for one ADR-007 axis (ADR-008 §Decision).

    Carries the homogeneous-vs-heterogeneous success-rate gap and the
    safety signals that feed the HRS-vector entry for this axis.
    ``gap_pp`` is the ≥20pp gap statistic from ADR-007 §Validation
    criteria; ``ci_low_pp`` / ``ci_high_pp`` are the cluster-bootstrap
    95% bounds from :mod:`chamber.evaluation.bootstrap`.

    Attributes:
        axis: ADR-007 axis name.
        n_episodes: Total episodes contributing to this row.
        homogeneous_success: IQM success rate on the homogeneous side.
        heterogeneous_success: IQM success rate on the heterogeneous
            side.
        gap_pp: ``(homogeneous_success - heterogeneous_success) *
            100`` — the percentage-point gap (ADR-007 §Validation
            criteria).
        ci_low_pp: Lower bound of the 95% cluster-bootstrap CI on
            ``gap_pp``.
        ci_high_pp: Upper bound of the 95% cluster-bootstrap CI on
            ``gap_pp``.
        violation_rate: Per-step CBF-constraint violation rate across
            episodes (ADR-014 §Decision Table 2).
        fallback_rate: Fraction of episodes in which the braking
            fallback fired at least once (separate from
            ``violation_rate`` per reviewer P0).
    """

    model_config = ConfigDict(extra="forbid", frozen=True)

    axis: str
    n_episodes: NonNegativeInt
    homogeneous_success: NonNegativeFloat
    heterogeneous_success: NonNegativeFloat
    gap_pp: float
    ci_low_pp: float
    ci_high_pp: float
    violation_rate: NonNegativeFloat
    fallback_rate: NonNegativeFloat

EpisodeResult

Bases: BaseModel

A single evaluation episode of a CHAMBER spike (ADR-007 §Validation criteria).

The fields cover the three observable quantities the project reports per ADR-014 §Decision Table 2: episode success, peak constraint-violation magnitude, and fallback-fire count. The force_peak slot is the SA-axis specific signal used in ADR-014's Table 1 / Table 2 vendor-compliance rows when ADR-007 Stage-3 SA decomposes the safety axis.

Attributes:

• seed (int) –

  Root seed for this episode (ADR-002 P6 determinism).

• episode_idx (NonNegativeInt) –

  Zero-based episode index within the (seed, condition) cell.

• initial_state_seed (int) –

  Sub-stream seed for the initial state reset, used to pair homogeneous-vs-heterogeneous episodes in :func:chamber.evaluation.bootstrap.pacluster_bootstrap (ADR-007 §Validation criteria; reviewer P1-9).

• success (bool) –

  True iff the task succeeded per the env's terminal reward.

• constraint_violation_peak (float) –

  Worst-case CBF-constraint gap over the episode (ADR-014 §Decision Table 2 "constraint violation" column).

• fallback_fired (NonNegativeInt) –

  Number of braking-fallback fires during the episode (ADR-014 §Decision Table 2 "fallback fired" column; separate from violations per reviewer P0).

• force_peak (float | None) –

  Peak contact force in newtons; None outside the SA spike (ADR-007 Stage 3).

• metadata (dict[str, Any]) –

  Free-form per-episode metadata.

Source code in src/chamber/evaluation/results.py

class EpisodeResult(BaseModel):
    """A single evaluation episode of a CHAMBER spike (ADR-007 §Validation criteria).

    The fields cover the three observable quantities the project
    reports per ADR-014 §Decision Table 2: episode success, peak
    constraint-violation magnitude, and fallback-fire count. The
    ``force_peak`` slot is the SA-axis specific signal used in
    ADR-014's Table 1 / Table 2 vendor-compliance rows when ADR-007
    Stage-3 SA decomposes the safety axis.

    Attributes:
        seed: Root seed for this episode (ADR-002 P6 determinism).
        episode_idx: Zero-based episode index within the ``(seed,
            condition)`` cell.
        initial_state_seed: Sub-stream seed for the initial state
            reset, used to pair homogeneous-vs-heterogeneous episodes
            in :func:`chamber.evaluation.bootstrap.pacluster_bootstrap`
            (ADR-007 §Validation criteria; reviewer P1-9).
        success: ``True`` iff the task succeeded per the env's
            terminal reward.
        constraint_violation_peak: Worst-case CBF-constraint gap over
            the episode (ADR-014 §Decision Table 2 "constraint
            violation" column).
        fallback_fired: Number of braking-fallback fires during the
            episode (ADR-014 §Decision Table 2 "fallback fired"
            column; separate from violations per reviewer P0).
        force_peak: Peak contact force in newtons; ``None`` outside
            the SA spike (ADR-007 Stage 3).
        metadata: Free-form per-episode metadata.
    """

    model_config = ConfigDict(extra="forbid", frozen=True)

    seed: int
    episode_idx: NonNegativeInt
    initial_state_seed: int
    success: bool
    constraint_violation_peak: float = 0.0
    fallback_fired: NonNegativeInt = 0
    force_peak: float | None = None
    metadata: dict[str, Any] = Field(default_factory=dict)

HRSVector

Bases: BaseModel

Per-axis HRS vector emitted alongside the scalar (ADR-008 §Decision).

Reviewer P1-8 requires the vector to be emitted unconditionally so consumers can recompute the scalar under a different weighting; the leaderboard renderer enforces this by refusing entries that carry only the scalar.

Attributes:

• entries (list[HRSVectorEntry]) –

  Per-axis entries in the ADR-008 default order (CM > PF > CR > SA > OM > AS), subject to axis survival.

Source code in src/chamber/evaluation/results.py

class HRSVector(BaseModel):
    """Per-axis HRS vector emitted alongside the scalar (ADR-008 §Decision).

    Reviewer P1-8 requires the vector to be emitted *unconditionally*
    so consumers can recompute the scalar under a different
    weighting; the leaderboard renderer enforces this by refusing
    entries that carry only the scalar.

    Attributes:
        entries: Per-axis entries in the ADR-008 default order
            (CM > PF > CR > SA > OM > AS), subject to axis survival.
    """

    model_config = ConfigDict(extra="forbid", frozen=True)

    entries: list[HRSVectorEntry]

HRSVectorEntry

Bases: BaseModel

One axis row of the HRS vector (ADR-008 §Decision).

ADR-008 binds the HRS bundle to the surviving ADR-007 axes and fixes the default ordering CM > PF > CR > SA > OM > AS. Each entry carries the per-axis score plus the gap-PP that feeds :func:chamber.evaluation.hrs.compute_hrs_scalar.

Attributes:

• axis (str) –

  ADR-007 axis name.

• score (NonNegativeFloat) –

  Normalised per-axis score in [0, 1] (success rate on the heterogeneous condition, by default).

• gap_pp (float) –

  Percentage-point gap from the matching :class:ConditionResult (kept for traceability).

• weight (NonNegativeFloat) –

  Weight assigned to this axis in the scalar aggregation (defaults to ADR-008 Option D ordering).

Source code in src/chamber/evaluation/results.py

class HRSVectorEntry(BaseModel):
    """One axis row of the HRS vector (ADR-008 §Decision).

    ADR-008 binds the HRS bundle to the surviving ADR-007 axes and
    fixes the default ordering CM > PF > CR > SA > OM > AS. Each
    entry carries the per-axis score plus the gap-PP that feeds
    :func:`chamber.evaluation.hrs.compute_hrs_scalar`.

    Attributes:
        axis: ADR-007 axis name.
        score: Normalised per-axis score in ``[0, 1]`` (success rate
            on the heterogeneous condition, by default).
        gap_pp: Percentage-point gap from the matching
            :class:`ConditionResult` (kept for traceability).
        weight: Weight assigned to this axis in the scalar
            aggregation (defaults to ADR-008 Option D ordering).
    """

    model_config = ConfigDict(extra="forbid", frozen=True)

    axis: str
    score: NonNegativeFloat
    gap_pp: float
    weight: NonNegativeFloat

LeaderboardEntry

Bases: BaseModel

A single method/result pair as it appears on the CHAMBER leaderboard (ADR-008 §Decision).

Ranks by hrs_scalar. The accompanying :class:HRSVector is emitted unconditionally per reviewer P1-8; the renderer in :mod:chamber.evaluation.render displays the vector as a sub-row below the scalar.

Attributes:

• method_id (str) –

  Identifier of the method being evaluated (e.g. "concerto-ego-aht-v0.1").

• spike_runs (list[str]) –

  Spike-run IDs that contributed to this entry.

• hrs_vector (HRSVector) –

  Per-axis HRS values (always emitted).

• hrs_scalar (NonNegativeFloat) –

  Aggregated HRS scalar (ADR-008 §Decision; the ranking metric).

• violation_rate (NonNegativeFloat) –

  Aggregate per-step violation rate across the contributing spike runs.

• fallback_rate (NonNegativeFloat) –

  Aggregate fraction of episodes triggering the braking fallback (ADR-014 §Decision).

• schema_version (int) –

  Result-archive schema version (default :data:SCHEMA_VERSION).

Source code in src/chamber/evaluation/results.py

class LeaderboardEntry(BaseModel):
    """A single method/result pair as it appears on the CHAMBER leaderboard (ADR-008 §Decision).

    Ranks by ``hrs_scalar``. The accompanying :class:`HRSVector` is
    emitted unconditionally per reviewer P1-8; the renderer in
    :mod:`chamber.evaluation.render` displays the vector as a sub-row
    below the scalar.

    Attributes:
        method_id: Identifier of the method being evaluated (e.g.
            ``"concerto-ego-aht-v0.1"``).
        spike_runs: Spike-run IDs that contributed to this entry.
        hrs_vector: Per-axis HRS values (always emitted).
        hrs_scalar: Aggregated HRS scalar (ADR-008 §Decision; the
            ranking metric).
        violation_rate: Aggregate per-step violation rate across the
            contributing spike runs.
        fallback_rate: Aggregate fraction of episodes triggering the
            braking fallback (ADR-014 §Decision).
        schema_version: Result-archive schema version
            (default :data:`SCHEMA_VERSION`).
    """

    model_config = ConfigDict(extra="forbid", frozen=True)

    method_id: str
    spike_runs: list[str]
    hrs_vector: HRSVector
    hrs_scalar: NonNegativeFloat
    violation_rate: NonNegativeFloat
    fallback_rate: NonNegativeFloat
    schema_version: int = SCHEMA_VERSION

PairedEpisode dataclass

One paired homogeneous-vs-heterogeneous episode (ADR-007 §Validation criteria).

Pairs are matched on (seed, episode_idx, initial_state_seed) so the gap test in :func:pacluster_bootstrap is computed on matched pairs rather than on pooled means (reviewer P1-9).

Attributes:

• seed (int) –

  Shared root seed.

• episode_idx (int) –

  Shared episode index within the seed.

• initial_state_seed (int) –

  Shared env-reset sub-stream seed.

• homogeneous (float) –

  Per-episode metric on the homogeneous side.

• heterogeneous (float) –

  Per-episode metric on the heterogeneous side.

Source code in src/chamber/evaluation/bootstrap.py

@dataclass(frozen=True)
class PairedEpisode:
    """One paired homogeneous-vs-heterogeneous episode (ADR-007 §Validation criteria).

    Pairs are matched on ``(seed, episode_idx, initial_state_seed)``
    so the gap test in :func:`pacluster_bootstrap` is computed on
    matched pairs rather than on pooled means (reviewer P1-9).

    Attributes:
        seed: Shared root seed.
        episode_idx: Shared episode index within the seed.
        initial_state_seed: Shared env-reset sub-stream seed.
        homogeneous: Per-episode metric on the homogeneous side.
        heterogeneous: Per-episode metric on the heterogeneous side.
    """

    seed: int
    episode_idx: int
    initial_state_seed: int
    homogeneous: float
    heterogeneous: float

PlatformFingerprint

Bases: BaseModel

Platform fingerprint of a result bundle (ADR-028 §Decision 1).

ADR-028: "OS, Python, key dependency versions, device". CPU-only verification (ADR-028 §Decision 3) never compares this block — it is provenance for the reader, not a reproducibility gate.

Attributes:

• os (str) –

  platform.platform() string.

• python (str) –

  platform.python_version() string.

• numpy (str) –

  Installed numpy version.

• torch (str | None) –

  Installed torch version, or None if absent.

• device (str) –

  Compute device the run used (GPU name or "cpu").

Source code in src/chamber/evaluation/results.py

class PlatformFingerprint(BaseModel):
    """Platform fingerprint of a result bundle (ADR-028 §Decision 1).

    ADR-028: "OS, Python, key dependency versions, device". CPU-only
    verification (ADR-028 §Decision 3) never *compares* this block —
    it is provenance for the reader, not a reproducibility gate.

    Attributes:
        os: ``platform.platform()`` string.
        python: ``platform.python_version()`` string.
        numpy: Installed numpy version.
        torch: Installed torch version, or ``None`` if absent.
        device: Compute device the run used (GPU name or ``"cpu"``).
    """

    model_config = ConfigDict(extra="forbid", frozen=True)

    os: str
    python: str
    numpy: str
    torch: str | None
    device: str

PreregDocument

Bases: BaseModel

Document-form pre-registration (ADR-028 §Decision 2).

The generalized Gate-0-style prereg: task-keyed, with arbitrary committed parameter blocks (frozen thresholds, verdict spaces, power/pre-check artefacts) and decision-rule text, locked to a git tag exactly like the axis-form. "The prereg is frozen" becomes machine-verifiable — :func:verify_git_tag runs the same file-blob-vs-tag-blob check Gate-0 did by hand.

Attributes:

• schema_version (int) –

  Pre-registration schema version (:data:PREREG_SCHEMA_VERSION).

• task_id (str) –

  ADR-027 task the prereg keys on.

• git_tag (str) –

  Tag locking the document (ADR-007 §Discipline).

• parameters (dict[str, Any]) –

  Arbitrary committed parameter blocks — thresholds, cell tables, power artefacts. Frozen verbatim; the tag blob check covers the bytes, this model only checks shape.

• decision_rules (str) –

  The pre-committed decision-rule text (verdict space + stop rules).

• revision (str) –

  Human-readable revision label (e.g. "rev2").

• notes (str) –

  Free-text caveats.

Source code in src/chamber/evaluation/prereg.py

class PreregDocument(BaseModel):
    """Document-form pre-registration (ADR-028 §Decision 2).

    The generalized Gate-0-style prereg: task-keyed, with arbitrary
    committed parameter blocks (frozen thresholds, verdict spaces,
    power/pre-check artefacts) and decision-rule text, locked to a git
    tag exactly like the axis-form. "The prereg is frozen" becomes
    machine-verifiable — :func:`verify_git_tag` runs the same
    file-blob-vs-tag-blob check Gate-0 did by hand.

    Attributes:
        schema_version: Pre-registration schema version
            (:data:`PREREG_SCHEMA_VERSION`).
        task_id: ADR-027 task the prereg keys on.
        git_tag: Tag locking the document (ADR-007 §Discipline).
        parameters: Arbitrary committed parameter blocks — thresholds,
            cell tables, power artefacts. Frozen verbatim; the tag
            blob check covers the bytes, this model only checks shape.
        decision_rules: The pre-committed decision-rule text (verdict
            space + stop rules).
        revision: Human-readable revision label (e.g. ``"rev2"``).
        notes: Free-text caveats.
    """

    model_config = ConfigDict(extra="forbid", frozen=True)

    schema_version: int = PREREG_SCHEMA_VERSION
    task_id: str
    git_tag: str
    parameters: dict[str, Any]
    decision_rules: str
    revision: str = ""
    notes: str = ""

PreregistrationError

Bases: RuntimeError

Raised when a pre-registration fails the ADR-007 §Discipline check (ADR-007 §Discipline).

Source code in src/chamber/evaluation/prereg.py

class PreregistrationError(RuntimeError):
    """Raised when a pre-registration fails the ADR-007 §Discipline check (ADR-007 §Discipline)."""

PreregistrationSpec

Bases: BaseModel

Schema for an ADR-007 pre-registration YAML (ADR-007 §Discipline).

Required fields mirror the operational contract in docs/reference/evaluation.md §3: the homogeneous-vs- heterogeneous pair, the seed list, the episodes-per-seed budget, the estimator, and the bootstrap method. The default bootstrap is cluster per reviewer P1-9 — pooled IID bootstrap on seed-clustered data understates the CI width.

Attributes:

• axis (str) –

  One of the ADR-007 §3.4 axes ("CR" / "AS" / "OM" / "CM" / "PF" / "SA").

• condition_pair (ConditionPair) –

  Homogeneous-vs-heterogeneous baseline pair.

• seeds (list[int]) –

  List of root seeds for ADR-002 P6 determinism.

• episodes_per_seed (PositiveInt) –

  Episode budget per (seed, condition) cell.

• estimator (str) –

  Identifier of the headline estimator (e.g. "iqm_success_rate").

• bootstrap_method (BootstrapMethod) –

  Default "cluster" (reviewer P1-9); "hierarchical" is an alias accepted for back-compat; "iid" is allowed only for power calculations, not leaderboard entries (reviewer P1-5, enforced by :meth:_check_bootstrap_policy).

• failure_policy (FailurePolicy) –

  "strict" (the spike fails if any seed errors) or "best_effort" (errored seeds are dropped and reported).

• git_tag (str) –

  Pre-registration git tag this YAML is locked to (ADR-007 §Discipline; verified by :func:verify_git_tag).

• notes (str) –

  Free-form notes carried into the leaderboard entry.

• run_purpose (RunPurpose) –

  "leaderboard" (default), "power", or "debug" (reviewer P1-5). Only "leaderboard" runs are admitted to the public ranking; the other two values relax the iid-bootstrap ban so power calculations and local debug runs can still use a pooled iid baseline.

Source code in src/chamber/evaluation/prereg.py

class PreregistrationSpec(BaseModel):
    """Schema for an ADR-007 pre-registration YAML (ADR-007 §Discipline).

    Required fields mirror the operational contract in
    ``docs/reference/evaluation.md`` §3: the homogeneous-vs-
    heterogeneous pair, the seed list, the episodes-per-seed budget,
    the estimator, and the bootstrap method. The default bootstrap is
    ``cluster`` per reviewer P1-9 — pooled IID bootstrap on
    seed-clustered data understates the CI width.

    Attributes:
        axis: One of the ADR-007 §3.4 axes
            (``"CR"`` / ``"AS"`` / ``"OM"`` / ``"CM"`` / ``"PF"`` /
            ``"SA"``).
        condition_pair: Homogeneous-vs-heterogeneous baseline pair.
        seeds: List of root seeds for ADR-002 P6 determinism.
        episodes_per_seed: Episode budget per ``(seed, condition)``
            cell.
        estimator: Identifier of the headline estimator (e.g.
            ``"iqm_success_rate"``).
        bootstrap_method: Default ``"cluster"`` (reviewer P1-9);
            ``"hierarchical"`` is an alias accepted for back-compat;
            ``"iid"`` is allowed only for power calculations, not
            leaderboard entries (reviewer P1-5, enforced by
            :meth:`_check_bootstrap_policy`).
        failure_policy: ``"strict"`` (the spike fails if any seed
            errors) or ``"best_effort"`` (errored seeds are dropped
            and reported).
        git_tag: Pre-registration git tag this YAML is locked to
            (ADR-007 §Discipline; verified by
            :func:`verify_git_tag`).
        notes: Free-form notes carried into the leaderboard entry.
        run_purpose: ``"leaderboard"`` (default), ``"power"``, or
            ``"debug"`` (reviewer P1-5). Only ``"leaderboard"`` runs
            are admitted to the public ranking; the other two values
            relax the iid-bootstrap ban so power calculations and
            local debug runs can still use a pooled iid baseline.
    """

    model_config = ConfigDict(extra="forbid", frozen=True)

    axis: str
    condition_pair: ConditionPair
    seeds: list[int]
    episodes_per_seed: PositiveInt
    estimator: str
    bootstrap_method: BootstrapMethod = "cluster"
    failure_policy: FailurePolicy = "strict"
    git_tag: str
    notes: str = Field(default="")
    run_purpose: RunPurpose = "leaderboard"

    @model_validator(mode="after")
    def _check_bootstrap_policy(self) -> PreregistrationSpec:
        """Enforce the iid-not-allowed-for-leaderboard rule (reviewer P1-5).

        The pooled IID bootstrap on seed-clustered episode data
        understates CI width; admitting it to the leaderboard would
        let entries claim tighter intervals than the data supports.
        Power-analysis and debug runs are exempt because they are not
        published.
        """
        if self.run_purpose == "leaderboard" and self.bootstrap_method == "iid":
            msg = (
                "iid bootstrap is not permitted for leaderboard "
                "entries; use cluster (default) or hierarchical."
            )
            raise ValueError(msg)
        return self

    def normalised_axis(self) -> str:
        """Return the validated ADR-007 axis label (ADR-007 §Decision).

        Raises:
            ValueError: When :attr:`axis` is not one of the ADR-007
                §3.4 Option D shortlist.
        """
        if self.axis not in _AXIS_LABELS:
            msg = (
                f"axis {self.axis!r} is not one of the ADR-007 §3.4 shortlist "
                f"{sorted(_AXIS_LABELS)!r}"
            )
            raise ValueError(msg)
        return self.axis

normalised_axis

normalised_axis() -> str

Return the validated ADR-007 axis label (ADR-007 §Decision).

Raises:

• ValueError –

  When :attr:axis is not one of the ADR-007 §3.4 Option D shortlist.

Source code in src/chamber/evaluation/prereg.py

def normalised_axis(self) -> str:
    """Return the validated ADR-007 axis label (ADR-007 §Decision).

    Raises:
        ValueError: When :attr:`axis` is not one of the ADR-007
            §3.4 Option D shortlist.
    """
    if self.axis not in _AXIS_LABELS:
        msg = (
            f"axis {self.axis!r} is not one of the ADR-007 §3.4 shortlist "
            f"{sorted(_AXIS_LABELS)!r}"
        )
        raise ValueError(msg)
    return self.axis

ResultBundle

Bases: BaseModel

The v3 result-bundle record — bundle.json (ADR-028 §Decision 1).

Wraps the existing :class:EpisodeResult machinery: the raw episode records live in the bundle directory's per-seed JSONL files (one :class:EpisodeResult JSON object per line), listed in manifest; bundle.json carries the provenance fields ADR-028 authorizes plus the recomputable :class:BundleSummary.

Attributes:

• schema_version (int) –

  Result-archive schema version (v3; :data:SCHEMA_VERSION).

• task_id (str) –

  ADR-027 task identity (with task_version: task_id@vN).

• task_version (int) –

  ADR-027 task version.

• policy_id (str) –

  Ego policy reference the bundle evaluates (ADR-011 baseline IDs; e.g. "random" = B-RND).

• partner_set_id (str) –

  Partner-set identity (ADR-009 as amended). Ad-hoc single-partner runs use "adhoc:<registry-name>" until partner sets ship.

• partner_hashes (dict[str, str]) –

  Per-member partner identity hashes — PartnerSpec.partner_id (SHA-256 custody hash, ADR-018) keyed by member name.

• git_sha (str) –

  Launch commit, captured once per run (ADR-002 §Rev 2026-06-12 process-cache discipline).

• dirty (bool) –

  True iff the bundle was produced from a dirty working tree under --allow-dirty. Dirty bundles are ineligible for leaderboard use (ADR-028 §Rev 2026-07-05).

• package_version (str) –

  Installed concerto-multirobot distribution version.

• seed_schedule (SeedSchedule) –

  Explicit seed schedule (ADR-028 §Decision 1).

• repro_command (str) –

  Exact reproduction invocation (the repro_command.txt convention promoted into the bundle).

• platform (PlatformFingerprint) –

  Platform fingerprint (ADR-028 §Decision 1).

• manifest (dict[str, str]) –

  SHA-256 hex digest of every file in the bundle directory except bundle.json itself (which cannot contain its own hash), keyed by file name.

• summary (BundleSummary) –

  Recomputable summary statistics (ADR-028 §Decision 3).

• prereg_git_tag (str | None) –

  Pre-registration tag the run was gated on, or None for unpreregistered (diagnostic) runs.

• prereg_blob_sha (str | None) –

  Verified prereg blob SHA at the tag, or None.

Source code in src/chamber/evaluation/results.py

class ResultBundle(BaseModel):
    """The v3 result-bundle record — ``bundle.json`` (ADR-028 §Decision 1).

    Wraps the existing :class:`EpisodeResult` machinery: the raw
    episode records live in the bundle directory's per-seed JSONL
    files (one :class:`EpisodeResult` JSON object per line), listed in
    ``manifest``; ``bundle.json`` carries the provenance fields ADR-028
    authorizes plus the recomputable :class:`BundleSummary`.

    Attributes:
        schema_version: Result-archive schema version (v3;
            :data:`SCHEMA_VERSION`).
        task_id: ADR-027 task identity (with ``task_version``:
            ``task_id@vN``).
        task_version: ADR-027 task version.
        policy_id: Ego policy reference the bundle evaluates (ADR-011
            baseline IDs; e.g. ``"random"`` = B-RND).
        partner_set_id: Partner-set identity (ADR-009 as amended).
            Ad-hoc single-partner runs use ``"adhoc:<registry-name>"``
            until partner sets ship.
        partner_hashes: Per-member partner identity hashes —
            ``PartnerSpec.partner_id`` (SHA-256 custody hash, ADR-018)
            keyed by member name.
        git_sha: Launch commit, captured once per run (ADR-002
            §Rev 2026-06-12 process-cache discipline).
        dirty: ``True`` iff the bundle was produced from a dirty
            working tree under ``--allow-dirty``. Dirty bundles are
            ineligible for leaderboard use (ADR-028 §Rev 2026-07-05).
        package_version: Installed ``concerto-multirobot``
            distribution version.
        seed_schedule: Explicit seed schedule (ADR-028 §Decision 1).
        repro_command: Exact reproduction invocation (the
            ``repro_command.txt`` convention promoted into the
            bundle).
        platform: Platform fingerprint (ADR-028 §Decision 1).
        manifest: SHA-256 hex digest of every file in the bundle
            directory except ``bundle.json`` itself (which cannot
            contain its own hash), keyed by file name.
        summary: Recomputable summary statistics (ADR-028 §Decision 3).
        prereg_git_tag: Pre-registration tag the run was gated on, or
            ``None`` for unpreregistered (diagnostic) runs.
        prereg_blob_sha: Verified prereg blob SHA at the tag, or
            ``None``.
    """

    model_config = ConfigDict(extra="forbid", frozen=True)

    schema_version: int = SCHEMA_VERSION
    task_id: str
    task_version: int
    policy_id: str
    partner_set_id: str
    partner_hashes: dict[str, str]
    git_sha: str
    dirty: bool
    package_version: str
    seed_schedule: SeedSchedule
    repro_command: str
    platform: PlatformFingerprint
    manifest: dict[str, str]
    summary: BundleSummary
    prereg_git_tag: str | None = None
    prereg_blob_sha: str | None = None

SeedSchedule

Bases: BaseModel

Explicit seed schedule of a result bundle (ADR-028 §Decision 1).

ADR-028 requires "the explicit seed list/derivation, not just a root seed": root_seed is the run-level pin, seeds the exact per-episode-cluster seed list, and substream_labels the :func:concerto.training.seeding.derive_substream name patterns the run used (ADR-002 P6 — the schedule is re-derivable from these three facts alone).

Attributes:

• root_seed (int) –

  Run-level root seed (ADR-002 P6).

• seeds (list[int]) –

  Exact per-cluster seed list, in run order.

• episodes_per_seed (NonNegativeInt) –

  Episodes run per seed cluster.

• substream_labels (list[str]) –

  derive_substream name patterns used ({seed} / {episode} placeholders literal).

Source code in src/chamber/evaluation/results.py

class SeedSchedule(BaseModel):
    """Explicit seed schedule of a result bundle (ADR-028 §Decision 1).

    ADR-028 requires "the explicit seed list/derivation, not just a
    root seed": ``root_seed`` is the run-level pin, ``seeds`` the
    exact per-episode-cluster seed list, and ``substream_labels`` the
    :func:`concerto.training.seeding.derive_substream` name patterns
    the run used (ADR-002 P6 — the schedule is re-derivable from these
    three facts alone).

    Attributes:
        root_seed: Run-level root seed (ADR-002 P6).
        seeds: Exact per-cluster seed list, in run order.
        episodes_per_seed: Episodes run per seed cluster.
        substream_labels: ``derive_substream`` name patterns used
            (``{seed}`` / ``{episode}`` placeholders literal).
    """

    model_config = ConfigDict(extra="forbid", frozen=True)

    root_seed: int
    seeds: list[int]
    episodes_per_seed: NonNegativeInt
    substream_labels: list[str]

SlackAggregate dataclass

Per-condition OSCBF slack aggregate (ADR-014 §Revision history 2026-05-16).

Carries the two scalar columns ADR-014 Table 2 v2 adds to :class:concerto.safety.reporting.ConditionRow. The values are aggregated by :func:aggregate_oscbf_slack over the per-step :class:concerto.safety.oscbf.OSCBFResult stream within a single ADR-014 Table 2 condition.

Attributes:

• max_slack (float) –

  Maximum over steps k in the condition of OSCBFResult.max_slack — the worst single-step OSCBF relaxation observed across the condition. Non-negative by construction (the source signal is non-negative).

• slack_l2 (float) –

  Mean over steps k of OSCBFResult.slack_l2 — the mean L2-norm of the per-step slack vector across the condition. Non-negative by construction.

Source code in src/chamber/evaluation/oscbf_aggregate.py

@dataclass(frozen=True)
class SlackAggregate:
    """Per-condition OSCBF slack aggregate (ADR-014 §Revision history 2026-05-16).

    Carries the two scalar columns ADR-014 Table 2 v2 adds to
    :class:`concerto.safety.reporting.ConditionRow`. The values are
    aggregated by :func:`aggregate_oscbf_slack` over the per-step
    :class:`concerto.safety.oscbf.OSCBFResult` stream within a single
    ADR-014 Table 2 condition.

    Attributes:
        max_slack: Maximum over steps ``k`` in the condition of
            ``OSCBFResult.max_slack`` — the worst single-step OSCBF
            relaxation observed across the condition. Non-negative by
            construction (the source signal is non-negative).
        slack_l2: Mean over steps ``k`` of ``OSCBFResult.slack_l2`` —
            the mean L2-norm of the per-step slack vector across the
            condition. Non-negative by construction.
    """

    max_slack: float
    slack_l2: float

SpikeRun

Bases: BaseModel

Full record of one ADR-007 staged spike (ADR-007 §Discipline; ADR-016 §Decision).

Carries the pre-registration provenance (prereg_sha / git_tag) so the leaderboard renderer can refuse entries that do not match the locked YAML. The episode_results list is the raw observation feed for :mod:chamber.evaluation.bootstrap and :mod:chamber.evaluation.hrs.

Attributes:

• spike_id (str) –

  Free-form identifier (e.g. "stage2_cm_urllc").

• prereg_sha (str) –

  Git-blob SHA of the locked pre-registration YAML (ADR-007 §Discipline; verified by :func:chamber.evaluation.prereg.verify_git_tag).

• git_tag (str) –

  Git tag the pre-registration was locked to (ADR-007 §Discipline).

• axis (str) –

  Name of the ADR-007 heterogeneity axis under test (one of "CR", "AS", "OM", "CM", "PF", "SA").

• sub_stage (SubStage) –

  ADR-007 §Implementation-staging sub-stage label (one of "1a" / "1b" / "2" / "3"). Required, no default — see ADR-016 §Decision and §Rationale for why the silent default-by-axis fallback the v1 schema relied on was retired.

• condition_pair (ConditionPair) –

  Homogeneous-vs-heterogeneous pair.

• seeds (list[int]) –

  List of root seeds used in this spike (ADR-002 P6).

• episode_results (list[EpisodeResult]) –

  Flat list of per-episode results across all seeds and both pair sides.

• schema_version (int) –

  Result-archive schema version (default :data:SCHEMA_VERSION; currently 2 per ADR-016 §Decision).

Source code in src/chamber/evaluation/results.py

class SpikeRun(BaseModel):
    """Full record of one ADR-007 staged spike (ADR-007 §Discipline; ADR-016 §Decision).

    Carries the pre-registration provenance (``prereg_sha`` /
    ``git_tag``) so the leaderboard renderer can refuse entries that
    do not match the locked YAML. The ``episode_results`` list is the
    raw observation feed for
    :mod:`chamber.evaluation.bootstrap` and
    :mod:`chamber.evaluation.hrs`.

    Attributes:
        spike_id: Free-form identifier (e.g. ``"stage2_cm_urllc"``).
        prereg_sha: Git-blob SHA of the locked pre-registration YAML
            (ADR-007 §Discipline; verified by
            :func:`chamber.evaluation.prereg.verify_git_tag`).
        git_tag: Git tag the pre-registration was locked to
            (ADR-007 §Discipline).
        axis: Name of the ADR-007 heterogeneity axis under test
            (one of ``"CR"``, ``"AS"``, ``"OM"``, ``"CM"``,
            ``"PF"``, ``"SA"``).
        sub_stage: ADR-007 §Implementation-staging sub-stage label
            (one of ``"1a"`` / ``"1b"`` / ``"2"`` / ``"3"``).
            Required, no default — see ADR-016 §Decision and
            §Rationale for why the silent default-by-axis fallback
            the v1 schema relied on was retired.
        condition_pair: Homogeneous-vs-heterogeneous pair.
        seeds: List of root seeds used in this spike (ADR-002 P6).
        episode_results: Flat list of per-episode results across all
            seeds and both pair sides.
        schema_version: Result-archive schema version
            (default :data:`SCHEMA_VERSION`; currently 2 per
            ADR-016 §Decision).
    """

    model_config = ConfigDict(extra="forbid", frozen=True)

    spike_id: str
    prereg_sha: str
    git_tag: str
    axis: str
    sub_stage: SubStage
    condition_pair: ConditionPair
    seeds: list[int]
    episode_results: list[EpisodeResult]
    schema_version: int = SCHEMA_VERSION

WrappedEvidenceSpec

Bases: BaseModel

A check backed by an existing immutable archive (ADR-027 §Admission protocol; I8).

Wrapping never re-runs and never hand-copies numbers: the archive files are SHA-256-verified against the hashes committed in the prereg, and the statistics are re-extracted from the verified bytes by a named extractor at report-build time.

Attributes:

• archive (str) –

  Repo-relative archive directory the evidence lives in.

• files (dict[str, str]) –

  Repo-relative file paths → expected SHA-256 hex digests (committed in the prereg; the wrap fails loudly on any mismatch).

• extractor (str) –

  Key into the wrap-extractor registry (:data:chamber.benchmarks.admission_cells.WRAP_EXTRACTORS).

• params (dict[str, Any]) –

  Extractor-specific committed parameters (e.g. the pinned coupling-valid cell family).

Source code in src/chamber/evaluation/admission.py

class WrappedEvidenceSpec(BaseModel):
    """A check backed by an existing immutable archive (ADR-027 §Admission protocol; I8).

    Wrapping never re-runs and never hand-copies numbers: the archive
    files are SHA-256-verified against the hashes committed in the
    prereg, and the statistics are re-extracted from the verified bytes
    by a named extractor at report-build time.

    Attributes:
        archive: Repo-relative archive directory the evidence lives in.
        files: Repo-relative file paths → expected SHA-256 hex digests
            (committed in the prereg; the wrap fails loudly on any
            mismatch).
        extractor: Key into the wrap-extractor registry
            (:data:`chamber.benchmarks.admission_cells.WRAP_EXTRACTORS`).
        params: Extractor-specific committed parameters (e.g. the
            pinned coupling-valid cell family).
    """

    model_config = ConfigDict(frozen=True, extra="forbid")

    archive: str
    files: dict[str, str]
    extractor: str
    params: dict[str, Any] = Field(default_factory=dict)

admission_spec_from_prereg

admission_spec_from_prereg(
    doc: PreregDocument,
) -> AdmissionSpec

Build the :class:AdmissionSpec from a document-form prereg (ADR-028 §Decision 2).

The spec body lives in doc.parameters["admission"]; task_id and git_tag are injected from the document envelope so the two can never disagree with the tag-locked YAML.

Raises:

• AdmissionError –

  When the admission parameter block is missing.

• ValidationError –

  When the block does not match :class:AdmissionSpec (unknown keys fail loudly).

Source code in src/chamber/evaluation/admission.py

def admission_spec_from_prereg(doc: PreregDocument) -> AdmissionSpec:
    """Build the :class:`AdmissionSpec` from a document-form prereg (ADR-028 §Decision 2).

    The spec body lives in ``doc.parameters["admission"]``; ``task_id``
    and ``git_tag`` are injected from the document envelope so the two
    can never disagree with the tag-locked YAML.

    Raises:
        AdmissionError: When the ``admission`` parameter block is
            missing.
        pydantic.ValidationError: When the block does not match
            :class:`AdmissionSpec` (unknown keys fail loudly).
    """
    block = doc.parameters.get("admission")
    if not isinstance(block, dict):
        msg = (
            f"prereg for task {doc.task_id!r} carries no 'admission' parameter "
            "block (ADR-027 §Admission protocol)"
        )
        raise AdmissionError(msg)
    payload = {**block, "task_id": doc.task_id, "git_tag": doc.git_tag}
    return AdmissionSpec.model_validate(payload)

aggregate_metrics

aggregate_metrics(
    values: Mapping[int, Sequence[float]],
    *,
    metrics: Sequence[str] = (
        "iqm",
        "optimality_gap",
        "performance_profile",
    ),
    threshold: float = 1.0,
) -> dict[str, float | None]

rliable-compatible aggregate metrics (ADR-008 §Decision; ADR-014 §Decision).

If the optional rliable package is installed, delegates to its library.get_interval_estimates / aggregate_func helpers. Otherwise, IQM and optimality gap are computed natively and a runtime warning explains that performance profiles require the optional extra. The native path is sufficient for unit tests and the Phase-0 golden-file integration test.

Parameters:

• values (Mapping[int, Sequence[float]]) –

  {seed: [per-episode metric]} mapping.

• metrics (Sequence[str], default: ('iqm', 'optimality_gap', 'performance_profile') ) –

  Subset of {"iqm", "optimality_gap", "performance_profile"} to compute.

• threshold (float, default: 1.0 ) –

  Reference score for optimality gap (default 1.0 for normalised success rates).

Returns:

• dict[str, float | None] –

  Dict keyed by metric name with float values; the

• dict[str, float | None] –

  "performance_profile" slot is None when the optional

• dict[str, float | None] –

  rliable extra is not installed.

Source code in src/chamber/evaluation/bootstrap.py

def aggregate_metrics(
    values: Mapping[int, Sequence[float]],
    *,
    metrics: Sequence[str] = ("iqm", "optimality_gap", "performance_profile"),
    threshold: float = 1.0,
) -> dict[str, float | None]:
    """rliable-compatible aggregate metrics (ADR-008 §Decision; ADR-014 §Decision).

    If the optional ``rliable`` package is installed, delegates to
    its ``library.get_interval_estimates`` / ``aggregate_func``
    helpers. Otherwise, IQM and optimality gap are computed natively
    and a runtime warning explains that performance profiles require
    the optional extra. The native path is sufficient for unit tests
    and the Phase-0 golden-file integration test.

    Args:
        values: ``{seed: [per-episode metric]}`` mapping.
        metrics: Subset of ``{"iqm", "optimality_gap",
            "performance_profile"}`` to compute.
        threshold: Reference score for optimality gap (default
            ``1.0`` for normalised success rates).

    Returns:
        Dict keyed by metric name with float values; the
        ``"performance_profile"`` slot is ``None`` when the optional
        ``rliable`` extra is not installed.
    """
    flat = np.concatenate(
        [np.asarray(v, dtype=np.float64) for v in values.values() if len(v) > 0]
        or [np.array([], dtype=np.float64)]
    )
    out: dict[str, float | None] = {}
    if "iqm" in metrics:
        out["iqm"] = _interquartile_mean(flat)
    if "optimality_gap" in metrics:
        out["optimality_gap"] = _optimality_gap(flat, threshold=threshold)
    if "performance_profile" in metrics:
        if _RLIABLE_AVAILABLE:
            # The rliable performance-profile API returns a histogram of
            # threshold-vs-coverage; CHAMBER's renderer summarises it to
            # area-under-the-profile to fit a single leaderboard column.
            from rliable import library as rly  # type: ignore[import-not-found]  # noqa: PLC0415

            tau = np.linspace(0.0, 1.0, num=51)
            profile, _ = rly.create_performance_profile({"x": flat[None, :]}, tau)
            # Trapezoidal area under the performance profile; np.trapezoid
            # supersedes np.trapz from NumPy 2.0.
            trapezoid = getattr(np, "trapezoid", None) or np.trapz  # type: ignore[attr-defined]
            out["performance_profile"] = float(trapezoid(profile["x"], tau))
        else:
            warnings.warn(
                "performance_profile requires the optional `rliable` extra "
                "(`uv pip install rliable`); returning None for this column",
                RuntimeWarning,
                stacklevel=2,
            )
            out["performance_profile"] = None
    return out

aggregate_oscbf_slack

aggregate_oscbf_slack(
    results: Iterable[OSCBFResult],
) -> SlackAggregate

Aggregate per-step :class:OSCBFResult values into the ADR-014 contract.

Implements the locked aggregation contract from ADR-014 §Revision history 2026-05-16:

• max_slack is the max over steps of OSCBFResult.max_slack.
• slack_l2 is the mean over steps of OSCBFResult.slack_l2.

A consumed empty iterable produces SlackAggregate(0.0, 0.0) so the result composes with the :class:concerto.safety.reporting.ConditionRow defaults (the Stage-1a EGO_ONLY path that does not exercise the OSCBF inner filter; issue #142).

Parameters:

• results (Iterable[OSCBFResult]) –

  Iterable of per-step :class:concerto.safety.oscbf.OSCBFResult values from the steps within a single ADR-014 Table 2 condition. Order is irrelevant; the aggregator consumes the iterable exactly once.

Returns:

• The ( SlackAggregate ) –

  class:SlackAggregate carrying the two ADR-014 v2

• SlackAggregate –

  ConditionRow columns.

Source code in src/chamber/evaluation/oscbf_aggregate.py

def aggregate_oscbf_slack(results: Iterable[OSCBFResult]) -> SlackAggregate:
    """Aggregate per-step :class:`OSCBFResult` values into the ADR-014 contract.

    Implements the locked aggregation contract from ADR-014 §Revision
    history 2026-05-16:

    - ``max_slack`` is the max over steps of ``OSCBFResult.max_slack``.
    - ``slack_l2`` is the mean over steps of ``OSCBFResult.slack_l2``.

    A consumed empty iterable produces ``SlackAggregate(0.0, 0.0)`` so
    the result composes with the
    :class:`concerto.safety.reporting.ConditionRow` defaults (the
    Stage-1a EGO_ONLY path that does not exercise the OSCBF inner
    filter; issue #142).

    Args:
        results: Iterable of per-step
            :class:`concerto.safety.oscbf.OSCBFResult` values from the
            steps within a single ADR-014 Table 2 condition. Order is
            irrelevant; the aggregator consumes the iterable exactly
            once.

    Returns:
        The :class:`SlackAggregate` carrying the two ADR-014 v2
        ConditionRow columns.
    """
    max_slack = 0.0
    slack_l2_sum = 0.0
    n_steps = 0
    for result in results:
        max_slack = max(max_slack, result.max_slack)
        slack_l2_sum += result.slack_l2
        n_steps += 1
    slack_l2_mean = slack_l2_sum / n_steps if n_steps > 0 else 0.0
    return SlackAggregate(max_slack=max_slack, slack_l2=slack_l2_mean)

cluster_bootstrap

cluster_bootstrap(
    values: Mapping[int, Sequence[float]],
    *,
    n_resamples: int,
    rng: Generator,
) -> BootstrapCI

Cluster bootstrap over {seed: [per-episode values]} (reviewer P1-9; ADR-008 §Decision).

Resamples seeds with replacement (the cluster level), then resamples episodes with replacement within each resampled seed. Returns IQM, plain mean, and the 95% CI on the IQM estimator. This is the headline aggregator for ADR-014 §Decision Table 2 when the bootstrap method is "cluster".

Parameters:

• values (Mapping[int, Sequence[float]]) –

  {seed: [per-episode metric]} mapping. Empty seeds are dropped from the resample but a fully empty input yields a degenerate nan interval.

• n_resamples (int) –

  Number of bootstrap resamples (e.g. 2000).

• rng (Generator) –

  Deterministic np.random.Generator (ADR-002 P6).

Returns:

• BootstrapCI –

  class:BootstrapCI with the IQM, plain mean, and 95% bounds.

Source code in src/chamber/evaluation/bootstrap.py

def cluster_bootstrap(
    values: Mapping[int, Sequence[float]],
    *,
    n_resamples: int,
    rng: np.random.Generator,
) -> BootstrapCI:
    """Cluster bootstrap over ``{seed: [per-episode values]}`` (reviewer P1-9; ADR-008 §Decision).

    Resamples seeds with replacement (the cluster level), then
    resamples episodes with replacement within each resampled seed.
    Returns IQM, plain mean, and the 95% CI on the *IQM* estimator.
    This is the headline aggregator for ADR-014 §Decision Table 2
    when the bootstrap method is ``"cluster"``.

    Args:
        values: ``{seed: [per-episode metric]}`` mapping. Empty
            seeds are dropped from the resample but a fully empty
            input yields a degenerate ``nan`` interval.
        n_resamples: Number of bootstrap resamples (e.g. ``2000``).
        rng: Deterministic ``np.random.Generator`` (ADR-002 P6).

    Returns:
        :class:`BootstrapCI` with the IQM, plain mean, and 95% bounds.
    """
    if n_resamples <= 0:
        msg = f"n_resamples must be positive, got {n_resamples}"
        raise ValueError(msg)

    all_values = np.concatenate(
        [np.asarray(v, dtype=np.float64) for v in values.values() if len(v) > 0]
        or [np.array([], dtype=np.float64)]
    )
    point_iqm = _interquartile_mean(all_values)
    point_mean = float(np.mean(all_values)) if all_values.size else float("nan")

    iqm_samples = np.empty(n_resamples, dtype=np.float64)
    for k in range(n_resamples):
        resample = _resample_cluster(values, rng=rng)
        iqm_samples[k] = _interquartile_mean(resample) if resample.size else np.nan

    finite = iqm_samples[np.isfinite(iqm_samples)]
    if finite.size == 0:
        return BootstrapCI(
            iqm=point_iqm,
            mean=point_mean,
            ci_low=float("nan"),
            ci_high=float("nan"),
            n_resamples=n_resamples,
        )
    ci_low = float(np.percentile(finite, 2.5))
    ci_high = float(np.percentile(finite, 97.5))
    return BootstrapCI(
        iqm=point_iqm,
        mean=point_mean,
        ci_low=ci_low,
        ci_high=ci_high,
        n_resamples=n_resamples,
    )

compute_hrs_scalar

compute_hrs_scalar(
    vector: HRSVector,
    *,
    weights: dict[str, float] | None = None,
) -> float

Aggregate the HRS vector into a single scalar (ADR-008 §Decision).

Defined as sum(w_i * s_i) / sum(w_i) over the entries in vector — a weighted mean over the surviving axes, with the ADR-008 Option D ordering as default. Returns 0.0 for an empty vector (no surviving axes), which makes a method that failed every ≥20pp test sort to the bottom of the leaderboard.

Parameters:

• vector (HRSVector) –

  Per-axis HRS values from :func:compute_hrs_vector.

• weights (dict[str, float] | None, default: None ) –

  Override the per-axis weight map; if None, the weights embedded in vector.entries are used (so the scalar matches the vector that ships with it).

Returns:

• float –

  Scalar in [0, 1].

Source code in src/chamber/evaluation/hrs.py

def compute_hrs_scalar(
    vector: HRSVector,
    *,
    weights: dict[str, float] | None = None,
) -> float:
    """Aggregate the HRS vector into a single scalar (ADR-008 §Decision).

    Defined as ``sum(w_i * s_i) / sum(w_i)`` over the entries in
    ``vector`` — a weighted mean over the surviving axes, with the
    ADR-008 Option D ordering as default. Returns ``0.0`` for an
    empty vector (no surviving axes), which makes a method that
    failed every ≥20pp test sort to the bottom of the leaderboard.

    Args:
        vector: Per-axis HRS values from :func:`compute_hrs_vector`.
        weights: Override the per-axis weight map; if ``None``, the
            weights embedded in ``vector.entries`` are used (so the
            scalar matches the vector that ships with it).

    Returns:
        Scalar in ``[0, 1]``.
    """
    if not vector.entries:
        return 0.0
    if weights is None:
        weight_seq = [e.weight for e in vector.entries]
    else:
        weight_seq = [weights[e.axis] for e in vector.entries]
    score_seq = [e.score for e in vector.entries]
    weight_total = sum(weight_seq)
    if weight_total <= 0.0:
        return 0.0
    return sum(w * s for w, s in zip(weight_seq, score_seq, strict=True)) / weight_total

compute_hrs_vector

compute_hrs_vector(
    condition_results: dict[str, ConditionResult],
    *,
    weights: dict[str, float] | None = None,
) -> HRSVector

Compute the per-axis HRS vector (ADR-008 §Decision; reviewer P1-8).

The per-axis score is the heterogeneous-side success rate (normalised to [0, 1]). Axes missing from condition_results are not emitted as zero-score entries — ADR-007's axis-survival rule means missing axes are cut from the headline, not silently scored as failure.

Parameters:

• condition_results (dict[str, ConditionResult]) –

  {axis: ConditionResult} covering the surviving ADR-007 axes.

• weights (dict[str, float] | None, default: None ) –

  Override the per-axis weight map; defaults to :data:DEFAULT_AXIS_WEIGHTS (ADR-008 §Decision Option D).

Returns:

• HRSVector –

  class:HRSVector with one entry per axis in the canonical

• HRSVector –

  ADR-008 ordering (CM > PF > CR > SA > OM > AS), filtered to

• HRSVector –

  the axes present in condition_results.

Source code in src/chamber/evaluation/hrs.py

def compute_hrs_vector(
    condition_results: dict[str, ConditionResult],
    *,
    weights: dict[str, float] | None = None,
) -> HRSVector:
    """Compute the per-axis HRS vector (ADR-008 §Decision; reviewer P1-8).

    The per-axis score is the heterogeneous-side success rate
    (normalised to ``[0, 1]``). Axes missing from
    ``condition_results`` are *not* emitted as zero-score entries —
    ADR-007's axis-survival rule means missing axes are cut from the
    headline, not silently scored as failure.

    Args:
        condition_results: ``{axis: ConditionResult}`` covering the
            surviving ADR-007 axes.
        weights: Override the per-axis weight map; defaults to
            :data:`DEFAULT_AXIS_WEIGHTS` (ADR-008 §Decision Option D).

    Returns:
        :class:`HRSVector` with one entry per axis in the canonical
        ADR-008 ordering (CM > PF > CR > SA > OM > AS), filtered to
        the axes present in ``condition_results``.
    """
    chosen_weights = weights if weights is not None else DEFAULT_AXIS_WEIGHTS
    ordered_axes = [a for a in chosen_weights if a in condition_results]
    entries = [
        HRSVectorEntry(
            axis=axis,
            score=float(condition_results[axis].heterogeneous_success),
            gap_pp=float(condition_results[axis].gap_pp),
            weight=float(chosen_weights[axis]),
        )
        for axis in ordered_axes
    ]
    return HRSVector(entries=entries)

load_admission_report

load_admission_report(path: Path) -> AdmissionReport

Load a committed admission_report.json (ADR-027 §Admission protocol).

Raises ValueError when the payload carries a different schema_version (the ADR-016 loud-fail convention).

Source code in src/chamber/evaluation/admission.py

def load_admission_report(path: Path) -> AdmissionReport:
    """Load a committed ``admission_report.json`` (ADR-027 §Admission protocol).

    Raises ``ValueError`` when the payload carries a different
    ``schema_version`` (the ADR-016 loud-fail convention).
    """
    payload = json.loads(path.read_text(encoding="utf-8"))
    version = payload.get("schema_version") if isinstance(payload, dict) else None
    if version != ADMISSION_REPORT_SCHEMA_VERSION:
        msg = (
            f"{path}: admission-report schema_version {version!r} != "
            f"{ADMISSION_REPORT_SCHEMA_VERSION}"
        )
        raise ValueError(msg)
    return AdmissionReport.model_validate(payload)

load_prereg

load_prereg(path: Path) -> PreregistrationSpec

Load and validate a pre-registration YAML (ADR-007 §Discipline).

Parameters:

• path (Path) –

  Absolute path to the YAML file.

Returns:

• PreregistrationSpec –

  The validated :class:PreregistrationSpec.

Raises:

• FileNotFoundError –

  When path does not exist.

• ValidationError –

  When the YAML payload does not match the schema.

• ValueError –

  When :attr:PreregistrationSpec.axis is not on the ADR-007 §3.4 shortlist.

Source code in src/chamber/evaluation/prereg.py

def load_prereg(path: Path) -> PreregistrationSpec:
    """Load and validate a pre-registration YAML (ADR-007 §Discipline).

    Args:
        path: Absolute path to the YAML file.

    Returns:
        The validated :class:`PreregistrationSpec`.

    Raises:
        FileNotFoundError: When ``path`` does not exist.
        pydantic.ValidationError: When the YAML payload does not
            match the schema.
        ValueError: When :attr:`PreregistrationSpec.axis` is not on
            the ADR-007 §3.4 shortlist.
    """
    raw = path.read_text(encoding="utf-8")
    data = yaml.safe_load(raw) or {}
    spec = PreregistrationSpec.model_validate(data)
    spec.normalised_axis()
    return spec

load_prereg_document

load_prereg_document(path: Path) -> PreregDocument

Load and validate a document-form pre-registration YAML (ADR-028 §Decision 2).

Parameters:

• path (Path) –

  Absolute path to the YAML file.

Returns:

• PreregDocument –

  The validated :class:PreregDocument.

Raises:

• FileNotFoundError –

  When path does not exist.

• ValidationError –

  When the YAML payload does not match the document-form schema (unknown keys fail loudly — extra="forbid").

Source code in src/chamber/evaluation/prereg.py

def load_prereg_document(path: Path) -> PreregDocument:
    """Load and validate a document-form pre-registration YAML (ADR-028 §Decision 2).

    Args:
        path: Absolute path to the YAML file.

    Returns:
        The validated :class:`PreregDocument`.

    Raises:
        FileNotFoundError: When ``path`` does not exist.
        pydantic.ValidationError: When the YAML payload does not match
            the document-form schema (unknown keys fail loudly —
            ``extra="forbid"``).
    """
    raw = path.read_text(encoding="utf-8")
    data = yaml.safe_load(raw) or {}
    return PreregDocument.model_validate(data)

load_run_archive

load_run_archive(
    path: str | PathLike[str],
) -> SpikeRun | ResultBundle

Load a result archive, dispatching on schema_version (ADR-028 §Decision 4).

v3 archives (bundle.json) validate as :class:ResultBundle; v1/v2 archives validate as :class:SpikeRun — the read-only compatibility path: v2 archives are readable forever, never migrated in place (invariant I8), and treated as historical inputs with explicitly-absent provenance, never as errors.

Parameters:

• path (str | PathLike[str]) –

  Path to the archive JSON file (os.PathLike/str).

Returns:

• A ( SpikeRun | ResultBundle ) –

  class:ResultBundle (v3) or :class:SpikeRun (v1/v2).

Raises:

• ValueError –

  If the file carries no integer schema_version.

• ValidationError –

  If the payload does not match the model its version claims (the ADR-016 loud-fail mode).

Source code in src/chamber/evaluation/results.py

def load_run_archive(path: str | os.PathLike[str]) -> SpikeRun | ResultBundle:
    """Load a result archive, dispatching on ``schema_version`` (ADR-028 §Decision 4).

    v3 archives (``bundle.json``) validate as :class:`ResultBundle`;
    v1/v2 archives validate as :class:`SpikeRun` — the read-only
    compatibility path: v2 archives are readable forever, never
    migrated in place (invariant I8), and treated as historical inputs
    with explicitly-absent provenance, never as errors.

    Args:
        path: Path to the archive JSON file (``os.PathLike``/``str``).

    Returns:
        A :class:`ResultBundle` (v3) or :class:`SpikeRun` (v1/v2).

    Raises:
        ValueError: If the file carries no integer ``schema_version``.
        pydantic.ValidationError: If the payload does not match the
            model its version claims (the ADR-016 loud-fail mode).
    """
    raw = Path(path).read_text(encoding="utf-8")
    payload = json.loads(raw)
    version = payload.get("schema_version") if isinstance(payload, dict) else None
    if not isinstance(version, int):
        msg = f"{path}: no integer schema_version field; not a CHAMBER result archive"
        raise ValueError(msg)
    if version >= _RESULT_BUNDLE_MIN_SCHEMA_VERSION:
        return ResultBundle.model_validate(payload)
    return SpikeRun.model_validate(payload)

make_condition_row

make_condition_row(
    *,
    predictor: str,
    conformal_mode: str,
    vendor_compliance: str | None,
    n_episodes: int,
    violations: int,
    fallback_fires: int,
    oscbf_results: Iterable[OSCBFResult] = (),
) -> ConditionRow

Construct a :class:ConditionRow with slack aggregates wired in (issue #142).

The natural call-site at three_tables.json emission time. Routes the per-step :class:concerto.safety.oscbf.OSCBFResult stream through :func:aggregate_oscbf_slack so the v2 slack columns are populated per the locked ADR-014 §Revision history 2026-05-16 contract. Callers on the EGO_ONLY outer-filter path (the Stage-1a default) pass the default empty tuple and get the schema-v2 0.0 defaults — exactly the behaviour documented on :class:concerto.safety.reporting.ConditionRow.

Parameters:

• predictor (str) –

  "gt" or "pred" (Huriot & Sibai 2025 Table I labels).

• conformal_mode (str) –

  "noLearn" or "Learn".

• vendor_compliance (str | None) –

  ADR-007 rev 3 placeholder; None in Phase-0.

• n_episodes (int) –

  Number of episodes in this condition.

• violations (int) –

  Count of CBF-constraint violations.

• fallback_fires (int) –

  Count of braking-fallback fires.

• oscbf_results (Iterable[OSCBFResult], default: () ) –

  Per-step :class:OSCBFResult stream for the condition. Defaults to an empty tuple — the Stage-1a EGO_ONLY path that does not exercise the OSCBF inner filter (issue #142).

Returns:

• A ( ConditionRow ) –

  class:ConditionRow carrying both the Phase-0 columns and

• ConditionRow –

  the ADR-014 v2 slack aggregates.

Source code in src/chamber/evaluation/oscbf_aggregate.py

def make_condition_row(
    *,
    predictor: str,
    conformal_mode: str,
    vendor_compliance: str | None,
    n_episodes: int,
    violations: int,
    fallback_fires: int,
    oscbf_results: Iterable[OSCBFResult] = (),
) -> ConditionRow:
    """Construct a :class:`ConditionRow` with slack aggregates wired in (issue #142).

    The natural call-site at ``three_tables.json`` emission time. Routes
    the per-step :class:`concerto.safety.oscbf.OSCBFResult` stream through
    :func:`aggregate_oscbf_slack` so the v2 slack columns are populated
    per the locked ADR-014 §Revision history 2026-05-16 contract. Callers
    on the EGO_ONLY outer-filter path (the Stage-1a default) pass the
    default empty tuple and get the schema-v2 ``0.0`` defaults — exactly
    the behaviour documented on
    :class:`concerto.safety.reporting.ConditionRow`.

    Args:
        predictor: ``"gt"`` or ``"pred"`` (Huriot & Sibai 2025 Table I
            labels).
        conformal_mode: ``"noLearn"`` or ``"Learn"``.
        vendor_compliance: ADR-007 rev 3 placeholder; ``None`` in
            Phase-0.
        n_episodes: Number of episodes in this condition.
        violations: Count of CBF-constraint violations.
        fallback_fires: Count of braking-fallback fires.
        oscbf_results: Per-step :class:`OSCBFResult` stream for the
            condition. Defaults to an empty tuple — the Stage-1a
            EGO_ONLY path that does not exercise the OSCBF inner
            filter (issue #142).

    Returns:
        A :class:`ConditionRow` carrying both the Phase-0 columns and
        the ADR-014 v2 slack aggregates.
    """
    aggregate = aggregate_oscbf_slack(oscbf_results)
    return ConditionRow(
        predictor=predictor,
        conformal_mode=conformal_mode,
        vendor_compliance=vendor_compliance,
        n_episodes=n_episodes,
        violations=violations,
        fallback_fires=fallback_fires,
        max_slack=aggregate.max_slack,
        slack_l2=aggregate.slack_l2,
    )

pacluster_bootstrap

pacluster_bootstrap(
    pairs: Iterable[PairedEpisode],
    *,
    n_resamples: int,
    rng: Generator,
) -> BootstrapCI

Paired-cluster bootstrap for the ≥20pp gap test (ADR-007 §Validation criteria).

Pairs are matched on (seed, episode_idx, initial_state_seed) so the homogeneous - heterogeneous delta is computed on the same initial state, removing one of the dominant sources of cross-condition variance. The cluster level is the seed, exactly as in :func:cluster_bootstrap.

Parameters:

• pairs (Iterable[PairedEpisode]) –

  Iterable of :class:PairedEpisode records.

• n_resamples (int) –

  Number of bootstrap resamples.

• rng (Generator) –

  Deterministic np.random.Generator (ADR-002 P6).

Returns:

• BootstrapCI –

  class:BootstrapCI on the per-pair delta (in raw units,

• BootstrapCI –

  not percentage points — the renderer multiplies by 100 when

• BootstrapCI –

  formatting).

Source code in src/chamber/evaluation/bootstrap.py

def pacluster_bootstrap(
    pairs: Iterable[PairedEpisode],
    *,
    n_resamples: int,
    rng: np.random.Generator,
) -> BootstrapCI:
    """Paired-cluster bootstrap for the ≥20pp gap test (ADR-007 §Validation criteria).

    Pairs are matched on ``(seed, episode_idx, initial_state_seed)``
    so the ``homogeneous - heterogeneous`` delta is computed on the
    *same* initial state, removing one of the dominant sources of
    cross-condition variance. The cluster level is the seed, exactly
    as in :func:`cluster_bootstrap`.

    Args:
        pairs: Iterable of :class:`PairedEpisode` records.
        n_resamples: Number of bootstrap resamples.
        rng: Deterministic ``np.random.Generator`` (ADR-002 P6).

    Returns:
        :class:`BootstrapCI` on the per-pair delta (in raw units,
        not percentage points — the renderer multiplies by 100 when
        formatting).
    """
    if n_resamples <= 0:
        msg = f"n_resamples must be positive, got {n_resamples}"
        raise ValueError(msg)

    by_seed: dict[int, list[PairedEpisode]] = {}
    for pair in pairs:
        by_seed.setdefault(pair.seed, []).append(pair)

    all_deltas = np.asarray(
        [p.homogeneous - p.heterogeneous for episodes in by_seed.values() for p in episodes],
        dtype=np.float64,
    )
    point_iqm = _interquartile_mean(all_deltas)
    point_mean = float(np.mean(all_deltas)) if all_deltas.size else float("nan")

    iqm_samples = np.empty(n_resamples, dtype=np.float64)
    for k in range(n_resamples):
        resample = _resample_paired_cluster(by_seed, rng=rng)
        iqm_samples[k] = _interquartile_mean(resample) if resample.size else np.nan

    finite = iqm_samples[np.isfinite(iqm_samples)]
    if finite.size == 0:
        return BootstrapCI(
            iqm=point_iqm,
            mean=point_mean,
            ci_low=float("nan"),
            ci_high=float("nan"),
            n_resamples=n_resamples,
        )
    return BootstrapCI(
        iqm=point_iqm,
        mean=point_mean,
        ci_low=float(np.percentile(finite, 2.5)),
        ci_high=float(np.percentile(finite, 97.5)),
        n_resamples=n_resamples,
    )

render_admission_report_md

render_admission_report_md(
    report: AdmissionReport, spec: AdmissionSpec
) -> str

Render the human-readable admission report (ADR-027 §Admission protocol).

Source code in src/chamber/evaluation/admission.py

def render_admission_report_md(report: AdmissionReport, spec: AdmissionSpec) -> str:
    """Render the human-readable admission report (ADR-027 §Admission protocol)."""
    lines = [
        f"# Admission report — {report.task_id}@v{report.task_version}",
        "",
        f"**Verdict.** `{report.verdict}`",
        "",
        f"- Pre-registration: tag `{report.prereg_git_tag}`, blob `{report.prereg_blob_sha}`",
        f"- Launch commit: `{report.git_sha}`"
        + ("  **[DIRTY — not flip evidence]**" if report.dirty else ""),
        f"- Archive date: {report.date_stamp}",
        f"- Seed extension used: {'yes' if report.seed_extension_used else 'no'}",
        "",
        "## Committed thresholds (ADR-007 §Discipline — fixed before any run)",
        "",
        f"- `tau_solv` = {spec.tau_solv} (A1 success floor, CI lower bound)",
        f"- `stress_limit` = {spec.stress_limit} (A1 stress ceiling on successes)",
        f"- `tau_infeasible` = {spec.tau_infeasible} (A2 success ceiling, CI upper bound)",
        f"- `delta_min` = {spec.delta_min} (A3 reference-minus-blind margin, CI lower bound)",
    ]
    if spec.c_min_ego is not None:
        lines.append(
            f"- `c_min_ego` = {spec.c_min_ego} "
            "(A4 ego-robustness floor, per-partner CI lower bound)"
        )
    lines += [
        f"- seeds = {spec.seeds}, episodes/seed = {spec.episodes_per_seed}, "
        f"extension = {spec.extension_seeds}",
        "",
        "## Checks",
        "",
    ]
    for check in report.checks:
        lines.append(f"### {check.check} — {check.outcome}")
        lines.append("")
        lines.append(f"Criterion: {check.criterion}")
        lines.append("")
        lines.extend(f"- `{key}` = {check.statistics[key]:.6g}" for key in sorted(check.statistics))
        if check.bundles:
            lines.append(f"- bundles: {', '.join(check.bundles)} (each `chamber-eval verify`-able)")
        if check.extended:
            lines.append("- pre-committed seed extension consumed")
        if check.notes:
            lines.append(f"- notes: {check.notes}")
        lines.append("")
    if report.binding_evidence:
        lines.append("## A2 binding evidence — stress on matched successes (ADR-026 §Decision 2)")
        lines.append("")
        lines.extend(
            f"- `{key}` = {report.binding_evidence[key]:.6g}"
            for key in sorted(report.binding_evidence)
        )
        lines.append("")
    if report.ego_robustness_profile:
        lines.append("## A4 instrument robustness — per admitted partner (ADR-027 §Admission A4)")
        lines.append("")
        columns = [
            "n_episodes",
            "success_iqm",
            "success_ci_low",
            "success_ci_high",
            "stress_p90",
            "stress_max",
        ]
        lines.append("| partner | " + " | ".join(f"`{col}`" for col in columns) + " |")
        lines.append("|---" * (len(columns) + 1) + "|")
        for member in sorted(report.ego_robustness_profile):
            stats = report.ego_robustness_profile[member]
            cells = [f"{stats[col]:.6g}" if col in stats else "—" for col in columns]
            lines.append(f"| {member} | " + " | ".join(cells) + " |")
        lines.append("")
    if report.notes:
        lines.append(f"_{report.notes}_")
        lines.append("")
    return "\n".join(lines)

render_leaderboard

render_leaderboard(
    entries: Sequence[LeaderboardEntry],
) -> str

Render the CHAMBER leaderboard (ADR-008 §Decision; reviewer P1-8).

Entries are sorted by hrs_scalar descending. Each method has two rows: the headline row carrying the scalar + aggregate violation / fallback rates, and a sub-row showing the HRS vector as axis: score (weight) pairs. The vector sub-row is unconditional per reviewer P1-8 — entries lacking an HRSVector raise :class:ValueError.

Entries built from a single spike-run archive are tagged [PARTIAL: <axis>] in front of the method name (reviewer P1-3) so a one-axis row is never mistaken for a complete HRS-bundle row (ADR-008 §Decision binds the bundle to the surviving-axis set).

Parameters:

• entries (Sequence[LeaderboardEntry]) –

  Sequence of :class:LeaderboardEntry records.

Returns:

• str –

  Markdown table suitable for embedding in README or

• str –

  leaderboard pages.

Raises:

• ValueError –

  When any entry's :class:HRSVector is empty (no surviving axes) — the leaderboard refuses methods that did not produce a HRS vector per reviewer P1-8.

Source code in src/chamber/evaluation/render.py

def render_leaderboard(entries: Sequence[LeaderboardEntry]) -> str:
    """Render the CHAMBER leaderboard (ADR-008 §Decision; reviewer P1-8).

    Entries are sorted by ``hrs_scalar`` descending. Each method has
    two rows: the headline row carrying the scalar + aggregate
    violation / fallback rates, and a sub-row showing the HRS
    vector as ``axis: score (weight)`` pairs. The vector sub-row is
    *unconditional* per reviewer P1-8 — entries lacking an HRSVector
    raise :class:`ValueError`.

    Entries built from a single spike-run archive are tagged
    ``[PARTIAL: <axis>]`` in front of the method name (reviewer P1-3)
    so a one-axis row is never mistaken for a complete HRS-bundle row
    (ADR-008 §Decision binds the bundle to the surviving-axis set).

    Args:
        entries: Sequence of :class:`LeaderboardEntry` records.

    Returns:
        Markdown table suitable for embedding in README or
        leaderboard pages.

    Raises:
        ValueError: When any entry's :class:`HRSVector` is empty
            (no surviving axes) — the leaderboard refuses methods
            that did not produce a HRS vector per reviewer P1-8.
    """
    for entry in entries:
        if not entry.hrs_vector.entries:
            msg = (
                f"leaderboard entry for method {entry.method_id!r} has an empty HRS vector; "
                "ADR-008 §Decision requires the vector to be emitted unconditionally "
                "(reviewer P1-8)"
            )
            raise ValueError(msg)

    sorted_entries = sorted(entries, key=lambda e: e.hrs_scalar, reverse=True)
    lines: list[str] = [
        "| Rank | Method | HRS scalar | Violation rate | Fallback rate |",
        "| --- | --- | ---: | ---: | ---: |",
    ]
    for rank, entry in enumerate(sorted_entries, start=1):
        if len(entry.spike_runs) == 1:
            partial_axis = entry.hrs_vector.entries[0].axis
            method_label = f"[PARTIAL: {partial_axis}] `{entry.method_id}`"
        else:
            method_label = f"`{entry.method_id}`"
        lines.append(
            f"| {rank} | {method_label} | {entry.hrs_scalar:.3f} "
            f"| {_fmt_pct(entry.violation_rate)} "
            f"| {_fmt_pct(entry.fallback_rate)} |"
        )
        vector_repr = ", ".join(
            f"{e.axis}={e.score:.3f}(w={e.weight:.2f})" for e in entry.hrs_vector.entries
        )
        lines.append(f"|   | ↳ HRS vector | {vector_repr} | | |")
    return "\n".join(lines) + "\n"

render_three_table_safety_report

render_three_table_safety_report(
    report: Mapping[str, Any], *, fmt: str = "markdown"
) -> str

Render the ADR-014 three-table safety report (ADR-014 §Decision).

Consumes the JSON-serialised payload produced by :func:concerto.safety.reporting.emit_three_tables (or any structurally equivalent ThreeTableReport.to_jsonable() output) and emits Markdown or LaTeX. The fallback-fired column in Table 2 is rendered separately from constraint-violation per ADR-014 §Decision and the reviewer P0 review on safety reporting.

Parameters:

• report (Mapping[str, Any]) –

  A dict matching the :class:concerto.safety.reporting.ThreeTableReport to_jsonable() shape (table_1, table_2, table_3).

• fmt (str, default: 'markdown' ) –

  Output format — "markdown" or "latex".

Returns:

• str –

  The rendered three-table report as a string.

Raises:

• ValueError –

  When fmt is not one of the supported formats, or the report dict is missing required keys.

Source code in src/chamber/evaluation/render.py

def render_three_table_safety_report(
    report: Mapping[str, Any],
    *,
    fmt: str = "markdown",
) -> str:
    """Render the ADR-014 three-table safety report (ADR-014 §Decision).

    Consumes the JSON-serialised payload produced by
    :func:`concerto.safety.reporting.emit_three_tables` (or any
    structurally equivalent ``ThreeTableReport.to_jsonable()``
    output) and emits Markdown or LaTeX. The fallback-fired column
    in Table 2 is rendered separately from constraint-violation per
    ADR-014 §Decision and the reviewer P0 review on safety reporting.

    Args:
        report: A dict matching the
            :class:`concerto.safety.reporting.ThreeTableReport`
            ``to_jsonable()`` shape (``table_1``, ``table_2``,
            ``table_3``).
        fmt: Output format — ``"markdown"`` or ``"latex"``.

    Returns:
        The rendered three-table report as a string.

    Raises:
        ValueError: When ``fmt`` is not one of the supported
            formats, or the report dict is missing required keys.
    """
    for key in ("table_1", "table_2", "table_3"):
        if key not in report:
            msg = f"three-table report is missing required key {key!r}"
            raise ValueError(msg)

    if fmt == "markdown":
        return _three_table_markdown(report)
    if fmt == "latex":
        return _three_table_latex(report)
    msg = f"fmt must be one of {{'markdown', 'latex'}}, got {fmt!r}"
    raise ValueError(msg)

run_admission

run_admission(
    spec: AdmissionSpec,
    *,
    out_dir: Path,
    repo_path: Path,
    prereg_path: Path,
    date_stamp: str,
    repro_command: str,
    allow_dirty: bool = False,
    render_backend: str | None = None,
    cell_runner_resolver: Callable[
        [str], Callable[..., CellRun]
    ]
    | None = None,
) -> AdmissionReport

Execute the admission checks and write the archive (ADR-027 §Admission protocol).

Order of operations: the pre-registration gate runs first (tag + blob verification, ADR-007 §Discipline — nothing is measured on a failed gate); the working tree must be clean unless allow_dirty (a dirty report is never flip evidence); then A1 → A2 → A3 — plus A4 iff the spec commits c_min_ego (an instrument-based contrast, ADR-027 §Admission A4) — with the NOT_SOLVABLE short-circuit on A1 failure ("stop before any threshold discussion") and the single pre-committed seed extension on a straddled CI. Every measured cell is written as an ADR-028 v3 bundle under out_dir so chamber-eval verify admits each check independently; the archive is completed by admission_report.json, ADMISSION_REPORT.md, and SHA256SUMS.txt (invariant I8 — the directory must not already contain files).

Parameters:

• spec (AdmissionSpec) –

  The preregistered admission spec.

• out_dir (Path) –

  Admission archive directory to create (spikes/results/admission/<task_id>-<date>/).

• repo_path (Path) –

  Git working tree (prereg tag + provenance source).

• prereg_path (Path) –

  The tag-locked prereg YAML on disk.

• date_stamp (str) –

  Archive date label (caller-supplied; P6 — never sampled here).

• repro_command (str) –

  Exact reproduction invocation for the bundles.

• allow_dirty (bool, default: False ) –

  Tolerate a dirty tree (development only; the report records dirty: true).

• render_backend (str | None, default: None ) –

  Optional render backend forwarded to SAPIEN cell runners ("none" on headless hosts).

• cell_runner_resolver (Callable[[str], Callable[..., CellRun]] | None, default: None ) –

  Test seam; defaults to the :mod:chamber.benchmarks.admission_cells registry.

Returns:

• The ( AdmissionReport ) –

  class:AdmissionReport as written to the archive.

Raises:

• AdmissionError –

  Dirty tree without allow_dirty, non-empty out_dir, wrapped-evidence hash mismatch, or a cell pairing failure.

• PreregistrationError –

  Failed prereg gate (callers map this to exit code 4).

Source code in src/chamber/evaluation/admission.py

def run_admission(
    spec: AdmissionSpec,
    *,
    out_dir: Path,
    repo_path: Path,
    prereg_path: Path,
    date_stamp: str,
    repro_command: str,
    allow_dirty: bool = False,
    render_backend: str | None = None,
    cell_runner_resolver: Callable[[str], Callable[..., CellRun]] | None = None,
) -> AdmissionReport:
    """Execute the admission checks and write the archive (ADR-027 §Admission protocol).

    Order of operations: the pre-registration gate runs first (tag +
    blob verification, ADR-007 §Discipline — nothing is measured on a
    failed gate); the working tree must be clean unless ``allow_dirty``
    (a dirty report is never flip evidence); then A1 → A2 → A3 — plus
    A4 iff the spec commits ``c_min_ego`` (an instrument-based
    contrast, ADR-027 §Admission A4) — with the NOT_SOLVABLE
    short-circuit on A1 failure ("stop before any threshold
    discussion") and the single pre-committed seed extension on a
    straddled CI. Every measured cell is written as an ADR-028 v3
    bundle under ``out_dir`` so ``chamber-eval verify`` admits each
    check independently; the archive is completed by
    ``admission_report.json``, ``ADMISSION_REPORT.md``, and
    ``SHA256SUMS.txt`` (invariant I8 — the directory must not already
    contain files).

    Args:
        spec: The preregistered admission spec.
        out_dir: Admission archive directory to create
            (``spikes/results/admission/<task_id>-<date>/``).
        repo_path: Git working tree (prereg tag + provenance source).
        prereg_path: The tag-locked prereg YAML on disk.
        date_stamp: Archive date label (caller-supplied; P6 — never
            sampled here).
        repro_command: Exact reproduction invocation for the bundles.
        allow_dirty: Tolerate a dirty tree (development only; the
            report records ``dirty: true``).
        render_backend: Optional render backend forwarded to SAPIEN
            cell runners (``"none"`` on headless hosts).
        cell_runner_resolver: Test seam; defaults to the
            :mod:`chamber.benchmarks.admission_cells` registry.

    Returns:
        The :class:`AdmissionReport` as written to the archive.

    Raises:
        AdmissionError: Dirty tree without ``allow_dirty``, non-empty
            ``out_dir``, wrapped-evidence hash mismatch, or a cell
            pairing failure.
        chamber.evaluation.prereg.PreregistrationError: Failed prereg
            gate (callers map this to exit code 4).
    """
    doc = load_prereg_document(prereg_path)
    blob = verify_git_tag(doc, prereg_path, repo_path=repo_path)
    if doc.task_id != spec.task_id or doc.git_tag != spec.git_tag:
        msg = (
            f"prereg document ({doc.task_id!r}, {doc.git_tag!r}) does not match "
            f"the admission spec ({spec.task_id!r}, {spec.git_tag!r})"
        )
        raise AdmissionError(msg)

    provenance = git_provenance(repo_path)
    if provenance.dirty and not allow_dirty:
        msg = (
            f"working tree at {repo_path} is dirty (or git state is unprovable); "
            "an admission report must be traceable to a commit (ADR-028 §Decision 1). "
            "Commit first, or pass allow_dirty for a development run."
        )
        raise AdmissionError(msg)

    out_dir.mkdir(parents=True, exist_ok=True)
    if any(out_dir.iterdir()):
        msg = f"refusing to write admission archive into non-empty {out_dir} (I8)"
        raise AdmissionError(msg)

    ctx = _RunContext(
        spec=spec,
        out_dir=out_dir,
        repo_path=repo_path,
        prereg_path=prereg_path,
        git_sha=provenance.sha,
        dirty=provenance.dirty,
        repro_command=repro_command,
        resolver=cell_runner_resolver or _default_cell_runner_resolver,
        render_backend=render_backend,
    )

    checks: list[CheckReport] = []
    binding_evidence: dict[str, float] = {}

    # ----- A1 — solvability -------------------------------------------------
    a1_report, a1_episodes = _check_a1(ctx)
    checks.append(a1_report)
    if a1_report.outcome == "FAIL":
        return _finalize(
            ctx,
            doc_blob=blob,
            date_stamp=date_stamp,
            checks=checks,
            verdict="NOT_SOLVABLE",
            binding_evidence={},
            notes=(
                "A1 failed at the committed thresholds; A2/A3 were not run "
                "(the ADR-027 short-circuit — thresholds do not move after the fact)."
            ),
        )

    # ----- A2 — two-robot infeasibility + binding evidence ------------------
    binding_evidence = stress_statistics(a1_episodes) if a1_episodes else {}
    a2_report = _check_a2(ctx)
    checks.append(a2_report)

    # ----- A3 — partner-relevance -------------------------------------------
    a3_report = _check_a3(ctx, a1_episodes=a1_episodes)
    checks.append(a3_report)

    # ----- A4 — instrument (ego) robustness (instrument contrasts only) ------
    a4_check: CheckOutcome | None = None
    ego_profile: dict[str, dict[str, float]] | None = None
    if spec.c_min_ego is not None:
        a4_report, ego_profile = _check_a4(ctx)
        checks.append(a4_report)
        a4_check = a4_report.outcome

    verdict = overall_verdict(a1_report.outcome, a2_report.outcome, a3_report.outcome, a4_check)
    return _finalize(
        ctx,
        doc_blob=blob,
        date_stamp=date_stamp,
        checks=checks,
        verdict=verdict,
        binding_evidence=binding_evidence,
        ego_robustness_profile=ego_profile,
        notes="",
    )

verify_git_tag

verify_git_tag(
    spec: PreregistrationSpec | PreregDocument,
    prereg_path: Path,
    *,
    repo_path: Path,
) -> str

Verify the pre-registration matches its git tag (ADR-007 §Discipline).

Confirms (i) the tag exists in the repository and (ii) the blob SHA of prereg_path on disk matches the blob SHA of the same file as stored at the tag. The second check is the lock that catches the "edit-the-YAML-after-launch" anti-pattern: any change to the YAML's bytes after the tag was cut shifts the on-disk blob SHA but not the tagged blob SHA.

Works for both prereg forms (ADR-028 §Decision 2): the check only reads spec.git_tag, which the axis-form and document-form models share.

Parameters:

• spec (PreregistrationSpec | PreregDocument) –

  The loaded :class:PreregistrationSpec or :class:PreregDocument.

• prereg_path (Path) –

  Path to the YAML file on disk (absolute or repo-relative; will be resolved against repo_path).

• repo_path (Path) –

  Root of the git working tree.

Returns:

• str –

  The verified blob SHA (hex digest, 40-char SHA-1).

Raises:

• PreregistrationError –

  When the tag is missing, the file is outside the repo, or the blob SHAs disagree.

Source code in src/chamber/evaluation/prereg.py

def verify_git_tag(
    spec: PreregistrationSpec | PreregDocument,
    prereg_path: Path,
    *,
    repo_path: Path,
) -> str:
    """Verify the pre-registration matches its git tag (ADR-007 §Discipline).

    Confirms (i) the tag exists in the repository and (ii) the blob
    SHA of ``prereg_path`` on disk matches the blob SHA of the same
    file as stored at the tag. The second check is the lock that
    catches the "edit-the-YAML-after-launch" anti-pattern: any change
    to the YAML's bytes after the tag was cut shifts the on-disk
    blob SHA but not the tagged blob SHA.

    Works for both prereg forms (ADR-028 §Decision 2): the check only
    reads ``spec.git_tag``, which the axis-form and document-form
    models share.

    Args:
        spec: The loaded :class:`PreregistrationSpec` or
            :class:`PreregDocument`.
        prereg_path: Path to the YAML file on disk (absolute or
            repo-relative; will be resolved against ``repo_path``).
        repo_path: Root of the git working tree.

    Returns:
        The verified blob SHA (hex digest, 40-char SHA-1).

    Raises:
        PreregistrationError: When the tag is missing, the file is
            outside the repo, or the blob SHAs disagree.
    """
    abs_path = prereg_path if prereg_path.is_absolute() else (repo_path / prereg_path)
    try:
        rel = abs_path.resolve().relative_to(repo_path.resolve())
    except ValueError as exc:
        msg = f"pre-registration path {abs_path} is outside repo {repo_path}"
        raise PreregistrationError(msg) from exc

    try:
        _git("rev-parse", "--verify", f"refs/tags/{spec.git_tag}", repo_path=repo_path)
    except PreregistrationError as exc:
        msg = f"git tag {spec.git_tag!r} does not exist in {repo_path}"
        raise PreregistrationError(msg) from exc

    on_disk = _blob_sha_on_disk(path=abs_path, repo_path=repo_path)
    at_tag = _blob_sha_at_tag(tag=spec.git_tag, file_relpath=str(rel), repo_path=repo_path)
    if on_disk != at_tag:
        msg = (
            f"pre-registration blob SHA mismatch: on-disk {on_disk} != tagged {at_tag} "
            f"(tag={spec.git_tag}, file={rel})"
        )
        raise PreregistrationError(msg)
    return on_disk

chamber.benchmarks

CHAMBER spike runners — Stage 0/1/2/3 benchmark experiments.

Implements the staged heterogeneity-axis spike protocol from ADR-007. Each spike module reads a pre-registered YAML (spikes/preregistration/) and refuses to run if the SHA does not match its git tag (project principle P4).

Chamber-side ego-AHT training-run launcher (T4b.11; ADR-002 §Decisions).

Bridges the method-side :func:concerto.training.ego_aht.train (which intentionally does not import chamber.*) to the concrete env + partner instances that live on the benchmark side. The dependency direction stays clean: chamber.benchmarks.training_runner imports both concerto.* (the algorithm-agnostic loop + config) and chamber.* (the env + partner registry), and orchestrates them.

Public surface:

• :func:build_env — turns an :class:~concerto.training.config.EnvConfig into a concrete env (Phase-0 dispatch table: "mpe_cooperative_push" → :class:MPECooperativePushEnv; "stage0_smoke" is reserved for T4b.3 and raises :class:NotImplementedError until the HARL fork's concerto_env_adapter lands).
• :func:build_partner — turns a :class:~concerto.training.config.PartnerConfig into a frozen partner via :func:chamber.partners.registry.load_partner (ADR-009 §Decision).
• :func:run_training — the end-to-end entry point: builds env, builds partner, calls :func:concerto.training.ego_aht.train, returns the :class:~concerto.training.ego_aht.TrainingResult (P1.04 NamedTuple wrapping the :class:RewardCurve + trained :class:EgoTrainer).

ADR-002 §Decisions / plan/05 §3.5: this module is the natural home for the env-task → env-class dispatch table; concrete env classes live here. M4b-7 will extend the dispatch with the HARL fork's concerto_env_adapter wrapper for stage0_smoke.

build_bounds_for_env

build_bounds_for_env(env: Env[Any, Any]) -> Bounds

Source per-task :class:Bounds from the env (P1.04.5; ADR-006 §Decision).

Delegates to env.build_bounds() when present (:class:chamber.envs.stage1_pickplace.Stage1PickPlaceEnv adds this in P1.04.5); falls back to a sensible default for envs that don't expose the method (Tier-1 fake envs, MPE stand-in).

Parameters:

• env (Env[Any, Any]) –

  A Gymnasium env. The Stage-1b env's :meth:Stage1PickPlaceEnv.build_bounds returns the per-task envelope pinned at construction (cartesian_accel_capacity from PANDA_CARTESIAN_ACCEL_CAPACITY_MS2 = 10.0 m/s²).

Returns:

• Bounds –

  class:concerto.safety.api.Bounds.

Source code in src/chamber/benchmarks/training_runner.py

def build_bounds_for_env(env: gym.Env[Any, Any]) -> Bounds:
    """Source per-task :class:`Bounds` from the env (P1.04.5; ADR-006 §Decision).

    Delegates to ``env.build_bounds()`` when present
    (:class:`chamber.envs.stage1_pickplace.Stage1PickPlaceEnv` adds this
    in P1.04.5); falls back to a sensible default for envs that don't
    expose the method (Tier-1 fake envs, MPE stand-in).

    Args:
        env: A Gymnasium env. The Stage-1b env's
            :meth:`Stage1PickPlaceEnv.build_bounds` returns the per-task
            envelope pinned at construction (cartesian_accel_capacity
            from ``PANDA_CARTESIAN_ACCEL_CAPACITY_MS2 = 10.0 m/s²``).

    Returns:
        :class:`concerto.safety.api.Bounds`.
    """
    from concerto.safety.api import Bounds

    builder = getattr(env, "build_bounds", None)
    if callable(builder):
        return cast("Bounds", builder())
    # Phase-0 fallback for envs without the method (MPE / Tier-1 fakes).
    # Values matched to the Phase-0 empirical-guarantee env (MPE
    # Cooperative-Push); per-task overrides happen via env.build_bounds.
    return Bounds(
        action_linf_component=1.0,
        cartesian_accel_capacity=1.0,
        action_rate=10.0,
        comm_latency_ms=0.0,
        force_limit=50.0,
    )

build_control_models

build_control_models(
    env: Env[Any, Any],
) -> Mapping[str, AgentControlModel]

Build a per-uid :class:AgentControlModel map from an env (ADR-004 §Decision; spike_004A).

Two-tier dispatch (P1.03 / Task B):

1. Env-provided. If the env exposes a callable build_control_models instance method (the contract :class:chamber.envs.stage1_pickplace.Stage1PickPlaceEnv adds in P1.03), delegate to it. The Stage-1b env's method returns a :class:JacobianControlModel for the 7-DOF panda uid with a working Jacobian callable, plus :class:DoubleIntegratorControlModel for the fetch uid — the per-embodiment dispatch lives there because the env knows its own URDF and articulation best (ADR-004 §Decision; ADR-007 §Stage 1b).
2. Default fallback. Read each uid's action_space[uid] Box shape and return a :class:DoubleIntegratorControlModel per uid sized to shape[0]. Phase-0 envs in CHAMBER expose their actions as Cartesian velocities or accelerations (the safety filter's CBF assumes Cartesian acceleration), so the double-integrator identity model is the correct default for the MPE / Stage-0 envs.

Parameters:

• env (Env[Any, Any]) –

  A multi-agent Gymnasium-conformant env. If the env exposes build_control_models, the helper delegates; otherwise it falls back to the default-DI dispatch over env.action_space.spaces.

Returns:

• Mapping[str, AgentControlModel] –

  {uid: AgentControlModel} per uid in

• Mapping[str, AgentControlModel] –

  env.action_space.spaces (or per the env's own

• Mapping[str, AgentControlModel] –

  build_control_models() if delegated).

Raises:

• TypeError –

  If the fallback path is taken and env.action_space is not a :class:gymnasium.spaces.Dict or any action_space[uid] is not a :class:gymnasium.spaces.Box.

• ValueError –

  If the fallback path is taken and any uid's action Box is not 1-D (multi-D action shapes would need a custom control model rather than the double-integrator identity).

Source code in src/chamber/benchmarks/training_runner.py

def build_control_models(env: gym.Env[Any, Any]) -> Mapping[str, AgentControlModel]:
    """Build a per-uid :class:`AgentControlModel` map from an env (ADR-004 §Decision; spike_004A).

    Two-tier dispatch (P1.03 / Task B):

    1. **Env-provided.** If the env exposes a callable
       ``build_control_models`` instance method (the contract
       :class:`chamber.envs.stage1_pickplace.Stage1PickPlaceEnv` adds
       in P1.03), delegate to it. The Stage-1b env's method returns a
       :class:`JacobianControlModel` for the 7-DOF panda uid with a
       working Jacobian callable, plus
       :class:`DoubleIntegratorControlModel` for the fetch uid — the
       per-embodiment dispatch lives there because the env knows its
       own URDF and articulation best (ADR-004 §Decision; ADR-007
       §Stage 1b).
    2. **Default fallback.** Read each uid's ``action_space[uid]`` Box
       shape and return a :class:`DoubleIntegratorControlModel` per uid
       sized to ``shape[0]``. Phase-0 envs in CHAMBER expose their
       actions as Cartesian velocities or accelerations (the safety
       filter's CBF assumes Cartesian acceleration), so the
       double-integrator identity model is the correct default for the
       MPE / Stage-0 envs.

    Args:
        env: A multi-agent Gymnasium-conformant env. If the env
            exposes ``build_control_models``, the helper delegates;
            otherwise it falls back to the default-DI dispatch over
            ``env.action_space.spaces``.

    Returns:
        ``{uid: AgentControlModel}`` per uid in
        ``env.action_space.spaces`` (or per the env's own
        ``build_control_models()`` if delegated).

    Raises:
        TypeError: If the fallback path is taken and
            ``env.action_space`` is not a :class:`gymnasium.spaces.Dict`
            or any ``action_space[uid]`` is not a :class:`gymnasium.spaces.Box`.
        ValueError: If the fallback path is taken and any uid's
            action Box is not 1-D (multi-D action shapes would need a
            custom control model rather than the double-integrator
            identity).
    """
    env_builder = getattr(env, "build_control_models", None)
    if callable(env_builder):
        # Env-side dispatch — Stage-1b path. The env's method is
        # responsible for sizing each uid's model correctly (panda gets
        # JacobianControlModel with a working jacobian_fn; fetch gets
        # DoubleIntegratorControlModel sized to the action space).
        # pyright sees getattr's return as ``object``; the cast pins
        # the contract Stage1PickPlaceEnv.build_control_models honours.
        return cast("Mapping[str, AgentControlModel]", env_builder())
    action_space = env.action_space
    if not isinstance(action_space, gym.spaces.Dict):
        msg = (
            "build_control_models requires env.action_space to be a "
            f"gym.spaces.Dict; got {type(action_space).__name__}."
        )
        raise TypeError(msg)
    control_models: dict[str, AgentControlModel] = {}
    for uid, sub in action_space.spaces.items():
        if not isinstance(sub, gym.spaces.Box):
            msg = f"action_space[{uid!r}] must be a gym.spaces.Box; got {type(sub).__name__}."
            raise TypeError(msg)
        if len(sub.shape) != 1:
            msg = (
                f"action_space[{uid!r}].shape={sub.shape} is not 1-D; "
                "non-1-D actions require a custom AgentControlModel rather "
                "than the DoubleIntegratorControlModel default."
            )
            raise ValueError(msg)
        model: AgentControlModel = DoubleIntegratorControlModel(
            uid=uid, action_dim=int(sub.shape[0])
        )
        control_models[uid] = model
    return control_models

build_emergency_controllers

build_emergency_controllers(
    env: Env[Any, Any],
) -> dict[str, EmergencyController]

Build per-uid emergency-controller dispatch for the cell's env (P1.04.6).

ADR-007 §Stage 1b Rev 8: the training-time :func:concerto.safety.braking.maybe_brake call routes each dangerous-pair uid's aggregate repulsion through its :class:~concerto.safety.emergency.EmergencyController to translate the Cartesian vector into a control-space override. Heterogeneous embodiments need heterogeneous controllers:

• 7-DOF panda uids (action_dim != position_dim): dispatch to :class:~concerto.safety.emergency.JacobianEmergencyController with the env-built :class:JacobianControlModel (same instance the outer CBF row uses, so the kinematic convention is configured once at chamber-side wiring time per ADR-004 §Revision history 2026-05-17).
• Double-integrator uids (action_dim == position_dim, fetch / MPE / Stage-0 default): dispatch to :class:~concerto.safety.emergency.CartesianAccelEmergencyController.

Dispatch on :class:JacobianControlModel instance identity rather than on uid strings or action_dim heuristics — the model is the source-of-truth for the embodiment / control-space mapping.

Parameters:

• env (Env[Any, Any]) –

  A multi-agent Gymnasium-conformant env. Must expose build_control_models() (the env-side dispatch) or match the default-DI fallback in :func:build_control_models.

Returns:

• dict[str, EmergencyController] –

  {uid: EmergencyController} for every uid in the cell.

Source code in src/chamber/benchmarks/training_runner.py

def build_emergency_controllers(
    env: gym.Env[Any, Any],
) -> dict[str, EmergencyController]:
    """Build per-uid emergency-controller dispatch for the cell's env (P1.04.6).

    ADR-007 §Stage 1b Rev 8: the training-time
    :func:`concerto.safety.braking.maybe_brake` call routes each
    dangerous-pair uid's aggregate repulsion through its
    :class:`~concerto.safety.emergency.EmergencyController` to translate
    the Cartesian vector into a control-space override. Heterogeneous
    embodiments need heterogeneous controllers:

    - **7-DOF panda uids** (action_dim != position_dim): dispatch to
      :class:`~concerto.safety.emergency.JacobianEmergencyController`
      with the env-built :class:`JacobianControlModel` (same instance
      the outer CBF row uses, so the kinematic convention is configured
      once at chamber-side wiring time per ADR-004 §Revision history
      2026-05-17).
    - **Double-integrator uids** (action_dim == position_dim, fetch /
      MPE / Stage-0 default): dispatch to
      :class:`~concerto.safety.emergency.CartesianAccelEmergencyController`.

    Dispatch on :class:`JacobianControlModel` instance identity rather
    than on ``uid`` strings or ``action_dim`` heuristics — the model is
    the source-of-truth for the embodiment / control-space mapping.

    Args:
        env: A multi-agent Gymnasium-conformant env. Must expose
            ``build_control_models()`` (the env-side dispatch) or match
            the default-DI fallback in :func:`build_control_models`.

    Returns:
        ``{uid: EmergencyController}`` for every uid in the cell.
    """
    from concerto.safety.emergency import (
        CartesianAccelEmergencyController,
        JacobianEmergencyController,
    )

    control_models = build_control_models(env)
    controllers: dict[str, EmergencyController] = {}
    for uid, model in control_models.items():
        if isinstance(model, JacobianControlModel):
            controllers[uid] = JacobianEmergencyController(control_model=model)
        else:
            controllers[uid] = CartesianAccelEmergencyController()
    return controllers

build_env

build_env(env_cfg: EnvConfig, *, root_seed: int) -> EnvLike

Construct the env from :class:EnvConfig (T4b.11; ADR-002 §Decisions; plan/05 §3.5).

Dispatch table:

• "mpe_cooperative_push" → :class:MPECooperativePushEnv (T4b.13's empirical-guarantee env; Phase-0 stand-in).
• "stage0_smoke" → :func:chamber.benchmarks.stage0_smoke_adapter.make_stage0_training_env (T4b.3 / plan/05 §3.4). Constructs the rig-validated ADR-001 3-robot env and adapts it to the :class:~concerto.training.ego_aht.EnvLike shape. Requires a Vulkan-capable GPU.
• "stage1_pickplace" → :func:chamber.envs.stage1_pickplace.make_stage1_pickplace_env (P1.04 / ADR-007 §Stage 1b). The Stage-1b science-evaluation env; panda + fetch / panda + panda_partner tuple. EnvConfig.agent_uids drives the per-condition selection (:func:chamber.envs.stage1_pickplace.resolve_condition resolves via the prereg-driven condition_id table). :class:TrainedPolicyFactory invokes this dispatch from its __call__ body through the chamber-side :func:run_training wrapper. Requires SAPIEN + Vulkan.
• "cocarry" → :func:chamber.envs.cocarry_obs.make_cocarry_training_env (ADR-026 §Decision 4; R-2026-06-B §15 Rung 2). The two-Panda co-carry env wrapped with the ego-state synthesizer for the trainer. EnvConfig.condition_id selects the condition (the Rung-2 cell trains cocarry_matched_panda_pair); single-env only (the matched frozen partner reads env 0). Requires SAPIEN + Vulkan.

Parameters:

• env_cfg (EnvConfig) –

  The validated :class:~concerto.training.config.EnvConfig.

• root_seed (int) –

  Project root seed routed to the env's :func:concerto.training.seeding.derive_substream substream for P6 reproducibility.

Returns:

• EnvLike –

  Concrete env instance satisfying the

• EnvLike –

  class:~concerto.training.ego_aht.EnvLike Protocol.

Raises:

• ValueError –

  If env_cfg.task is not in the dispatch table.

• ChamberEnvCompatibilityError –

  If a SAPIEN-backed env (stage0_smoke / stage1_pickplace) is requested and SAPIEN / Vulkan is unavailable (see ADR-001 §Risks).

Source code in src/chamber/benchmarks/training_runner.py

def build_env(env_cfg: EnvConfig, *, root_seed: int) -> EnvLike:
    """Construct the env from :class:`EnvConfig` (T4b.11; ADR-002 §Decisions; plan/05 §3.5).

    Dispatch table:

    - ``"mpe_cooperative_push"`` → :class:`MPECooperativePushEnv` (T4b.13's
      empirical-guarantee env; Phase-0 stand-in).
    - ``"stage0_smoke"`` → :func:`chamber.benchmarks.stage0_smoke_adapter.make_stage0_training_env`
      (T4b.3 / plan/05 §3.4). Constructs the rig-validated ADR-001
      3-robot env and adapts it to the
      :class:`~concerto.training.ego_aht.EnvLike` shape. Requires a
      Vulkan-capable GPU.
    - ``"stage1_pickplace"`` → :func:`chamber.envs.stage1_pickplace.make_stage1_pickplace_env`
      (P1.04 / ADR-007 §Stage 1b). The Stage-1b science-evaluation env;
      panda + fetch / panda + panda_partner tuple. ``EnvConfig.agent_uids``
      drives the per-condition selection
      (:func:`chamber.envs.stage1_pickplace.resolve_condition` resolves
      via the prereg-driven ``condition_id`` table).
      :class:`TrainedPolicyFactory` invokes this dispatch from its
      ``__call__`` body through the chamber-side
      :func:`run_training` wrapper. Requires SAPIEN + Vulkan.
    - ``"cocarry"`` → :func:`chamber.envs.cocarry_obs.make_cocarry_training_env`
      (ADR-026 §Decision 4; R-2026-06-B §15 Rung 2). The two-Panda
      co-carry env wrapped with the ego-``state`` synthesizer for the
      trainer. ``EnvConfig.condition_id`` selects the condition (the
      Rung-2 cell trains ``cocarry_matched_panda_pair``); single-env
      only (the matched frozen partner reads env 0). Requires SAPIEN +
      Vulkan.

    Args:
        env_cfg: The validated :class:`~concerto.training.config.EnvConfig`.
        root_seed: Project root seed routed to the env's
            :func:`concerto.training.seeding.derive_substream` substream
            for P6 reproducibility.

    Returns:
        Concrete env instance satisfying the
        :class:`~concerto.training.ego_aht.EnvLike` Protocol.

    Raises:
        ValueError: If ``env_cfg.task`` is not in the dispatch table.
        ChamberEnvCompatibilityError: If a SAPIEN-backed env
            (``stage0_smoke`` / ``stage1_pickplace``) is requested and
            SAPIEN / Vulkan is unavailable (see ADR-001 §Risks).
    """
    if env_cfg.mask_partner_obs and env_cfg.task != "cocarry":
        msg = (
            "build_env: EnvConfig.mask_partner_obs=True is only wired for "
            "task='cocarry' (the B-BLIND baseline, ADR-011 §Decision as "
            f"amended); got task={env_cfg.task!r}."
        )
        raise ValueError(msg)
    if env_cfg.task == "mpe_cooperative_push":
        return MPECooperativePushEnv(
            agent_uids=env_cfg.agent_uids,
            episode_length=env_cfg.episode_length,
            root_seed=root_seed,
        )
    if env_cfg.task == "stage0_smoke":
        return make_stage0_training_env(
            agent_uids=env_cfg.agent_uids,
            episode_length=env_cfg.episode_length,
            root_seed=root_seed,
        )
    if env_cfg.task == "stage1_pickplace":
        # Lazy import to keep build_env Tier-1-safe — the Stage-1b env
        # defers ManiSkill / SAPIEN imports to its own factory body
        # (ADR-007 §Stage 1b; Tier-1 import-safety on Vulkan-less hosts).
        from chamber.envs.stage1_pickplace import (
            make_stage1_pickplace_env,
        )

        # The condition_id is required for Stage-1b; the OM-homo vs
        # OM-hetero conditions share the same agent_uids tuple
        # ("panda_wristcam", "fetch"), so the tuple alone is insufficient
        # to disambiguate. EnvConfig.condition_id (P1.04) is the explicit
        # disambiguator: the cfg yaml sets a default; the
        # TrainedPolicyFactory overrides per call from env.condition_id.
        if env_cfg.condition_id is None:
            msg = (
                "build_env: task='stage1_pickplace' requires "
                "EnvConfig.condition_id to be set (one of the four "
                "Stage-1 prereg condition_id strings; see "
                "chamber.envs.stage1_pickplace.resolve_condition). The "
                "cfg yaml's env.condition_id field carries a default; "
                "TrainedPolicyFactory overrides per cell."
            )
            raise ValueError(msg)
        # make_stage1_pickplace_env returns gym.Env[Any, Any]; pyright
        # can't verify the structural EnvLike Protocol from that opaque
        # type. The Stage1PickPlaceEnv class (defined inside the factory
        # body) satisfies EnvLike at runtime (the class has the right
        # reset / step signatures); pin via cast so the dispatch typechecks.
        return cast(
            "EnvLike",
            make_stage1_pickplace_env(
                condition_id=env_cfg.condition_id,
                episode_length=env_cfg.episode_length,
                root_seed=root_seed,
                # P1.05.10 (ADR-007 §Stage 1b regime-alignment): the
                # training-cell parallelisation count. 1 (default)
                # preserves the historical single-env cell; > 1 builds
                # the GPU-parallel cell (ManiSkill physx_cuda) with the
                # chamber-side auto-reset wrapper outermost.
                num_envs=env_cfg.num_envs,
            ),
        )
    if env_cfg.task == "cocarry":
        # Lazy import to keep build_env Tier-1-safe — make_cocarry_training_env
        # defers ManiSkill / SAPIEN imports to the cocarry factory body
        # (ADR-026 §Decision 1; Tier-1 import-safety on Vulkan-less hosts).
        # The synthesizer wrapper supplies obs["agent"][ego_uid]["state"]
        # for the trainer (R-2026-06-B §15 Rung 2).
        from chamber.envs.cocarry_obs import make_cocarry_training_env

        # The condition_id is required: the matched pair vs the single-arm
        # positive-control share the agent_uids tuple, so it disambiguates
        # (see chamber.envs.cocarry.resolve_cocarry_condition). The Rung-2
        # cell trains only the matched condition; the positive-control is a
        # measurement condition, never trained.
        if env_cfg.condition_id is None:
            msg = (
                "build_env: task='cocarry' requires EnvConfig.condition_id to be "
                "set (a co-carry condition_id string; see "
                "chamber.envs.cocarry.resolve_cocarry_condition). The cfg yaml's "
                "env.condition_id carries 'cocarry_matched_panda_pair' as default."
            )
            raise ValueError(msg)
        cocarry_env = make_cocarry_training_env(
            condition_id=env_cfg.condition_id,
            episode_length=env_cfg.episode_length,
            root_seed=root_seed,
            num_envs=env_cfg.num_envs,
        )
        if env_cfg.mask_partner_obs:
            # B-BLIND (ADR-011 §Decision as amended): zero the ego-state
            # partner + coupling slice OUTSIDE the synthesizer — a pure
            # observation transform, no trainer changes. The masked cell
            # trains the same 46-D actor on the blinded interface.
            from chamber.envs.cocarry_blind_mask import CoCarryEgoBlindMask

            cocarry_env = CoCarryEgoBlindMask(cocarry_env)
        return cast("EnvLike", cocarry_env)
    raise ValueError(
        f"Unknown env task {env_cfg.task!r}; supported: "
        "'mpe_cooperative_push', 'stage0_smoke', 'stage1_pickplace', 'cocarry'."
    )

build_partner

build_partner(partner_cfg: PartnerConfig) -> PartnerLike

Construct the frozen partner from :class:PartnerConfig (ADR-009 §Decision).

Builds a :class:~chamber.partners.api.PartnerSpec from the config fields and routes through :func:chamber.partners.registry.load_partner so the M4a registry's loud-fail contract (KeyError listing known classes) applies uniformly.

Parameters:

• partner_cfg (PartnerConfig) –

  The validated :class:~concerto.training.config.PartnerConfig.

Returns:

• PartnerLike –

  Concrete frozen partner satisfying the

• PartnerLike –

  class:~concerto.training.ego_aht.PartnerLike Protocol.

Raises:

• KeyError –

  If partner_cfg.class_name is not registered in :data:chamber.partners.registry._REGISTRY.

Source code in src/chamber/benchmarks/training_runner.py

def build_partner(partner_cfg: PartnerConfig) -> PartnerLike:
    """Construct the frozen partner from :class:`PartnerConfig` (ADR-009 §Decision).

    Builds a :class:`~chamber.partners.api.PartnerSpec` from the config
    fields and routes through :func:`chamber.partners.registry.load_partner`
    so the M4a registry's loud-fail contract (KeyError listing known
    classes) applies uniformly.

    Args:
        partner_cfg: The validated
            :class:`~concerto.training.config.PartnerConfig`.

    Returns:
        Concrete frozen partner satisfying the
        :class:`~concerto.training.ego_aht.PartnerLike` Protocol.

    Raises:
        KeyError: If ``partner_cfg.class_name`` is not registered in
            :data:`chamber.partners.registry._REGISTRY`.
    """
    spec = PartnerSpec(
        class_name=partner_cfg.class_name,
        seed=partner_cfg.seed,
        checkpoint_step=partner_cfg.checkpoint_step,
        weights_uri=partner_cfg.weights_uri,
        extra=dict(partner_cfg.extra),
    )
    return load_partner(spec)

build_safety_dt

build_safety_dt(
    env: Env[Any, Any], *, fallback: float = 0.02
) -> float

Source the control-step dt from the env (P1.04.5; ADR-007 §Stage 1b).

Reads :attr:env.control_timestep (the ManiSkill BaseEnv default; forwarded through the Stage-1b wrapper chain via the :class:Stage1ASStateSynthesizer.__getattr__ forwarder). Falls back to fallback (default 0.02 s — the ManiSkill v3 default) on envs that don't expose control_timestep (Tier-1 fake envs that aren't ManiSkill-backed).

Parameters:

• env (Env[Any, Any]) –

  The cell's env.

• fallback (float, default: 0.02 ) –

  Default dt in seconds when the env has no control_timestep. The training loop's safety wiring uses this for the conformal predictor's lookahead horizon and for the numerical-difference velocity computation in :meth:Stage1PickPlaceEnv.build_agent_snapshots.

Returns:

• float –

  The control-step dt in seconds.

Source code in src/chamber/benchmarks/training_runner.py

def build_safety_dt(env: gym.Env[Any, Any], *, fallback: float = 0.02) -> float:
    """Source the control-step dt from the env (P1.04.5; ADR-007 §Stage 1b).

    Reads :attr:`env.control_timestep` (the ManiSkill BaseEnv default;
    forwarded through the Stage-1b wrapper chain via the
    :class:`Stage1ASStateSynthesizer.__getattr__` forwarder). Falls
    back to ``fallback`` (default 0.02 s — the ManiSkill v3 default)
    on envs that don't expose ``control_timestep`` (Tier-1 fake envs
    that aren't ManiSkill-backed).

    Args:
        env: The cell's env.
        fallback: Default dt in seconds when the env has no
            ``control_timestep``. The training loop's safety wiring
            uses this for the conformal predictor's lookahead horizon
            and for the numerical-difference velocity computation in
            :meth:`Stage1PickPlaceEnv.build_agent_snapshots`.

    Returns:
        The control-step dt in seconds.
    """
    dt = getattr(env, "control_timestep", None)
    if dt is None and hasattr(env, "get_wrapper_attr"):
        try:
            dt = env.get_wrapper_attr("control_timestep")
        except AttributeError:
            dt = None
    if dt is None:
        return fallback
    try:
        return float(dt)
    except (TypeError, ValueError):
        return fallback

build_safety_filter

build_safety_filter(
    env: Env[Any, Any],
) -> EgoOnlySafetyFilter

Construct the CBF-QP outer filter for the cell's env (P1.04.5; ADR-007 §Stage 1b).

Wraps :meth:concerto.safety.cbf_qp.ExpCBFQP.ego_only with the per-uid control-model map sourced from :func:build_control_models (the env's build_control_models() method when present; otherwise the default-DI dispatch). The filter is constructed once per (seed, condition) cell by :class:chamber.benchmarks.stage1_common.TrainedPolicyFactory and handed to :func:concerto.training.ego_aht.train via the safety_filter kwarg.

Construction is cheap (no scene-state assumed); the filter's per-step :meth:filter method is what does the work.

Parameters:

• env (Env[Any, Any]) –

  A multi-agent Gymnasium-conformant env exposing a build_control_models() method (or matching the default- DI dispatch in :func:build_control_models).

Returns:

• EgoOnlySafetyFilter –

  class:concerto.safety.api.EgoOnlySafetyFilter instance.

Source code in src/chamber/benchmarks/training_runner.py

def build_safety_filter(env: gym.Env[Any, Any]) -> EgoOnlySafetyFilter:
    """Construct the CBF-QP outer filter for the cell's env (P1.04.5; ADR-007 §Stage 1b).

    Wraps :meth:`concerto.safety.cbf_qp.ExpCBFQP.ego_only` with the
    per-uid control-model map sourced from
    :func:`build_control_models` (the env's
    ``build_control_models()`` method when present; otherwise the
    default-DI dispatch). The filter is constructed once per
    ``(seed, condition)`` cell by
    :class:`chamber.benchmarks.stage1_common.TrainedPolicyFactory`
    and handed to :func:`concerto.training.ego_aht.train` via the
    ``safety_filter`` kwarg.

    Construction is cheap (no scene-state assumed); the filter's
    per-step :meth:`filter` method is what does the work.

    Args:
        env: A multi-agent Gymnasium-conformant env exposing a
            ``build_control_models()`` method (or matching the default-
            DI dispatch in :func:`build_control_models`).

    Returns:
        :class:`concerto.safety.api.EgoOnlySafetyFilter` instance.
    """
    from concerto.safety.cbf_qp import ExpCBFQP

    control_models = build_control_models(env)
    return ExpCBFQP.ego_only(control_models=control_models)

build_safety_snapshot_builder

build_safety_snapshot_builder(
    env: Env[Any, Any],
) -> (
    Callable[[gym.Env[Any, Any]], dict[str, AgentSnapshot]]
    | None
)

Return the env's build_agent_snapshots method, or None (P1.04.5; ADR-007 §Stage 1b).

The training loop calls the returned callable once per step (when the safety filter is wired) to build the per-uid Cartesian snapshot map the conformal layer consumes. Envs that don't expose build_agent_snapshots return None; the training loop then treats the safety stack as inert (the kwargs validation in :func:concerto.training.ego_aht.train raises if the operator passed a filter without a snapshot builder).

Parameters:

• env (Env[Any, Any]) –

  A Gymnasium env. The Stage-1b env's :meth:Stage1PickPlaceEnv.build_agent_snapshots returns the per-uid snapshot dict.

Returns:

• Callable[[Env[Any, Any]], dict[str, AgentSnapshot]] | None –

  The bound method or None. The returned callable's signature

• Callable[[Env[Any, Any]], dict[str, AgentSnapshot]] | None –

  is (env) -> dict[str, AgentSnapshot] for symmetry with the

• Callable[[Env[Any, Any]], dict[str, AgentSnapshot]] | None –

  other build_* helpers — implementations may ignore the

• Callable[[Env[Any, Any]], dict[str, AgentSnapshot]] | None –

  env arg if they're bound methods on the env itself.

Source code in src/chamber/benchmarks/training_runner.py

def build_safety_snapshot_builder(
    env: gym.Env[Any, Any],
) -> Callable[[gym.Env[Any, Any]], dict[str, AgentSnapshot]] | None:
    """Return the env's ``build_agent_snapshots`` method, or ``None`` (P1.04.5; ADR-007 §Stage 1b).

    The training loop calls the returned callable once per step (when
    the safety filter is wired) to build the per-uid Cartesian snapshot
    map the conformal layer consumes. Envs that don't expose
    ``build_agent_snapshots`` return ``None``; the training loop then
    treats the safety stack as inert (the kwargs validation in
    :func:`concerto.training.ego_aht.train` raises if the operator
    passed a filter without a snapshot builder).

    Args:
        env: A Gymnasium env. The Stage-1b env's
            :meth:`Stage1PickPlaceEnv.build_agent_snapshots` returns
            the per-uid snapshot dict.

    Returns:
        The bound method or ``None``. The returned callable's signature
        is ``(env) -> dict[str, AgentSnapshot]`` for symmetry with the
        other ``build_*`` helpers — implementations may ignore the
        ``env`` arg if they're bound methods on the env itself.
    """
    builder = getattr(env, "build_agent_snapshots", None)
    if not callable(builder):
        return None

    def _adapter(_env: gym.Env[Any, Any]) -> dict[str, AgentSnapshot]:
        del _env  # builder is bound to the env already.
        return cast("dict[str, AgentSnapshot]", builder())

    return _adapter

run_training

run_training(
    cfg: EgoAHTConfig,
    *,
    trainer_factory: TrainerFactory | None = None,
    repo_root: Path | None = None,
    safety_filter: EgoOnlySafetyFilter | None = None,
    safety_state: SafetyState | None = None,
    safety_bounds: Bounds | None = None,
    safety_snapshot_builder: Callable[
        [EnvLike], dict[str, AgentSnapshot]
    ]
    | None = None,
    safety_dt: float | None = None,
    safety_emergency_controllers: Mapping[
        str, EmergencyController
    ]
    | None = None,
) -> TrainingResult

Build env + partner and run the ego-AHT training loop (T4b.11; ADR-002 §Decisions).

Drives :func:concerto.training.ego_aht.train with the chamber-side env + partner instances. The default trainer_factory is :meth:~chamber.benchmarks.ego_ppo_trainer.EgoPPOTrainer.from_config (M4b-8a / plan/05 §3.5): the HARL-HAPPO-backed ego-PPO trainer that the empirical-guarantee experiment (M4b-8b / T4b.13) measures. Pass trainer_factory=None is therefore a no-op fallback to the learning trainer; callers that explicitly want :class:~concerto.training.ego_aht.RandomEgoTrainer (test fixtures, smoke runs) must construct it and pass it in.

Returns a :class:~concerto.training.ego_aht.TrainingResult NamedTuple (P1.04 / ADR-007 §Stage 1b) carrying both the diagnostic :class:~concerto.training.ego_aht.RewardCurve and the trained :class:~concerto.training.ego_aht.EgoTrainer instance. The trainer is exposed alongside the curve so Phase-1 callers (:class:chamber.benchmarks.stage1_common.TrainedPolicyFactory) can wrap result.trainer.act in a per-cell closure without paying a checkpoint round-trip cost. Pre-P1.04 the return type was the bare :class:RewardCurve; the NamedTuple wrapper is backward-compatible at the tuple-unpack level (curve, trainer = run_training(cfg)).

Parameters:

• cfg (EgoAHTConfig) –

  Validated :class:~concerto.training.config.EgoAHTConfig.

• trainer_factory (TrainerFactory | None, default: None ) –

  Optional :class:~concerto.training.ego_aht.TrainerFactory. None (default) selects the M4b-8a :class:~chamber.benchmarks.ego_ppo_trainer.EgoPPOTrainer via its from_config classmethod.

• repo_root (Path | None, default: None ) –

  Working-tree root for run-metadata provenance.

• safety_filter (EgoOnlySafetyFilter | None, default: None ) –

  Optional CBF-QP outer filter (P1.04.5; ADR-007 §Stage 1b). All five safety kwargs are threaded through to :func:concerto.training.ego_aht.train. The chamber- side :class:chamber.benchmarks.stage1_common.TrainedPolicyFactory constructs them per cell via :meth:_build_safety_for_cell.

• safety_state (SafetyState | None, default: None ) –

  Optional :class:SafetyState (conformal slack vector; mutated in place per step).

• safety_bounds (Bounds | None, default: None ) –

  Optional per-task :class:Bounds.

• safety_snapshot_builder (Callable[[EnvLike], dict[str, AgentSnapshot]] | None, default: None ) –

  Optional callable building the per-uid :class:AgentSnapshot map per step.

• safety_dt (float | None, default: None ) –

  Optional control-step dt in seconds for the predictor lookahead.

• safety_emergency_controllers (Mapping[str, EmergencyController] | None, default: None ) –

  Optional per-uid :class:~concerto.safety.emergency.EmergencyController map (P1.04.6; ADR-007 §Stage 1b Rev 8). Threaded through to :func:concerto.training.ego_aht.train for the in-rollout :func:concerto.safety.braking.maybe_brake call. Built per cell by :class:chamber.benchmarks.stage1_common.TrainedPolicyFactory via :func:build_emergency_controllers.

Returns:

• TrainingResult –

  class:~concerto.training.ego_aht.TrainingResult —

• TrainingResult –

  result.curve is the :class:RewardCurve; result.trainer

• TrainingResult –

  is the trained :class:EgoTrainer instance.

Raises:

• ValueError –

  If the env task is unknown.

• NotImplementedError –

  If the env task is stage0_smoke (deferred).

• KeyError –

  If the partner class is not registered.

Source code in src/chamber/benchmarks/training_runner.py

def run_training(
    cfg: EgoAHTConfig,
    *,
    trainer_factory: TrainerFactory | None = None,
    repo_root: Path | None = None,
    # P1.04.5 / ADR-007 §Stage 1b: safety-stack kwargs threaded through
    # to train(). All-None => pre-P1.04.5 unfiltered behaviour. When
    # cfg.safety.enabled is True the caller must populate all five;
    # train() loud-fails on intent mismatch.
    safety_filter: EgoOnlySafetyFilter | None = None,
    safety_state: SafetyState | None = None,
    safety_bounds: Bounds | None = None,
    safety_snapshot_builder: (Callable[[EnvLike], dict[str, AgentSnapshot]] | None) = None,
    safety_dt: float | None = None,
    # P1.04.6 / ADR-007 §Stage 1b Rev 8: per-uid emergency-controller
    # dispatch for :func:`concerto.safety.braking.maybe_brake`. ``None``
    # falls back to the Cartesian default — correct for double-
    # integrator MPE-stand-in cells but a silent dimension-mismatch
    # foot-gun for the Stage-1b 7-DOF panda uid. Stage-1b callers must
    # populate via :func:`build_emergency_controllers`.
    safety_emergency_controllers: Mapping[str, EmergencyController] | None = None,
) -> TrainingResult:
    """Build env + partner and run the ego-AHT training loop (T4b.11; ADR-002 §Decisions).

    Drives :func:`concerto.training.ego_aht.train` with the chamber-side
    env + partner instances. The default ``trainer_factory`` is
    :meth:`~chamber.benchmarks.ego_ppo_trainer.EgoPPOTrainer.from_config`
    (M4b-8a / plan/05 §3.5): the HARL-HAPPO-backed ego-PPO trainer that
    the empirical-guarantee experiment (M4b-8b / T4b.13) measures.
    Pass ``trainer_factory=None`` is therefore a no-op fallback to the
    learning trainer; callers that explicitly want
    :class:`~concerto.training.ego_aht.RandomEgoTrainer` (test fixtures,
    smoke runs) must construct it and pass it in.

    Returns a :class:`~concerto.training.ego_aht.TrainingResult` NamedTuple
    (P1.04 / ADR-007 §Stage 1b) carrying both the diagnostic
    :class:`~concerto.training.ego_aht.RewardCurve` and the trained
    :class:`~concerto.training.ego_aht.EgoTrainer` instance. The trainer
    is exposed alongside the curve so Phase-1 callers
    (:class:`chamber.benchmarks.stage1_common.TrainedPolicyFactory`) can
    wrap ``result.trainer.act`` in a per-cell closure without paying a
    checkpoint round-trip cost. Pre-P1.04 the return type was the bare
    :class:`RewardCurve`; the NamedTuple wrapper is backward-compatible
    at the tuple-unpack level (``curve, trainer = run_training(cfg)``).

    Args:
        cfg: Validated :class:`~concerto.training.config.EgoAHTConfig`.
        trainer_factory: Optional :class:`~concerto.training.ego_aht.TrainerFactory`.
            ``None`` (default) selects the M4b-8a
            :class:`~chamber.benchmarks.ego_ppo_trainer.EgoPPOTrainer`
            via its ``from_config`` classmethod.
        repo_root: Working-tree root for run-metadata provenance.
        safety_filter: Optional CBF-QP outer filter (P1.04.5; ADR-007
            §Stage 1b). All five safety kwargs are threaded through
            to :func:`concerto.training.ego_aht.train`. The chamber-
            side :class:`chamber.benchmarks.stage1_common.TrainedPolicyFactory`
            constructs them per cell via :meth:`_build_safety_for_cell`.
        safety_state: Optional :class:`SafetyState` (conformal slack
            vector; mutated in place per step).
        safety_bounds: Optional per-task :class:`Bounds`.
        safety_snapshot_builder: Optional callable building the per-uid
            :class:`AgentSnapshot` map per step.
        safety_dt: Optional control-step dt in seconds for the
            predictor lookahead.
        safety_emergency_controllers: Optional per-uid
            :class:`~concerto.safety.emergency.EmergencyController`
            map (P1.04.6; ADR-007 §Stage 1b Rev 8). Threaded through to
            :func:`concerto.training.ego_aht.train` for the in-rollout
            :func:`concerto.safety.braking.maybe_brake` call. Built per
            cell by
            :class:`chamber.benchmarks.stage1_common.TrainedPolicyFactory`
            via :func:`build_emergency_controllers`.

    Returns:
        :class:`~concerto.training.ego_aht.TrainingResult` —
        ``result.curve`` is the :class:`RewardCurve`; ``result.trainer``
        is the trained :class:`EgoTrainer` instance.

    Raises:
        ValueError: If the env task is unknown.
        NotImplementedError: If the env task is ``stage0_smoke`` (deferred).
        KeyError: If the partner class is not registered.
    """
    env = build_env(cfg.env, root_seed=cfg.seed)
    # P1.05.11 (ADR-007 §Stage 1b Rev 18): potential-based settle term
    # around the TRAINING env only, gated on shaping.settle_alpha > 0
    # (default 0 = wrapper never constructed = byte-identical behaviour,
    # ADR-002). Eval envs are built elsewhere and never shaped; the
    # canonical env reward and evaluate() are untouched.
    if cfg.shaping.settle_alpha > 0.0:
        from chamber.envs.stage1_shaping import (
            Stage1SettleShapingWrapper,
        )
        from chamber.envs.stage1_vector import (
            Stage1AutoResetWrapper,
        )

        gym_env = cast("gym.Env[Any, Any]", env)
        if isinstance(gym_env, Stage1AutoResetWrapper):
            # Issue #232 / ADR-007 §Stage 1b Rev 18 boundary convention:
            # the shaping wrapper sits INSIDE the auto-reset wrapper on
            # the vectorised path, so Phi(s') at a truncation boundary
            # reads the actual pre-reset final state (the auto-reset
            # partial reset happens above it). The auto-reset wrapper is
            # stateless, so re-seating it around the shaped chain is
            # equivalent to having built it there.
            gym_env = Stage1AutoResetWrapper(
                Stage1SettleShapingWrapper(
                    gym_env.env,
                    alpha=cfg.shaping.settle_alpha,
                    qvel_cap=cfg.shaping.settle_qvel_cap,
                    gamma=cfg.happo.gamma,
                    ego_uid=cfg.env.agent_uids[0],
                )
            )
        else:
            gym_env = Stage1SettleShapingWrapper(
                gym_env,
                alpha=cfg.shaping.settle_alpha,
                qvel_cap=cfg.shaping.settle_qvel_cap,
                gamma=cfg.happo.gamma,
                ego_uid=cfg.env.agent_uids[0],
            )
        env = cast("EnvLike", gym_env)
    # Co-carry Rung-2 remediation (COCARRY_RUNG2_REMEDIATION_2026-06-16;
    # ADR-026 §Decision 4): policy-invariant transport PBRS around the
    # TRAINING env only, gated on shaping.transport_pbrs_coeff > 0 (default
    # 0 = wrapper never constructed = byte-identical, ADR-002; non-co-carry
    # cells are unaffected). The wrapper reads the env's privileged
    # bar-centroid-to-goal distance (never the obs) and uses the training
    # MDP's gamma (NHR invariance). The canonical env reward + evaluate()
    # are untouched; eval envs are never shaped.
    if cfg.shaping.transport_pbrs_coeff > 0.0:
        from chamber.envs.cocarry_shaping import CoCarryTransportPBRSWrapper

        env = cast(
            "EnvLike",
            CoCarryTransportPBRSWrapper(
                cast("gym.Env[Any, Any]", env),
                coeff=cfg.shaping.transport_pbrs_coeff,
                gamma=cfg.happo.gamma,
            ),
        )
    partner = build_partner(cfg.partner)
    # EXPLORATORY (2026-06-11 homo-static slice §2; default-off,
    # ADR-002): zero-action partner override. Gate-facing runs cannot
    # reach here with the flag set - TrainedPolicyFactory refuses it at
    # construction (the safety-loud-fail pattern).
    if cfg.exploratory.partner_static_override:
        from chamber.partners.exploratory.static_override import (
            ExploratoryStaticPartnerOverride,
        )

        partner = ExploratoryStaticPartnerOverride(partner)
    factory: TrainerFactory = (
        trainer_factory if trainer_factory is not None else EgoPPOTrainer.from_config
    )
    return train(
        cfg,
        env=env,
        partner=partner,
        trainer_factory=factory,
        repo_root=repo_root,
        safety_filter=safety_filter,
        safety_state=safety_state,
        safety_bounds=safety_bounds,
        safety_snapshot_builder=safety_snapshot_builder,
        safety_dt=safety_dt,
        safety_emergency_controllers=safety_emergency_controllers,
    )

Ego-PPO trainer wrapping HARL's HAPPO actor (M4b-8a; ADR-002 §Decisions).

The :class:EgoPPOTrainer is the concrete :class:~concerto.training.ego_aht.EgoTrainer that drives the Phase-0 ego-AHT empirical-guarantee experiment (T4b.13 / plan/05 §3.5). It satisfies the Protocol with a thin layer over HARL's :class:harl.algorithms.actors.happo.HAPPO actor + a hand-rolled MLP critic + a hand-rolled rollout buffer.

Architecture (plan/05 §3.5; ADR-002 §Decisions):

• The HARL fork's :class:harl.algorithms.actors.ego_aht_happo.EgoAHTHAPPO is a thin reference subclass for external researchers; its :meth:from_config body is intentionally :class:NotImplementedError.
• CONCERTO's training run binds :meth:EgoPPOTrainer.from_config instead. The bridge from :class:~concerto.training.config.EgoAHTConfig (project- specific Pydantic) to HARL's 18-key args dict lives here, on the CONCERTO side, where project-specific surfaces belong.
• Rollout / GAE / advantage normalization / PPO update / critic update all run in this module — not in the fork, not via HARL's :class:OnPolicyHARunner. This satisfies the architecture rule in plan/05 §3.5 ("rollout/update logic on the CONCERTO side") and lets the test_advantage_decomposition.py property test compare against a hand-rolled GAE reference without tautology.

Public surface:

• :func:compute_gae — module-level GAE recurrence (ADR-002 §Decisions; Schulman et al. 2016 §6.3). Used both by :class:EgoPPOTrainer and by the property test (T4b.13 / plan/05 §5).
• :func:normalize_advantages — module-level mean/std normalization. Same formula HARL applies inside :meth:HAPPO.train for state_type "EP" (without nan-masking, since the ego is always active in our 2-agent task — documented in the function's docstring).
• :class:EgoPPOTrainer — the trainer.

ADR-002 risk-mitigation #1: the empirical-guarantee assertion in T4b.13 / plan/05 §6 criterion 4 is a trip-wire for the framework choice. Do not change the GAE / normalization / PPO update math without re-running the property test and re-validating the reference implementation against the canonical PPO paper formulation.

EgoPPOTrainer

Ego-PPO trainer wrapping HARL's HAPPO actor (M4b-8a; ADR-002 §Decisions).

Implements the :class:~concerto.training.ego_aht.EgoTrainer Protocol over a HARL :class:HAPPO actor + a hand-rolled :class:_EgoCritic. The training loop in :func:concerto.training.ego_aht.train calls :meth:act per step, :meth:observe per step (with the next obs + reward + done), and :meth:update at every rollout_length boundary. The trainer's internal rollout buffer accumulates (obs, action, log_prob, value, reward, done) tuples between update calls; :meth:update then runs GAE + normalization + a HARL PPO update + a hand-rolled critic update, then clears the buffer.

Determinism caveat (P6 / ADR-002): HARL's :class:DiagGaussian samples actions via :meth:torch.distributions.Normal.sample, which uses torch's global RNG. The trainer seeds that global RNG once at construction time via :func:concerto.training.seeding.derive_substream; this is enough for byte-identical CPU runs at the same seed but means concurrent trainers in the same process would alias each other's draws. Phase-0 runs are single-trainer per process, so this is acceptable.

See plan/05 §3.5 for the architecture rationale (rollout/update logic on the CONCERTO side, not in the fork) and plan/05 §5 for the empirical-guarantee verification contract (T4b.13).

Source code in src/chamber/benchmarks/ego_ppo_trainer.py

class EgoPPOTrainer:
    """Ego-PPO trainer wrapping HARL's HAPPO actor (M4b-8a; ADR-002 §Decisions).

    Implements the :class:`~concerto.training.ego_aht.EgoTrainer` Protocol
    over a HARL :class:`HAPPO` actor + a hand-rolled :class:`_EgoCritic`.
    The training loop in :func:`concerto.training.ego_aht.train` calls
    :meth:`act` per step, :meth:`observe` per step (with the *next* obs +
    reward + done), and :meth:`update` at every ``rollout_length``
    boundary. The trainer's internal rollout buffer accumulates
    ``(obs, action, log_prob, value, reward, done)`` tuples between
    update calls; :meth:`update` then runs GAE + normalization + a HARL
    PPO update + a hand-rolled critic update, then clears the buffer.

    Determinism caveat (P6 / ADR-002): HARL's :class:`DiagGaussian` samples
    actions via :meth:`torch.distributions.Normal.sample`, which uses
    torch's *global* RNG. The trainer seeds that global RNG once at
    construction time via
    :func:`concerto.training.seeding.derive_substream`; this is enough
    for byte-identical CPU runs at the same seed but means concurrent
    trainers in the same process would alias each other's draws.
    Phase-0 runs are single-trainer per process, so this is acceptable.

    See plan/05 §3.5 for the architecture rationale (rollout/update logic
    on the CONCERTO side, not in the fork) and plan/05 §5 for the
    empirical-guarantee verification contract (T4b.13).
    """

    #: Class-level marker for the property test ``test_advantage_decomposition.py``
    #: to assert this trainer routes through the module-level
    #: :func:`compute_gae` + :func:`normalize_advantages` (rather than a
    #: shadow re-implementation). Keeps the test honest if a refactor
    #: ever inlines the GAE math into :meth:`update`.
    USES_MODULE_GAE: ClassVar[bool] = True

    def __init__(
        self,
        *,
        cfg: EgoAHTConfig,
        ego_uid: str,
        ego_obs_space: gym.spaces.Box,  # type: ignore[type-arg]
        ego_act_space: gym.spaces.Box,  # type: ignore[type-arg]
        partner: PartnerLike,
        device: torch.device | None = None,
        logger: structlog.BoundLogger | None = None,
    ) -> None:
        """Build the trainer (M4b-8a; ADR-002 §Decisions; plan/05 §3.5).

        Prefer :meth:`from_config` over direct construction — it derives
        ``ego_obs_space`` and ``ego_act_space`` from the env so the call
        site cannot drift from the env's actual shapes.

        The partner-freeze gate (ADR-009 §Consequences; plan/05 §6 #3)
        runs first, before any tensor allocation: a partner with any
        ``requires_grad=True`` parameter (and no
        :class:`~chamber.partners.interface.PartnerBase` shield blocking
        ``named_parameters`` access) aborts the construction with a
        :class:`ValueError` that names the offending parameter path.

        Args:
            cfg: Validated :class:`~concerto.training.config.EgoAHTConfig`.
                The trainer reads ``cfg.seed``, ``cfg.happo.*``.
            ego_uid: The env-side uid the ego acts on (matches
                ``cfg.env.agent_uids[0]``).
            ego_obs_space: The Box space for the ego's flat state vector.
                Synthesized by :meth:`from_config` from the env's nested
                observation_space.
            ego_act_space: The Box space for the ego's action vector.
                Read directly from ``env.action_space[ego_uid]``.
            partner: The frozen partner instance the ego will be trained
                against. Validated via :func:`_assert_partner_is_frozen`
                before any tensor allocation. The trainer does not retain
                a reference — the partner is consumed by the training
                loop in :func:`concerto.training.ego_aht.train`, not by
                the trainer itself.
            device: Torch device. Defaults to CPU when called directly;
                :meth:`from_config` resolves it from
                :attr:`RuntimeConfig.device` (auto / cpu / cuda / mps)
                via :func:`_resolve_device` and applies the determinism
                flag from :attr:`RuntimeConfig.deterministic_torch` on
                CPU before constructing the trainer (ADR-002 §Decisions;
                plan/08 §4).
            logger: Optional structlog ``BoundLogger`` from
                :func:`concerto.training.logging.bind_run_logger`.
                When non-``None``, every PPO update emits one
                ``event="scalar"`` line per rollout via
                :func:`concerto.training.logging.log_scalars` (with
                ``metric_namespace="train"``) carrying HARL's
                ``policy_loss``, ``dist_entropy``, ``actor_grad_norm``
                + the trainer's locally-computed ``critic_loss``,
                ``approx_kl``, ``clip_fraction``, ``ratio_min/max``,
                advantage stats, and learning rate. Default ``None``
                preserves the pre-P1.05.11 silent-trainer behaviour
                so existing callers (tests, the non-Stage-1b paths)
                see no change.

        Raises:
            ValueError: If ``partner`` exposes a torch parameter with
                ``requires_grad=True`` (ADR-009 §Consequences).
        """
        # ADR-009 §Consequences + plan/05 §6 #3: partner-freeze gate is
        # the first construction step, before any tensor allocation.
        _assert_partner_is_frozen(partner)
        self._device = device or torch.device("cpu")
        self._ego_uid = ego_uid
        self._gamma = cfg.happo.gamma
        self._gae_lambda = cfg.happo.gae_lambda
        self._n_epochs = cfg.happo.n_epochs
        self._batch_size = cfg.happo.batch_size
        self._rollout_length = cfg.happo.rollout_length
        # P1.05.11 / ADR-017: capture PPO clip + learning rate locally so
        # ``update()`` can compute clip_fraction + emit lr per rollout.
        # No behaviour change — these are read-only references to cfg.
        self._clip_param: float = cfg.happo.clip_eps
        self._learning_rate: float = cfg.happo.lr
        # P1.05.11 / ADR-017: optional bound logger from
        # :func:`concerto.training.logging.bind_run_logger`. ``None``
        # (default) preserves the pre-P1.05.11 silent-trainer behaviour.
        # The driver
        # :func:`concerto.training.ego_aht.train` threads its bound
        # logger here via :meth:`from_config`'s ``logger=`` kwarg.
        self._logger: structlog.BoundLogger | None = logger
        # P1.05.11 / ADR-017: global-step counter incremented per
        # :meth:`observe` call (one env step). ``update()`` emits its
        # scalar line at this step so the W&B x-axis matches frames.
        self._global_step: int = 0
        # Seed torch's global RNG. ``derive_substream`` is the project-wide
        # P6 reproducibility entry-point; we cast its 64-bit draw down to
        # int32 because ``torch.manual_seed`` documents 64-bit input but
        # has historically failed silently on values > 2**63 on macOS.
        torch_seed_int = int(
            derive_substream(_TORCH_SUBSTREAM, root_seed=cfg.seed)
            .default_rng()
            .integers(0, 2**31 - 1)
        )
        torch.manual_seed(torch_seed_int)
        self._minibatch_rng: np.random.Generator = derive_substream(
            _MINIBATCH_SUBSTREAM, root_seed=cfg.seed
        ).default_rng()

        harl_args = _build_harl_args(happo=cfg.happo)
        self._harl_args = harl_args
        self._happo: HAPPO = HAPPO(harl_args, ego_obs_space, ego_act_space, self._device)
        obs_dim = int(ego_obs_space.shape[0])
        self._obs_dim = obs_dim
        self._act_dim = int(ego_act_space.shape[0])
        self._critic = _EgoCritic(obs_dim=obs_dim, hidden_dim=cfg.happo.hidden_dim).to(self._device)
        self._critic_optim = torch.optim.Adam(self._critic.parameters(), lr=cfg.happo.lr)

        # Rollout buffer (cleared after each update). Single-env cells
        # buffer scalars per step; vectorised cells (P1.05.10; ADR-007
        # §Stage 1b regime-alignment) buffer per-env vectors per step —
        # :meth:`update` branches on the buffered layout.
        self._buf_obs: list[NDArray[np.float32]] = []
        self._buf_actions: list[NDArray[np.float32]] = []
        self._buf_log_probs: list[NDArray[np.float32]] = []
        self._buf_values: list[float | NDArray[np.float32]] = []
        self._buf_rewards: list[float | NDArray[np.float32]] = []
        # ADR-002 §Decisions + Pardo 2017 / issue #62: terminated and
        # truncated are stored *separately* so :meth:`update` can build a
        # per-step bootstrap target. Treating truncation as termination
        # zeros V(s_next) at every time-limit boundary, biasing advantages
        # and slowing learning 2-3x on time-limit-only envs.
        self._buf_terminated: list[bool | NDArray[np.bool_]] = []
        self._buf_truncated: list[bool | NDArray[np.bool_]] = []
        # V(s_truncated_final) computed via the critic at observe time
        # when a truncation occurs. Indexed parallel to the buffer; unused
        # at non-truncation steps but populated with 0.0 so the array
        # shapes stay aligned.
        self._buf_truncation_bootstraps: list[float | NDArray[np.float32]] = []
        # Pre-step cache (filled by :meth:`act`, consumed by :meth:`observe`).
        self._pending: _PendingStep | None = None
        # Last next-obs (cached by :meth:`observe`) for the critic
        # bootstrap at update time.
        self._last_next_obs: NDArray[np.float32] | None = None

    @classmethod
    def from_config(
        cls,
        cfg: EgoAHTConfig,
        *,
        env: EnvLike,
        partner: PartnerLike,
        ego_uid: str,
        logger: structlog.BoundLogger | None = None,
    ) -> EgoPPOTrainer:
        """Build from :class:`EgoAHTConfig` + a concrete env + the frozen partner.

        ADR-002 §Decisions / ADR-009 §Consequences / plan/05 §3.5 + §6 #3.

        This is the :class:`~concerto.training.ego_aht.TrainerFactory`
        callable that :func:`concerto.training.ego_aht.train` plugs in via
        dependency injection. The factory reads the ego's observation +
        action shapes off the env directly so the trainer's network
        widths cannot drift from what the env actually emits.

        The partner-freeze gate (:func:`_assert_partner_is_frozen`) runs
        first, before any tensor allocation, so a bad partner aborts
        cheaply (plan/05 §6 #3).

        Per plan/05 §3.5 the bridge from :class:`EgoAHTConfig` to HARL's
        args dict lives in this CONCERTO-side module rather than in the
        fork's :meth:`EgoAHTHAPPO.from_config` (which intentionally
        stays :class:`NotImplementedError` — see
        ``scripts/harl-fork-patches/v0.1.0-aht/`` README for the
        role-split rationale).

        Args:
            cfg: Validated :class:`~concerto.training.config.EgoAHTConfig`.
            env: Concrete env satisfying :class:`EnvLike`. Must expose
                ``observation_space["agent"][ego_uid]["state"]`` as a
                :class:`gym.spaces.Box` and ``action_space[ego_uid]``
                as a :class:`gym.spaces.Box`.
            partner: Frozen partner instance the ego will train against.
                Validated by :func:`_assert_partner_is_frozen` as the
                first construction step (ADR-009 §Consequences).
            ego_uid: The env-side uid the ego acts on.
            logger: Optional structlog ``BoundLogger`` from
                :func:`concerto.training.logging.bind_run_logger`.
                P1.05.11 / ADR-017 §Decisions: when supplied, every
                PPO update emits one namespaced ``event="scalar"``
                line. Default ``None`` preserves the pre-P1.05.11
                silent-trainer behaviour. Threaded through
                :class:`~concerto.training.ego_aht.TrainerFactory` by
                the canonical training driver.

        Returns:
            A constructed :class:`EgoPPOTrainer` ready for
            :func:`concerto.training.ego_aht.train`.

        Raises:
            ValueError: If ``partner`` exposes a torch parameter with
                ``requires_grad=True`` (ADR-009 §Consequences).
            TypeError: If the env's ego observation or action space is
                not a :class:`gym.spaces.Box`.
        """
        # ADR-009 §Consequences / plan/05 §6 #3: partner-freeze gate
        # runs first, before any env-space introspection or tensor
        # allocation. A bad partner aborts the construction cheaply.
        _assert_partner_is_frozen(partner)
        env_obs_space = env.observation_space  # type: ignore[attr-defined]
        ego_state_space = env_obs_space["agent"][ego_uid]["state"]
        if not isinstance(ego_state_space, gym.spaces.Box):
            raise TypeError(
                "EgoPPOTrainer.from_config requires "
                f"env.observation_space['agent'][{ego_uid!r}]['state'] to be "
                f"a gym.spaces.Box; got {type(ego_state_space).__name__}."
            )
        env_act_space = env.action_space  # type: ignore[attr-defined]
        ego_act_space = env_act_space[ego_uid]
        if not isinstance(ego_act_space, gym.spaces.Box):
            raise TypeError(
                "EgoPPOTrainer.from_config requires "
                f"env.action_space[{ego_uid!r}] to be a gym.spaces.Box; "
                f"got {type(ego_act_space).__name__}."
            )
        # P1.05.10 (ADR-007 §Stage 1b regime-alignment): vectorised
        # ManiSkill envs expose batched (num_envs, dim) spaces; the
        # actor/critic are sized per env. _per_env_box is the identity
        # for the historical 1-D spaces.
        ego_state_space = _per_env_box(ego_state_space)
        ego_act_space = _per_env_box(ego_act_space)
        device = _resolve_device(cfg.runtime.device)
        if device.type == "cpu" and cfg.runtime.deterministic_torch:
            # CPU determinism is the project's P6 contract (plan/08 §4).
            # Skip on CUDA/MPS where the contract is relaxed because
            # cuDNN / Metal kernels are not bit-deterministic even with
            # this flag.
            _set_torch_determinism(True)
        return cls(
            cfg=cfg,
            ego_uid=ego_uid,
            ego_obs_space=ego_state_space,
            ego_act_space=ego_act_space,
            partner=partner,
            device=device,
            logger=logger,
        )

    def act(
        self,
        obs: Mapping[str, Any],
        *,
        deterministic: bool = False,
    ) -> NDArray[np.floating]:
        """Sample the ego action; cache log-prob + value for :meth:`observe` (ADR-002 §Decisions).

        Caches ``(obs, action, log_prob, value)`` in private state so the
        next call to :meth:`observe` can insert them into the rollout
        buffer with the actual reward + done flag. The pairing relies on
        the contract in :func:`concerto.training.ego_aht.train` (each
        ``act(obs)`` is followed by exactly one
        ``observe(obs_next, reward, done)`` before the next ``act``).

        Args:
            obs: Env obs dict. The ego's flat state vector is read from
                ``obs["agent"][ego_uid]["state"]``.
            deterministic: When ``True``, returns the distribution mode
                instead of a sample. Used by evaluation paths
                (M4b-8b's per-checkpoint deterministic eval).

        Returns:
            The ego action as a length-``act_dim`` float32 array, ready
            to be packed into the env's dict-action.
        """
        flat = _flat_ego_obs(obs, self._ego_uid)
        if flat.ndim == 2:  # noqa: PLR2004 - rank-2 is the vectorised (num_envs, obs_dim) layout
            # P1.05.10 (ADR-007 §Stage 1b regime-alignment): vectorised
            # path — one HARL forward over the whole (num_envs, obs_dim)
            # batch; the action / log-prob / value keep the batch dim
            # so :meth:`observe` can buffer per-env rows.
            n = flat.shape[0]
            rnn_states_b = np.zeros(
                (n, self._harl_args["recurrent_n"], self._harl_args["hidden_sizes"][-1]),
                dtype=np.float32,
            )
            masks_b = np.ones((n, 1), dtype=np.float32)
            with torch.no_grad():
                action_t, log_prob_t, _ = self._happo.get_actions(
                    flat, rnn_states_b, masks_b, None, deterministic
                )
                value_t = self._critic(torch.from_numpy(flat).to(self._device))
            action_b = action_t.detach().cpu().numpy().astype(np.float32)
            log_prob_b = log_prob_t.detach().cpu().numpy().astype(np.float32)
            value_b = value_t.detach().cpu().numpy().reshape(-1).astype(np.float32)
            self._pending = _PendingStep(
                obs=flat, action=action_b, log_prob=log_prob_b, value=value_b
            )
            return action_b
        # HARL expects shape ``(batch, obs_dim)`` and a positional
        # ``(rnn_states, masks)`` even when the policy is feedforward.
        # rnn_states is ignored downstream (use_recurrent_policy=False);
        # masks=1.0 means "do not reset the RNN state" — also a no-op
        # without an RNN. We pass shape-correct placeholders so HARL's
        # internal ``check`` calls accept them.
        obs_t = flat.reshape(1, -1)
        rnn_states = np.zeros(
            (1, self._harl_args["recurrent_n"], self._harl_args["hidden_sizes"][-1]),
            dtype=np.float32,
        )
        masks = np.ones((1, 1), dtype=np.float32)
        with torch.no_grad():
            action_t, log_prob_t, _ = self._happo.get_actions(
                obs_t, rnn_states, masks, None, deterministic
            )
            value_t = self._critic(torch.from_numpy(flat).to(self._device).unsqueeze(0))
        action = action_t.detach().cpu().numpy().squeeze(0).astype(np.float32)
        log_prob = log_prob_t.detach().cpu().numpy().squeeze(0).astype(np.float32)
        value = float(value_t.detach().cpu().numpy().squeeze())
        self._pending = _PendingStep(obs=flat, action=action, log_prob=log_prob, value=value)
        return action

    def observe(
        self,
        obs: Mapping[str, Any],
        reward: Any,  # noqa: ANN401 - scalar float (single-env) or (num_envs,) array/tensor (vectorised; P1.05.10)
        done: Any,  # noqa: ANN401 - scalar bool or (num_envs,) array/tensor
        *,
        truncated: Any = False,  # noqa: ANN401 - scalar bool or (num_envs,) array/tensor
        final_obs: Mapping[str, Any] | None = None,
    ) -> None:
        """Buffer ``(pending, reward, terminated, truncated)`` (ADR-002 §Decisions; Pardo 2017).

        The trainer keeps a single ``(obs, action, log_prob, value)``
        cache — set by :meth:`act` — and pairs it with the
        ``(reward, done, truncated)`` from :meth:`observe`. The post-step
        ``obs`` is also remembered as the bootstrap target for
        :meth:`update`.

        ``done`` keeps the historical "this step ended the episode" meaning
        (terminated OR truncated). ``truncated`` is the new keyword-only
        flag that distinguishes time-limit truncation from true
        termination. The trainer derives
        ``terminated = done and not truncated`` internally; the GAE
        bootstrap then treats truncation correctly per Pardo et al. 2017
        (V(s_truncated_final) flows through, not 0) — see :func:`compute_gae`
        + project issue #62 for the root-cause writeup.

        At truncation boundaries this method calls the critic on the
        post-step obs once to capture V(s_truncated_final); that value
        is later threaded into :func:`compute_gae` as the per-step
        bootstrap target. At non-truncation steps the recorded value is
        ``0.0`` and unused.

        Args:
            obs: Post-step env obs (the obs the env returned after the
                action passed to the most recent :meth:`act` call).
            reward: Per-step ego reward (the env's shared scalar).
            done: ``True`` if the env terminated *or* truncated this step
                (i.e. the loop should reset the env for the next step).
            truncated: ``True`` iff this step ended the episode via
                time-limit truncation (env returned ``truncated=True``).
                Default ``False`` is the conservative legacy behavior —
                callers that don't yet distinguish truncation from
                termination see the historical "treat as terminal"
                semantics.
            final_obs: Vectorised cells only (P1.05.10; ADR-007
                §Stage 1b regime-alignment): the *pre-reset* batched
                obs of this step, surfaced by
                :class:`chamber.envs.stage1_vector.Stage1AutoResetWrapper`
                via ``info["final_observation"]``. Required whenever
                any env truncated this step — the auto-reset wrapper
                has already replaced ``obs`` with the new episode's
                reset obs, so the Pardo truncation bootstrap
                ``V(s_truncated_final)`` must be computed against
                ``final_obs`` instead. Ignored on the single-env path
                (the loop's act-then-observe-then-reset ordering means
                ``obs`` *is* the final obs there).
        """
        pending = self._pending
        if pending is None:
            # No prior :meth:`act` — defensive no-op so the trainer can
            # safely ignore a stray ``observe`` (eg. a pre-rollout
            # bookkeeping call).
            return
        if pending.action.ndim == 2:  # noqa: PLR2004 - rank-2 is the vectorised layout
            self._observe_vectorised(
                obs, reward, done, truncated=truncated, final_obs=final_obs, pending=pending
            )
            return
        terminated = bool(done) and not bool(truncated)
        truncated_b = bool(truncated)
        self._buf_obs.append(pending.obs)
        self._buf_actions.append(pending.action)
        self._buf_log_probs.append(pending.log_prob)
        self._buf_values.append(pending.value)
        self._buf_rewards.append(float(reward))
        self._buf_terminated.append(terminated)
        self._buf_truncated.append(truncated_b)
        next_flat = _flat_ego_obs(obs, self._ego_uid)
        # Capture V(s_truncated_final) eagerly at the boundary. Doing it
        # here (rather than at update time) is the cleanest place because
        # ``next_flat`` is the actual post-step obs of the truncated
        # episode; by update time the training loop has already reset
        # the env, and the per-step "next obs in buffer" at index
        # ``t + 1`` is from the *new* episode. The cost is one extra
        # critic forward pass per truncation boundary.
        if truncated_b and not terminated:
            with torch.no_grad():
                v_trunc = float(
                    self._critic(torch.from_numpy(next_flat).to(self._device).unsqueeze(0))
                    .squeeze()
                    .item()
                )
            self._buf_truncation_bootstraps.append(v_trunc)
        else:
            self._buf_truncation_bootstraps.append(0.0)
        self._last_next_obs = next_flat
        # Clear the pre-step cache so a stray double-observe cannot
        # double-insert the same tuple.
        self._pending = None
        # P1.05.11 / ADR-017: bump the global step counter so the next
        # :meth:`update` emission carries the current frame index.
        self._global_step += 1

    def _observe_vectorised(
        self,
        obs: Mapping[str, Any],
        reward: Any,  # noqa: ANN401 - (num_envs,) array/tensor
        done: Any,  # noqa: ANN401 - (num_envs,) array/tensor
        *,
        truncated: Any,  # noqa: ANN401 - (num_envs,) array/tensor
        final_obs: Mapping[str, Any] | None,
        pending: _PendingStep,
    ) -> None:
        """Buffer one batched step (P1.05.10; ADR-007 §Stage 1b regime-alignment; Pardo 2017).

        The vectorised analogue of the single-env :meth:`observe` body:
        per-env rows are buffered with the batch dim intact (stacked to
        ``(T, num_envs, …)`` at :meth:`update` time), and the Pardo
        truncation bootstrap is computed against ``final_obs`` (the
        pre-reset obs from
        :class:`chamber.envs.stage1_vector.Stage1AutoResetWrapper`)
        for exactly the envs that truncated without terminating.
        """
        n = pending.action.shape[0]
        reward_arr = _to_float_vec(reward, n)
        done_arr = _to_bool_vec(done, n)
        trunc_arr = _to_bool_vec(truncated, n)
        terminated_arr = done_arr & ~trunc_arr
        self._buf_obs.append(pending.obs)
        self._buf_actions.append(pending.action)
        self._buf_log_probs.append(pending.log_prob)
        self._buf_values.append(np.asarray(pending.value, dtype=np.float32))  # type: ignore[arg-type]
        self._buf_rewards.append(reward_arr)  # type: ignore[arg-type]
        self._buf_terminated.append(terminated_arr)  # type: ignore[arg-type]
        self._buf_truncated.append(trunc_arr)  # type: ignore[arg-type]
        bootstraps = np.zeros(n, dtype=np.float32)
        trunc_only = trunc_arr & ~terminated_arr
        if bool(trunc_only.any()):
            if final_obs is None:
                msg = (
                    "EgoPPOTrainer._observe_vectorised: a truncation boundary "
                    "occurred but no final_obs was supplied. Vectorised cells "
                    "must surface the pre-reset obs via "
                    "info['final_observation'] (Stage1AutoResetWrapper) so the "
                    "Pardo truncation bootstrap is computed against the actual "
                    "terminal obs, not the new episode's reset obs "
                    "(issue #62; ADR-007 §Stage 1b regime-alignment)."
                )
                raise ValueError(msg)
            final_flat = _flat_ego_obs(final_obs, self._ego_uid)
            idx = np.nonzero(trunc_only)[0]
            with torch.no_grad():
                v_trunc = (
                    self._critic(torch.from_numpy(final_flat[idx]).to(self._device))
                    .detach()
                    .cpu()
                    .numpy()
                    .reshape(-1)
                )
            bootstraps[idx] = v_trunc.astype(np.float32)
        self._buf_truncation_bootstraps.append(bootstraps)  # type: ignore[arg-type]
        # Post-step obs (for done envs this is the auto-reset obs — only
        # consumed as the rollout-tail bootstrap for *non-boundary* tail
        # envs, where it is the genuine next obs).
        self._last_next_obs = _flat_ego_obs(obs, self._ego_uid)
        self._pending = None
        self._global_step += n

    def _build_next_values(
        self,
        values: NDArray[np.float32],
        terminated: NDArray[np.bool_],
        truncated: NDArray[np.bool_],
        truncation_bootstraps: NDArray[np.float32],
    ) -> NDArray[np.float32]:
        """Per-step ``V(s_{t+1})`` bootstrap target for GAE (Pardo 2017 §4; issue #62).

        Mid-rollout non-boundary steps use ``values[t + 1]``. At
        terminations the bootstrap is ``0`` (true terminal: no value
        after). At truncations it is ``V(s_truncated_final)`` captured
        at observe time. The rollout-tail step (``t = n-1``) follows the
        same three-way rule, with the live critic call against the
        remembered next-obs as the non-boundary tail bootstrap.
        """
        n_steps = values.shape[0]
        next_values = np.zeros(n_steps, dtype=np.float32)
        for t in range(n_steps - 1):
            if terminated[t]:
                next_values[t] = 0.0
            elif truncated[t]:
                next_values[t] = truncation_bootstraps[t]
            else:
                next_values[t] = values[t + 1]
        last_t = n_steps - 1
        if terminated[last_t]:
            next_values[last_t] = 0.0
        elif truncated[last_t]:
            next_values[last_t] = truncation_bootstraps[last_t]
        elif self._last_next_obs is None:
            # Defensive: no remembered next-obs (rollout never observed
            # anything past the last step). Falls back to zero — safe
            # because the rollout will be cleared and the next one starts
            # fresh.
            next_values[last_t] = 0.0
        else:
            with torch.no_grad():
                next_values[last_t] = float(
                    self._critic(
                        torch.from_numpy(self._last_next_obs).to(self._device).unsqueeze(0)
                    )
                    .squeeze()
                    .item()
                )
        return next_values

    def _build_next_values_vectorised(
        self,
        values: NDArray[np.float32],
        terminated: NDArray[np.bool_],
        truncated: NDArray[np.bool_],
        truncation_bootstraps: NDArray[np.float32],
    ) -> NDArray[np.float32]:
        """Per-(step, env) GAE bootstrap targets (P1.05.10; Pardo 2017 §4; issue #62).

        The ``(T, N)`` analogue of :meth:`_build_next_values`: mid-rollout
        non-boundary entries use ``values[t + 1, e]``; terminations
        bootstrap ``0``; truncations use the per-env
        ``V(s_truncated_final)`` captured at observe time from
        ``final_obs``. The rollout-tail row applies the same three-way
        rule, with one batched critic call over the remembered
        ``(N, obs_dim)`` next obs as the non-boundary tail bootstrap.
        """
        n_steps, n_envs = values.shape
        next_values = np.zeros((n_steps, n_envs), dtype=np.float32)
        if n_steps > 1:
            next_values[:-1] = values[1:]
            next_values[:-1][truncated[:-1]] = truncation_bootstraps[:-1][truncated[:-1]]
            next_values[:-1][terminated[:-1]] = 0.0
        last_t = n_steps - 1
        if self._last_next_obs is None:
            tail = np.zeros(n_envs, dtype=np.float32)
        else:
            with torch.no_grad():
                tail = (
                    self._critic(torch.from_numpy(self._last_next_obs).to(self._device))
                    .detach()
                    .cpu()
                    .numpy()
                    .reshape(-1)
                    .astype(np.float32)
                )
        next_values[last_t] = tail
        next_values[last_t][truncated[last_t]] = truncation_bootstraps[last_t][truncated[last_t]]
        next_values[last_t][terminated[last_t]] = 0.0
        return next_values

    def update(self) -> None:  # noqa: PLR0915 - P1.05.11 added metric accumulation; refactor blocked by HARL.update tuple shape
        """Compute GAE; run PPO + critic updates; clear the buffer (ADR-002 §Decisions; Pardo 2017).

        Order of operations (Schulman 2017, lifted to ego-only / frozen-
        partner per plan/05 §3.5):

        1. Build the per-step ``next_values`` bootstrap array (Pardo 2017
           §4): ``V(s_truncated_final_t)`` at truncation boundaries (cached
           at observe time), ``0.0`` at terminations, ``values[t + 1]``
           otherwise; rollout-tail bootstrap at ``t = T - 1`` is the same
           rule applied to ``self._last_next_obs``.
        2. :func:`compute_gae` → raw advantages ``A_t``.
        3. ``returns_t = A_t + V(s_t)`` (the critic regression target).
        4. :func:`normalize_advantages` → normalized ``A_t`` for the
           PPO importance-weighted surrogate loss.
        5. For each of ``n_epochs`` epochs, shuffle indices and walk
           ``actor_num_mini_batch`` minibatches. For each minibatch, build
           the 9-tuple :meth:`HAPPO.update` expects and call it directly
           (skipping :meth:`HAPPO.train`'s buffer-machinery wrapper).
        6. Train the critic on the same minibatch with MSE on returns.
        7. Clear the buffer.

        The ``factor_batch`` argument :meth:`HAPPO.update` requires for
        HAPPO's sequential multi-agent update is set to all ``1.0`` — the
        ego is the only updating agent (ADR-009 §Decision: black-box AHT,
        partner is frozen), so previous-agent importance weights are
        identically 1.
        """
        if not self._buf_rewards:
            return

        vectorised = np.ndim(self._buf_rewards[0]) == 1
        if vectorised:
            # P1.05.10 (ADR-007 §Stage 1b regime-alignment): batched
            # rollout. Stack to (T, N, …), run GAE independently per env
            # column through the SAME module-level compute_gae the
            # property test pins (USES_MODULE_GAE stays honest), then
            # flatten to (T*N, …) for the minibatch sweep.
            rewards_tn = np.stack(self._buf_rewards).astype(np.float32)  # (T, N)
            values_tn = np.stack(self._buf_values).astype(np.float32)
            terminated_tn = np.stack(self._buf_terminated).astype(np.bool_)
            truncated_tn = np.stack(self._buf_truncated).astype(np.bool_)
            bootstraps_tn = np.stack(self._buf_truncation_bootstraps).astype(np.float32)
            next_values_tn = self._build_next_values_vectorised(
                values_tn, terminated_tn, truncated_tn, bootstraps_tn
            )
            boundaries_tn = terminated_tn | truncated_tn
            n_envs = rewards_tn.shape[1]
            raw_adv_tn = np.stack(
                [
                    compute_gae(
                        rewards_tn[:, e],
                        values_tn[:, e],
                        next_values_tn[:, e],
                        boundaries_tn[:, e],
                        gamma=self._gamma,
                        gae_lambda=self._gae_lambda,
                    )
                    for e in range(n_envs)
                ],
                axis=1,
            )
            returns_tn = (raw_adv_tn + values_tn).astype(np.float32)
            rewards = rewards_tn.reshape(-1)
            values = values_tn.reshape(-1)
            raw_advantages = raw_adv_tn.reshape(-1)
            returns = returns_tn.reshape(-1)
            norm_advantages = normalize_advantages(raw_advantages)
            obs_arr = np.stack(self._buf_obs).astype(np.float32).reshape(-1, self._obs_dim)
            actions_arr = np.stack(self._buf_actions).astype(np.float32).reshape(-1, self._act_dim)
            log_probs_arr = (
                np.stack(self._buf_log_probs).astype(np.float32).reshape(obs_arr.shape[0], -1)
            )
        else:
            rewards = np.asarray(self._buf_rewards, dtype=np.float32)
            values = np.asarray(self._buf_values, dtype=np.float32)
            terminated = np.asarray(self._buf_terminated, dtype=np.bool_)
            truncated = np.asarray(self._buf_truncated, dtype=np.bool_)
            truncation_bootstraps = np.asarray(self._buf_truncation_bootstraps, dtype=np.float32)
            next_values = self._build_next_values(
                values, terminated, truncated, truncation_bootstraps
            )
            episode_boundaries = terminated | truncated
            raw_advantages = compute_gae(
                rewards,
                values,
                next_values,
                episode_boundaries,
                gamma=self._gamma,
                gae_lambda=self._gae_lambda,
            )
            returns = (raw_advantages + values).astype(np.float32)
            norm_advantages = normalize_advantages(raw_advantages)

            obs_arr = np.stack(self._buf_obs).astype(np.float32)
            actions_arr = np.stack(self._buf_actions).astype(np.float32)
            log_probs_arr = np.stack(self._buf_log_probs).astype(np.float32)

        n_steps = rewards.shape[0]
        n_minibatches = max(1, n_steps // self._batch_size)
        mb_size = max(1, n_steps // n_minibatches)

        # P1.05.11 / ADR-017: per-update metric accumulators. Sums are
        # mean-reduced post-loop so a single ``log_scalars`` call
        # carries the rollout-aggregated PPO health snapshot. Captured
        # iff a logger is bound — short-circuits the accumulation work
        # otherwise so the silent-trainer path stays free.
        emit_metrics = self._logger is not None
        sum_policy_loss = 0.0
        sum_critic_loss = 0.0
        sum_dist_entropy = 0.0
        sum_grad_norm = 0.0
        sum_approx_kl = 0.0
        sum_clip_fraction = 0.0
        ratio_min_seen = float("inf")
        ratio_max_seen = float("-inf")
        n_updates = 0

        for _epoch in range(self._n_epochs):
            perm = self._minibatch_rng.permutation(n_steps)
            for mb in range(n_minibatches):
                start = mb * mb_size
                end = start + mb_size if mb < n_minibatches - 1 else n_steps
                mb_idx = perm[start:end]
                mb_obs = obs_arr[mb_idx]
                mb_actions = actions_arr[mb_idx]
                mb_old_log_probs = log_probs_arr[mb_idx]
                # HAPPO expects ``adv_targ`` shape ``(mb, 1)``. log-probs
                # for diag-Gaussian are already per-action-dim; HAPPO's
                # action_aggregation="prod" reduces them inside update().
                mb_advantages = norm_advantages[mb_idx].reshape(-1, 1).astype(np.float32)
                this_mb_size = mb_idx.shape[0]
                mb_rnn_states = np.zeros(
                    (
                        this_mb_size,
                        self._harl_args["recurrent_n"],
                        self._harl_args["hidden_sizes"][-1],
                    ),
                    dtype=np.float32,
                )
                mb_masks = np.ones((this_mb_size, 1), dtype=np.float32)
                mb_active_masks = np.ones((this_mb_size, 1), dtype=np.float32)
                # ``factor_batch`` = 1 because the ego is the only updating
                # agent (ADR-009 §Decision); see plan/05 §3.5.
                mb_factor = np.ones((this_mb_size, 1), dtype=np.float32)
                sample = (
                    mb_obs,
                    mb_rnn_states,
                    mb_actions,
                    mb_masks,
                    mb_active_masks,
                    mb_old_log_probs,
                    mb_advantages,
                    None,
                    mb_factor,
                )
                # P1.05.11 / ADR-017: capture HARL's 4-tuple return value.
                # Pre-P1.05.11 the trainer discarded it; commit 3 wires the
                # values through the bound logger. ``imp_weights`` is the
                # PPO importance ratio (exp of new-vs-old log-prob diff).
                policy_loss, dist_entropy, actor_grad_norm, imp_weights = self._happo.update(sample)

                # Critic update: simple MSE regression on returns.
                mb_returns = torch.from_numpy(returns[mb_idx]).to(self._device).float()
                mb_obs_t = torch.from_numpy(mb_obs).to(self._device).float()
                value_pred = self._critic(mb_obs_t).squeeze(-1)
                critic_loss = ((value_pred - mb_returns) ** 2).mean()
                self._critic_optim.zero_grad()
                critic_loss.backward()
                self._critic_optim.step()

                if emit_metrics:
                    # P1.05.11 / ADR-017: per-minibatch metric capture.
                    # Locally compute approx_kl and clip_fraction; HARL
                    # does not expose them. The torch.no_grad() guard
                    # is defensive — these are read-only reductions
                    # against detached tensors.
                    with torch.no_grad():
                        ratio = imp_weights.detach()
                        approx_kl = float(((ratio - 1.0) ** 2).mean().item()) * 0.5
                        clip_fraction = float(
                            ((ratio - 1.0).abs() > self._clip_param).float().mean().item()
                        )
                        r_min = float(ratio.min().item())
                        r_max = float(ratio.max().item())
                    sum_policy_loss += float(policy_loss.detach().item())
                    sum_critic_loss += float(critic_loss.detach().item())
                    sum_dist_entropy += float(dist_entropy.detach().item())
                    sum_grad_norm += float(
                        actor_grad_norm.detach().item()
                        if torch.is_tensor(actor_grad_norm)
                        else actor_grad_norm
                    )
                    sum_approx_kl += approx_kl
                    sum_clip_fraction += clip_fraction
                    ratio_min_seen = min(ratio_min_seen, r_min)
                    ratio_max_seen = max(ratio_max_seen, r_max)
                    n_updates += 1

        # P1.05.11 / ADR-017: emit one ``event="scalar"`` line per
        # ``update()`` call with the rollout-aggregated PPO health snapshot.
        # Skipped when no logger is bound (the existing silent path).
        if emit_metrics and self._logger is not None and n_updates > 0:
            # Lazy import: keeping the structlog helper out of module-top
            # imports preserves the trainer's Tier-1 importability story
            # (the trainer's TYPE_CHECKING block already gates structlog).
            from concerto.training.logging import log_scalars

            log_scalars(
                self._logger,
                step=self._global_step,
                namespace="train",
                policy_loss=sum_policy_loss / n_updates,
                value_loss=sum_critic_loss / n_updates,
                dist_entropy=sum_dist_entropy / n_updates,
                actor_grad_norm=sum_grad_norm / n_updates,
                approx_kl=sum_approx_kl / n_updates,
                clip_fraction=sum_clip_fraction / n_updates,
                ratio_min=ratio_min_seen,
                ratio_max=ratio_max_seen,
                advantage_mean=float(raw_advantages.mean()),
                advantage_std=float(raw_advantages.std()),
                value_mean=float(values.mean()),
                value_std=float(values.std()),
                learning_rate=self._learning_rate,
            )

        # Reset rollout buffer.
        self._buf_obs.clear()
        self._buf_actions.clear()
        self._buf_log_probs.clear()
        self._buf_values.clear()
        self._buf_rewards.clear()
        self._buf_terminated.clear()
        self._buf_truncated.clear()
        self._buf_truncation_bootstraps.clear()
        self._last_next_obs = None

    def state_dict(self) -> dict[str, Any]:
        """Return a flat dict with actor + critic + optimizer states (ADR-002 §Decisions; T4b.12).

        The returned dict is what :func:`concerto.training.checkpoints.save_checkpoint`
        ``torch.save``s to the ``.pt`` artefact. Loading is the dual:
        each component reads its own sub-key off the loaded dict via
        :meth:`load_state_dict`.
        """
        return {
            "actor": self._happo.actor.state_dict(),
            "actor_optim": self._happo.actor_optimizer.state_dict(),
            "critic": self._critic.state_dict(),
            "critic_optim": self._critic_optim.state_dict(),
        }

__init__

__init__(
    *,
    cfg: EgoAHTConfig,
    ego_uid: str,
    ego_obs_space: Box,
    ego_act_space: Box,
    partner: PartnerLike,
    device: device | None = None,
    logger: BoundLogger | None = None,
) -> None

Build the trainer (M4b-8a; ADR-002 §Decisions; plan/05 §3.5).

Prefer :meth:from_config over direct construction — it derives ego_obs_space and ego_act_space from the env so the call site cannot drift from the env's actual shapes.

The partner-freeze gate (ADR-009 §Consequences; plan/05 §6 #3) runs first, before any tensor allocation: a partner with any requires_grad=True parameter (and no :class:~chamber.partners.interface.PartnerBase shield blocking named_parameters access) aborts the construction with a :class:ValueError that names the offending parameter path.

Parameters:

• cfg (EgoAHTConfig) –

  Validated :class:~concerto.training.config.EgoAHTConfig. The trainer reads cfg.seed, cfg.happo.*.

• ego_uid (str) –

  The env-side uid the ego acts on (matches cfg.env.agent_uids[0]).

• ego_obs_space (Box) –

  The Box space for the ego's flat state vector. Synthesized by :meth:from_config from the env's nested observation_space.

• ego_act_space (Box) –

  The Box space for the ego's action vector. Read directly from env.action_space[ego_uid].

• partner (PartnerLike) –

  The frozen partner instance the ego will be trained against. Validated via :func:_assert_partner_is_frozen before any tensor allocation. The trainer does not retain a reference — the partner is consumed by the training loop in :func:concerto.training.ego_aht.train, not by the trainer itself.

• device (device | None, default: None ) –

  Torch device. Defaults to CPU when called directly; :meth:from_config resolves it from :attr:RuntimeConfig.device (auto / cpu / cuda / mps) via :func:_resolve_device and applies the determinism flag from :attr:RuntimeConfig.deterministic_torch on CPU before constructing the trainer (ADR-002 §Decisions; plan/08 §4).

• logger (BoundLogger | None, default: None ) –

  Optional structlog BoundLogger from :func:concerto.training.logging.bind_run_logger. When non-None, every PPO update emits one event="scalar" line per rollout via :func:concerto.training.logging.log_scalars (with metric_namespace="train") carrying HARL's policy_loss, dist_entropy, actor_grad_norm + the trainer's locally-computed critic_loss, approx_kl, clip_fraction, ratio_min/max, advantage stats, and learning rate. Default None preserves the pre-P1.05.11 silent-trainer behaviour so existing callers (tests, the non-Stage-1b paths) see no change.

Raises:

• ValueError –

  If partner exposes a torch parameter with requires_grad=True (ADR-009 §Consequences).

Source code in src/chamber/benchmarks/ego_ppo_trainer.py

def __init__(
    self,
    *,
    cfg: EgoAHTConfig,
    ego_uid: str,
    ego_obs_space: gym.spaces.Box,  # type: ignore[type-arg]
    ego_act_space: gym.spaces.Box,  # type: ignore[type-arg]
    partner: PartnerLike,
    device: torch.device | None = None,
    logger: structlog.BoundLogger | None = None,
) -> None:
    """Build the trainer (M4b-8a; ADR-002 §Decisions; plan/05 §3.5).

    Prefer :meth:`from_config` over direct construction — it derives
    ``ego_obs_space`` and ``ego_act_space`` from the env so the call
    site cannot drift from the env's actual shapes.

    The partner-freeze gate (ADR-009 §Consequences; plan/05 §6 #3)
    runs first, before any tensor allocation: a partner with any
    ``requires_grad=True`` parameter (and no
    :class:`~chamber.partners.interface.PartnerBase` shield blocking
    ``named_parameters`` access) aborts the construction with a
    :class:`ValueError` that names the offending parameter path.

    Args:
        cfg: Validated :class:`~concerto.training.config.EgoAHTConfig`.
            The trainer reads ``cfg.seed``, ``cfg.happo.*``.
        ego_uid: The env-side uid the ego acts on (matches
            ``cfg.env.agent_uids[0]``).
        ego_obs_space: The Box space for the ego's flat state vector.
            Synthesized by :meth:`from_config` from the env's nested
            observation_space.
        ego_act_space: The Box space for the ego's action vector.
            Read directly from ``env.action_space[ego_uid]``.
        partner: The frozen partner instance the ego will be trained
            against. Validated via :func:`_assert_partner_is_frozen`
            before any tensor allocation. The trainer does not retain
            a reference — the partner is consumed by the training
            loop in :func:`concerto.training.ego_aht.train`, not by
            the trainer itself.
        device: Torch device. Defaults to CPU when called directly;
            :meth:`from_config` resolves it from
            :attr:`RuntimeConfig.device` (auto / cpu / cuda / mps)
            via :func:`_resolve_device` and applies the determinism
            flag from :attr:`RuntimeConfig.deterministic_torch` on
            CPU before constructing the trainer (ADR-002 §Decisions;
            plan/08 §4).
        logger: Optional structlog ``BoundLogger`` from
            :func:`concerto.training.logging.bind_run_logger`.
            When non-``None``, every PPO update emits one
            ``event="scalar"`` line per rollout via
            :func:`concerto.training.logging.log_scalars` (with
            ``metric_namespace="train"``) carrying HARL's
            ``policy_loss``, ``dist_entropy``, ``actor_grad_norm``
            + the trainer's locally-computed ``critic_loss``,
            ``approx_kl``, ``clip_fraction``, ``ratio_min/max``,
            advantage stats, and learning rate. Default ``None``
            preserves the pre-P1.05.11 silent-trainer behaviour
            so existing callers (tests, the non-Stage-1b paths)
            see no change.

    Raises:
        ValueError: If ``partner`` exposes a torch parameter with
            ``requires_grad=True`` (ADR-009 §Consequences).
    """
    # ADR-009 §Consequences + plan/05 §6 #3: partner-freeze gate is
    # the first construction step, before any tensor allocation.
    _assert_partner_is_frozen(partner)
    self._device = device or torch.device("cpu")
    self._ego_uid = ego_uid
    self._gamma = cfg.happo.gamma
    self._gae_lambda = cfg.happo.gae_lambda
    self._n_epochs = cfg.happo.n_epochs
    self._batch_size = cfg.happo.batch_size
    self._rollout_length = cfg.happo.rollout_length
    # P1.05.11 / ADR-017: capture PPO clip + learning rate locally so
    # ``update()`` can compute clip_fraction + emit lr per rollout.
    # No behaviour change — these are read-only references to cfg.
    self._clip_param: float = cfg.happo.clip_eps
    self._learning_rate: float = cfg.happo.lr
    # P1.05.11 / ADR-017: optional bound logger from
    # :func:`concerto.training.logging.bind_run_logger`. ``None``
    # (default) preserves the pre-P1.05.11 silent-trainer behaviour.
    # The driver
    # :func:`concerto.training.ego_aht.train` threads its bound
    # logger here via :meth:`from_config`'s ``logger=`` kwarg.
    self._logger: structlog.BoundLogger | None = logger
    # P1.05.11 / ADR-017: global-step counter incremented per
    # :meth:`observe` call (one env step). ``update()`` emits its
    # scalar line at this step so the W&B x-axis matches frames.
    self._global_step: int = 0
    # Seed torch's global RNG. ``derive_substream`` is the project-wide
    # P6 reproducibility entry-point; we cast its 64-bit draw down to
    # int32 because ``torch.manual_seed`` documents 64-bit input but
    # has historically failed silently on values > 2**63 on macOS.
    torch_seed_int = int(
        derive_substream(_TORCH_SUBSTREAM, root_seed=cfg.seed)
        .default_rng()
        .integers(0, 2**31 - 1)
    )
    torch.manual_seed(torch_seed_int)
    self._minibatch_rng: np.random.Generator = derive_substream(
        _MINIBATCH_SUBSTREAM, root_seed=cfg.seed
    ).default_rng()

    harl_args = _build_harl_args(happo=cfg.happo)
    self._harl_args = harl_args
    self._happo: HAPPO = HAPPO(harl_args, ego_obs_space, ego_act_space, self._device)
    obs_dim = int(ego_obs_space.shape[0])
    self._obs_dim = obs_dim
    self._act_dim = int(ego_act_space.shape[0])
    self._critic = _EgoCritic(obs_dim=obs_dim, hidden_dim=cfg.happo.hidden_dim).to(self._device)
    self._critic_optim = torch.optim.Adam(self._critic.parameters(), lr=cfg.happo.lr)

    # Rollout buffer (cleared after each update). Single-env cells
    # buffer scalars per step; vectorised cells (P1.05.10; ADR-007
    # §Stage 1b regime-alignment) buffer per-env vectors per step —
    # :meth:`update` branches on the buffered layout.
    self._buf_obs: list[NDArray[np.float32]] = []
    self._buf_actions: list[NDArray[np.float32]] = []
    self._buf_log_probs: list[NDArray[np.float32]] = []
    self._buf_values: list[float | NDArray[np.float32]] = []
    self._buf_rewards: list[float | NDArray[np.float32]] = []
    # ADR-002 §Decisions + Pardo 2017 / issue #62: terminated and
    # truncated are stored *separately* so :meth:`update` can build a
    # per-step bootstrap target. Treating truncation as termination
    # zeros V(s_next) at every time-limit boundary, biasing advantages
    # and slowing learning 2-3x on time-limit-only envs.
    self._buf_terminated: list[bool | NDArray[np.bool_]] = []
    self._buf_truncated: list[bool | NDArray[np.bool_]] = []
    # V(s_truncated_final) computed via the critic at observe time
    # when a truncation occurs. Indexed parallel to the buffer; unused
    # at non-truncation steps but populated with 0.0 so the array
    # shapes stay aligned.
    self._buf_truncation_bootstraps: list[float | NDArray[np.float32]] = []
    # Pre-step cache (filled by :meth:`act`, consumed by :meth:`observe`).
    self._pending: _PendingStep | None = None
    # Last next-obs (cached by :meth:`observe`) for the critic
    # bootstrap at update time.
    self._last_next_obs: NDArray[np.float32] | None = None

act

act(
    obs: Mapping[str, Any], *, deterministic: bool = False
) -> NDArray[np.floating]

Sample the ego action; cache log-prob + value for :meth:observe (ADR-002 §Decisions).

Caches (obs, action, log_prob, value) in private state so the next call to :meth:observe can insert them into the rollout buffer with the actual reward + done flag. The pairing relies on the contract in :func:concerto.training.ego_aht.train (each act(obs) is followed by exactly one observe(obs_next, reward, done) before the next act).

Parameters:

• obs (Mapping[str, Any]) –

  Env obs dict. The ego's flat state vector is read from obs["agent"][ego_uid]["state"].

• deterministic (bool, default: False ) –

  When True, returns the distribution mode instead of a sample. Used by evaluation paths (M4b-8b's per-checkpoint deterministic eval).

Returns:

• NDArray[floating] –

  The ego action as a length-act_dim float32 array, ready

• NDArray[floating] –

  to be packed into the env's dict-action.

Source code in src/chamber/benchmarks/ego_ppo_trainer.py

def act(
    self,
    obs: Mapping[str, Any],
    *,
    deterministic: bool = False,
) -> NDArray[np.floating]:
    """Sample the ego action; cache log-prob + value for :meth:`observe` (ADR-002 §Decisions).

    Caches ``(obs, action, log_prob, value)`` in private state so the
    next call to :meth:`observe` can insert them into the rollout
    buffer with the actual reward + done flag. The pairing relies on
    the contract in :func:`concerto.training.ego_aht.train` (each
    ``act(obs)`` is followed by exactly one
    ``observe(obs_next, reward, done)`` before the next ``act``).

    Args:
        obs: Env obs dict. The ego's flat state vector is read from
            ``obs["agent"][ego_uid]["state"]``.
        deterministic: When ``True``, returns the distribution mode
            instead of a sample. Used by evaluation paths
            (M4b-8b's per-checkpoint deterministic eval).

    Returns:
        The ego action as a length-``act_dim`` float32 array, ready
        to be packed into the env's dict-action.
    """
    flat = _flat_ego_obs(obs, self._ego_uid)
    if flat.ndim == 2:  # noqa: PLR2004 - rank-2 is the vectorised (num_envs, obs_dim) layout
        # P1.05.10 (ADR-007 §Stage 1b regime-alignment): vectorised
        # path — one HARL forward over the whole (num_envs, obs_dim)
        # batch; the action / log-prob / value keep the batch dim
        # so :meth:`observe` can buffer per-env rows.
        n = flat.shape[0]
        rnn_states_b = np.zeros(
            (n, self._harl_args["recurrent_n"], self._harl_args["hidden_sizes"][-1]),
            dtype=np.float32,
        )
        masks_b = np.ones((n, 1), dtype=np.float32)
        with torch.no_grad():
            action_t, log_prob_t, _ = self._happo.get_actions(
                flat, rnn_states_b, masks_b, None, deterministic
            )
            value_t = self._critic(torch.from_numpy(flat).to(self._device))
        action_b = action_t.detach().cpu().numpy().astype(np.float32)
        log_prob_b = log_prob_t.detach().cpu().numpy().astype(np.float32)
        value_b = value_t.detach().cpu().numpy().reshape(-1).astype(np.float32)
        self._pending = _PendingStep(
            obs=flat, action=action_b, log_prob=log_prob_b, value=value_b
        )
        return action_b
    # HARL expects shape ``(batch, obs_dim)`` and a positional
    # ``(rnn_states, masks)`` even when the policy is feedforward.
    # rnn_states is ignored downstream (use_recurrent_policy=False);
    # masks=1.0 means "do not reset the RNN state" — also a no-op
    # without an RNN. We pass shape-correct placeholders so HARL's
    # internal ``check`` calls accept them.
    obs_t = flat.reshape(1, -1)
    rnn_states = np.zeros(
        (1, self._harl_args["recurrent_n"], self._harl_args["hidden_sizes"][-1]),
        dtype=np.float32,
    )
    masks = np.ones((1, 1), dtype=np.float32)
    with torch.no_grad():
        action_t, log_prob_t, _ = self._happo.get_actions(
            obs_t, rnn_states, masks, None, deterministic
        )
        value_t = self._critic(torch.from_numpy(flat).to(self._device).unsqueeze(0))
    action = action_t.detach().cpu().numpy().squeeze(0).astype(np.float32)
    log_prob = log_prob_t.detach().cpu().numpy().squeeze(0).astype(np.float32)
    value = float(value_t.detach().cpu().numpy().squeeze())
    self._pending = _PendingStep(obs=flat, action=action, log_prob=log_prob, value=value)
    return action

from_config classmethod

from_config(
    cfg: EgoAHTConfig,
    *,
    env: EnvLike,
    partner: PartnerLike,
    ego_uid: str,
    logger: BoundLogger | None = None,
) -> EgoPPOTrainer

Build from :class:EgoAHTConfig + a concrete env + the frozen partner.

ADR-002 §Decisions / ADR-009 §Consequences / plan/05 §3.5 + §6 #3.

This is the :class:~concerto.training.ego_aht.TrainerFactory callable that :func:concerto.training.ego_aht.train plugs in via dependency injection. The factory reads the ego's observation + action shapes off the env directly so the trainer's network widths cannot drift from what the env actually emits.

The partner-freeze gate (:func:_assert_partner_is_frozen) runs first, before any tensor allocation, so a bad partner aborts cheaply (plan/05 §6 #3).

Per plan/05 §3.5 the bridge from :class:EgoAHTConfig to HARL's args dict lives in this CONCERTO-side module rather than in the fork's :meth:EgoAHTHAPPO.from_config (which intentionally stays :class:NotImplementedError — see scripts/harl-fork-patches/v0.1.0-aht/ README for the role-split rationale).

Parameters:

• cfg (EgoAHTConfig) –

  Validated :class:~concerto.training.config.EgoAHTConfig.

• env (EnvLike) –

  Concrete env satisfying :class:EnvLike. Must expose observation_space["agent"][ego_uid]["state"] as a :class:gym.spaces.Box and action_space[ego_uid] as a :class:gym.spaces.Box.

• partner (PartnerLike) –

  Frozen partner instance the ego will train against. Validated by :func:_assert_partner_is_frozen as the first construction step (ADR-009 §Consequences).

• ego_uid (str) –

  The env-side uid the ego acts on.

• logger (BoundLogger | None, default: None ) –

  Optional structlog BoundLogger from :func:concerto.training.logging.bind_run_logger. P1.05.11 / ADR-017 §Decisions: when supplied, every PPO update emits one namespaced event="scalar" line. Default None preserves the pre-P1.05.11 silent-trainer behaviour. Threaded through :class:~concerto.training.ego_aht.TrainerFactory by the canonical training driver.

Returns:

• EgoPPOTrainer –

  A constructed :class:EgoPPOTrainer ready for

• EgoPPOTrainer –

  func:concerto.training.ego_aht.train.

Raises:

• ValueError –

  If partner exposes a torch parameter with requires_grad=True (ADR-009 §Consequences).

• TypeError –

  If the env's ego observation or action space is not a :class:gym.spaces.Box.

Source code in src/chamber/benchmarks/ego_ppo_trainer.py

@classmethod
def from_config(
    cls,
    cfg: EgoAHTConfig,
    *,
    env: EnvLike,
    partner: PartnerLike,
    ego_uid: str,
    logger: structlog.BoundLogger | None = None,
) -> EgoPPOTrainer:
    """Build from :class:`EgoAHTConfig` + a concrete env + the frozen partner.

    ADR-002 §Decisions / ADR-009 §Consequences / plan/05 §3.5 + §6 #3.

    This is the :class:`~concerto.training.ego_aht.TrainerFactory`
    callable that :func:`concerto.training.ego_aht.train` plugs in via
    dependency injection. The factory reads the ego's observation +
    action shapes off the env directly so the trainer's network
    widths cannot drift from what the env actually emits.

    The partner-freeze gate (:func:`_assert_partner_is_frozen`) runs
    first, before any tensor allocation, so a bad partner aborts
    cheaply (plan/05 §6 #3).

    Per plan/05 §3.5 the bridge from :class:`EgoAHTConfig` to HARL's
    args dict lives in this CONCERTO-side module rather than in the
    fork's :meth:`EgoAHTHAPPO.from_config` (which intentionally
    stays :class:`NotImplementedError` — see
    ``scripts/harl-fork-patches/v0.1.0-aht/`` README for the
    role-split rationale).

    Args:
        cfg: Validated :class:`~concerto.training.config.EgoAHTConfig`.
        env: Concrete env satisfying :class:`EnvLike`. Must expose
            ``observation_space["agent"][ego_uid]["state"]`` as a
            :class:`gym.spaces.Box` and ``action_space[ego_uid]``
            as a :class:`gym.spaces.Box`.
        partner: Frozen partner instance the ego will train against.
            Validated by :func:`_assert_partner_is_frozen` as the
            first construction step (ADR-009 §Consequences).
        ego_uid: The env-side uid the ego acts on.
        logger: Optional structlog ``BoundLogger`` from
            :func:`concerto.training.logging.bind_run_logger`.
            P1.05.11 / ADR-017 §Decisions: when supplied, every
            PPO update emits one namespaced ``event="scalar"``
            line. Default ``None`` preserves the pre-P1.05.11
            silent-trainer behaviour. Threaded through
            :class:`~concerto.training.ego_aht.TrainerFactory` by
            the canonical training driver.

    Returns:
        A constructed :class:`EgoPPOTrainer` ready for
        :func:`concerto.training.ego_aht.train`.

    Raises:
        ValueError: If ``partner`` exposes a torch parameter with
            ``requires_grad=True`` (ADR-009 §Consequences).
        TypeError: If the env's ego observation or action space is
            not a :class:`gym.spaces.Box`.
    """
    # ADR-009 §Consequences / plan/05 §6 #3: partner-freeze gate
    # runs first, before any env-space introspection or tensor
    # allocation. A bad partner aborts the construction cheaply.
    _assert_partner_is_frozen(partner)
    env_obs_space = env.observation_space  # type: ignore[attr-defined]
    ego_state_space = env_obs_space["agent"][ego_uid]["state"]
    if not isinstance(ego_state_space, gym.spaces.Box):
        raise TypeError(
            "EgoPPOTrainer.from_config requires "
            f"env.observation_space['agent'][{ego_uid!r}]['state'] to be "
            f"a gym.spaces.Box; got {type(ego_state_space).__name__}."
        )
    env_act_space = env.action_space  # type: ignore[attr-defined]
    ego_act_space = env_act_space[ego_uid]
    if not isinstance(ego_act_space, gym.spaces.Box):
        raise TypeError(
            "EgoPPOTrainer.from_config requires "
            f"env.action_space[{ego_uid!r}] to be a gym.spaces.Box; "
            f"got {type(ego_act_space).__name__}."
        )
    # P1.05.10 (ADR-007 §Stage 1b regime-alignment): vectorised
    # ManiSkill envs expose batched (num_envs, dim) spaces; the
    # actor/critic are sized per env. _per_env_box is the identity
    # for the historical 1-D spaces.
    ego_state_space = _per_env_box(ego_state_space)
    ego_act_space = _per_env_box(ego_act_space)
    device = _resolve_device(cfg.runtime.device)
    if device.type == "cpu" and cfg.runtime.deterministic_torch:
        # CPU determinism is the project's P6 contract (plan/08 §4).
        # Skip on CUDA/MPS where the contract is relaxed because
        # cuDNN / Metal kernels are not bit-deterministic even with
        # this flag.
        _set_torch_determinism(True)
    return cls(
        cfg=cfg,
        ego_uid=ego_uid,
        ego_obs_space=ego_state_space,
        ego_act_space=ego_act_space,
        partner=partner,
        device=device,
        logger=logger,
    )

observe

observe(
    obs: Mapping[str, Any],
    reward: Any,
    done: Any,
    *,
    truncated: Any = False,
    final_obs: Mapping[str, Any] | None = None,
) -> None

Buffer (pending, reward, terminated, truncated) (ADR-002 §Decisions; Pardo 2017).

The trainer keeps a single (obs, action, log_prob, value) cache — set by :meth:act — and pairs it with the (reward, done, truncated) from :meth:observe. The post-step obs is also remembered as the bootstrap target for :meth:update.

done keeps the historical "this step ended the episode" meaning (terminated OR truncated). truncated is the new keyword-only flag that distinguishes time-limit truncation from true termination. The trainer derives terminated = done and not truncated internally; the GAE bootstrap then treats truncation correctly per Pardo et al. 2017 (V(s_truncated_final) flows through, not 0) — see :func:compute_gae + project issue #62 for the root-cause writeup.

At truncation boundaries this method calls the critic on the post-step obs once to capture V(s_truncated_final); that value is later threaded into :func:compute_gae as the per-step bootstrap target. At non-truncation steps the recorded value is 0.0 and unused.

Parameters:

• obs (Mapping[str, Any]) –

  Post-step env obs (the obs the env returned after the action passed to the most recent :meth:act call).

• reward (Any) –

  Per-step ego reward (the env's shared scalar).

• done (Any) –

  True if the env terminated or truncated this step (i.e. the loop should reset the env for the next step).

• truncated (Any, default: False ) –

  True iff this step ended the episode via time-limit truncation (env returned truncated=True). Default False is the conservative legacy behavior — callers that don't yet distinguish truncation from termination see the historical "treat as terminal" semantics.

• final_obs (Mapping[str, Any] | None, default: None ) –

  Vectorised cells only (P1.05.10; ADR-007 §Stage 1b regime-alignment): the pre-reset batched obs of this step, surfaced by :class:chamber.envs.stage1_vector.Stage1AutoResetWrapper via info["final_observation"]. Required whenever any env truncated this step — the auto-reset wrapper has already replaced obs with the new episode's reset obs, so the Pardo truncation bootstrap V(s_truncated_final) must be computed against final_obs instead. Ignored on the single-env path (the loop's act-then-observe-then-reset ordering means obs is the final obs there).

Source code in src/chamber/benchmarks/ego_ppo_trainer.py

def observe(
    self,
    obs: Mapping[str, Any],
    reward: Any,  # noqa: ANN401 - scalar float (single-env) or (num_envs,) array/tensor (vectorised; P1.05.10)
    done: Any,  # noqa: ANN401 - scalar bool or (num_envs,) array/tensor
    *,
    truncated: Any = False,  # noqa: ANN401 - scalar bool or (num_envs,) array/tensor
    final_obs: Mapping[str, Any] | None = None,
) -> None:
    """Buffer ``(pending, reward, terminated, truncated)`` (ADR-002 §Decisions; Pardo 2017).

    The trainer keeps a single ``(obs, action, log_prob, value)``
    cache — set by :meth:`act` — and pairs it with the
    ``(reward, done, truncated)`` from :meth:`observe`. The post-step
    ``obs`` is also remembered as the bootstrap target for
    :meth:`update`.

    ``done`` keeps the historical "this step ended the episode" meaning
    (terminated OR truncated). ``truncated`` is the new keyword-only
    flag that distinguishes time-limit truncation from true
    termination. The trainer derives
    ``terminated = done and not truncated`` internally; the GAE
    bootstrap then treats truncation correctly per Pardo et al. 2017
    (V(s_truncated_final) flows through, not 0) — see :func:`compute_gae`
    + project issue #62 for the root-cause writeup.

    At truncation boundaries this method calls the critic on the
    post-step obs once to capture V(s_truncated_final); that value
    is later threaded into :func:`compute_gae` as the per-step
    bootstrap target. At non-truncation steps the recorded value is
    ``0.0`` and unused.

    Args:
        obs: Post-step env obs (the obs the env returned after the
            action passed to the most recent :meth:`act` call).
        reward: Per-step ego reward (the env's shared scalar).
        done: ``True`` if the env terminated *or* truncated this step
            (i.e. the loop should reset the env for the next step).
        truncated: ``True`` iff this step ended the episode via
            time-limit truncation (env returned ``truncated=True``).
            Default ``False`` is the conservative legacy behavior —
            callers that don't yet distinguish truncation from
            termination see the historical "treat as terminal"
            semantics.
        final_obs: Vectorised cells only (P1.05.10; ADR-007
            §Stage 1b regime-alignment): the *pre-reset* batched
            obs of this step, surfaced by
            :class:`chamber.envs.stage1_vector.Stage1AutoResetWrapper`
            via ``info["final_observation"]``. Required whenever
            any env truncated this step — the auto-reset wrapper
            has already replaced ``obs`` with the new episode's
            reset obs, so the Pardo truncation bootstrap
            ``V(s_truncated_final)`` must be computed against
            ``final_obs`` instead. Ignored on the single-env path
            (the loop's act-then-observe-then-reset ordering means
            ``obs`` *is* the final obs there).
    """
    pending = self._pending
    if pending is None:
        # No prior :meth:`act` — defensive no-op so the trainer can
        # safely ignore a stray ``observe`` (eg. a pre-rollout
        # bookkeeping call).
        return
    if pending.action.ndim == 2:  # noqa: PLR2004 - rank-2 is the vectorised layout
        self._observe_vectorised(
            obs, reward, done, truncated=truncated, final_obs=final_obs, pending=pending
        )
        return
    terminated = bool(done) and not bool(truncated)
    truncated_b = bool(truncated)
    self._buf_obs.append(pending.obs)
    self._buf_actions.append(pending.action)
    self._buf_log_probs.append(pending.log_prob)
    self._buf_values.append(pending.value)
    self._buf_rewards.append(float(reward))
    self._buf_terminated.append(terminated)
    self._buf_truncated.append(truncated_b)
    next_flat = _flat_ego_obs(obs, self._ego_uid)
    # Capture V(s_truncated_final) eagerly at the boundary. Doing it
    # here (rather than at update time) is the cleanest place because
    # ``next_flat`` is the actual post-step obs of the truncated
    # episode; by update time the training loop has already reset
    # the env, and the per-step "next obs in buffer" at index
    # ``t + 1`` is from the *new* episode. The cost is one extra
    # critic forward pass per truncation boundary.
    if truncated_b and not terminated:
        with torch.no_grad():
            v_trunc = float(
                self._critic(torch.from_numpy(next_flat).to(self._device).unsqueeze(0))
                .squeeze()
                .item()
            )
        self._buf_truncation_bootstraps.append(v_trunc)
    else:
        self._buf_truncation_bootstraps.append(0.0)
    self._last_next_obs = next_flat
    # Clear the pre-step cache so a stray double-observe cannot
    # double-insert the same tuple.
    self._pending = None
    # P1.05.11 / ADR-017: bump the global step counter so the next
    # :meth:`update` emission carries the current frame index.
    self._global_step += 1

state_dict

state_dict() -> dict[str, Any]

Return a flat dict with actor + critic + optimizer states (ADR-002 §Decisions; T4b.12).

The returned dict is what :func:concerto.training.checkpoints.save_checkpoint torch.saves to the .pt artefact. Loading is the dual: each component reads its own sub-key off the loaded dict via :meth:load_state_dict.

Source code in src/chamber/benchmarks/ego_ppo_trainer.py

def state_dict(self) -> dict[str, Any]:
    """Return a flat dict with actor + critic + optimizer states (ADR-002 §Decisions; T4b.12).

    The returned dict is what :func:`concerto.training.checkpoints.save_checkpoint`
    ``torch.save``s to the ``.pt`` artefact. Loading is the dual:
    each component reads its own sub-key off the loaded dict via
    :meth:`load_state_dict`.
    """
    return {
        "actor": self._happo.actor.state_dict(),
        "actor_optim": self._happo.actor_optimizer.state_dict(),
        "critic": self._critic.state_dict(),
        "critic_optim": self._critic_optim.state_dict(),
    }

update

update() -> None

Compute GAE; run PPO + critic updates; clear the buffer (ADR-002 §Decisions; Pardo 2017).

Order of operations (Schulman 2017, lifted to ego-only / frozen- partner per plan/05 §3.5):

1. Build the per-step next_values bootstrap array (Pardo 2017 §4): V(s_truncated_final_t) at truncation boundaries (cached at observe time), 0.0 at terminations, values[t + 1] otherwise; rollout-tail bootstrap at t = T - 1 is the same rule applied to self._last_next_obs.
2. :func:compute_gae → raw advantages A_t.
3. returns_t = A_t + V(s_t) (the critic regression target).
4. :func:normalize_advantages → normalized A_t for the PPO importance-weighted surrogate loss.
5. For each of n_epochs epochs, shuffle indices and walk actor_num_mini_batch minibatches. For each minibatch, build the 9-tuple :meth:HAPPO.update expects and call it directly (skipping :meth:HAPPO.train's buffer-machinery wrapper).
6. Train the critic on the same minibatch with MSE on returns.
7. Clear the buffer.

The factor_batch argument :meth:HAPPO.update requires for HAPPO's sequential multi-agent update is set to all 1.0 — the ego is the only updating agent (ADR-009 §Decision: black-box AHT, partner is frozen), so previous-agent importance weights are identically 1.

Source code in src/chamber/benchmarks/ego_ppo_trainer.py

def update(self) -> None:  # noqa: PLR0915 - P1.05.11 added metric accumulation; refactor blocked by HARL.update tuple shape
    """Compute GAE; run PPO + critic updates; clear the buffer (ADR-002 §Decisions; Pardo 2017).

    Order of operations (Schulman 2017, lifted to ego-only / frozen-
    partner per plan/05 §3.5):

    1. Build the per-step ``next_values`` bootstrap array (Pardo 2017
       §4): ``V(s_truncated_final_t)`` at truncation boundaries (cached
       at observe time), ``0.0`` at terminations, ``values[t + 1]``
       otherwise; rollout-tail bootstrap at ``t = T - 1`` is the same
       rule applied to ``self._last_next_obs``.
    2. :func:`compute_gae` → raw advantages ``A_t``.
    3. ``returns_t = A_t + V(s_t)`` (the critic regression target).
    4. :func:`normalize_advantages` → normalized ``A_t`` for the
       PPO importance-weighted surrogate loss.
    5. For each of ``n_epochs`` epochs, shuffle indices and walk
       ``actor_num_mini_batch`` minibatches. For each minibatch, build
       the 9-tuple :meth:`HAPPO.update` expects and call it directly
       (skipping :meth:`HAPPO.train`'s buffer-machinery wrapper).
    6. Train the critic on the same minibatch with MSE on returns.
    7. Clear the buffer.

    The ``factor_batch`` argument :meth:`HAPPO.update` requires for
    HAPPO's sequential multi-agent update is set to all ``1.0`` — the
    ego is the only updating agent (ADR-009 §Decision: black-box AHT,
    partner is frozen), so previous-agent importance weights are
    identically 1.
    """
    if not self._buf_rewards:
        return

    vectorised = np.ndim(self._buf_rewards[0]) == 1
    if vectorised:
        # P1.05.10 (ADR-007 §Stage 1b regime-alignment): batched
        # rollout. Stack to (T, N, …), run GAE independently per env
        # column through the SAME module-level compute_gae the
        # property test pins (USES_MODULE_GAE stays honest), then
        # flatten to (T*N, …) for the minibatch sweep.
        rewards_tn = np.stack(self._buf_rewards).astype(np.float32)  # (T, N)
        values_tn = np.stack(self._buf_values).astype(np.float32)
        terminated_tn = np.stack(self._buf_terminated).astype(np.bool_)
        truncated_tn = np.stack(self._buf_truncated).astype(np.bool_)
        bootstraps_tn = np.stack(self._buf_truncation_bootstraps).astype(np.float32)
        next_values_tn = self._build_next_values_vectorised(
            values_tn, terminated_tn, truncated_tn, bootstraps_tn
        )
        boundaries_tn = terminated_tn | truncated_tn
        n_envs = rewards_tn.shape[1]
        raw_adv_tn = np.stack(
            [
                compute_gae(
                    rewards_tn[:, e],
                    values_tn[:, e],
                    next_values_tn[:, e],
                    boundaries_tn[:, e],
                    gamma=self._gamma,
                    gae_lambda=self._gae_lambda,
                )
                for e in range(n_envs)
            ],
            axis=1,
        )
        returns_tn = (raw_adv_tn + values_tn).astype(np.float32)
        rewards = rewards_tn.reshape(-1)
        values = values_tn.reshape(-1)
        raw_advantages = raw_adv_tn.reshape(-1)
        returns = returns_tn.reshape(-1)
        norm_advantages = normalize_advantages(raw_advantages)
        obs_arr = np.stack(self._buf_obs).astype(np.float32).reshape(-1, self._obs_dim)
        actions_arr = np.stack(self._buf_actions).astype(np.float32).reshape(-1, self._act_dim)
        log_probs_arr = (
            np.stack(self._buf_log_probs).astype(np.float32).reshape(obs_arr.shape[0], -1)
        )
    else:
        rewards = np.asarray(self._buf_rewards, dtype=np.float32)
        values = np.asarray(self._buf_values, dtype=np.float32)
        terminated = np.asarray(self._buf_terminated, dtype=np.bool_)
        truncated = np.asarray(self._buf_truncated, dtype=np.bool_)
        truncation_bootstraps = np.asarray(self._buf_truncation_bootstraps, dtype=np.float32)
        next_values = self._build_next_values(
            values, terminated, truncated, truncation_bootstraps
        )
        episode_boundaries = terminated | truncated
        raw_advantages = compute_gae(
            rewards,
            values,
            next_values,
            episode_boundaries,
            gamma=self._gamma,
            gae_lambda=self._gae_lambda,
        )
        returns = (raw_advantages + values).astype(np.float32)
        norm_advantages = normalize_advantages(raw_advantages)

        obs_arr = np.stack(self._buf_obs).astype(np.float32)
        actions_arr = np.stack(self._buf_actions).astype(np.float32)
        log_probs_arr = np.stack(self._buf_log_probs).astype(np.float32)

    n_steps = rewards.shape[0]
    n_minibatches = max(1, n_steps // self._batch_size)
    mb_size = max(1, n_steps // n_minibatches)

    # P1.05.11 / ADR-017: per-update metric accumulators. Sums are
    # mean-reduced post-loop so a single ``log_scalars`` call
    # carries the rollout-aggregated PPO health snapshot. Captured
    # iff a logger is bound — short-circuits the accumulation work
    # otherwise so the silent-trainer path stays free.
    emit_metrics = self._logger is not None
    sum_policy_loss = 0.0
    sum_critic_loss = 0.0
    sum_dist_entropy = 0.0
    sum_grad_norm = 0.0
    sum_approx_kl = 0.0
    sum_clip_fraction = 0.0
    ratio_min_seen = float("inf")
    ratio_max_seen = float("-inf")
    n_updates = 0

    for _epoch in range(self._n_epochs):
        perm = self._minibatch_rng.permutation(n_steps)
        for mb in range(n_minibatches):
            start = mb * mb_size
            end = start + mb_size if mb < n_minibatches - 1 else n_steps
            mb_idx = perm[start:end]
            mb_obs = obs_arr[mb_idx]
            mb_actions = actions_arr[mb_idx]
            mb_old_log_probs = log_probs_arr[mb_idx]
            # HAPPO expects ``adv_targ`` shape ``(mb, 1)``. log-probs
            # for diag-Gaussian are already per-action-dim; HAPPO's
            # action_aggregation="prod" reduces them inside update().
            mb_advantages = norm_advantages[mb_idx].reshape(-1, 1).astype(np.float32)
            this_mb_size = mb_idx.shape[0]
            mb_rnn_states = np.zeros(
                (
                    this_mb_size,
                    self._harl_args["recurrent_n"],
                    self._harl_args["hidden_sizes"][-1],
                ),
                dtype=np.float32,
            )
            mb_masks = np.ones((this_mb_size, 1), dtype=np.float32)
            mb_active_masks = np.ones((this_mb_size, 1), dtype=np.float32)
            # ``factor_batch`` = 1 because the ego is the only updating
            # agent (ADR-009 §Decision); see plan/05 §3.5.
            mb_factor = np.ones((this_mb_size, 1), dtype=np.float32)
            sample = (
                mb_obs,
                mb_rnn_states,
                mb_actions,
                mb_masks,
                mb_active_masks,
                mb_old_log_probs,
                mb_advantages,
                None,
                mb_factor,
            )
            # P1.05.11 / ADR-017: capture HARL's 4-tuple return value.
            # Pre-P1.05.11 the trainer discarded it; commit 3 wires the
            # values through the bound logger. ``imp_weights`` is the
            # PPO importance ratio (exp of new-vs-old log-prob diff).
            policy_loss, dist_entropy, actor_grad_norm, imp_weights = self._happo.update(sample)

            # Critic update: simple MSE regression on returns.
            mb_returns = torch.from_numpy(returns[mb_idx]).to(self._device).float()
            mb_obs_t = torch.from_numpy(mb_obs).to(self._device).float()
            value_pred = self._critic(mb_obs_t).squeeze(-1)
            critic_loss = ((value_pred - mb_returns) ** 2).mean()
            self._critic_optim.zero_grad()
            critic_loss.backward()
            self._critic_optim.step()

            if emit_metrics:
                # P1.05.11 / ADR-017: per-minibatch metric capture.
                # Locally compute approx_kl and clip_fraction; HARL
                # does not expose them. The torch.no_grad() guard
                # is defensive — these are read-only reductions
                # against detached tensors.
                with torch.no_grad():
                    ratio = imp_weights.detach()
                    approx_kl = float(((ratio - 1.0) ** 2).mean().item()) * 0.5
                    clip_fraction = float(
                        ((ratio - 1.0).abs() > self._clip_param).float().mean().item()
                    )
                    r_min = float(ratio.min().item())
                    r_max = float(ratio.max().item())
                sum_policy_loss += float(policy_loss.detach().item())
                sum_critic_loss += float(critic_loss.detach().item())
                sum_dist_entropy += float(dist_entropy.detach().item())
                sum_grad_norm += float(
                    actor_grad_norm.detach().item()
                    if torch.is_tensor(actor_grad_norm)
                    else actor_grad_norm
                )
                sum_approx_kl += approx_kl
                sum_clip_fraction += clip_fraction
                ratio_min_seen = min(ratio_min_seen, r_min)
                ratio_max_seen = max(ratio_max_seen, r_max)
                n_updates += 1

    # P1.05.11 / ADR-017: emit one ``event="scalar"`` line per
    # ``update()`` call with the rollout-aggregated PPO health snapshot.
    # Skipped when no logger is bound (the existing silent path).
    if emit_metrics and self._logger is not None and n_updates > 0:
        # Lazy import: keeping the structlog helper out of module-top
        # imports preserves the trainer's Tier-1 importability story
        # (the trainer's TYPE_CHECKING block already gates structlog).
        from concerto.training.logging import log_scalars

        log_scalars(
            self._logger,
            step=self._global_step,
            namespace="train",
            policy_loss=sum_policy_loss / n_updates,
            value_loss=sum_critic_loss / n_updates,
            dist_entropy=sum_dist_entropy / n_updates,
            actor_grad_norm=sum_grad_norm / n_updates,
            approx_kl=sum_approx_kl / n_updates,
            clip_fraction=sum_clip_fraction / n_updates,
            ratio_min=ratio_min_seen,
            ratio_max=ratio_max_seen,
            advantage_mean=float(raw_advantages.mean()),
            advantage_std=float(raw_advantages.std()),
            value_mean=float(values.mean()),
            value_std=float(values.std()),
            learning_rate=self._learning_rate,
        )

    # Reset rollout buffer.
    self._buf_obs.clear()
    self._buf_actions.clear()
    self._buf_log_probs.clear()
    self._buf_values.clear()
    self._buf_rewards.clear()
    self._buf_terminated.clear()
    self._buf_truncated.clear()
    self._buf_truncation_bootstraps.clear()
    self._last_next_obs = None

compute_gae

compute_gae(
    rewards: NDArray[float32],
    values: NDArray[float32],
    next_values: NDArray[float32],
    episode_boundaries: NDArray[bool_],
    *,
    gamma: float,
    gae_lambda: float,
) -> NDArray[np.float32]

GAE with per-step bootstrap (Schulman 2016 §6.3; Pardo 2017; ADR-002 §Decisions).

Pardo et al. 2017 ("Time Limits in Reinforcement Learning") motivates the per-step bootstrap target shape: time-limit truncation is not a terminal state — the policy should still receive the value of the state it would have transitioned to. Treating truncation as termination zeros that bootstrap and biases advantages systematically, slowing learning materially (see project issue #62).

The recurrence is::

delta_t = r_t + gamma * next_values[t]     - V(s_t)
A_t     = delta_t + gamma * lambda * (1 - boundary_t) * A_{t+1}
A_T     = delta_T

where next_values[t] is the caller-supplied bootstrap target — in production it is:

• values[t + 1] for non-boundary steps (typical mid-rollout).
• V(s_truncated_final_t) at truncation boundaries (the value of the actual post-step obs of the truncated episode, computed by the caller via the critic).
• 0.0 at termination boundaries (true terminal state — no value after).
• The rollout-tail bootstrap (V(s_T+1) if the rollout ends mid-episode; 0.0 if it ends on an episode boundary) at the final timestep t = T - 1.

episode_boundaries[t] is True iff step t ended an episode (terminated or truncated). It zeros GAE propagation across the boundary — advantages from a different episode (steps > t after a boundary) must not contribute to A_t.

plan/05 §5 + the property test tests/property/test_advantage_decomposition.py verify this formula matches a freshly hand-rolled reference to within 1e-6 on synthetic trajectories that include both termination and truncation boundaries.

Parameters:

• rewards (NDArray[float32]) –

  Per-step ego reward. Shape (T,).

• values (NDArray[float32]) –

  Per-step critic value estimate V(s_t). Shape (T,).

• next_values (NDArray[float32]) –

  Per-step bootstrap target. Shape (T,). Caller responsibility (see module docstring + issue #62 root-cause writeup for why this split matters).

• episode_boundaries (NDArray[bool_]) –

  True at steps that ended an episode (terminated OR truncated). Shape (T,). Zeros GAE propagation across the boundary.

• gamma (float) –

  Discount factor in [0, 1].

• gae_lambda (float) –

  GAE exponential smoothing in [0, 1].

Returns:

• NDArray[float32] –

  Advantages A_t, same shape and dtype (float32) as rewards.

Source code in src/chamber/benchmarks/ego_ppo_trainer.py

def compute_gae(
    rewards: NDArray[np.float32],
    values: NDArray[np.float32],
    next_values: NDArray[np.float32],
    episode_boundaries: NDArray[np.bool_],
    *,
    gamma: float,
    gae_lambda: float,
) -> NDArray[np.float32]:
    """GAE with per-step bootstrap (Schulman 2016 §6.3; Pardo 2017; ADR-002 §Decisions).

    Pardo et al. 2017 ("Time Limits in Reinforcement Learning") motivates
    the per-step bootstrap target shape: time-limit truncation is **not**
    a terminal state — the policy should still receive the value of the
    state it would have transitioned to. Treating truncation as
    termination zeros that bootstrap and biases advantages
    systematically, slowing learning materially (see project issue #62).

    The recurrence is::

        delta_t = r_t + gamma * next_values[t]     - V(s_t)
        A_t     = delta_t + gamma * lambda * (1 - boundary_t) * A_{t+1}
        A_T     = delta_T

    where ``next_values[t]`` is the *caller-supplied* bootstrap target —
    in production it is:

    - ``values[t + 1]`` for non-boundary steps (typical mid-rollout).
    - ``V(s_truncated_final_t)`` at truncation boundaries (the value of
      the actual post-step obs of the truncated episode, computed by the
      caller via the critic).
    - ``0.0`` at termination boundaries (true terminal state — no value
      after).
    - The rollout-tail bootstrap (``V(s_T+1)`` if the rollout ends
      mid-episode; ``0.0`` if it ends on an episode boundary) at the
      final timestep ``t = T - 1``.

    ``episode_boundaries[t]`` is ``True`` iff step ``t`` ended an episode
    (terminated *or* truncated). It zeros GAE propagation across the
    boundary — advantages from a *different* episode (steps ``> t`` after
    a boundary) must not contribute to ``A_t``.

    plan/05 §5 + the property test
    ``tests/property/test_advantage_decomposition.py`` verify this formula
    matches a freshly hand-rolled reference to within 1e-6 on synthetic
    trajectories that include both termination and truncation boundaries.

    Args:
        rewards: Per-step ego reward. Shape ``(T,)``.
        values: Per-step critic value estimate ``V(s_t)``. Shape ``(T,)``.
        next_values: Per-step bootstrap target. Shape ``(T,)``. Caller
            responsibility (see module docstring + issue #62 root-cause
            writeup for why this split matters).
        episode_boundaries: ``True`` at steps that ended an episode
            (terminated OR truncated). Shape ``(T,)``. Zeros GAE
            propagation across the boundary.
        gamma: Discount factor in ``[0, 1]``.
        gae_lambda: GAE exponential smoothing in ``[0, 1]``.

    Returns:
        Advantages ``A_t``, same shape and dtype (float32) as ``rewards``.
    """
    n = rewards.shape[0]
    advantages = np.zeros(n, dtype=np.float32)
    # Accumulate ``gae`` in Python float64 — keeping intermediate
    # advantages at higher precision avoids the 1e-6 rounding drift that
    # float32 in-loop accumulation accrues over long horizons. The final
    # store to ``advantages[t]`` casts back to the declared float32
    # storage. The property test against ``reference_gae`` relies on
    # both implementations using the same accumulation precision.
    gae = 0.0
    for t in reversed(range(n)):
        boundary = bool(episode_boundaries[t])
        delta = float(rewards[t]) + gamma * float(next_values[t]) - float(values[t])
        # Zero GAE propagation across episode boundaries: advantages from
        # the next episode must not flow back into this episode (Pardo 2017
        # §4; issue #62 root-cause writeup).
        gae = delta + gamma * gae_lambda * (0.0 if boundary else 1.0) * gae
        advantages[t] = np.float32(gae)
    return advantages

normalize_advantages

normalize_advantages(
    advantages: NDArray[float32],
) -> NDArray[np.float32]

Mean/std-normalize advantages (ADR-002 §Decisions; matches HAPPO state_type='EP').

The formula::

A_normalized = (A - mean(A)) / (std(A) + 1e-5)

matches the EP-state branch in :meth:HAPPO.train (lines 122-127 of harl/algorithms/actors/happo.py) without the nan-masking it applies to inactive agents. The ego in our 2-agent task is never inactive (use_policy_active_masks=False in :data:_HARL_FIXED_DEFAULTS), so the nan-masking branch is dead code in our setting and the formula collapses to a plain mean/std normalization.

plan/05 §5: pulled out of HARL into this module so the property test (T4b.13) can verify the formula matches single-agent PPO without tautology.

Parameters:

• advantages (NDArray[float32]) –

  Raw advantages (typically from :func:compute_gae).

Returns:

• NDArray[float32] –

  Normalized advantages, same shape and dtype.

Source code in src/chamber/benchmarks/ego_ppo_trainer.py

def normalize_advantages(advantages: NDArray[np.float32]) -> NDArray[np.float32]:
    """Mean/std-normalize advantages (ADR-002 §Decisions; matches HAPPO state_type='EP').

    The formula::

        A_normalized = (A - mean(A)) / (std(A) + 1e-5)

    matches the EP-state branch in :meth:`HAPPO.train`
    (lines 122-127 of ``harl/algorithms/actors/happo.py``) without the
    nan-masking it applies to inactive agents. The ego in our 2-agent
    task is never inactive (``use_policy_active_masks=False`` in
    :data:`_HARL_FIXED_DEFAULTS`), so the nan-masking branch is dead
    code in our setting and the formula collapses to a plain
    mean/std normalization.

    plan/05 §5: pulled out of HARL into this module so the property test
    (T4b.13) can verify the formula matches single-agent PPO without
    tautology.

    Args:
        advantages: Raw advantages (typically from :func:`compute_gae`).

    Returns:
        Normalized advantages, same shape and dtype.
    """
    mean = float(advantages.mean())
    std = float(advantages.std())
    return ((advantages - mean) / (std + 1e-5)).astype(np.float32)

Stage-1 spike-adapter common surface (ADR-007 §Stage 1a / §Stage 1b; plan/07 §T5b.2).

Single source of truth for the seam that Stage-1 AS and OM adapters (:mod:chamber.benchmarks.stage1_as, :mod:chamber.benchmarks.stage1_om) share — the :class:EgoActionFactory Protocol the Phase-1 trained-ego path plugs into, and the Stage-1a production-default :func:_zero_ego_action_factory.

Why a Protocol (not a per-step Callable):

• The factory contract is called once per (seed, condition) pair. That matches the natural shape of a trained-policy injection point — Phase 1 (ADR-007 §Stage 1b) supplies a factory that calls :func:concerto.training.ego_aht.train for the homogeneous condition's env at the given seed, then returns a closure that wraps the trained policy's act (the closure is then re-used across the 20 evaluation episodes within that (seed, condition) cell).
• The Phase-0 per-step ego_action_fn was unable to express this contract — there was no place to hang a "this happens once per (seed, condition), not once per step" idea. The Protocol seam pins the lifecycle explicitly.

Phase-1 wiring contract (verbatim, do not rewrite without an ADR-007 amendment):

Phase-1 supplies a factory that calls concerto.training.ego_aht.train for the homogeneous condition's env at the given seed, returns lambda obs: trained_policy.act(obs). The factory is called once per (seed, condition) pair so the trained policy is reused across the 20 evaluation episodes within a seed.

Stage-1a production default: :func:_zero_ego_action_factory returns a closure that emits a zero action vector of the env's ego-action shape. Stage-1a's purpose is to exercise the rig (env steps, partner acts, episode terminations, success thresholding, SpikeRun aggregation, chamber-eval pipeline) without confounding the rig signal with a trainer signal; a learning ego is sequenced to Stage-1b (ADR-007 §Stage 1b).

Stage-1b production default (P1.04): :class:TrainedPolicyFactory — wires :func:chamber.benchmarks.training_runner.run_training for each (seed, condition) cell and returns a closure that wraps the trained :class:~concerto.training.ego_aht.EgoTrainer's act method (deterministic mode). One ego-AHT training run per cell (5 GPU-h per axis on A100 at the 100k-frame budget per ADR-007 §Stage 1b); the trainer is recovered from the :class:~concerto.training.ego_aht.TrainingResult NamedTuple rather than reloaded from disk, so no checkpoint round-trip per cell. The Phase-0 _zero_ego_action_factory is unchanged — Stage-1a runs keep the rig-validation contract; the Stage-1b dispatch swap is sequenced to P1.05 (separate slice).

EgoActionFactory

Bases: Protocol

Stage-1 ego-action factory contract (ADR-007 §Stage 1a / §Stage 1b).

Called once per (seed, condition) pair by the Stage-1 spike adapter's :func:_run_axis_with_factories. The returned callable is invoked once per env step for the 20 evaluation episodes within that (seed, condition) cell.

Two production implementations satisfy this Protocol:

• :func:_zero_ego_action_factory — the Stage-1a default (rig validation). Returns a closure that emits a zero action vector of the env's ego-action shape. No randomness; no training.
• :class:TrainedPolicyFactory — the Stage-1b default (science evaluation; ADR-007 §Stage 1b). Wires :func:concerto.training.ego_aht.train via :func:chamber.benchmarks.training_runner.run_training for each (seed, condition) cell, then returns a closure that wraps the trained :class:~concerto.training.ego_aht.EgoTrainer's act method (deterministic mode for evaluation).

The Protocol is intentionally tiny — (env, seed) → callable — so an external user can plug in their own algorithm without changing :func:_run_axis_with_factories. Project test fixtures can build a counting factory (see tests.integration.test_stage1_*_fake) to assert the lifecycle contract.

Source code in src/chamber/benchmarks/stage1_common.py

class EgoActionFactory(Protocol):
    """Stage-1 ego-action factory contract (ADR-007 §Stage 1a / §Stage 1b).

    Called once per ``(seed, condition)`` pair by the Stage-1 spike
    adapter's :func:`_run_axis_with_factories`. The returned callable
    is invoked once per env step for the 20 evaluation episodes within
    that ``(seed, condition)`` cell.

    Two production implementations satisfy this Protocol:

    - :func:`_zero_ego_action_factory` — the Stage-1a default (rig
      validation). Returns a closure that emits a zero action vector
      of the env's ego-action shape. No randomness; no training.
    - :class:`TrainedPolicyFactory` — the Stage-1b default (science
      evaluation; ADR-007 §Stage 1b). Wires
      :func:`concerto.training.ego_aht.train` via
      :func:`chamber.benchmarks.training_runner.run_training` for each
      ``(seed, condition)`` cell, then returns a closure that wraps
      the trained :class:`~concerto.training.ego_aht.EgoTrainer`'s
      ``act`` method (deterministic mode for evaluation).

    The Protocol is intentionally tiny — ``(env, seed)`` → callable —
    so an external user can plug in their own algorithm without
    changing :func:`_run_axis_with_factories`. Project test fixtures
    can build a counting factory (see
    ``tests.integration.test_stage1_*_fake``) to assert the lifecycle
    contract.
    """

    def __call__(
        self,
        env: gym.Env[Any, Any],
        seed: int,
    ) -> Callable[[Mapping[str, Any]], NDArray[np.float32]]:
        """Build the per-step ego-action callable for one ``(seed, condition)`` cell."""
        ...  # pragma: no cover

__call__

__call__(
    env: Env[Any, Any], seed: int
) -> Callable[[Mapping[str, Any]], NDArray[np.float32]]

Build the per-step ego-action callable for one (seed, condition) cell.

Source code in src/chamber/benchmarks/stage1_common.py

def __call__(
    self,
    env: gym.Env[Any, Any],
    seed: int,
) -> Callable[[Mapping[str, Any]], NDArray[np.float32]]:
    """Build the per-step ego-action callable for one ``(seed, condition)`` cell."""
    ...  # pragma: no cover

TrainedPolicyFactory

Phase-1 :class:EgoActionFactory — wires the ego-AHT training loop per cell.

ADR-007 §Stage 1b production factory. Implements the :class:EgoActionFactory Protocol (this module) by calling :func:chamber.benchmarks.training_runner.run_training for each (seed, condition) cell and returning a closure that wraps the trained :class:~concerto.training.ego_aht.EgoTrainer's act method (deterministic mode for evaluation).

Lifecycle (ADR-007 §Stage 1b lifecycle contract):

The factory is called once per (seed, condition) pair by the Stage-1 spike adapter's :func:_run_axis_with_factories (5 seeds x 2 conditions = 10 calls per Stage-1 spike). Each call drives one full training run (5 x 100k frames per axis = 1M frames per axis on A100; ~5 GPU-h per axis per the compute plan); the returned closure is re-used across the 20 evaluation episodes within the cell so the trained policy is not retrained per-episode.

Determinism (ADR-007 §Discipline + ADR-002 §Decisions; P6):

The trained-policy seed is set via Pydantic model_copy on cfg.seed; the underlying training run derives all its randomness from :func:concerto.training.seeding.derive_substream. Two invocations at the same (seed, condition) pair produce byte-identical trained policies on CPU; on GPU, the cuDNN / cuBLAS non-bit- determinism caveat (plan/08 §4) applies.

Caching policy (intentionally NO cache):

The factory does NOT cache trained policies across __call__ invocations — each call trains a fresh policy. Caching would silently violate the per-(seed, condition) determinism contract if the cache key were not exhaustive (env identity, partner identity, prereg tag, code state). If the operator needs to resume a partial run, the right tool is the :class:~concerto.training.checkpoints.CheckpointMetadata sidecar serialised under cfg.artifacts_root (the training loop emits one per cfg.checkpoint_every steps); not an in-memory cache.

Partner-freeze gate (ADR-009 §Consequences; plan/05 §6 #3):

The partner-freeze gate is honoured by :meth:EgoPPOTrainer.__init__'s :func:_assert_partner_is_frozen call (run first, before any tensor allocation). The factory does not bypass it.

Per-condition partner-uid routing (P1.04 / Q-C refinement):

The factory reads the env's :attr:partner_uid and :attr:ego_uid properties at __call__ time and overrides cfg.env.agent_uids accordingly — single source of truth at the env layer; the factory carries no per-condition dispatch table. For AS-homo (partner=panda_partner) vs AS-hetero / OM-* (partner=fetch), the env's condition_id drives the routing via the :data:chamber.envs.stage1_pickplace._CONDITION_TABLE. Envs that don't expose the properties (Tier-1 fake envs, MPE stand-in) fall back to cfg.env.agent_uids[0] / [1] — the Phase-0 contract that pre-dates the property.

Action-dim handoff to partner (P1.04 / Q-C refinement):

The :class:~chamber.partners.heuristic.ScriptedHeuristicPartner reads its action dimension from spec.extra["action_dim"] and zero-pads beyond the planar xy. The factory reads the actual env.action_space.spaces[partner_uid].shape[0] at call time and overrides cfg.partner.extra["action_dim"] so the partner's action vector matches the env's expectation per-condition. This avoids a side-table; the action_dim is sourced from the env that owns the contract.

Parameters:

• cfg (EgoAHTConfig) –

  A fully-resolved :class:~concerto.training.config.EgoAHTConfig. The factory rewrites cfg.seed per call via cfg.model_copy(update={"seed": call_seed}) and applies the per-condition env+partner overrides described above; all other fields are honoured as-is.

Example wiring at the Stage-1b adapter (sequenced to P1.05):

.. code-block:: python

from chamber.benchmarks.stage1_common import TrainedPolicyFactory
from concerto.training.config import load_config

factory = TrainedPolicyFactory(
    cfg=load_config(
        config_path=Path("configs/training/ego_aht_happo/stage1_pickplace.yaml")
    )
)
spike_run = _run_axis_with_factories(
    prereg=spec,
    prereg_sha=prereg_sha,
    env_factory=_default_env_factory,
    ego_action_factory=factory,
)

Source code in src/chamber/benchmarks/stage1_common.py

class TrainedPolicyFactory:
    """Phase-1 :class:`EgoActionFactory` — wires the ego-AHT training loop per cell.

    ADR-007 §Stage 1b production factory. Implements the
    :class:`EgoActionFactory` Protocol (this module) by calling
    :func:`chamber.benchmarks.training_runner.run_training` for each
    ``(seed, condition)`` cell and returning a closure that wraps the
    trained :class:`~concerto.training.ego_aht.EgoTrainer`'s ``act``
    method (deterministic mode for evaluation).

    Lifecycle (ADR-007 §Stage 1b lifecycle contract):

    The factory is called *once per ``(seed, condition)`` pair* by the
    Stage-1 spike adapter's :func:`_run_axis_with_factories` (5 seeds x
    2 conditions = 10 calls per Stage-1 spike). Each call drives one
    full training run (5 x 100k frames per axis = 1M frames per axis
    on A100; ~5 GPU-h per axis per the compute plan); the returned
    closure is re-used across the 20 evaluation episodes within the
    cell so the trained policy is not retrained per-episode.

    Determinism (ADR-007 §Discipline + ADR-002 §Decisions; P6):

    The trained-policy seed is set via Pydantic ``model_copy`` on
    ``cfg.seed``; the underlying training run derives all its
    randomness from
    :func:`concerto.training.seeding.derive_substream`. Two invocations
    at the same ``(seed, condition)`` pair produce byte-identical
    trained policies on CPU; on GPU, the cuDNN / cuBLAS non-bit-
    determinism caveat (plan/08 §4) applies.

    Caching policy (intentionally NO cache):

    The factory does NOT cache trained policies across ``__call__``
    invocations — each call trains a fresh policy. Caching would
    silently violate the per-``(seed, condition)`` determinism contract
    if the cache key were not exhaustive (env identity, partner
    identity, prereg tag, code state). If the operator needs to resume
    a partial run, the right tool is the
    :class:`~concerto.training.checkpoints.CheckpointMetadata` sidecar
    serialised under ``cfg.artifacts_root`` (the training loop emits
    one per ``cfg.checkpoint_every`` steps); not an in-memory cache.

    Partner-freeze gate (ADR-009 §Consequences; plan/05 §6 #3):

    The partner-freeze gate is honoured by
    :meth:`EgoPPOTrainer.__init__`'s :func:`_assert_partner_is_frozen`
    call (run first, before any tensor allocation). The factory does
    not bypass it.

    Per-condition partner-uid routing (P1.04 / Q-C refinement):

    The factory reads the env's :attr:`partner_uid` and :attr:`ego_uid`
    properties at ``__call__`` time and overrides
    ``cfg.env.agent_uids`` accordingly — single source of truth at the
    env layer; the factory carries no per-condition dispatch table.
    For AS-homo (partner=``panda_partner``) vs AS-hetero / OM-*
    (partner=``fetch``), the env's ``condition_id`` drives the routing
    via the
    :data:`chamber.envs.stage1_pickplace._CONDITION_TABLE`. Envs that
    don't expose the properties (Tier-1 fake envs, MPE stand-in) fall
    back to ``cfg.env.agent_uids[0]`` / ``[1]`` — the Phase-0 contract
    that pre-dates the property.

    Action-dim handoff to partner (P1.04 / Q-C refinement):

    The :class:`~chamber.partners.heuristic.ScriptedHeuristicPartner`
    reads its action dimension from ``spec.extra["action_dim"]`` and
    zero-pads beyond the planar xy. The factory reads the actual
    ``env.action_space.spaces[partner_uid].shape[0]`` at call time and
    overrides ``cfg.partner.extra["action_dim"]`` so the partner's
    action vector matches the env's expectation per-condition. This
    avoids a side-table; the action_dim is sourced from the env that
    owns the contract.

    Args:
        cfg: A fully-resolved :class:`~concerto.training.config.EgoAHTConfig`.
            The factory rewrites ``cfg.seed`` per call via
            ``cfg.model_copy(update={"seed": call_seed})`` and applies
            the per-condition env+partner overrides described above;
            all other fields are honoured as-is.

    Example wiring at the Stage-1b adapter (sequenced to P1.05):

    .. code-block:: python

        from chamber.benchmarks.stage1_common import TrainedPolicyFactory
        from concerto.training.config import load_config

        factory = TrainedPolicyFactory(
            cfg=load_config(
                config_path=Path("configs/training/ego_aht_happo/stage1_pickplace.yaml")
            )
        )
        spike_run = _run_axis_with_factories(
            prereg=spec,
            prereg_sha=prereg_sha,
            env_factory=_default_env_factory,
            ego_action_factory=factory,
        )
    """

    def __init__(self, *, cfg: EgoAHTConfig) -> None:
        """Build the factory; capture the base config.

        Vectorised cells (``cfg.env.num_envs > 1``; ADR-007 §Stage 1b
        Rev 17): SAPIEN GPU PhysX is enabled eagerly here, at factory
        construction — which the spike adapters evaluate *before* any
        per-cell env build — because GPU PhysX can only be enabled
        before any other PhysX use in the process, and the adapter's
        per-cell ordering builds the (CPU-sim) eval env before invoking
        this factory (issue #215; the gate-readiness note's blocker B1).
        With GPU PhysX enabled first, both the CPU-sim eval env and the
        ``physx_cuda`` training env compose in either order. Single-env
        configs are untouched (no SAPIEN import, no side effect).

        Args:
            cfg: Validated :class:`~concerto.training.config.EgoAHTConfig`
                — the Stage-1b config (typically loaded from
                ``configs/training/ego_aht_happo/stage1_pickplace.yaml``).
                The original instance is never mutated; per-call
                overrides are applied via ``model_copy``.

        Raises:
            ChamberEnvCompatibilityError: If ``cfg.env.num_envs > 1``
                and GPU PhysX cannot be enabled (CUDA/SAPIEN missing,
                or the process has already used CPU PhysX — e.g. a
                pytest session whose GPU gate built a probe env;
                vectorised cells then need a fresh process, exactly as
                ``tests/integration/test_stage1_vectorised_real.py``
                isolates them).
        """
        if cfg.exploratory.partner_static_override:
            msg = (
                "TrainedPolicyFactory: cfg.exploratory.partner_static_override "
                "is set. EXPLORATORY knobs are structurally barred from the "
                "gate-facing dispatch - the production spike path cannot train "
                "against a static-override partner. Sole pre-stated use: the "
                "2026-06-11 homo-static slice (its own driver, not this "
                "factory). Gate-facing use requires an ADR, not a config edit."
            )
            raise ValueError(msg)
        if cfg.env.num_envs > 1:
            _ensure_gpu_physx_enabled(num_envs=cfg.env.num_envs)
        self._cfg = cfg

    def __call__(
        self,
        env: gym.Env[Any, Any],
        seed: int,
    ) -> EgoActionCallable:
        """Train a per-cell policy and return the per-step closure (ADR-007 §Stage 1b).

        Lifecycle: invoked once per ``(seed, condition)`` cell by the
        Stage-1 adapter's :func:`_run_axis_with_factories`. The returned
        callable is reused across the 20 evaluation episodes within
        the cell.

        Args:
            env: The per-condition evaluation env. ``env.ego_uid`` /
                ``env.partner_uid`` (P1.04 properties on
                :class:`chamber.envs.stage1_pickplace.Stage1PickPlaceEnv`)
                drive the per-condition overrides applied to the base
                ``cfg``. ``env`` itself is NOT stepped by the factory;
                the training run inside :func:`run_training` builds
                its own env from the (overridden) ``cfg.env``. The
                eval env is what the spike adapter's loop steps after
                this factory returns.
            seed: Per-cell seed; the factory overrides ``cfg.seed`` via
                ``model_copy``.

        Returns:
            ``(obs) -> action`` callable that wraps
            ``trained_policy.act(obs, deterministic=True)`` and casts
            the output to ``float32``.

        Raises:
            ValueError: Propagated from :meth:`EgoPPOTrainer.__init__`
                if the partner is non-frozen (ADR-009 §Consequences).
                Any other exception raised by
                :func:`chamber.benchmarks.training_runner.run_training`
                also propagates unchanged (per the
                ``test_run_training_failure_propagates`` contract in
                ``tests/integration/test_trained_policy_factory_fake.py``).
        """
        # Imported lazily so chamber.benchmarks.stage1_common stays
        # cheap to import for Stage-1a-only consumers (the Phase-0 path
        # that does not need the HARL HAPPO trainer in scope).
        from chamber.benchmarks.training_runner import run_training

        # 1. Resolve the per-condition ego + partner uids from the env
        #    (P1.04 / Q-C: single source of truth at the env layer).
        #    Fall back to the cfg's agent_uids for envs that don't
        #    expose the properties (Tier-1 fake envs, MPE stand-in).
        ego_uid = self._resolve_ego_uid(env)
        partner_uid = self._resolve_partner_uid(env)

        # 2. Resolve the partner's action_dim from the env's
        #    action_space — avoids a per-condition side-table.
        partner_action_dim = self._resolve_partner_action_dim(env, partner_uid)

        # 3. Resolve the env's condition_id for Stage-1b disambiguation
        #    (OM-homo vs OM-hetero share the same agent_uids tuple, so
        #    the condition_id is the explicit signal that drives the
        #    Stage-1b env build inside run_training → build_env). None
        #    for non-Stage-1b envs; build_env ignores the field when
        #    task != "stage1_pickplace".
        condition_id = self._resolve_condition_id(env)

        # 4. Compose the per-call cfg via Pydantic model_copy so the
        #    base config passed at __init__ is never mutated.
        cfg_for_call = self._compose_cfg_for_call(
            seed=seed,
            ego_uid=ego_uid,
            partner_uid=partner_uid,
            partner_action_dim=partner_action_dim,
            condition_id=condition_id,
        )

        # 5. Build the per-cell safety stack (P1.04.5; ADR-007 §Stage 1b).
        #    When cfg.safety.enabled=True, construct the filter +
        #    SafetyState + Bounds + snapshot builder + dt now, pass
        #    through to run_training. When False, all five stay None
        #    and train() runs the pre-P1.04.5 unfiltered path.
        safety_kwargs = self._build_safety_for_cell(env=env, cfg=cfg_for_call)

        # 6. Drive the chamber-side training entry point. Returns a
        #    TrainingResult NamedTuple (P1.04) carrying the curve +
        #    the trained EgoTrainer instance — no checkpoint
        #    round-trip needed.
        result = run_training(cfg_for_call, repo_root=None, **safety_kwargs)
        trainer = result.trainer

        # 6. Build the per-step closure. Deterministic mode for eval;
        #    cast to float32 so the adapter's step-loop dict can be
        #    handed straight to the env's step boundary.
        def _act(obs: Mapping[str, Any]) -> NDArray[np.float32]:
            """ADR-007 §Stage 1b per-step ego closure (deterministic)."""
            action = trainer.act(obs, deterministic=True)
            return np.asarray(action, dtype=np.float32)

        return _act

    # ----- Internal composition helpers -----

    def _resolve_ego_uid(self, env: gym.Env[Any, Any]) -> str:
        """Read ``env.ego_uid`` (P1.04 property); fall back to ``cfg.env.agent_uids[0]``."""
        uid = getattr(env, "ego_uid", None)
        if isinstance(uid, str):
            return uid
        return self._cfg.env.agent_uids[0]

    def _resolve_partner_uid(self, env: gym.Env[Any, Any]) -> str:
        """Read ``env.partner_uid`` (P1.04 property); fall back to ``cfg.env.agent_uids[1]``."""
        uid = getattr(env, "partner_uid", None)
        if isinstance(uid, str):
            return uid
        return self._cfg.env.agent_uids[1]

    def _resolve_partner_action_dim(
        self,
        env: gym.Env[Any, Any],
        partner_uid: str,
    ) -> int:
        """Read partner action_dim from ``env.action_space.spaces[partner_uid].shape[0]``.

        Falls back to the cfg's existing ``partner.extra["action_dim"]`` if
        the env's action_space doesn't carry the partner uid (Tier-1 fake
        envs that don't index by the same uid).
        """
        action_space = env.action_space
        if isinstance(action_space, gym.spaces.Dict):
            sub = action_space.spaces.get(partner_uid)
            if isinstance(sub, gym.spaces.Box) and sub.shape is not None:
                return int(sub.shape[0])
        # Fallback: trust the cfg.
        existing = self._cfg.partner.extra.get("action_dim", "2")
        try:
            return int(existing)
        except (TypeError, ValueError):
            return 2

    def _resolve_condition_id(self, env: gym.Env[Any, Any]) -> str | None:
        """Read ``env.condition_id`` (P1.03 property); ``None`` for non-Stage-1b envs.

        The condition_id disambiguates OM-homo vs OM-hetero at the
        chamber-side build_env dispatch (both conditions share the
        ``("panda_wristcam", "fetch")`` agent_uids tuple, so the
        condition_id is the only signal that drives the right Stage-1b
        env build).
        """
        cid = getattr(env, "condition_id", None)
        return cid if isinstance(cid, str) else None

    def _compose_cfg_for_call(
        self,
        *,
        seed: int,
        ego_uid: str,
        partner_uid: str,
        partner_action_dim: int,
        condition_id: str | None,
    ) -> EgoAHTConfig:
        """Apply seed + env + partner overrides via Pydantic ``model_copy`` (P6)."""
        env_update: dict[str, object] = {"agent_uids": (ego_uid, partner_uid)}
        if condition_id is not None:
            env_update["condition_id"] = condition_id
        env_override = self._cfg.env.model_copy(update=env_update)
        partner_extra = dict(self._cfg.partner.extra)
        partner_extra["uid"] = partner_uid
        partner_extra["action_dim"] = str(partner_action_dim)
        partner_override = self._cfg.partner.model_copy(update={"extra": partner_extra})
        return self._cfg.model_copy(
            update={
                "seed": seed,
                "env": env_override,
                "partner": partner_override,
            }
        )

    def _build_safety_for_cell(
        self,
        *,
        env: gym.Env[Any, Any],
        cfg: EgoAHTConfig,
    ) -> dict[str, Any]:
        """Construct the per-cell safety stack (P1.04.5; ADR-007 §Stage 1b).

        Called once per ``(seed, condition)`` cell by
        :meth:`__call__`. When ``cfg.safety.enabled=True`` builds the
        filter + SafetyState + Bounds + snapshot builder + dt from the
        env via the chamber-side helpers; otherwise returns an all-
        ``None`` dict that's a no-op kwargs unpack at the
        :func:`run_training` boundary.

        The :class:`SafetyState` is sized to ``n_pairs = n_agents *
        (n_agents - 1) / 2`` (1 for Stage-1b's 2-agent cell) and
        warm-started via
        :func:`concerto.safety.conformal.reset_on_partner_swap` with
        ``cfg.safety.lambda_safe`` + ``cfg.safety.n_warmup_steps``.
        Per D3 of the P1.04.5 design pass, the state is NOT reset per
        episode — the conformal slack accumulates across episodes
        within the cell per Huriot-Sibai §IV.A's long-run rule.

        Args:
            env: The per-cell evaluation env (the same env the
                returned closure will step). Used to source
                ``build_safety_filter``, ``build_bounds_for_env``,
                ``build_safety_snapshot_builder``, ``build_safety_dt``.
            cfg: The per-call cfg (post seed + condition_id overrides).
                ``cfg.safety`` drives the stack's parameters.

        Returns:
            ``dict`` with keys ``safety_filter``, ``safety_state``,
            ``safety_bounds``, ``safety_snapshot_builder``,
            ``safety_dt``, and ``safety_emergency_controllers``
            (P1.04.6 addition; ADR-007 §Stage 1b Rev 8). All-``None``
            when ``cfg.safety.enabled`` is False; all-populated
            otherwise. The dict unpacks directly into the
            :func:`run_training` kwargs (intent-mismatch detection for
            the first five keys lives in
            :func:`concerto.training.ego_aht.train`'s validation
            block; ``safety_emergency_controllers`` is a free-standing
            hint, only consulted when the first five are wired and
            :func:`concerto.safety.braking.maybe_brake` fires).
        """
        if not cfg.safety.enabled:
            return {
                "safety_filter": None,
                "safety_state": None,
                "safety_bounds": None,
                "safety_snapshot_builder": None,
                "safety_dt": None,
                "safety_emergency_controllers": None,
            }
        # Lazy imports: keep the factory Tier-1-import-safe on
        # Vulkan-less hosts; safety_state construction only resolves
        # when the cfg says so.
        from chamber.benchmarks.training_runner import (
            build_bounds_for_env,
            build_emergency_controllers,
            build_safety_dt,
            build_safety_filter,
            build_safety_snapshot_builder,
        )
        from concerto.safety.api import SafetyState, make_lambda_dict
        from concerto.safety.conformal import reset_on_partner_swap

        # Construct the filter + bounds from the env.
        safety_filter = build_safety_filter(env)
        safety_bounds = build_bounds_for_env(env)
        snapshot_builder = build_safety_snapshot_builder(env)
        safety_dt = build_safety_dt(env)
        # P1.04.6 (ADR-007 §Stage 1b Rev 8): per-uid emergency-controller
        # dispatch for the in-rollout :func:`maybe_brake` call. Built
        # from the same env-side control-model map :func:`build_safety_filter`
        # consumes, so the Jacobian-vs-DI dispatch matches the outer CBF
        # row's per-uid embodiment assumption.
        emergency_controllers = build_emergency_controllers(env)
        if snapshot_builder is None:
            msg = (
                "TrainedPolicyFactory._build_safety_for_cell: cfg.safety.enabled "
                "is True but env exposes no build_agent_snapshots() method. "
                "The Stage-1b env (chamber.envs.stage1_pickplace.Stage1PickPlaceEnv) "
                "ships this method in P1.04.5; envs that don't are not eligible "
                "for the safety stack."
            )
            raise ValueError(msg)
        # SafetyState construction + warm-start. Issue #144 promoted
        # ``lambda_`` to a :data:`concerto.safety.api.LambdaDict` keyed
        # by canonical UID-pair tuples over the cell's partner set.
        agent_uids = cfg.env.agent_uids
        state = SafetyState(lambda_=make_lambda_dict(agent_uids))
        reset_on_partner_swap(
            state,
            uids=agent_uids,
            lambda_safe=cfg.safety.lambda_safe,
            n_warmup_steps=cfg.safety.n_warmup_steps,
        )
        return {
            "safety_filter": safety_filter,
            "safety_state": state,
            "safety_bounds": safety_bounds,
            "safety_snapshot_builder": snapshot_builder,
            "safety_dt": safety_dt,
            "safety_emergency_controllers": emergency_controllers,
        }

__call__

__call__(
    env: Env[Any, Any], seed: int
) -> EgoActionCallable

Train a per-cell policy and return the per-step closure (ADR-007 §Stage 1b).

Lifecycle: invoked once per (seed, condition) cell by the Stage-1 adapter's :func:_run_axis_with_factories. The returned callable is reused across the 20 evaluation episodes within the cell.

Parameters:

• env (Env[Any, Any]) –

  The per-condition evaluation env. env.ego_uid / env.partner_uid (P1.04 properties on :class:chamber.envs.stage1_pickplace.Stage1PickPlaceEnv) drive the per-condition overrides applied to the base cfg. env itself is NOT stepped by the factory; the training run inside :func:run_training builds its own env from the (overridden) cfg.env. The eval env is what the spike adapter's loop steps after this factory returns.

• seed (int) –

  Per-cell seed; the factory overrides cfg.seed via model_copy.

Returns:

• EgoActionCallable –

  (obs) -> action callable that wraps

• EgoActionCallable –

  trained_policy.act(obs, deterministic=True) and casts

• EgoActionCallable –

  the output to float32.

Raises:

• ValueError –

  Propagated from :meth:EgoPPOTrainer.__init__ if the partner is non-frozen (ADR-009 §Consequences). Any other exception raised by :func:chamber.benchmarks.training_runner.run_training also propagates unchanged (per the test_run_training_failure_propagates contract in tests/integration/test_trained_policy_factory_fake.py).

Source code in src/chamber/benchmarks/stage1_common.py

def __call__(
    self,
    env: gym.Env[Any, Any],
    seed: int,
) -> EgoActionCallable:
    """Train a per-cell policy and return the per-step closure (ADR-007 §Stage 1b).

    Lifecycle: invoked once per ``(seed, condition)`` cell by the
    Stage-1 adapter's :func:`_run_axis_with_factories`. The returned
    callable is reused across the 20 evaluation episodes within
    the cell.

    Args:
        env: The per-condition evaluation env. ``env.ego_uid`` /
            ``env.partner_uid`` (P1.04 properties on
            :class:`chamber.envs.stage1_pickplace.Stage1PickPlaceEnv`)
            drive the per-condition overrides applied to the base
            ``cfg``. ``env`` itself is NOT stepped by the factory;
            the training run inside :func:`run_training` builds
            its own env from the (overridden) ``cfg.env``. The
            eval env is what the spike adapter's loop steps after
            this factory returns.
        seed: Per-cell seed; the factory overrides ``cfg.seed`` via
            ``model_copy``.

    Returns:
        ``(obs) -> action`` callable that wraps
        ``trained_policy.act(obs, deterministic=True)`` and casts
        the output to ``float32``.

    Raises:
        ValueError: Propagated from :meth:`EgoPPOTrainer.__init__`
            if the partner is non-frozen (ADR-009 §Consequences).
            Any other exception raised by
            :func:`chamber.benchmarks.training_runner.run_training`
            also propagates unchanged (per the
            ``test_run_training_failure_propagates`` contract in
            ``tests/integration/test_trained_policy_factory_fake.py``).
    """
    # Imported lazily so chamber.benchmarks.stage1_common stays
    # cheap to import for Stage-1a-only consumers (the Phase-0 path
    # that does not need the HARL HAPPO trainer in scope).
    from chamber.benchmarks.training_runner import run_training

    # 1. Resolve the per-condition ego + partner uids from the env
    #    (P1.04 / Q-C: single source of truth at the env layer).
    #    Fall back to the cfg's agent_uids for envs that don't
    #    expose the properties (Tier-1 fake envs, MPE stand-in).
    ego_uid = self._resolve_ego_uid(env)
    partner_uid = self._resolve_partner_uid(env)

    # 2. Resolve the partner's action_dim from the env's
    #    action_space — avoids a per-condition side-table.
    partner_action_dim = self._resolve_partner_action_dim(env, partner_uid)

    # 3. Resolve the env's condition_id for Stage-1b disambiguation
    #    (OM-homo vs OM-hetero share the same agent_uids tuple, so
    #    the condition_id is the explicit signal that drives the
    #    Stage-1b env build inside run_training → build_env). None
    #    for non-Stage-1b envs; build_env ignores the field when
    #    task != "stage1_pickplace".
    condition_id = self._resolve_condition_id(env)

    # 4. Compose the per-call cfg via Pydantic model_copy so the
    #    base config passed at __init__ is never mutated.
    cfg_for_call = self._compose_cfg_for_call(
        seed=seed,
        ego_uid=ego_uid,
        partner_uid=partner_uid,
        partner_action_dim=partner_action_dim,
        condition_id=condition_id,
    )

    # 5. Build the per-cell safety stack (P1.04.5; ADR-007 §Stage 1b).
    #    When cfg.safety.enabled=True, construct the filter +
    #    SafetyState + Bounds + snapshot builder + dt now, pass
    #    through to run_training. When False, all five stay None
    #    and train() runs the pre-P1.04.5 unfiltered path.
    safety_kwargs = self._build_safety_for_cell(env=env, cfg=cfg_for_call)

    # 6. Drive the chamber-side training entry point. Returns a
    #    TrainingResult NamedTuple (P1.04) carrying the curve +
    #    the trained EgoTrainer instance — no checkpoint
    #    round-trip needed.
    result = run_training(cfg_for_call, repo_root=None, **safety_kwargs)
    trainer = result.trainer

    # 6. Build the per-step closure. Deterministic mode for eval;
    #    cast to float32 so the adapter's step-loop dict can be
    #    handed straight to the env's step boundary.
    def _act(obs: Mapping[str, Any]) -> NDArray[np.float32]:
        """ADR-007 §Stage 1b per-step ego closure (deterministic)."""
        action = trainer.act(obs, deterministic=True)
        return np.asarray(action, dtype=np.float32)

    return _act

__init__

__init__(*, cfg: EgoAHTConfig) -> None

Build the factory; capture the base config.

Vectorised cells (cfg.env.num_envs > 1; ADR-007 §Stage 1b Rev 17): SAPIEN GPU PhysX is enabled eagerly here, at factory construction — which the spike adapters evaluate before any per-cell env build — because GPU PhysX can only be enabled before any other PhysX use in the process, and the adapter's per-cell ordering builds the (CPU-sim) eval env before invoking this factory (issue #215; the gate-readiness note's blocker B1). With GPU PhysX enabled first, both the CPU-sim eval env and the physx_cuda training env compose in either order. Single-env configs are untouched (no SAPIEN import, no side effect).

Parameters:

• cfg (EgoAHTConfig) –

  Validated :class:~concerto.training.config.EgoAHTConfig — the Stage-1b config (typically loaded from configs/training/ego_aht_happo/stage1_pickplace.yaml). The original instance is never mutated; per-call overrides are applied via model_copy.

Raises:

• ChamberEnvCompatibilityError –

  If cfg.env.num_envs > 1 and GPU PhysX cannot be enabled (CUDA/SAPIEN missing, or the process has already used CPU PhysX — e.g. a pytest session whose GPU gate built a probe env; vectorised cells then need a fresh process, exactly as tests/integration/test_stage1_vectorised_real.py isolates them).

Source code in src/chamber/benchmarks/stage1_common.py

def __init__(self, *, cfg: EgoAHTConfig) -> None:
    """Build the factory; capture the base config.

    Vectorised cells (``cfg.env.num_envs > 1``; ADR-007 §Stage 1b
    Rev 17): SAPIEN GPU PhysX is enabled eagerly here, at factory
    construction — which the spike adapters evaluate *before* any
    per-cell env build — because GPU PhysX can only be enabled
    before any other PhysX use in the process, and the adapter's
    per-cell ordering builds the (CPU-sim) eval env before invoking
    this factory (issue #215; the gate-readiness note's blocker B1).
    With GPU PhysX enabled first, both the CPU-sim eval env and the
    ``physx_cuda`` training env compose in either order. Single-env
    configs are untouched (no SAPIEN import, no side effect).

    Args:
        cfg: Validated :class:`~concerto.training.config.EgoAHTConfig`
            — the Stage-1b config (typically loaded from
            ``configs/training/ego_aht_happo/stage1_pickplace.yaml``).
            The original instance is never mutated; per-call
            overrides are applied via ``model_copy``.

    Raises:
        ChamberEnvCompatibilityError: If ``cfg.env.num_envs > 1``
            and GPU PhysX cannot be enabled (CUDA/SAPIEN missing,
            or the process has already used CPU PhysX — e.g. a
            pytest session whose GPU gate built a probe env;
            vectorised cells then need a fresh process, exactly as
            ``tests/integration/test_stage1_vectorised_real.py``
            isolates them).
    """
    if cfg.exploratory.partner_static_override:
        msg = (
            "TrainedPolicyFactory: cfg.exploratory.partner_static_override "
            "is set. EXPLORATORY knobs are structurally barred from the "
            "gate-facing dispatch - the production spike path cannot train "
            "against a static-override partner. Sole pre-stated use: the "
            "2026-06-11 homo-static slice (its own driver, not this "
            "factory). Gate-facing use requires an ADR, not a config edit."
        )
        raise ValueError(msg)
    if cfg.env.num_envs > 1:
        _ensure_gpu_physx_enabled(num_envs=cfg.env.num_envs)
    self._cfg = cfg