Compilation and interface boundary
Component releases, backend variants, plugin bindings, resource digests, and rates are resolved during compilation. Runtime does not scan directories, download implicitly, or choose a conflict by import order.
The CLI, Python API, and Server operate on one ExecutionPlan. Their presentation differs, but lifecycle, state, control, and failure semantics must not fork.
Ownership and capability boundary
Core understands physical worlds, timing, observations, control targets, cancellation, outputs, and provenance. It does not interpret behavior trees, Actions, Goals, grasps, or evaluation rules. scenario.behavior and scenario.evaluation are locked, then granted to authorized plugins.
A plugin manifest declares roles, services, and Scenario inputs. Run access and deployment policy narrow that declaration further. Missing backend capabilities are reported explicitly, never disguised as successful empty results.
Scene mutations and control commands enter Runtime at valid generation and tick boundaries. Plugins and remote interfaces cannot retain native backend objects or bypass arbitration.
Failure, portability, and documentation
Configuration diagnostics, missing capabilities, rejected control, timeouts, cancellation, and output failures have explicit states. A caller timeout is not proof that an operation was cancelled, and incomplete output must not be published as complete.
UniRoboSim stabilizes application contracts and capability discovery while each Provider reports its real limitations. FastSim does not promise identical numerical results across physics engines.
Concepts explain system boundaries; guides cover a class of task; references list exact current interfaces; examples provide runnable instances. Source README count does not define navigation.
Runtime invariants
Entities, joints, links, frames, sensors, control groups, and resources use stable identities. Backend-native handles remain inside Providers. This is what makes plugin code portable and recorded data interpretable after the original process is gone.
Core owns lifecycle, generations, services, control admission, Operations, and publication. Plugins own task, model, device, data, and interface semantics. Any plugin action that changes the common world or control resources returns through an authorized Core service.
Installed does not mean selected, and selected does not mean unrestricted. Compilation combines plugin manifests, instance bindings/access, and Provider capabilities. Runtime imports only selected factories and grants only scoped services. Unused camera, kinematics, recording, or server features should not create threads, allocate buffers, or open ports.
Reset and Run replacement invalidate snapshots, subscriptions, Operations, leases, and long-running computations from the old world. Work is checked both before computation and before publication or admission. A wait timeout is not cancellation; cancellation has an explicit request and terminal result.
The backend world and Application state are serialized by one owner. Algorithms, codecs, and network work can use workers, but cross the boundary through immutable requests, bounded queues, and explicit results. Every overload point chooses block, drop, sample, or fail and reports the outcome.
Compilation rejects what can be known before launch. Runtime errors retain stable codes and run/generation/entity context. Stop and close prevent new work, converge accepted work, revoke services, finalize or reject outputs, and release the Provider—even when an intermediate hook fails.
Recording writes private staging, validates structure or strict content integrity, and atomically publishes a final output. Offline readers never mutate the source FSR. Derived assets record source digest, tool version, mapping, and validation.
Use these questions in design review: which layer owns the fact, how does it enter the Plan, what stable identity does it use, how is the capability granted and revoked, what happens on reset/timeout/failure, where is backpressure, and what structured evidence proves the behavior?