toto171/loom

1. What Loom is

Loom is a Python 3.12+ framework for composing a vehicle from swappable subsystems, checking those subsystem contracts, simulating the composed vehicle against a plant model, and generating safety evidence artifacts. The repository is organized around a single end-to-end pipeline, not a standalone app server or a library of unrelated utilities.

2. Primary inputs and configuration

The core input is a vehicle composition YAML file in spec/ that references module contracts, plant selection, and scenario/fault configuration. Module-specific contract files live under modules/*/contract*.yaml; plant implementations live under plant/*/plant.py; scenarios live under scenarios/*.yaml. Schema definitions in spec/schema/ define the two main configuration domains: vehicle composition and module contracts.

3. Composition and resolution layer

The loom.compose package is the first major subsystem. It loads the vehicle composition, resolves module references, and produces a composed model. This layer is the boundary where the declared vehicle architecture is turned into an executable configuration that later stages can validate, simulate, and analyze.

4. Contract and static-checking layer

The loom.contracts package models each module’s contract and performs static composition checks. The checker enforces things like producer uniqueness, signal resolution, units consistency, and timing/assume-guarantee constraints. It also encodes an explicit license policy for default modules, so legal metadata is treated as part of the architecture rather than an afterthought.

5. Runtime execution core

The execution entrypoint is loom.run.execute_run, which the CLI and dashboard both reuse. The main lifecycle is: compose → validate → check → gate → simulate → assure. This is the central data flow of the repo; every user-facing path ultimately converges here.

6. Orchestrators and bus abstraction

Loom separates orchestration from the bus transport. The loom.orchestrator package defines the control loop and multiple orchestrator backends: in-process, Compose/KUKSA, and Ankaios. The loom.bus package provides the transport abstraction, with a shim/in-process bus and a KUKSA-backed bus. This boundary is important because it lets the same simulation/control loop run either locally or against distributed infrastructure.

7. Modules and closed-loop vehicle behavior

The reference modules in modules/ are the swappable subsystems being composed: BMS, powertrain, ADAS, HMI, and body. In the default closed loop, the driver target speed propagates through powertrain commands into the plant, while BMS tracks state of charge and reacts to plant state. These modules are intentionally split from the plant so the architecture can show how contract changes affect composition without changing the underlying physics model.

8. Plant models

The loom.plant package loads the plant implementation selected by the vehicle spec. The repository includes at least two plant families: a longitudinal plant and a higher-fidelity Motoquant plant. Plant choice changes simulation fidelity and dynamics but does not require changing module contracts, which is a key separation in the architecture.

9. Simulation, stimuli, and fault injection

The loom.sim package contains the execution-time mechanics around scenarios, stimulus generation, traces, and faults. Scenario files drive the simulated driving conditions, while fault injection can model dropout, stuck values, latency, and crashes. This layer feeds the runtime monitors and produces trace artifacts for later reporting.

10. Monitoring and safety gating

Runtime checks live in loom.monitors and loom.safety. Monitors evaluate predicates over observed runtime signals, and the safety gate blocks below-line swaps unless revalidation is explicitly requested. This is the repository’s main safety boundary: it separates allowed “above the line” changes from changes that require renewed evidence.

11. Assurance artifacts

The loom.assurance package generates evidence artifacts during or after a run. The README indicates three main outputs: per-module SBOMs, an aggregate vehicle SBOM, and a GSN assurance-case skeleton. These are written into each runs/<id>/ directory along with trace and report data, making the run directory the primary evidence bundle for a composition.

12. Deployment path

The loom.deploy package generates an Eclipse Ankaios workload manifest for composed systems. This is a separate output path from simulation: it translates the same composed vehicle model into deployment-oriented artifacts rather than runtime evidence. That makes deployment another first-class boundary in the architecture.

13. Dashboard and operational surface

The dashboard/ app is a FastAPI-based UI with HTML templates for composing vehicles, launching runs, and inspecting results. It is a thin operational frontend over the same execution core used by the CLI, so it does not define a separate business path; it visualizes and drives the same pipeline.

14. Persistence and baseline state

Runs are persisted under runs/ and the safety baseline is committed in locks/*.lock.json. The committed lock file is architecturally important because it prevents the safety gate from being reset simply by deleting local run outputs. In other words, the repository distinguishes transient evidence from versioned safety state.

15. How to think about the architecture diagram

A good diagram for this repo should show a left-to-right flow from composition spec and contracts, through static checking and gating, into simulation with modules, bus, orchestrator, and plant, and then out to monitoring, SBOM/GSN assurance artifacts, and deployment output. The key cross-cutting boundaries are: contract vs runtime, orchestrator vs bus, modules vs plant, and transient run evidence vs committed lock/baseline state.