Sysml Requirements

Manage SysML v2 requirements

SysML v2 is implemented as a portable, source-backed requirements and system- structure boundary. It is not a second runtime physics engine and it is not a copy of the Twin's USD or Rhai state. Use this skill when the request mentions requirements, verification cases, SysML, KerML, traceability, or a missing capability that may already exist behind the optional SysML feature.

Capability matrix and ownership

Check the feature set and owner before saying that a capability is missing:

The source-of-truth rule is strict: SysML states what the system must be and why; USD states what is authored and observable; Modelica states continuous equations; supported SysML constraint expressions execute through the neutral IR. Rhai selects providers, queries observations, orchestrates behavior, and formats evidence. A verification registry selects a scene and script but does not duplicate requirement text or thresholds.

Windowed LunCoSim builds with the sysml feature also provide the SysML Requirements panel in View → Editor. It reads the active Twin's prepared analysis, displays requirement documentation, formal require criteria, resolved verify cases, parser diagnostics, and source locations. Selecting SysML Requirements from another perspective opens its owning Editor perspective. The panel starts with a compact requirement list and a detail pane; search and status filters narrow the list. Open at line opens the canonical SysmlDocument at the declaration or diagnostic location. Save source applies revision-checked ApplySysmlOps and SaveSysmlDocument commands. The text editor is read-only when the document is not writable or its source revision conflicts with the open draft.

The presentation model rebuilds when Twin, analysis, source-document, or evidence inputs change. Empty lifecycle queues are read before a mutable registry drain; idle publishing must not mark documents changed. Use sysml_requirements_rebuild input flags when profiling repeated rebuilds.

CloseDocument retires the SysML registry document and its shared lifecycle state, including dirty drafts. Twin replacement dispatches that command for every resident SysML document. Pending filesystem opens are admitted with an exact runtime owner and cannot install after that Twin closes.

The panel presents three independent status dimensions with separate filters: structured requirement evidence, linked scene-test execution, and model coverage (require criteria and resolved verify links). Requirement details show evidence channel, verification identity, source revision, simulation tick, and captured check results. Up to 64 check details are retained per requirement; aggregate check and failure counts remain available for larger reports. Running a mapped case uses the same production headless scene-test runner as the CLI; the panel shows elapsed time and live output, supports cancellation, and retains the run summary and output for the Twin session. Save or discard open SysML edits before running because tests read saved Twin files. Results are cleared when their Twin closes. The panel lives in the existing workbench Editor alongside the other native document tools.

The Traceability view maps one requirement's declared subject types, explicit standard satisfy relationships, resolved verify cases, Twin test registrations, run outcomes, and source-revision-scoped evidence. Do not treat a subject type as a satisfy link or infer missing relationships. Source-backed nodes navigate to their analyzed declarations, and a mapped test can run from the map. The Structure view presents a filterable package/part/item/ interface/port/connection hierarchy from the same prepared analysis and opens selected elements at their source lines. It is a hierarchy navigator, not full BDD/IBD diagram authoring or a general-purpose SysML editor.

Preserve declared collection shape

Read model values through the typed SysmlModel.value projection. Finite, unitless numeric constant initializers support resolved feature references, unary signs, and +, -, *, /, and integer powers, including each member of numeric tuples. Cross-package and local references use the same source snapshot. Authored expression text and classification stay intact alongside the numeric projection. This bounded source fold reuses the semantic unit-factor evaluator; it does not execute domain state or general KerML programs. Cycles, missing references, zero division, non-finite results, and unsupported initializers have no fabricated value; model.value reports a named error. Integer operands beyond the exactly representable f64 range remain unsupported in arithmetic rather than being silently rounded. A structured Position literal may lower to one native DVec3, while a declared Position[n] collection must remain an array of native DVec3 values. The generic Rust projection distinguishes vector components from declared multiplicity. Do not recover missing model values by walking AnalyzeSysml AST records, parsing string encodings, or rebuilding arrays in Twin Rhai. If a declared shape is missing, fix the shared typed projection and keep the Twin policy declarative.

For mission models with material-dependent structural, pressure, thermal, or electrical behavior, follow the physical-material data gate. Use typed material definitions/usages and unit-bearing properties with their conditions and evidence; do not encode material identity or property arrays as strings. The current typed SysML projection is not itself a material catalogue or an automatic cross-domain binding—keep the limit visible until a generic resolver and consumer path are demonstrated.

Model substrate and surface finish/coating as separate typed facts. Permit a component face/region to select a sourced finish independently of its bulk material. Keep visual UsdShade shader mapping distinct from optical/thermal engineering properties: a shader preset is not a source for absorptance, emittance, coating thickness, or Modelica thermal parameters. Record missing finish catalog and rendering adapters as generic tool gaps, not per-component string metadata.

Keep resolved type identity typed

Use the resolver-selected SysmlTypeRef.element handle for type comparisons and joins. If a typed contract needs a SysML type, carry that reference rather than its name. Its qualified_name is for reports and source navigation only; two semantic types must not be treated as equal because their display names match. The handle is scoped to its SysML source revision and fingerprint, so reject values assembled from a different snapshot.

For unit-bearing model data, author standard quantity-value and unit-reference features where the model needs them. Keep a unit suffix from source syntax as source spelling; it is not a resolved unit definition. Provider observations must carry a native Quantity constructed with a resolved EngineeringUnit, and a binding contract's optional unit must also be an EngineeringUnit. Do not add a second unit string to an observation or pass { value, unit: "m" }: those forms do not establish dimension or scale and are rejected by the adapter. The evaluator checks SI dimensions and converts compatible units during arithmetic and comparison. A resolved unit-bearing source literal now carries its measurement-unit feature handle, SI dimension, and source-derived scale. The AST resolver reads standard MeasurementUnit quantity-power factors and linear conversion relationships, including prefixes, reference-unit factors, and arithmetic unit definitions. Rhai exposes the resolved unit as a native EngineeringUnit; source verification and geometry adapters use that value without consulting a symbol table. Numeric conversion expressions support arithmetic, including integer powers; dimensional unit composition supports multiplication, division, and integer powers. Keep unit_symbol for source display only. The standard conversion isExact flag is projected onto native units as scale_is_exact and accumulated by native quantities as conversion_is_exact. These flags describe conversion exactness only, not measurement uncertainty. The bounded Modelica position adapter requires an exact SI scale before lowering to an unqualified vector. MeasurementScale mappings and unresolved or unsupported unit definitions do not produce an engineering unit and must remain unavailable; do not infer a scale from the spelling.

For a mission Twin, apply the generic mission and engineering quality gates alongside this parser/runtime contract. Requirements are the baselined bridge from mission intent and ConOps to component and interface acceptance; record provenance, assumptions, operating conditions, margins, and configuration revision. Keep verification against requirements separate from validation in a realistic nominal/off-nominal/recovery scenario, and make unresolved TBDs or fault-response requirements visible failures rather than defaults.

The existing Rhai lint substrate is part of this path: RunLint executes the domain policy in assets/scripting/policy/lint_<domain>.rhai over Rust-produced facts, while Twin verification scripts use assets/scripting/tools/sysml_requirements.rhai to read the mounted SysML snapshot, bind composed USD observations, execute supported source constraints through the neutral IR, and emit structured evidence. Keep provider and component selection in Rhai; keep supported acceptance predicates in SysML; Rust supplies generic typed mechanisms, not mission- or component-specific assertions.

Use ValidateSysml with the mounted Twin URI to review the full indexed source set and its structural lint findings. The lint.sysml policy flags requirement usages without typed source evidence, usages without an inherited or owned require acceptance predicate (assume memberships provide context but do not count as pass criteria), and identifier-like String values that appear to encode enumerators or member identities. Treat those findings as migration work, not as permission to preserve the encoding. Use an enum for a closed choice set; use typed part usages or references for named system members. A verify membership is required for each usage, and the Twin's verification registry must bind that case to its scene and observer.

For example, from an in-app Rhai tool with the Twin mounted:

let report = query("ValidateSysml", #{path: "twin://astrobotic-griffin-1"});

Review report.errors, report.warnings, and the structured report.findings. Use its stable rule, severity, subject, and message fields instead of parsing warning prose; SysML subjects include the qualified identity and source file/byte offset. Pay particular attention to sysml-requirement-* and sysml-string-encoded-identities.

Relevant implementation and design references:

• 24-domain-sysml.md — domain boundary and supported subset.
• sysml-requirement-verification.md — current Rhai bridge and verification contract.
• crates/lunco-twin/src/manifest.rs — [sysml] and [verification] manifest ownership.
• assets/scripting/tools/sysml_requirements.rhai — generic evaluator implementation.

Requirement quality gate

Treat an informal request as a stakeholder expectation until it has enough information to become a requirement. A good requirement is singular, clear, necessary, feasible, implementation-independent, traceable, and individually verifiable. It states one subject and one normative behavior or characteristic, usually with shall, plus the measure, units, limit or tolerance, operating condition, and verification method needed to decide pass or fail. This follows the NASA requirements guidance for statements that are clear, correct, feasible, unambiguous, measurable/verifiable, and traceable: NASA Appendix C and NPR 7123.1C.

Before authoring or baselining a requirement, check:

• Subject and scope: Which system, part, interface, or operating mode does it constrain? Name the subject and the condition or stimulus.
• Observable measure: What will be measured, inspected, demonstrated, analyzed, or tested? Include units, sampling rule, time window, population, and reference/baseline when they affect the result.
• Pass criterion: Give a numeric bound, range, tolerance, count, rate, state, or explicit finite acceptance rubric. “Good”, “stable”, “fast”, “intuitive”, “looks right”, and “make it look good” are not pass criteria.
• Single thought: Split and, or, and compound paragraphs into separate requirements unless the clauses are inseparable for verification.
• Traceability and intent: Record the requirement ID, source/parent goal, rationale, priority, and the qualified verification case. Keep design choices such as a particular class, algorithm, or shader implementation out unless they are themselves the required constraint.
• Normative content vs. implementation status: Requirement text states the required behavior or characteristic and how it will be accepted. Keep current implementation status, nonconformance, incomplete assets, proxy caveats, missing source data, historical milestones, and unresolved work in the owning gap/status report. Keep source history and provenance in the typed evidence/source catalog. Do not use requirement prose to say that the current model fails, that a parameter is only a proxy, or that a value is not publicly available. Write the positive desired outcome in the requirement; report actual-vs-required status separately under that requirement ID.
• Time-dependent acceptance: Identify the applicable mission phase or window, time scale, site/reference frame, and temporal envelope or sampling needed to accept a time-dependent requirement. Use one authoritative scene clock/epoch and derive environment state from its providers; keep a study epoch distinct from a mission schedule. Put unavailable schedule inputs and current verification coverage in the gap/status report.
• Failure behavior: For safety, reliability, or resilience requirements, specify the trigger, detection deadline, required response, and recovery or safe state. “The system shall handle errors” is incomplete.

Do not baseline an unmeasurable statement merely because its rationale is important. If a threshold, reference, or acceptance condition is missing, record the unresolved decision and required evidence in the gap/status report. Keep the requirement concise; put its sources in the evidence catalog and its verification evidence in the verification record.

For example, a solar-layout requirement should state the required installation relationship and the mission Sun-envelope comparison used for acceptance. Whether the current Twin has the right panel count, whether its existing roots are only proxies, and which installation data are still missing belong in the gap/status report, not in the requirement definition.

Ask the user when the requirement is underspecified

It is correct to ask targeted questions before writing SysML. Ask only the questions that block a measurable, verifiable statement, and show the proposed rewritten requirement so the user can confirm the interpretation. Do not invent numbers, tolerances, reference images, operating conditions, or priorities.

Use this compact question set as needed:

1. What exact subject is being constrained, and in which operating condition or scenario?
2. What observable quantity or finite outcome proves success? What are its units, range/threshold/tolerance, sampling rule, and time window?
3. What stimulus, initial state, environment, or reference baseline applies?
4. Should verification be by test, analysis, inspection, or demonstration, and what artifact or runtime evidence must be retained?
5. What stakeholder goal or parent requirement does it trace to, and what is the priority if it conflicts with another requirement?

If the user answers only “make it look good”, convert that into a clarification, not a requirement. Ask for the approved reference and observable visual criteria—for example camera/lighting/exposure, reference patches or objects, allowed luminance/color deviation, frame window, and the inspection or image analysis method. A valid visual requirement can be:

Under the approved camera, sun direction, and exposure, the terrain surface
shall keep the mean luminance of each of three approved reference patches within
±5% over a 10-second stationary capture. Verification: image analysis of 300
frames plus visual inspection against the approved albedo reference.

The numbers and reference artifacts in that example are placeholders, not defaults. Replace them with user-approved values before putting the statement in SysML. A similarly testable motion requirement names the scenario and window, for example: “During a 100 m straight run on a 10° slope at a commanded 1.0 m/s, the rover shall keep lateral error ≤0.5 m and speed within ±0.2 m/s for at least 90% of samples after the first 5 s.”

Do not weaken a vague request by choosing a permissive tolerance merely to make the first run pass. If the user cannot yet provide a bound, record it as an open stakeholder expectation/TBD with an owner, rationale, and resolution date; do not baseline it as a verified SysML requirement.

What is implemented, and what is not

The current supported subset is source-backed and deterministic:

• standard textual SysML v2 syntax in .sysml and .kerml files;
• packages/imports, part definitions/usages, ports, connections, requirement definitions/usages with documentation and attributes;
• standard external references plus satisfy and verification verify memberships;
• qualified names, typed scalar/vector/array literal projections, source spans, diagnostics, source files, and a deterministic source_revision; numeric literals expose a validated native finite number_value alongside source identity;
• Twin-indexed source-set discovery through the existing asset manifest, with SysmlPlugin opening the checked set automatically after TwinAssetMounted;
• a Twin-owned verification registry mapping a qualified SysML verification name to one scene, one Rhai observer, and an optional verdict channel;
• three generic Rust query boundaries: ValidateSysml for source status, diagnostics, and the structural lint.sysml pass; AnalyzeSysml for policy-neutral selectable typed facts; and ReadActiveTwinContract for active-Twin component/verification bindings;
• Rhai policy layers that consume those same facts independently: lint.sysml for structural quality, sysml_requirements.rhai for requirement/source provenance and verification, and sysml_modelica_constraints.rhai for geometry-constraint selection and Modelica source assembly;
• sysml_value(path, qualified_name) and sysml_value_from_report(report, qualified_name) return tagged typed outcomes. Successful values remain native (Vec3, Quat, Transform, quantity, enumeration, or array); failed lookups return ok: false with an error and add a scene-scoped warning to RuntimeDiagnostics. A policy may request selected attributes through AnalyzeSysml; a successful read clears only the warning for the same source path;
• sysml_model(path) returns a read-only, revision-pinned SysmlModel backed by the cached Rust semantic snapshot. For a mounted Twin it hands back the prepared analysis directly (no per-call lint-fact rebuild), so accessors that open the model on demand stay cheap enough for per-tick mission policy; source diagnostics still reject the model. Use model.value(qualified_name) for repeated typed reads in one builder/verifier, and use model.requirement(qualified_name) or model.verification(qualified_name) for source-owned traceability. This keeps the parsed source set and its revision together and avoids rebuilding a dynamic report for every attribute. The Rhai sysml_requirements::model() helper opens the active Twin's twin:// source; scripts must not read .sysml files directly or manufacture a second requirement-value table;
• the luncosim test --verification QUALIFIED_NAME selector; and
• structured per-check evidence emitted by report_structured_verdict. The summary event keeps small reports inline; larger reports emit one bounded *_EVIDENCE_RESULT event per observation with a stable result_index. Consumers must group by channel and source revision, then order by that index. This preserves the complete typed table without exceeding Rhai's bounded value budget. Check records may use qualified or validated short requirement/verification names; short names are preferred in repeated arrays to avoid duplicating package prefixes.

The shared sysml_requirements::evaluate call resolves those short identities once against the mounted source report and rewrites each check to the canonical qualified name before observing USD or source-derived predicates. Verification coverage is evaluated from resolved snapshot-scoped SysML element handles, not by joining requirement and verification names into a string key. The authored name selects the source element; the resolved handle pair determines coverage. Missing or colliding identities fail the evaluation; observers must not add a package-prefix guess or a second registry. Use sysml_requirements::requirement_name(report, id) and sysml_requirements::verification_name(report, id) when a canonical identity is needed before constructing additional evidence.

Unit-bearing literals expose measurement_reference, a snapshot-scoped handle to the resolved SysML measurement-unit feature and its declared unit type. Its unit_definition contains the standard-derived SI dimension and conversion; engineering_unit on the Rhai reference yields the native unit value. unit_symbol is only the spelling in source. New SysML verification and projection code must use the resolved reference; do not use the spelling as a unit registry key. Linear MeasurementUnit definitions are resolved from their quantity-power factors, standard SI base units, unit-conversion edges, and arithmetic initializers. Nonlinear or affine MeasurementScale mappings, malformed definitions, and expressions outside the resolver's supported arithmetic remain unavailable. Standard isExact metadata is projected and propagated through native quantity operations; it does not replace uncertainty or instrument-accuracy data. engineering_units.rhai serves explicit unit input at non-SysML boundaries; it is not authoritative for SysML source values.

Before lowering a unit-bearing vector to shared Vec3 or a Modelica parameter, validate the declared quantity kind, fixed cardinality, each resolved unit, and compatible dimensions. Do not read only number_value and drop unit identity. The bounded SysML-to-Modelica LengthValue[3] geometry path consumes the resolved measurement-reference unit and converts through the native SI quantity operation; it does not look up unit_symbol. Other physical-property quantities, including material properties, need the same unit-preserving treatment; capability-check the property kind and consumer before generating a model.

For CAD/mechanical intent, keep the requirement and tolerance in SysML, then call the reloadable assets/scripting/tools/mechanical_relations.rhai policy with resolved native values. Its generic vocabulary includes distance, coincidence, signed plane distance, under/clearance, parallelism, perpendicularity, collinearity, coplanarity, mirroring, and plane/axis symmetry. It returns residual/evidence records and knows neither Griffin names nor USD paths. Do not add a product-specific relation predicate to Rust; add a generic Rust numeric primitive only when the operation is shared, hot, and not expressible safely with the Rhai standard math surface.

source_with_attributes() is a bounded value projection and intentionally does not carry requirement/verification identity tables. Use source_with_selection() when evidence must retain source-linked requirement or verification identities. Identity and source revision remain Rust-owned. For a supported source predicate, create a generic constraint_check and pass it to evaluate or evaluate_document; Rhai selects explicit provider observations and the neutral IR returns pass, fail, inconclusive, or error. Do not collapse those states into a Twin-specific boolean assertion.

Keep normative requirement tolerances in SysML evidence. Runtime settings such as numerics.comparison.length_abs_m and numerics.solver.residual_abs are algorithm/solver policy, resolved once per operation from the active Twin and passed through the call graph. They must not silently replace a SysML acceptance tolerance or collapse different physical dimensions into one epsilon.

It does not provide a full SysML/KerML execution engine. Parsed generic elements, references, constraints, and relationships are source facts, not a claim that their behavior is executed. The bounded constraint path now compiles the resolved supported subset into lunco-sysml-ir; a Rhai policy selects provider bindings; and lunco-sysml-modelica renders a typed constraint into Modelica admitted through Rumoca. Native in-process policy can retain a SysmlModel handle, while API/MCP callers use the structured path-level functions sysml_constraint_ir, sysml_modelica_constraint, and sysml_evaluate_constraint without serializing a native handle. Authored source references use lunco://; a USD prim target remains a USD path.

The current IR supports typed scalar expressions, conditional expressions, fixed primitive multiplicities, source-linked diagnostics, and deterministic fingerprints. It does not yet support feature-chain navigation, reusable constraint invocation/default arguments, collection/index/aggregate expressions, full quantity conversion, redefinition/subsetting semantics, null/invalid propagation across all providers, requirement membership execution, applicability, or state/behavior execution. Do not recreate those features with a hidden Rhai parser, Griffin-specific Rust, parallel arrays, or qualified-name fallback tables. Add the generic AST/IR/provider mechanism and then author the standard SysML construct.

sysml_requirements::constraint_check binds a check table to that supported subset. Binding keys must match the source constraint parameter names; an unknown key is an error and an omitted observation is unavailable. Evidence retains the qualified constraint, source revision, fingerprint, provider observations, expression results, diagnostics, and four-state verdict. evaluate_document(source, doc_id, checks) gives the same generic checks an explicit Editor document scope for USD queries. Generic observation kinds include not_exists for absence requirements and typed source-vector component selection through expected_index. The tolerance argument on a check is numerical evaluator policy for equality comparisons; engineering acceptance bounds must remain parameters of the SysML constraint itself.

The existing CoincidentPointTranslation policy can still run a bounded asynchronous Modelica solve, read native finite f64 results by exact experiment identity, and produce a generation-bound typed USD placement plan. The plan remains dry and requires Editor review/commit; no result is applied automatically. This is a specific policy over the generic boundary, not arbitrary SysML constraint execution. General constraint/parametric execution, state and behavior execution, a dedicated SysML editor, full UI source-set browsing, and automatic SysML-to-USD projection remain outside the current runtime. If a request needs one of those, report the exact bounded gap after checking the current owner and dependencies.

Source organization

SysML files remain ordinary Twin files and must contain standard SysML syntax; do not add LunCo-specific annotations to make runtime wiring work. The Twin manifest owns source-set selection:

[sysml]
# Optional Twin-relative entry point; `.sysml` or `.kerml`.
root = "requirements/system.sysml"
# Additional Twin-relative roots. The indexed Twin files remain authoritative.
paths = ["requirements"]

[verification]
[[verification.cases]]
name = "Project::VerifyVisual"
scene = "tests/visual.usda"
script = "scenarios/tests/visual.rhai"
verdict_channel = "VISUAL_REQUIREMENTS"

Important source-set rules:

• twin.toml is configuration, not a replacement for SysML source text.
• The Twin's indexed files are the discovery authority; [sysml].root puts the entry point first and [sysml].paths narrows the indexed set.
• Paths in the verification registry are Twin-relative and are checked as indexed .usda/.rhai files. The registry selects execution; it does not define a requirement, a numeric limit, or a second backend.
• Use qualified names such as Project::VerifyVisual as stable keys for requirements and verification cases. Do not rely on a short name when packages can contain collisions.
• Use the existing twin://<name>/... and lunco://... identity schemes. Do not add a filesystem walker, a global source registry, or raw std::fs reads in a runtime crate.