SysML v2 requirements → Rivet traceability: complete extraction pipeline with satisfy/verify/refine

[avrabe]

Context

Spar's `spar-sysml2` crate already parses SysML v2 and extracts requirements to Rivet YAML (`extract.rs`). The current extraction handles:

• `requirement def` and `requirement usage` → rivet `requirement` artifacts
• `satisfy X by Y` → `satisfies` links
• `verify X by Y` → `verifies` links
• Doc comments → descriptions

With SysML v2 formally adopted by OMG (June 2025) and the official tooling locked to Eclipse IDE or Sirius Web, spar is the only Rust-based SysML v2 parser with VS Code/Theia/CLI support. This issue enhances the extraction pipeline to cover the full SysML v2 requirements and traceability model.

Competitive context:

• SysML v2 Pilot Implementation: Eclipse-only, Java, 215 stars
• SysON: Sirius Web (deploy a server), Java, graphical only
• SysIDE (Sensmetry): VS Code, but inactive since Oct 2025
• MontiCore: Java JAR, research-focused
• Spar: Rust, CLI + VS Code + WASM, actively maintained

Enhancements

1. Expanded requirement extraction

Currently `extract.rs` extracts basic requirements. Extend to capture:

SysML v2 Construct	Rivet Artifact	Notes
`requirement def` with `attribute` children	`requirement` with custom fields	Attributes become rivet fields
`requirement usage` with typed reference	`requirement` with link to definition	`:>` specialization
`concern def`	`requirement` (tagged `concern`)	Stakeholder concerns
`constraint def/usage`	`design-decision` or `requirement` (tagged `constraint`)	Design constraints
`satisfy`	`satisfies` link	Already works
`verify`	`verifies` link	Already works
`refine`	`refines` link	Already works (grammar), needs extraction
`allocate`	`allocated-to` link	Architecture allocation
`derive`	`derives-from` link	Requirement derivation

2. Architecture extraction alongside requirements

When extracting requirements, also extract architectural context:

SysML v2 Construct	Rivet Artifact	Schema
`part def/usage` (system components)	`aadl-component` (via existing AADL schema) or new `sysml-component`	Could extend `aadl.yaml` or create `sysml2.yaml`
`connection usage`	Architecture link	Interface traceability
`action def/usage`	`feature` or `design-decision`	Behavioral specification
`state def/usage`	System modes	Links to mode analysis in spar

3. `spar extract` CLI command

# Extract requirements from SysML v2 to rivet YAML
spar extract --format rivet-yaml model.sysml -o artifacts/sysml-requirements.yaml

# Extract with architecture context
spar extract --format rivet-yaml --include-architecture model.sysml

# Extract and feed directly to rivet validation
spar extract --format rivet-yaml model.sysml | rivet validate --stdin

# Extract and show traceability gaps
spar extract --format rivet-yaml model.sysml -o artifacts/
rivet coverage

4. Roundtrip: Rivet → SysML v2

For teams that want SysML v2 as the canonical format but rivet for validation:

# Import rivet artifacts as SysML v2
spar generate --from-rivet artifacts/requirements.yaml -o requirements.sysml

This generates SysML v2 source with `requirement def`, `satisfy`, `verify`, `refine` from rivet artifact links.

5. SysML v2 schema for Rivet

New `schemas/sysml2.yaml` that defines artifact types matching SysML v2 constructs:

schema:
  name: sysml2
  version: "0.1.0"
  extends: [common]

artifact-types:
  - name: sysml-requirement
    description: SysML v2 requirement (def or usage)
    fields:
      - name: sysml-id
        type: string
        required: false
        description: Original SysML v2 qualified name
      - name: requirement-kind
        type: string
        allowed-values: [functional, performance, interface, constraint, concern]
    link-fields:
      - name: satisfies
        link-type: satisfies
        cardinality: zero-or-many
      - name: derives-from
        link-type: derives-from
        cardinality: zero-or-many

  - name: sysml-component
    description: SysML v2 part definition or usage
    fields:
      - name: sysml-id
        type: string
      - name: component-kind
        type: string
        allowed-values: [system, subsystem, component, hardware, software]
    link-fields:
      - name: allocated-from
        link-type: allocated-from
        target-types: [sysml-requirement]
        cardinality: zero-or-many

Phasing

Phase 1: Enhanced extraction

• Expand `extract.rs` for refine, allocate, derive relationships
• Extract constraint defs/usages
• Add `spar extract` CLI command

Phase 2: Architecture context

• Extract part defs/usages as component artifacts
• Connection → link mapping
• `--include-architecture` flag

Phase 3: SysML v2 Rivet schema

• `schemas/sysml2.yaml` with appropriate types and rules
• Bridge to ASPICE schema (SysML requirements → ASPICE V-model)
• Bridge to STPA schema (SysML allocation → STPA control structure)

Phase 4: Roundtrip generation

• `spar generate --from-rivet` for SysML v2 output
• Preserve original SysML v2 qualified names for roundtrip fidelity

References

• Existing: `spar-sysml2/src/extract.rs`, `spar-sysml2/src/grammar/requirements.rs`
• SysML v2 Release (OMG)
• SysML v2 spec formally adopted (June 2025)
• Rivet AADL adapter: `rivet-core/src/adapters/aadl.rs`
• Spar-Rivet integration plan: `docs/plans/2026-03-08-spar-rivet-integration.md`

[avrabe]

All four phases merged: #97 (Phase 1: refine/allocate/derive), #98 (Phase 2: architecture extraction), #99 (Phase 3: SysML v2 Rivet schema), #100 (Phase 4: roundtrip generation).