Action Gating

Action gating extends the evaluation pipeline to preview proposed actions before they execute. It is a session-only feature available in state_plus_action_gate mode.

How Action Gating Works

When an EvaluationRequest includes a ProposedAction, the session:

1. Looks up a registered ActionPhysicsMapper for the action’s type
2. The mapper translates the domain action into a simulation move direction (left, stay, right)
3. The engine executes a preview tick — a simulation step that does not advance real time
4. The preview result is analyzed for adverse warning signals or loss events
5. The gate status is recorded in evaluation.actionGate

Preview is non-destructive: it forks the engine state, runs the tick, examines the outcome, and discards the fork. The real engine state is unchanged.

ProposedAction Format

{
  "type": "api_call",
  "target": "external_service",
  "payload": {
    "method": "POST",
    "endpoint": "/v1/execute"
  }
}

Field	Description
type	Action type string used to look up the mapper
target	Action target (service, device, endpoint)
payload	Opaque action-specific data passed to the mapper

ActionPhysicsMapper

The ActionPhysicsMapper trait defines how domain actions map onto simulation physics:

pub trait ActionPhysicsMapper: Send + Sync {
    fn map_action(
        &self,
        context: &ActionMappingContext,
    ) -> Result<ActionPhysicsMapping, ActionMapperError>;
}

The mapper receives an ActionMappingContext containing:

• The proposed action (type, target, payload)
• Current engine telemetry (warning signal, gamma, lambda)
• Actor ID

It returns an ActionPhysicsMapping with:

• A simulation move direction
• Optional metadata about the mapping decision

Built-in Mappers

Mapper	Crate	Action types	Mapping strategy
LLM Adapter	kairos-llm-adapter	LLM pipeline actions	Maps AI safety evaluation parameters onto move directions
MoE Adapter	kairos-moe-adapter	Expert routing decisions	Maps expert group routing onto the Substrate actor model

Custom mappers can be implemented by downstream integrations for domain-specific action types.

Mapper Registry

Mappers are registered on the SubstrateSession via ActionPhysicsMapperRegistry. Each mapper handles one or more action types. When an action arrives, the registry looks up the mapper by action.type:

• If a mapper is found → it maps the action and runs the preview
• If no mapper is found → the gate falls back to state-only evaluation with FALLBACK_STATE_ONLY

Action Gate Status

The evaluation.actionGate block in the response reports the gate outcome:

{
  "status": "MAPPED_PASS",
  "fallbackReason": null,
  "predictedMoveDirection": "right",
  "predictedWarningSignal": {
    "active": false,
    "level": 0.0,
    "kind": "NONE",
    "metrics": { ... }
  },
  "predictedLossEvent": null
}

Status Values

Status	Meaning
FALLBACK_STATE_ONLY	No mapper registered for this action type; state-gate result used
MAPPED_PASS	Mapper translated action, preview shows safe outcome
MAPPED_REJECT	Mapper translated action, preview shows unsafe outcome
MAPPER_ERROR	Mapper returned an error during translation

Fallback Reasons

When the status is FALLBACK_STATE_ONLY, the fallbackReason field explains why:

• No mapper registered for the action type
• Action field was absent from the request
• Mode is not state_plus_action_gate

Direction Tables

The mapper translates domain actions into one of three simulation move directions:

Direction	Simulation meaning	Typical domain mapping
left	Conservative / defensive move	Reduce scope, add constraints, limit autonomy
stay	Maintain current trajectory	Continue as-is, no significant change
right	Aggressive / expansive move	Increase scope, reduce constraints, expand autonomy

The direction determines which reachability path the preview explores. A right move into an area of low gamma headroom will trigger warnings and potential rejection, while a left move in the same state may pass safely.

Multi-Actor Preview

In multi-actor sessions, action preview uses coordinated baseline policy moves for non-evaluated actors. When previewing actor A’s proposed action, all other actors use their policy-decided moves (decide_all_moves()). This ensures the preview reflects realistic multi-agent dynamics rather than assuming other actors stand still.