Skip to content

entity-model.md

Latest commit

 

History

History
285 lines (218 loc) · 13.3 KB

entity-model.md

File metadata and controls

285 lines (218 loc) · 13.3 KB
Raw

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.15, 174 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.5.9 — 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