Shielding¶

Shielding prevents unsafe actions before they reach the environment. The project contains two related shielding paths: ordinary local shielding and contract-aware shielding.

Ordinary Local Shields¶

An ordinary local shield is the factorised Shielded-* baseline: one shield is synthesized for one protected agent at a time. It combines:

• the environment abstraction,
• one deterministic safety monitor,
• the protected agent's local action space,
• the set of successors reachable under teammate behavior.

A local action is safe only if all resulting product states remain in the winning region. This is robust with respect to teammates, which is simple and strong but can reject coordinated safe behavior.

At runtime, ShieldedParallelEnv emits action masks. A learner should sample only from allowed actions. If it submits a masked-out action, the wrapper treats that as a caller error.

The reward cost of ordinary shielding comes from the word "all" above. If an action is safe only when a teammate also cooperates, the ordinary local shield must reject it because the teammate might do anything. This is why ordinary shielding can be safety-correct but reward-suboptimal in tasks such as yielding on a shared track, coordinated loading, keeping a door open, or clearing a reserved route.

Contract Shields¶

A contract shield is synthesized for a whole certified contract profile. The product state contains the environment abstraction plus every agent's local-obligation monitor state.

At a product state, the shield computes allowed local actions for each agent. Those sets are safe only when every joint action formed from them keeps the full profile inside the certified fixed point. The contract shield can therefore use the fact that teammates are also obligation-constrained.

Contract shielding can improve reward when the active profile captures a reward-useful cooperation pattern. The profile does not weaken the global monitor; it makes teammate behavior less adversarial by adding certified local obligations such as yielding, holding a door, preserving route clearance, or cooperative loading. If those obligations match the task bottleneck, the contract mask can allow actions that ordinary local shielding must block.

This is not automatic. A certified library can be safe but unhelpful if the global formula is anti-reward, the local alphabet lacks the relevant coordination propositions, the first profile is too conservative, or the profile selector does not discover the high-return profile during training.

Monitoring Still Matters¶

The outer safety monitor remains the final witness for global safety. Shielding is a preventative mechanism, and monitoring records whether the trace actually violates the global formula. Benchmark evidence should be discarded if a shielded or contract run reports a global safety violation.

Where The Code Lives¶

• src/shield/core.py contains ordinary product graphs, winning regions, and LocalShield.
• src/shield/contracts.py contains local-obligation generation, contract certification, certified libraries, and contract-aware local shields.
• src/shield/wrapper.py contains the PettingZoo wrappers that expose masks and safety metrics to learners.