# Spanda Platform Architecture Manifest v2.0 # Source of truth for layer classification, dependency governance, and CI validation. # See docs/platform-architecture.md and docs/module-ownership.md. # # After editing this file, regenerate JSON for CI: # ruby -ryaml -rjson -e 'puts JSON.pretty_generate(YAML.load_file("scripts/architecture-manifest.yaml"))' \ # > scripts/architecture-manifest.json version: "2.0" # Layers are ordered bottom → top. A module at layer N may depend only on layers 0..N-1 # (strict) unless listed in dependency_waivers. layers: - id: foundation index: 0 title: Foundation description: Utilities, logging, configuration primitives, serialization, diagnostics, common types. - id: compiler index: 1 title: Compiler description: Lexer, parser, AST, type checker, SIR, optimizers, LLVM/WASM backends, compile-time tooling. - id: language_runtime index: 2 title: Language Runtime description: Scheduler, trigger engine, interpreter, execution engine, concurrency, task system, comm, safety, HAL. - id: core_platform index: 3 title: Core Platform description: Entity model, device registry, capability framework, hardware profiles, mission model, config, provider/package registries, transport. - id: platform_services index: 4 title: Platform Services description: Readiness, assurance, diagnosis, recovery, trust, health, security services, telemetry, simulation hooks, replay, policy. - id: interfaces index: 5 title: Interfaces description: Control Center, SDKs, REST API, gRPC, CLI, VS Code extension, WASM/Node bindings, public facade. - id: solution_blueprints index: 6 title: Solution Blueprints description: Industry compositions (warehouse, SAR, ADAS, healthcare, agriculture, …) — no new platform features. # Rust workspace crates — primary layer assignment. rust_crates: # Foundation spanda-audit: { layer: foundation, owner: security-audit, responsibility: Audit records, provenance, ledger abstractions. } spanda-connectivity: { layer: foundation, owner: connectivity, responsibility: Connectivity and positioning type catalogs. } spanda-deploy-http: { layer: foundation, owner: fleet-ota, responsibility: Minimal HTTP/1.1 for deploy and fleet agents. } spanda-regex-lang: { layer: compiler, owner: compiler, responsibility: First-class regex compilation. } # Compiler spanda-ast: { layer: compiler, owner: compiler, responsibility: AST nodes, foundations, comm declarations. } spanda-lexer: { layer: compiler, owner: compiler, responsibility: Tokenization and keywords. } spanda-parser: { layer: compiler, owner: compiler, responsibility: AST construction from tokens. } spanda-typecheck: { layer: compiler, owner: compiler, responsibility: Physical units and type system. } spanda-error: { layer: compiler, owner: compiler, responsibility: Compiler and runtime error types. } spanda-sir: { layer: compiler, owner: compiler, responsibility: Typed IR between AST and backends. } spanda-modules: { layer: compiler, owner: compiler, responsibility: Multi-file module loader. } spanda-format: { layer: compiler, owner: tooling, responsibility: Source formatter. } spanda-lint: { layer: compiler, owner: tooling, responsibility: Static analysis linter. } spanda-codegen: { layer: compiler, owner: tooling, responsibility: Codegen metadata from SIR. } spanda-docs: { layer: compiler, owner: tooling, responsibility: Program and language reference generators. } spanda-llvm: { layer: compiler, owner: codegen, responsibility: SIR → LLVM IR emitter (experimental). } spanda-rt: { layer: compiler, owner: codegen, responsibility: Native runtime C ABI (experimental). } # Language Runtime spanda-runtime: { layer: language_runtime, owner: runtime, responsibility: Scheduler, provider types, runtime state. } spanda-interpreter: { layer: language_runtime, owner: runtime, responsibility: Tree-walking interpreter and simulator. } spanda-runtime-host: { layer: language_runtime, owner: runtime, responsibility: Default RuntimeHost wiring. } spanda-comm: { layer: language_runtime, owner: runtime, responsibility: Comm bus trait and in-memory transport. } spanda-safety: { layer: language_runtime, owner: runtime, responsibility: Safety monitor, zones, motion validation. } spanda-hal: { layer: language_runtime, owner: runtime, responsibility: HAL simulation, SoC profiles, health hooks. } spanda-concurrency: { layer: language_runtime, owner: runtime, responsibility: Channels, spawn, select. } spanda-debug: { layer: language_runtime, owner: runtime, responsibility: Debugger and breakpoints. } spanda-ai: { layer: language_runtime, owner: runtime, responsibility: AI model registry and agent runtime. } spanda-connectivity-runtime: { layer: language_runtime, owner: runtime, responsibility: Runtime helpers from AST connectivity declarations. } spanda-bridge: { layer: language_runtime, owner: ffi, responsibility: Python/C++ extern bridges. } spanda-ffi: { layer: language_runtime, owner: ffi, responsibility: Extern function registry. } spanda-lib-registry: { layer: language_runtime, owner: runtime, responsibility: Sensor driver library registry. } spanda-driver: { layer: language_runtime, owner: runtime, responsibility: Lex → parse → type-check → run orchestration. } # Core Platform spanda-config: { layer: core_platform, owner: entity-config, responsibility: Entity model, cascading TOML config, device tree, validation. } spanda-hardware: { layer: core_platform, owner: hardware, responsibility: Builtin hardware profile catalog. } spanda-capability: { layer: core_platform, owner: capability, responsibility: Capability registry, traceability, health analysis. } spanda-certify: { layer: core_platform, owner: verify, responsibility: Deploy certification proof checklist. } spanda-package: { layer: core_platform, owner: packages, responsibility: Manifest, dependency resolution, registry. } spanda-providers: { layer: core_platform, owner: providers, responsibility: Official package bootstrap and transport wiring. } spanda-transport: { layer: core_platform, owner: transport, responsibility: Adapter traits, security policy, TLS. } spanda-transport-routing: { layer: core_platform, owner: transport, responsibility: RoutingCommBus across adapters. } spanda-transport-mqtt: { layer: core_platform, owner: transport, responsibility: MQTT backend. } spanda-transport-ros2: { layer: core_platform, owner: transport, responsibility: ROS 2 backend. } spanda-transport-dds: { layer: core_platform, owner: transport, responsibility: DDS backend. } spanda-transport-websocket: { layer: core_platform, owner: transport, responsibility: WebSocket backend. } spanda-ros2-rclrs-native: { layer: core_platform, owner: transport, responsibility: Native ROS 2 I/O via rclrs (optional). } spanda-fleet: { layer: core_platform, owner: fleet, responsibility: Fleet peer relay and mesh coordination. } spanda-ota: { layer: core_platform, owner: fleet, responsibility: OTA planning, agents, rollout. } spanda-core: { layer: core_platform, owner: platform, responsibility: Stable public facade for external embedders. } # Platform Services spanda-readiness: { layer: platform_services, owner: readiness, responsibility: Operational readiness and mission verification. } spanda-assurance: { layer: platform_services, owner: assurance, responsibility: Mission assurance and deployment evidence. } spanda-explain: { layer: platform_services, owner: diagnosis, responsibility: Explainability and failure reports. } spanda-runtime-faults: { layer: platform_services, owner: diagnosis, responsibility: Runtime fault detection. } spanda-decision: { layer: platform_services, owner: diagnosis, responsibility: Decision audit trail parsing. } spanda-graph: { layer: platform_services, owner: diagnosis, responsibility: Dependency graph and entity alignment visualization. } spanda-diff: { layer: platform_services, owner: diagnosis, responsibility: Mission differencing and change impact. } spanda-contract: { layer: platform_services, owner: assurance, responsibility: Mission contract static verification. } spanda-score: { layer: platform_services, owner: assurance, responsibility: Autonomous systems scorecard. } spanda-compliance: { layer: platform_services, owner: assurance, responsibility: Industry compliance profiles. } spanda-chaos: { layer: platform_services, owner: assurance, responsibility: Chaos engineering experiments. } spanda-autonomy: { layer: platform_services, owner: autonomy, responsibility: Bio-inspired autonomy — reflex, homeostasis, immunity, memory. } spanda-governance: { layer: platform_services, owner: governance, responsibility: Operational governance, deployment profiles, certification validation. } spanda-plugin: { layer: platform_services, owner: plugins, responsibility: Versioned capability-controlled plugin system. } spanda-recovery: { layer: platform_services, owner: recovery, responsibility: Recovery orchestrator — planning, coordination, validation. } spanda-risk: { layer: platform_services, owner: governance, responsibility: Mission deployment risk scoring. } spanda-twin-cloud: { layer: platform_services, owner: control-center, responsibility: Digital mission twin cloud sync. } spanda-whatif: { layer: platform_services, owner: diagnosis, responsibility: What-if failure scenario analysis. } spanda-estimate: { layer: platform_services, owner: assurance, responsibility: Mission resource estimation. } spanda-policy: { layer: platform_services, owner: policy, responsibility: Operational policy evaluation. } spanda-tamper: { layer: platform_services, owner: security, responsibility: Tamper and integrity analysis. } spanda-trust: { layer: platform_services, owner: trust, responsibility: Composite program trust scoring. } spanda-spoofing: { layer: platform_services, owner: security, responsibility: GPS/sensor spoofing detection. } spanda-threat: { layer: platform_services, owner: security, responsibility: Pre-deployment threat modeling. } spanda-security: { layer: platform_services, owner: security, responsibility: Identity, secrets, capabilities, signed messages. } spanda-telemetry-store: { layer: platform_services, owner: telemetry, responsibility: Persistent append-only telemetry, replay substrate. } spanda-ops: { layer: platform_services, owner: control-center, responsibility: Alerting and incident routing. } spanda-adr: { layer: platform_services, owner: dx, responsibility: Architecture decision record generation. } spanda-generate: { layer: platform_services, owner: dx, responsibility: Guardrailed template generation. } # Interfaces spanda-cli: { layer: interfaces, owner: cli, responsibility: Native CLI — check, run, sim, verify, entity, fleet. } spanda: { layer: interfaces, owner: cli, responsibility: Native CLI package name (crates/spanda-cli). } spanda-api: { layer: interfaces, owner: control-center, responsibility: REST and gRPC Control Center API v1. } spanda-sdk: { layer: interfaces, owner: sdk, responsibility: Official Rust SDK for Control Center API. } spanda-node: { layer: interfaces, owner: bindings, responsibility: Node.js N-API bindings. } spanda-wasm: { layer: interfaces, owner: bindings, responsibility: WebAssembly bindings. } spanda-dap: { layer: interfaces, owner: bindings, responsibility: Debug Adapter Protocol server. } # TypeScript / npm packages and SDKs. typescript_packages: src: { layer: language_runtime, owner: runtime, responsibility: TypeScript mirror of lean-core runtime and compiler. } packages/lsp: { layer: interfaces, owner: tooling, responsibility: Language Server Protocol for .sd files. } packages/web: { layer: interfaces, owner: control-center, responsibility: Control Center React panel and web playground. } packages/native: { layer: interfaces, owner: bindings, responsibility: N-API wrapper around spanda-node. } packages/control-center-desktop: { layer: interfaces, owner: control-center, responsibility: Tauri desktop Control Center shell. } sdk/typescript: { layer: interfaces, owner: sdk, responsibility: Official TypeScript SDK for Control Center API. } sdk/python: { layer: interfaces, owner: sdk, responsibility: Official Python SDK for Control Center API. } editor/vscode: { layer: interfaces, owner: tooling, responsibility: VS Code extension (syntax, LSP, debug). } # TypeScript path prefix → layer (longest match wins under src/). typescript_module_layers: src/comm/decls.ts: compiler src/ast/assurance-decls.ts: compiler src/readiness-types.ts: compiler src/types/sensor-types.ts: compiler src/types/checker-host.ts: compiler src/hardware-profile-types.ts: language_runtime src/rust-bridge-types.ts: language_runtime src/runtime/continuity-types.ts: language_runtime src/cli/checker-host.ts: interfaces src/cli/deploy-readiness-bridge.ts: interfaces src/cli/certify-bridge.ts: interfaces src/cli/hardware-verify-bridge.ts: interfaces src/cli: interfaces src/cli/run-program.ts: interfaces src/lsp: interfaces src/adapter-bridge.ts: interfaces src/adapter-verify.ts: interfaces src/adapter-package-verify.ts: interfaces src/lexer: compiler src/parser: compiler src/ast: compiler src/types: compiler src/units: compiler src/modules: compiler src/compile.ts: compiler src/foundations.ts: compiler src/type-system.ts: compiler src/regex.ts: compiler src/units.ts: compiler src/stdlib.ts: compiler src/assurance.ts: platform_services src/assurance_decl.ts: platform_services src/readiness.ts: platform_services src/operational.ts: platform_services src/telemetry-store.ts: platform_services src/telemetry-store-bridge.ts: platform_services src/security-runtime-bridge.ts: platform_services src/adapter-runtime-bridge.ts: interfaces src/provider-runtime-bridge.ts: language_runtime src/telemetry-cli.ts: platform_services src/telemetry-otlp.ts: platform_services src/telemetry-sqlite.ts: platform_services src/certify-runtime.ts: platform_services src/certify-verify.ts: platform_services src/certify-prover.ts: platform_services src/mission-continuity.ts: platform_services src/recovery.ts: platform_services src/security: platform_services src/trust: platform_services src/hardware-verify.ts: core_platform src/hardware-profile.ts: core_platform src/config-fallback.ts: core_platform src/fleet-agent.ts: core_platform src/fleet-mesh.ts: core_platform src/fleet-orchestrator.ts: core_platform src/fleet-remote.ts: core_platform src/deploy-agent.ts: core_platform src/deploy-bundle.ts: core_platform src/deploy-remote.ts: core_platform src/deploy-service.ts: core_platform src/swarm-coordinator.ts: core_platform src/connectivity-positioning.ts: language_runtime src/runtime: language_runtime src/comm: language_runtime src/safety: language_runtime src/hal: language_runtime src/simulator: language_runtime src/ai: language_runtime src/ffi: language_runtime src/transport: language_runtime src/providers: language_runtime src/ros2: language_runtime src/navigation: language_runtime src/soc: language_runtime src/lib: language_runtime src/concurrency.ts: language_runtime src/reliability.ts: language_runtime src/replay.ts: language_runtime src/network.ts: language_runtime src/continuity-checkpoint.ts: language_runtime src/readiness-spans.ts: language_runtime src/telemetry-fleet.ts: platform_services src/telemetry-push.ts: platform_services src/rust-bridge.ts: language_runtime solution_blueprints: - path: examples/end_to_end/warehouse_delivery name: Warehouse - path: examples/solutions/spatial-computing/search-and-rescue-ar name: Search and Rescue - path: examples/solutions/adas name: ADAS - path: examples/solutions/spatial-computing/wearable-health name: Healthcare - path: examples/solutions/agriculture name: Agriculture - path: examples/solutions/environmental-monitoring name: Environmental Monitoring - path: examples/solutions/maritime name: Maritime - path: examples/solutions/spatial-computing name: Spatial Computing # Canonical entity types — single source of truth in spanda-config. canonical_entity_types: owner_crate: spanda-config primary_types: - EntityRecord - EntityRegistry - EntityGraph - EntityQuery - EntityRelationship - EntityKind specialized_kinds: - Robot - Mission - Package - Provider - Human - Device - Fleet - Wearable - Facility forbidden_duplicates: - RobotRecord - DeviceRecord - MissionRecord - FleetRecord duplicate_type_exceptions: - crate: spanda-audit type: MissionRecord reason: Audit mission summary envelope, not entity Mission kind. # Common platform event model (see docs/event-model.md). event_types: namespace: spanda.events categories: entity: - EntityCreated - EntityUpdated - EntityDeleted - EntityTagged - EntityRelated health: - HealthChanged - HealthCheckFailed - DegradedModeEntered readiness: - ReadinessChanged - ReadinessGateFailed mission: - MissionStarted - MissionCompleted - MissionAborted - MissionPaused recovery: - RecoveryTriggered - RecoveryCompleted - RecoveryFailed trust: - TrustUpdated - TrustGateFailed security: - TamperDetected - SpoofingDetected - SecretRotated - AuthFailed package: - PackageInstalled - PackageRemoved - PackageVerified telemetry: - TraceFrameRecorded - MetricEmitted - LogEmitted fleet: - FleetMemberJoined - FleetMemberLeft - OtaRolloutStarted - OtaRolloutCompleted # Known dependency layer violations — baseline for regression detection. # Format: from -> to (from_layer depends on to_layer where to_layer >= from_layer). dependency_waivers: - from: spanda-fleet to: spanda-decision reason: Fleet decision vote ingestion uses decision runtime types. - from: spanda-interpreter to: spanda-decision reason: Distributed decision trace emission during program execution. - from: spanda-interpreter to: spanda-autonomy reason: Runtime autonomy hooks during program execution. - from: spanda-providers to: spanda-plugin reason: Official package bootstrap wires plugin host providers. # Known circular dependency baselines — production graph must stay acyclic. circular_dependency_waivers: [] typescript_dependency_waivers: []