mercurio-sysml

mercurio-sysml is a Rust toolkit for SysML v2 / KerML textual modeling with a text-first persisted model and an EMF-like semantic API.

The core goal is to treat .sysml / .kerml source text as authoritative, project it into a semantic model for analysis/editing, and render deterministic text updates back out. The semantic projection direction is now contract-derived import only; native Rust projection is being deprecated and removed from user-facing flows.

The supported analysis layers are:

• SyntaxOnly: parse/CST/errors only
• RowsOnly: imported contract rows only
• Contract: imported rows + feature facts + expressions
• Runtime: Rust semantic/query/edit materialization from imported contract data

Intent

• Build a general, extensible modeling stack rather than a single hardcoded transformer.
• Map parsed model constructs to stdlib metamodel concepts so semantic queries use model meaning, not only syntax.
• Enable "lightweight EMF in Rust": inspect and edit elements/features, then round-trip back to textual notation.
• Support both single-file workflows and multi-file session-based resolution.

What The Stack Provides

• Parsing pipeline: lexer/parser/CST for SysML v2 / KerML text.
• Semantic pipeline: imported contract bundle ingestion plus Rust-side EMF-like interpretation/runtime services.
• Session model: contract-backed project/session surfaces, EMF-like feature access (e_get, e_set, e_add), and semantic render paths.- Typed API layer: generated and curated wrappers for common element workflows.
• Transactional editing: preview, diff, conflict policies, and atomic apply on top of textual sources.
• Incremental workspace indexing with salsa-backed infrastructure.

Core Architecture

• Textual notation is the source of truth.
• Imported Xtext is the only strategic semantic projection engine.
• Native Rust projection is deprecated and is being retired from user-facing behavior.
• Semantic edits are expressed on projected elements/features and written back as valid textual notation. This makes it possible to:
• query semantic properties (for example, package name via Element.name),
• perform model-aware edits without editing raw strings directly,
• keep round-trip behavior predictable and testable.

Projection Authority

• .sysml / .kerml files are the canonical persisted model.
• contract exporter output is the authoritative semantic projection of that text.
• Rust should consume imported contract to build its EMF-like system implementation.
• Native Rust projection is deprecated and only exists as migration residue until removed.
• Parity should validate the Rust contract-derived EMF-like implementation against Java/EMF output.

Layered Analysis Pipeline

The canonical layer model is documented in docs/layered-analysis-pipeline.md.

Use the layers like this:

• SyntaxOnly for parser structure and syntax diagnostics
• RowsOnly for low-cost semantic row lookup
• Contract for Java-aligned semantic comparison and sidecar-aware model views
• Runtime for semantic query, render, and edit operations

Project and stdlib share the same code path at every non-syntax layer and are merged in memory with explicit Project vs Stdlib scope.

Current Capability Snapshot

• Strong support: package/part/item/attribute-oriented modeling flows, typed usage patterns, requirement + refine paths, metadata/doc blocks, transaction-based typed edits, and contract-backed query/render/file-sync surfaces.
• Active expansion: broader Top-50 SysML v2 construct coverage, deeper stdlib-feature imports, and richer multi-file cross-reference behavior.
• Performance path exists for multi-file sessions; fixture-driven analysis and gates are in place; auto-refreshable contract bundle ingestion is now part of the main projection direction.

Repository Layout

• mercurio-sysml (root crate): compatibility facade and binaries.
• crates/mercurio-sysml-core: syntax, lexer, parser, CST tree, and VFS primitives.
• crates/mercurio-sysml-semantics: defmap, resolution, HIR lowering, stdlib indexing, model-stdlib relations.
• crates/mercurio-sysml-runtime: runtime object graph and schema-backed metamodel access.
• crates/mercurio-sysml-gen: sync-time pilot ingestion helpers for Ecore and Xtext derived artifacts.
• crates/mercurio-sysml-session: session/projection orchestration and compatibility session helpers extracted from the root crate.
• crates/mercurio-sysml-workspace: project/workspace file discovery, descriptor handling, and project-model projection helpers.
• crates/mercurio-sysml-contract: imported contract bundle ingest/index surfaces and the emerging Xtext-first projection boundary.
• crates/mercurio-sysml-semantics (workspace module): salsa-backed incremental workspace indexing/reporting.

Documentation

• Docs index and consolidation guide: docs/README.md
• Computational framework overview and doc set entry point: docs/computational-framework-overview.md
• Semantic milestones and acceptance gates: docs/SEMANTIC_MILESTONES.md
• End-to-end semantic guide (parse -> project -> edit -> render): docs/SEMANTIC_USER_GUIDE.md
• Runnable mini-project guide: docs/SEMANTIC_USER_GUIDE_RUNNABLE.md
• Current supported APIs, verification matrix, and CI coverage: docs/developer-contract.md
• Repo burndown execution plan: docs/burndown-plan.md
• Java parity execution plan: docs/java-parity-plan.md
• Pilot/Xtext sync workflow: docs/PILOT_SYNC_WORKFLOW.md
• contract-only migration checklist: docs/CONTRACT_ONLY_MIGRATION_CHECKLIST.md
• Layered analysis pipeline: docs/layered-analysis-pipeline.md
• Standard semantic benchmark suite: docs/semantic-benchmark-suite.md

Xtext Hint Extraction

Pilot Xtext ingestion is design-time and committed. The repo-level source of truth is resources/generated/pilot/xtext/, produced by sync_pilot_semantics. mercurio-sysml-core/build.rs only compiles those committed artifacts into crate-local tables in OUT_DIR.

By default, sync looks for a sibling checkout at:

• ../SysML-v2-Pilot-Implementation

Override with:

$env:MERCURIO_PILOT_ROOT="C:\dev\git\mercurio\SysML-v2-Pilot-Implementation"

Pilot Sync

The standard repo-level pilot ingestion path is sync_pilot_semantics. It regenerates:

• Imported raw Ecore files in resources/generated/pilot/ecore/raw/
• Ecore-derived runtime domain traits in crates/mercurio-sysml-runtime/src/generated
• resources/metamodel_schema.json
• contract-derived grammar/projection artifacts in resources/generated/pilot/xtext/

The pilot exporter bundle is no longer just a parity oracle. A fresh exporter bundle is the preferred semantic import for project queries, expressions, and render/file-sync flows.

Run:

cargo run --quiet --bin sync_pilot_semantics -- --pilot-root <path-to-SysML-v2-Pilot-Implementation> --skip-parity

Or use the convenience scripts (prefer MERCURIO_PILOT_ROOT; SYSML_PILOT_ROOT remains a compatibility alias):

scripts/gen_all.sh

.\scripts\gen_all.ps1

CI: set repository variable PILOT_ECORE_REPO (for example owner/repo) to enable the generated-sources check job.

cargo run -p mercurio-sysml-gen --bin gen_domain -- --pilot-root ... remains available as a low-level Ecore generator, but it is no longer the standard repo sync path. Once raw Ecore files have been imported into resources/generated/pilot/ecore/raw/, Ecore-derived runtime artifacts can be regenerated without reading the pilot checkout by running sync_pilot_semantics --skip-xtext-sync.

Project Ingest (UI Integration)

For multi-file resolution and diagnostics, use the project ingest helper:

use mercurio_sysml::project_ingest::{collect_project_files, ingest_project_files};

let files = collect_project_files("resources/examples/examples")?;
let result = ingest_project_files(files)?;
println!("diagnostics={}", result.diagnostics.len());

Minimal Getting Started

cargo check -q

For the current developer-facing contract, see docs/developer-contract.md.

As of March 17, 2026, repo-wide cargo test is not the standing branch contract.

CLI Contracts

mercurio-sysml now exposes simple parser/semantic contracts for non-UI workflows:

mercurio-sysml symbols --root <project-root> --json
mercurio-sysml element --root <project-root> --qname <qualified-name> --json
mercurio-sysml compile-delta --root <project-root> --json

Optional --file <path> scopes each command to a single SysML/KerML file.

Semantic Schema Gate

Use this gate to validate Java vs Rust semantic contract shape on matched elements (direct/inherited keysets and canonical direct keys):

cargo run --quiet --bin schema_parity_gate -- --left target/full_examples_rust.jsonl --right target/full_examples_java.jsonl --checklist-out SEMANTIC_SCHEMA_PARITY_CHECKLIST.md

schema_parity_gate defaults to strict thresholds (0 drift). You can set numeric thresholds with:

• --max-canonical-missing-left
• --max-canonical-missing-right
• --max-direct-only-left-keys
• --max-direct-only-right-keys
• --max-inherited-only-left-keys
• --max-inherited-only-right-keys

parity_gate now runs schema_parity_gate automatically after the Rust/Java diff pass, uses strict semantic diff mode, writes a checklist (default: target/parity_gate_schema_checklist.md), and enforces production semantic decomposition-order parity with --max-decomposition-order-mismatches defaulting to 0.

Pilot Sync Workflow

Use one command to run parity and update a tracked manifest of semantic sync artifacts:

cargo run --quiet --bin sync_pilot_semantics -- --pilot-commit <pilot-git-sha>

Default manifest path: resources/pilot_sync_manifest.json.

The command:

• Runs parity_gate (unless --skip-parity is provided).
• Records Pilot source metadata (pilot_repo, pilot_commit).
• Records artifact metadata for semantic contract files and parity outputs.

Useful options:

• --examples-root <dir>
• --exporter-jar <path>
• --manifest <path>
• --skip-parity

CI note:

• The Java exporter now lives in-repo at java/contract-exporter/.
• Build it with mvn -q -s .mvn/settings-example.xml -DskipTests package from java/contract-exporter/.
• The Maven build still requires GitHub Packages credentials via GITHUB_ACTOR / GITHUB_TOKEN.

Semantic Load Benchmark

To compare Java and Rust full semantic load time on the same corpus:

cargo run --quiet --bin semantic_load_bench -- --simple-tests sysml

See docs/semantic-load-benchmark.md for the benchmark contract and options.

External Pilot Parse Sweep

An optional parser regression test can sweep an external SysML pilot examples tree.

• Test name: pilot_external_examples_tests::pilot_examples_parse_clean_when_configured
• Test target: layer_parser
• Env var: PILOT_EXAMPLES_ROOT

If PILOT_EXAMPLES_ROOT is not set (or the path is missing), the test self-skips.

Local run

$env:PILOT_EXAMPLES_ROOT="C:\dev\git\old_archived\sysml\SysML-v2-Pilot-Implementation\sysml\src\examples"
cargo test --test layer_parser pilot_external_examples_tests::pilot_examples_parse_clean_when_configured

CI run

The workflow /.github/workflows/ci.yml reads PILOT_EXAMPLES_ROOT from repository variable vars.PILOT_EXAMPLES_ROOT and runs the same test.

See docs/developer-contract.md for the current PR-vs-nightly CI coverage split.

License

MIT (LICENSE)