Project Workspace and canonical model requirements
Defines the portable, unit-aware, frame-aware project representation from which all executable simulations are compiled.
Section relationships
Depends on
Used by
| ID | Name | Priority | Requirement | Verification |
|---|---|---|---|---|
| MODEL-001 | Stable entity identity | MVP | Every canonical entity SHALL have a typed, stable logical identifier that does not depend on display name, collection order, source path, content identity, or backend handle; allocation, retirement, and no-reuse semantics SHALL follow ADR-0003. | Test |
| MODEL-002 | SI canonical units | MVP | Canonical continuous physical quantities SHALL have SI meaning in persisted and runtime-facing canonical contracts, with the available source lexical value, source units, conversion provenance, and display units retained as metadata. | Test |
| MODEL-003 | Dimensional validation | MVP | Connections and assignments between physical quantities SHALL be checked for dimensional compatibility. | Test |
| MODEL-004 | Canonical coordinate convention | MVP | BeforeMetal SHALL use the right-handed convention accepted in ADR-0004: the canonical robot base is +X forward, +Y left, and +Z up; a georeferenced local world uses ENU; a non-georeferenced world declares its horizontal basis, origin, and yaw provenance; and imported conventions are transformed explicitly. | Test |
| MODEL-005 | Explicit reference frames | MVP | Every spatial quantity SHALL identify or unambiguously inherit its reference frame. | Test |
| MODEL-006 | Versioned schema | MVP | Every persisted project and compiled model SHALL declare its schema version. | Inspection |
| MODEL-007 | Forward migration | Beta | BeforeMetal SHALL provide explicit migrations for every older project schema inside the published compatibility window. | Test |
| MODEL-008 | Immutable import source | MVP | Original imported assets SHALL be retained or referenced without in-place mutation by normalization or compilation. | Inspection |
| MODEL-009 | Source mapping | MVP | Normalized entities and properties SHALL retain a source map to their originating file element where available. | Test |
| MODEL-010 | Separate geometry roles | MVP | Visual, collision, and inertial representations SHALL be modeled as distinct roles even when they reference the same source geometry. | Inspection |
| MODEL-011 | Analysis geometry role | Beta | Aerodynamic, thermal, structural, and other analysis meshes SHALL be distinguishable from visual and collision geometry. | Inspection |
| MODEL-012 | Assembly hierarchy | MVP | The canonical model SHALL represent nested assemblies without using hierarchy as physical identity. | Test |
| MODEL-013 | Body model | MVP | A body SHALL support pose, mass, center of mass, inertia tensor, geometry references, material assignments, and user metadata. | Test |
| MODEL-014 | Joint model | MVP | A joint SHALL identify its connected bodies, local frames, degrees of freedom, limits, and optional drive and passive properties. | Test |
| MODEL-015 | Device model | MVP | A device SHALL declare its typed ports, parameters, state variables, sample or update rate, and validity range. | Inspection |
| MODEL-016 | Sensor model | MVP | A sensor SHALL declare its attachment frame, truth source, signal chain, timing, output schema, and validity range. | Inspection |
| MODEL-017 | Controller model | MVP | A controller SHALL declare its inputs, outputs, execution rate, state, configuration, and execution host. | Inspection |
| MODEL-018 | Fixed parameter representation | MVP | A compiled physical parameter SHALL have a fixed value with declared type, units where physical, bounds where known, and provenance. | Test |
| MODEL-019 | Property provenance | MVP | Engineering parameters SHALL support source, revision, author, calibration status, uncertainty, and applicable conditions. | Inspection |
| MODEL-020 | Validity envelope | MVP | Every active model SHALL declare either a quantified operating envelope for its evidence or an explicit unqualified status. | Inspection |
| MODEL-021 | Namespaced extensions | MVP | Non-core properties SHALL be stored in versioned namespaces so that unknown extensions can be preserved without being treated as active behavior. | Test |
| MODEL-022 | Backend extension isolation | Beta | Backend-specific properties SHALL not change canonical semantics unless explicitly selected by the experiment. | Test |
| MODEL-023 | Topology validation | MVP | The model validator SHALL detect dangling references, invalid joint graphs, duplicate identities, and illegal ownership cycles. | Test |
| MODEL-024 | Inertia validation | MVP | The model validator SHALL detect non-positive mass, invalid inertia tensors, and implausible inertia relative to geometry using documented rules. | Test |
| MODEL-025 | Content addressing | MVP | External, normalized, and compiled assets SHALL use the distinct raw-byte, semantic-content, and derived-artifact identity contracts accepted in ADR-0005 for run manifests and cache validation. | Test |
| MODEL-026 | Human-reviewable manifest | MVP | A project SHALL include a documented, diffable manifest that identifies its primary assets and experiment definitions. | Inspection |
| MODEL-027 | Atomic project save | MVP | Saving a project SHALL not leave a valid prior project in a partially overwritten state after interruption. | Test |
| MODEL-028 | Unknown-data preservation | Beta | Loading and resaving a supported project SHALL preserve unknown namespaced data unless the user explicitly removes it. | Test |
| MODEL-029 | Canonical numeric precision | MVP | Ordinary canonical continuous scalar, fixed-shape vector, matrix, tensor, and quaternion values SHALL use finite IEEE 754 binary64; source, canonical, and compute representations SHALL remain distinct, and any lower- or higher-precision storage or compute profile SHALL be versioned, capability declared, fidelity-visible, and unable to change canonical meaning silently. | Test |
| MODEL-030 | Reusable model definition | MVP | A robot, device, material, sensor, or environment model definition SHALL be referenceable by multiple project entities without copying its source definition. | Test |
| MODEL-031 | Instance override | MVP | A model instance SHALL declare its pose, stable identity, display name, and permitted parameter overrides separately from the referenced definition. | Test |
| MODEL-032 | Multi-robot world | Beta | A world SHALL support multiple robot instances with distinct identities, frames, controllers, sensors, collisions, and communication namespaces. | Demonstration |
| MODEL-033 | Primitive geometry authoring | MVP | A user SHALL be able to define dimensioned box, sphere, capsule, and cylinder geometry without importing a mesh. | Demonstration |
| MODEL-034 | Named parameter binding | MVP | A named design or scenario parameter SHALL be bindable to documented geometry, material, device, sensor, controller, environment, or initial-state properties that accept its type and units. | Test |
| MODEL-035 | Parameter distribution | Beta | An editable parameter definition SHALL support a documented probability distribution, physical bounds, and optional correlation group that is resolved to a fixed value before each run. | Test |
| MODEL-036 | Engineering parameter domain | MVP | Every active engineering parameter schema SHALL declare finite-value, physical-domain, and cross-property consistency constraints, and compilation SHALL reject values that violate them. | Test |
| MODEL-037 | Typed engineering property contract | MVP | Every recognized canonical engineering property SHALL declare a stable type identifier and schema version; value representation and shape; dimensions and units where applicable; frame, basis, or orientation where applicable; relation variables and domain where applicable; and uncertainty, provenance, and validity conditions using explicit known, unknown, not-supplied, or not-applicable states. | Test |
Change rationale (MODEL-037): Broad multiphysics data needs one backend-independent property envelope before domain-specific schemas are designed. This contract permits scalar, vector, tensor, tabulated, equation-backed, and namespaced property forms without claiming that every solver supports every form.
Change rationale (MODEL-001, MODEL-004, MODEL-005): Accepted ADR-0003 separates typed logical identity from names, paths, content identity, and backend handles and fixes authored, imported, retirement, and run-scoped allocation direction. Accepted ADR-0004 fixes the canonical base/world axes, transform direction, quaternion algebra and canonical form, and typed spatial-value boundary. These accepted architecture constraints direct the still-draft Canonical Model Specification; they do not by themselves approve schemas or implementation.
Change rationale (MODEL-025): ADR-0002 accepted strict JSON, typed content-identity classes, JCS, and SHA-256 as the direction, while ADR-0003 accepted the normalization-options identity slice required by imported-ID allocation. Accepted ADR-0005 now fixes the schema-owned semantic projections, numeric and Unicode equivalence, canonicalization and domain separation, typed identity records, and self-verifying derived-artifact descriptor. Requirements v0.6 records that resolution without approving the still-draft Canonical Model Specification, public schemas, a cache protocol, dependencies, or product implementation.
Change rationale (MODEL-002, MODEL-029, v0.7): Accepted ADR-0006 separates source spelling and units, canonical SI meaning, and solver compute representation. Finite binary64 remains the ordinary canonical continuous profile, while exact counters, time, ratios, identities, and digests retain typed non-floating semantics and alternate compute precision must remain explicit. This direction does not approve detailed schemas, public Rust types, a math dependency, or implementation.
Generated from the canonical specification. Edit section metadata or prose in docs/requirements.md; the website rebuilds this page and its relationships automatically.