Spanda

Unified Entity Model

The Unified Entity Model is a foundational platform pillar in Spanda. Every object managed by the platform — robots, fleets, humans, wearables, devices, providers, packages, missions, facilities, and control centers — is represented as an Entity with shared properties, relationships, health, readiness, trust, security, and lifecycle semantics.

Why a unified model?

As Spanda expands across industries (ADAS, healthcare, search & rescue, industrial automation, spatial computing), dedicated top-level models for each object type become inconsistent. The entity model provides:

• One registry and graph for traversal, dependency analysis, and impact analysis
• One query language for operational questions (“which robots use firmware X?”)
• One Control Center browse path for health, readiness, trust, and relationships
• Backward-compatible APIs — existing /v1/devices, /v1/robots, /v1/humans routes remain unchanged

Architecture

TOML / runtime sources                Unified projection
─────────────────────                 ──────────────────
DeviceTree ──────────┐
DeviceRegistry ──────┼──► build_entity_registry() ──► EntityRegistry
HumanRegistry ───────┤                                      │
LogicalPhysicalMap ──┤                                      ├── EntityGraph
Packages / Providers ┘                                      └── EntityQuery

Canonical implementation: crates/spanda-config/src/entity.rs

API surface: GET /v1/entities/* in crates/spanda-api/src/sdk_ops.rs

SDK: SpandaClient::list_entities, entity_graph, query_entities in crates/spanda-sdk

Entity hierarchy

The type taxonomy is extensible. Built-in kinds include:

Category	Entity kinds
People & teams	human, team
Autonomous systems	robot, drone, vehicle, fleet, swarm, ai_agent
Devices	device, sensor, actuator, camera, gps, plc, gateway, controller, wearable, medical_device
Spatial	ar_device, vr_device, iot_device
Software	provider, package, edge_service, cloud_service
Operations	mission, incident, digital_twin
Places	facility, building, zone, hazard, organization
Control	command_center, control_center
Custom	custom string via EntityKind::Custom

Domain-specific TOML types (HumanEntity, RobotNode, DeviceIdentityRecord, …) remain the source of truth. They project into EntityRecord — they are not replaced.

Common properties

Every EntityRecord carries:

Property	Description
id	Unique identifier
name, display_name, description	Human-facing labels
entity_type	Typed kind (EntityKind)
parent_id, children_ids	Hierarchy
labels, tags	Filtering and grouping
version, manufacturer, model, serial_number	Identity
hardware_revision, firmware_version, software_version	Revision tracking
provider, package	Software supply chain
location	Coordinates, zone references
capabilities	Operational capabilities
health_status	healthy, warning, degraded, offline, critical, unknown
readiness_status	ready, not_ready, partial, unknown
trust_status	verified, trusted, untrusted, compromised, unknown
security	Identity, certificates, permissions
lifecycle_state	discovered → archived
owner, metadata, audit	Governance

Legacy API field kind is preserved as an alias of entity_type.as_str() for SDK compatibility.

Entity capabilities

Capabilities are plain strings on the entity record. Examples:

Entity	Capabilities
Human	operate_robot, approve_mission, emergency_override
Robot	navigate, pick, place, inspect
Wearable	heart_rate, gps, fall_detection
Mission	pause, resume, cancel
Package	install, update, validate

Capability requirements for missions continue to flow through readiness and assurance crates; entities expose the inventory view.

Health, readiness, trust, security, lifecycle

Dimension	Enum	Notes
Health	EntityHealthStatus	Derived from device pool health and human health fields
Readiness	EntityReadinessStatus	Derived from lifecycle and operator availability
Trust	EntityTrustStatus	Maps legacy trust_level strings
Lifecycle	EntityLifecycleState	Maps DeviceLifecycleState and availability
Security	EntitySecurityIdentity	Certificates, permissions from TOML security sections

See also: entity-apis.md, entity-sdk.md, entity-verification.md, entity-relationships.md, entity-registry.md, entity-graph.md, entity-query-language.md.

Cognitive & Resilience profile (Entity.autonomy)

Functional domain state attaches via EntityAutonomyProfile on every entity. Populated by spanda-autonomy at registry load and enriched at GET /v1/entities/{id}/autonomy.

Field	Functional domain	Type
reflexes	Reflex & Safety	Vec<EntityReflexSummary>
attention	Attention Engine	EntityAttentionSnapshot
confidence	Sensory Fusion	EntityConfidenceSnapshot
homeostasis	Homeostasis Engine	EntityHomeostasisSnapshot
immunity_status	Platform Immunity	EntityImmunityStatus
memory_refs	Operational Memory	EntityMemoryRefs
damage_risk	Damage Risk Assessment	EntityDamageRisk
recovery_confidence	Adaptive Learning	EntityRecoveryConfidence

Guide: cognitive-resilience-architecture.md · Matrix: responsibility-matrix.md

API (additive)

Full REST and gRPC reference: entity-apis.md. SDK methods: entity-sdk.md.

Method	Path	Description
GET	/v1/entities	List entities (optional query filters)
GET	/v1/entities/graph	Full entity graph
POST	/v1/entities/query	Structured query body
GET	/v1/entities/{id}	Entity detail
GET	/v1/entities/{id}/relationships	Edges, impact analysis, dependency chain
GET	/v1/entities/{id}/health	Health snapshot
GET	/v1/entities/{id}/readiness	Readiness snapshot
POST	/v1/entities/{id}/verify	Unified verification (hardware, mission, fleet, device pool)
GET	/v1/entities/{id}/autonomy	Cognitive & resilience profile (enriched)
GET	/v1/entities/traceability	Unified traceability (entity + program graph)
POST	/v1/entities/register	Register or update entity overlay (Bearer)
POST	/v1/entities/{id}/tags	Add or remove tags (Bearer)
POST	/v1/entities/relationships	Relate two entities (Bearer)
POST	/v1/entities/sync	Sync overlay to TOML fragments (Bearer)

gRPC (tonic): same JSON payloads via entity RPCs on --grpc-bind (pin proto semver via GET /v1/version — currently 1.0.14, 164 RPCs). Mutations require Bearer metadata (Rust GrpcClient reads SPANDA_API_KEY). JSON-RPC gateway exposes read-only entity methods via POST /v1/rpc.

Existing routes (/v1/devices, /v1/robots, /v1/fleets, /v1/humans, …) are unchanged.

Control Center

The Entities tab in @davalgi-spanda/web uses the unified API:

• Browse and search the entity inventory
• Inspect health, readiness, trust, capabilities
• Traverse relationship edges and neighborhood graph

Component: packages/web/src/EntityGraphPanel.tsx

Roadmap integration

Before adding a new top-level platform abstraction, ask:

Should this be modeled as a new Entity kind?

If yes, extend EntityKind, add a projection in build_entity_registry, and document the mapping. See ../ROADMAP.md — Pillar 0 — Unified Entity Model.

Cross-references:

Roadmap item	Entity mapping
Device Registry (Pillar 4)	device, sensor, actuator, …
Human entity model (Pillar 4)	human, wearable, digital_twin
Fleet / swarm (Pillar 4)	fleet, robot, swarm
Provider registry (Pillar 2)	provider
Package loader (Pillar 2)	package
Digital thread (Pillar 6)	Graph edges complement dependency graph
Trust / security (Pillar 5)	trust_status, security on every entity

Migration plan

Phase 1 — Foundation (shipped)

• EntityRecord, EntityRegistry, EntityGraph, EntityQuery in spanda-config
• build_entity_registry(&ResolvedSystemConfig) projects fleet tree, device registry, human registry, logical map, packages, providers
• Expanded /v1/entities/* REST API (backward compatible kind field)
• Control Center Entities tab
• SDK typed fields on Entity

Phase 2 — Runtime missions (Complete)

• Project runtime MissionRuntime into entity registry during active programs
• Link mission entities to robot/fleet entities via participates_in edges
• Mission readiness overlays on entity readiness API

Phase 3 — Graph unification (Complete)

• Align spanda-graph dependency nodes with entity IDs
• Merge digital-thread device links into entity relationship store
• Unified traceability queries across program graph and entity graph (GET /v1/entities/traceability)

Phase 4 — Industry extensions (Complete)

• Facility, building, zone entities from solution blueprint TOML (spanda.facilities.toml, [[entity_kinds]])
• Medical device and ADAS-specific entity kinds with compliance metadata (entity_kind, compliance_profile, assurance/readiness/security profiles)
• Custom entity kinds via package manifests ([entity_kinds] on PackageManifest) and blueprint [[entity_kinds]]

Phase 5 — Write path (Complete)

• Entity mutation APIs (register, tag, relate) with audit
• Bi-directional sync from entity registry to TOML fragments (POST /v1/entities/sync)

Phase 6 — Verification integration (Complete)

• verify_entity in spanda-readiness routes all verification engines through EntityRegistry
• POST /v1/entities/{id}/verify REST endpoint
• spanda entity verify CLI and full spanda entity command family
• SDK entity_verify / verifyEntity on Rust, TypeScript, and Python clients
• CI smoke coverage in scripts/entity_model_smoke.sh

Phase 7 — Readiness, health, trust integration (Complete)

• evaluate_entity_readiness — kind-routed readiness with issues and score
• evaluate_entity_health — diagnostics, metrics, program health checks
• evaluate_entity_trust in spanda-trust — package, device, composite trust
• Enriched GET /v1/entities/{id}/health|readiness|trust with report payloads
• CLI spanda entity health|readiness|trust call evaluation engines locally

Stabilization (Complete)

• CI smoke script scripts/entity_model_smoke.sh (graph, traceability, query, mutations, TypeScript + Python SDK)
• Control Center Entities tab write UI (register, tag, relate, sync) with API key auth
• SDK parity: registerEntity / register_entity, tagEntity / tag_entity, relateEntities / relate_entities, syncEntities / sync_entities, entityGraph / entity_graph, entityTraceability / entity_traceability, queryEntities / query_entities (TypeScript, Python, Rust REST + Rust GrpcClient gRPC)
• Stable promotion gate: scripts/entity_model_stable_promotion_gate.sh + CI Nightly entity-model-promotion-gate — entity-model-stable-promotion.md

Promotion to Stable — Complete (2026-06-29)

• Implementation phases 1–7 and stabilization checklist
• SDKs published at 0.4.2 — cargo add spanda-sdk, pip install spanda-sdk, npm install @davalgi-spanda/sdk
• docs/feature-status.md Unified Entity Model row set to Stable
• CI Integration entity-model-smoke and CI Nightly entity-model-promotion-gate (implementation checks)

Shared enterprise field soak and third-party audit sign-off remain tracked separately for broader platform Stable tiers — see field-soak-gate.md.

Compatibility guarantees

1. No breaking changes to existing REST routes or TOML schemas in Phase 1–3
2. kind field on list responses remains stable for SDK consumers
3. Domain crates (HumanEntity, DeviceIdentityRecord, …) stay authoritative for configuration authoring

Developer checklist — adding a new industry object

1. Add or reuse an EntityKind variant (or Custom string)
2. Implement projection in build_entity_registry from your TOML/runtime source
3. Emit EntityRelationship edges to related entities
4. Add query filter fields if needed on EntityQuery
5. Update feature-status.md and roadmap cross-reference
6. Add Control Center filter label if user-facing

This site is open source. Improve this page.