Status: Stable — runtime enforcement, signing, escalation persistence, and conflict resolution are implemented and tested. See stable-hardening-distributed-decisions.md.
Spanda implements a brain / spinal cord / reflex model for hierarchical distributed autonomy. Decisions are made at the appropriate layer — closest to the device for safety and latency, centrally for strategy and governance.
Philosophy and naming: overview/philosophy.md.
| Layer | Name | Latency | Purpose |
|---|---|---|---|
| 0 | Reflex | milliseconds | Immediate safety (stop motor, e-stop, reject untrusted signal) |
| 1 | Local Entity | ms–seconds | Bounded local autonomy (degraded mode, sensor failover, offline continue) |
| 2 | Group / Fleet | seconds | Multi-entity coordination (reassign, delegate, swarm consensus) |
| 3 | Control Center | seconds–minutes | Strategy, policy, assurance, human approval |
Local decisions never bypass:
Central orchestration must not block immediate safety reflexes.
This architecture is extended (not replaced) by the Cognitive & Resilience Architecture: sensory fusion, homeostasis, platform immunity, operational memory, attention, habituation, damage-risk modeling, adaptive recovery, and maintenance windows — all entity-integrated.
Offline operation is bounded by signed policy with expiration.
Every distributed decision is auditable and replayable.
Declare per-entity authority inside robot blocks:
robot Rover001 {
local_decision_authority [emergency_stop, degraded_mode, return_home];
requires_central_approval [override_safety_policy, update_firmware];
}
Define local decision trees:
decision_tree GPSLossRecovery local {
when gps.status == Failed {
if visual_odometry.available { enter degraded_mode; }
else { pause_mission; }
}
}
Define offline bounds:
offline_policy RoverOffline {
max_duration = 30 min;
allowed_actions [continue_current_safe_mission, return_home];
forbidden_actions [disable_safety, accept_unknown_device];
}
During run / sim with SPANDA_DECISION_TRACE=1 or --record:
| Event | Layer | When |
|---|---|---|
kill_switch_activated |
reflex | Kill switch activation |
emergency_stop |
reflex | emergency_stop statement or scheduler halt |
safety_validate_rejected |
reflex | safety.validate() rejects a proposal |
decision_tree_eval |
local / fleet | Live tree match on health-fault injection or scheduler poll |
decision_action_blocked / decision_escalation_pending |
local / control_center | Offline policy or requires_central_approval gate at action dispatch |
continuity_takeover |
local / fleet | Continuity handoff |
fleet_mesh_continuity / fleet_mesh_recovery |
group_fleet | Fleet mesh relay with consensus trace |
DecisionRuntime is injected from CLI (DecisionBackedRuntime); TypeScript
collectDecisionDiagnostics mirrors Rust collect_decision_diagnostics for spanda check
--readiness-json.
spanda decision list mission.sd
spanda decision inspect mission.sd --entity Rover001
spanda decision simulate mission.sd --offline
spanda decision trace mission.trace
spanda decision explain mission.trace
spanda decision policy mission.sd
spanda decision sign-policy mission.sd --policy RoverOffline --write-cache
spanda decision cache show|sync|clear ...
spanda decision security-audit
spanda decision simulate-attack policy-tamper
spanda decision simulate-attack replayed-decision
spanda decision simulate-attack fake-coordinator
spanda decision simulate-attack offline-abuse
Flagship demo: distributed-decision-demo.md
| Method | Path | Description |
|---|---|---|
| GET | /v1/decisions |
List authorities, trees, offline policies |
| GET | /v1/entities/{id}/decisions |
Entity-scoped decision evaluation |
| POST | /v1/decisions/simulate |
Simulate under failure scenarios |
| POST | /v1/decisions/escalate |
Approve pending escalation |
| GET | /v1/decision-policies |
Offline policy specs from loaded program |
| GET | /v1/decisions/traces |
List v3 decision frames from mission trace (?file= or ?trace=) |
| GET | /v1/decision-policy-cache |
Persisted signed offline policy cache on disk |
| POST | /v1/programs/simulation |
Run sim; set decision_trace and record_trace for v3 frames |
Env knobs for runtime gates in sim: SPANDA_CENTRAL_CONNECTED, SPANDA_OFFLINE_MINUTES,
SPANDA_DECISION_ESCALATION_APPROVED.
client.list_decisions()?;
client.list_decision_traces(None, None)?;
client.list_decision_policy_cache(None)?;
client.get_entity_decisions("Rover001")?;
client.simulate_decision(&body)?;
client.approve_escalation(&body)?;
examples/showcase/distributed_decisions/ — GPS loss recovery, obstacle reflex, offline continue,
fleet takeover, swarm consensus, control center escalation.