Spanda

Spanda Packages

Spanda projects are organized as packages — self-contained units with a manifest (spanda.toml), source files, dependencies, and declared capabilities.

Spanda uses a lean-core architecture: the language core defines types, safety, and provider interfaces. Domain features (ROS2, MQTT, GPS, SLAM, vision, simulation, fleet, cloud) ship as official packages under packages/registry/.

See How Packages Work, How Providers Work, and How Runtime Resolution Works for the full platform integration pipeline.

Quick start

spanda init my_robot
cd my_robot
spanda install    # resolve dependencies → spanda.lock
spanda update     # refresh lockfile to latest compatible versions
spanda check      # type-check all sources
spanda build      # compile the project
spanda test       # run tests/

Project layout

my_robot/
├── spanda.toml       # package manifest
├── spanda.lock       # resolved dependency lockfile
├── src/
│   └── main.sd       # primary robot program
├── tests/
│   └── smoke.sd      # optional test sources
└── README.md

Creating a package

Run spanda init in an empty directory (or pass a name):

spanda init warehouse_robot --description "Warehouse robot controller"

Edit spanda.toml to declare dependencies, hardware targets, and capabilities. See spanda-toml.md for the full schema.

Importing packages

Spanda supports dotted import paths:

import navigation.path_planning;
import sensors.lidar;
import ai.openai;
import robotics.ros2;
import std.robotics;
import std.sensors;

Package dependencies expose import paths via the registry (see registry.md). Standard library namespaces use the std.* prefix:

Namespace Domain
std.ai LLM, vision models, planning
std.robotics Motion, agents, goals
std.sensors Camera, lidar, IMU types
std.actuators Motors, grippers, joints
std.safety Hazards, constraints, e-stop
std.communication Topics, services, QoS
std.hardware Profiles, peripherals
std.sim Simulation world/scene
std.twin Digital twin sync
std.hri Speech, gestures
std.units Physical units
std.spatial Pose, path, trajectory
std.core Result, Option, Error
std.security Identity, signatures, trust
std.audit Audit logs, provenance records
std.crypto Hashing and signing

See standard-library.md for the full namespace list.

ai.openai is available via the spanda-openai package and uses the Python bridge (openai_complete) for live calls when OPENAI_API_KEY is set.

ai.anthropic (spanda-anthropic) and ONNX inference (spanda-onnx, SPANDA_ONNX_MODEL_PATH) follow the same bridge pattern. See live-ai-provider.md.

Audit and blockchain packages (optional)

Blockchain is not part of the language core. Audit/provenance is built-in; ledger anchoring uses optional packages:

Package Purpose
spanda-provenance Mission provenance helpers
spanda-ledger Mock ledger backend (MVP)
spanda-did Device decentralized identity
spanda-supply-chain Hardware supply-chain traceability

Example manifest for an audit-enabled robot app:

[package]
name = "example_robot"
version = "0.1.0"
license = "Apache-2.0"

[dependencies]
spanda-ros2 = "0.1.0"
spanda-provenance = "0.1.0"

[capabilities]
required = [
  "camera.read",
  "lidar.read",
  "network.outbound",
  "audit.write"
]

[safety]
level = "simulation_only"

See audit-provenance.md and future-blockchain-support.md.

Packages declare what permissions they need in [capabilities]:

[capabilities]
uses = ["network.outbound", "camera.read", "lidar.read"]
required = ["motion.propose", "actuator.execute.safe"]

The compiler and runtime warn when a dependency’s capabilities exceed the application’s granted permissions. Grant capabilities in your robot program with can [...] blocks.

Hardware compatibility

Declare hardware requirements in [requires_hardware]:

[requires_hardware]
memory = ">=2GB"
gpu = ">=1 TOPS"
sensors = ["Camera", "Lidar"]

These integrate with spanda verify and the built-in hardware profile registry (RoverV1, JetsonOrin, etc.). Set deployment targets in [hardware]:

[hardware]
targets = ["RoverV1", "JetsonOrin"]

Package safety levels

Every package has a trust level in [safety]:

Level Description
experimental Unreviewed; default for new packages
simulation_only May not control physical actuators
hardware_safe Reviewed for real-hardware deployment
certified Formally verified / certified for production 
[safety]
level = "hardware_safe"
requires_review = false
can_control_actuators = true

Applications can restrict which safety levels are permitted. Packages at simulation_only cannot set can_control_actuators = true.

Dependency types

Source Example
Registry spanda-ros2 = "0.1.0"
Local path my-lib = { path = "../my-lib" }
Git spanda-nav = { git = "https://github.com/spanda/spanda-nav", branch = "main" }

Run spanda install to resolve all dependencies and write spanda.lock.

Official package provenance

Catalog membership (is_official_package) is not enough to wire built-in providers. Runtime and trust scoring require registry provenance:

Dependency source Built-in providers wire? Trust official_framework factor
Registry version (spanda-mqtt = "0.1") Yes Yes (when lockfile/registry metadata verifies)
Lockfile registry source Yes Yes
Path to canonical packages/registry/<name> Yes (monorepo dev) Yes
Path/git override of an official name elsewhere No — .sd stubs only No (with --project)

spanda install / spanda build emit an official_provenance warning when an official name is reused via path or git without registry provenance.

Production deploy (spanda deploy gate --policy production) treats name squatting as a hard failure and requires SPANDA_REGISTRY_REQUIRE_SIGNATURE=1 plus valid Ed25519 signatures for every registry dependency in spanda.lock. See deployment-gates.md and package-trust.md.

Publishing

spanda publish

Validates manifest, capabilities, hardware requirements, safety level, and license. On success:

  1. Local mirror — copies the bundle to registry/packages/<name>/<version>/ in the repo (maintainers run ./scripts/build-registry.sh to refresh the hosted index).
  2. Remote upload — when SPANDA_REGISTRY_URL is set, uploads the tarball to the configured registry base.

See registry.md for the hosted index, Ed25519 signatures, and ./scripts/registry_golden_path.sh.

CLI reference

Command Description
spanda init Create a new package
spanda install Resolve deps, write lockfile
spanda update Refresh lockfile and vendored packages
spanda build Compile all .sd sources
spanda check Type-check project (or single file)
spanda test Type-check tests/
spanda add <pkg> Add a dependency
spanda remove <pkg> Remove a dependency
spanda publish Validate and publish package (mirrors bundle to registry/packages/<name>/<version>)
spanda registry search <q> Search hosted index + local registry

Examples

See examples/packages/ for:

Community packages

Fork official scaffolds (e.g. spanda-ledger) for community-maintained integrations. Start from packages/community/README.md and run ./scripts/ledger_golden_path.sh to validate the ledger scaffold.

See also community-packages.md for package categories, driver/adapters, and planned framework packages.

This site is open source. Improve this page.