sysml2kit 0.1.0__tar.gz → 0.3.0__tar.gz

sysml2kit-0.3.0/CHANGELOG.md

@@ -0,0 +1,82 @@
+# Changelog
+
+## 0.3.0 — 2026-08-21
+
+- **Verification execution** (`sysml2kit.verify`): `verificationBinding`
+  metadata binds an analysis case to an engine resolved by name from the
+  `sysml2kit.engines` entry-point group (model text never names code paths).
+  `run_verification` executes bound analyses and checks each metricKey
+  requirement with margins; `apply_results` writes metrics and verdicts back
+  into the model with provenance, idempotently. CLI `sysml2kit verify`, MCP
+  tool `requirements_verify` (nine tools now), `verify` extra for YAML
+  configs, and a `docs/verification.md` flagship page. First engine:
+  phased-array-systems (PR #2 there).
+- **Live-server harness**: `docker/compose.yaml` runs the pilot
+  implementation (digest-pinned) + postgres; `api`-marked round-trip tests
+  pass against the real server; weekly advisory `live-api` workflow. Live
+  testing hardened the client and reader for the pilot dialect: list-typed
+  endpoints/typing/text adapted on push and tolerated on read, verify/derive
+  pushed as Dependency, multiplicity/doc dropped by the server, server-minted
+  element ids; known-@type records that do not fit the profile now degrade to
+  OpaqueElement instead of failing the read.
+- **`api` CLI group**: `projects`, `pull` (newest commit by default),
+  `push --create`; `SYSML2KIT_API_URL`/`SYSML2KIT_API_TOKEN` env vars;
+  `SysMLApiClient.head_commit`.
+- **Diagrams docs page** and a README refresh for the 0.3 surface.
+- Upstream sysmlpy fixes submitted for the two pinned parse losses:
+  dependency statements (mycr0ft/sysmlpy#7) and allocate endpoints
+  (mycr0ft/sysmlpy#6).
+
+## 0.2.0 — 2026-08-21
+
+- **Parse fidelity**: the sysmlpy backend now walks the raw ANTLR dict
+  (`load_grammar_antlr`) instead of the lossy wrapper objects. Short names,
+  feature typing (incl. cross-package), multiplicity, attribute values with
+  units, requirement subjects and text, docs, and satisfy statements survive
+  a text parse. Upstream visitor losses (dependency statements, allocate and
+  connect endpoints, verification cases) are pinned by tests, documented in
+  SPEC.md, and filed upstream (sysmlpy #4, #5).
+- **MCP server** (`pip install sysml2kit[mcp]`; `sysml2kit mcp serve`):
+  eight tools — model_show, model_validate, model_diff, model_export,
+  model_diagram, requirements_trace, requirements_extract, library_load.
+- **`fmt` command** with a loss-refusing safety gate (grammar-signature and
+  model-diff comparison; `--lossy` to override, `--check` for CI).
+- **Mermaid views** (`sysml2kit.views`): ownership tree and requirement
+  trace diagrams; `export --to mermaid` and the model_diagram tool.
+- **Conformance oracle** pinned to windtrader-java 0.1.1 (sha256-verified,
+  out-of-process pilot parser); weekly workflow green.
+- Downstream bridges landed as PRs: phased-array-systems#1 (op-form
+  RequirementSet) and aedl#1 (bound-form requirements); the RequirementSpec
+  field set is now frozen by a schema test.
+
+## 0.1.0 — 2026-08-21
+
+First working release.
+
+- Object model: the pragmatic profile (~20 element kinds) as pydantic
+  classes, `Model` container with identity/ownership/qualified names,
+  `assign_stable_ids()` (UUIDv5), fluent builder API, `AttributeValue` with
+  unit text and provenance, pint-backed unit helpers.
+- JSON interchange: Systems Modeling API serialization reader/writer,
+  deterministic output, `OpaqueElement` passthrough for unknown `@type`s;
+  json→model→json fixpoint property-tested.
+- Textual notation writer: deterministic `.sysml` output; verified against
+  the sysmlpy parser (write → parse → structural compare).
+- Traceability queries: satisfied_by/verified_by/derived_from,
+  unsatisfied/unverified requirements, allocation table, trace matrix.
+- Validation: rules S2K001–S2K009 with severities and stable ids.
+- Diff: element-level with `--by-name` matching for regenerated ids.
+- API client: hand-written httpx client for the Systems Modeling API
+  (projects/branches/commits/elements reads, create_project, push_model).
+- Parser backends: `ParserBackend` protocol; sysmlpy adapter behind the
+  `parse` extra.
+- Interop: `extract_requirements` reading the metricKey convention, with
+  dual-form thresholds for operator-style and bound-style engines.
+- CLI: `show` (`--traceability`), `validate`, `diff`, `export`
+  (`--stable-ids`), `version`.
+- Docs site, conformance-oracle workflow scaffold, prose lint tooling.
+
+## 0.0.1 — 2026-08-21
+
+- Package skeleton published to claim the PyPI name. Importable, no usable
+  functionality yet.

{sysml2kit-0.1.0 → sysml2kit-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sysml2kit
-Version: 0.1.0
+Version: 0.3.0
 Summary: API-first Python tooling for building, querying, validating, and automating SysML v2 models
 Project-URL: Homepage, https://github.com/jman4162/sysml2kit
 Project-URL: Source, https://github.com/jman4162/sysml2kit
@@ -30,8 +30,12 @@ Requires-Dist: pydantic>=2.7
 Requires-Dist: typer>=0.12
 Provides-Extra: graph
 Requires-Dist: networkx>=3.2; extra == 'graph'
+Provides-Extra: mcp
+Requires-Dist: mcp<2,>=1.26; extra == 'mcp'
 Provides-Extra: parse
 Requires-Dist: sysmlpy<0.37,>=0.36.2; extra == 'parse'
+Provides-Extra: verify
+Requires-Dist: pyyaml>=6.0; extra == 'verify'
 Description-Content-Type: text/markdown
 
 # sysml2kit
@@ -40,20 +44,25 @@ Description-Content-Type: text/markdown
 [![PyPI](https://img.shields.io/pypi/v/sysml2kit)](https://pypi.org/project/sysml2kit/)
 [![Python](https://img.shields.io/pypi/pyversions/sysml2kit)](https://pypi.org/project/sysml2kit/)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-jman4162.github.io-blue)](https://jman4162.github.io/sysml2kit/)
 
 API-first Python tooling for building, querying, validating, and automating
 SysML v2 models.
 
-> **Status: pre-alpha.** The 0.1.x line has a working core (model, writer,
-> interchange, queries, validation, diff, API client, parse backend); the API
-> may still move between minor versions. Pin an exact version if you depend
-> on it.
+> **Status: pre-alpha.** The 0.3.x line covers the full loop: model, writer,
+> interchange, queries, validation, diff, mermaid views, parse backend, MCP
+> server, API client with a live-server harness, and verification execution.
+> The API may still move between minor versions; pin an exact version if you
+> depend on it. Changes: [CHANGELOG.md](CHANGELOG.md).
 
 `sysml2kit` is the requirements/architecture/traceability layer for
 engineering automation stacks: build a system model in Python, emit standard
 SysML v2 textual notation and Systems Modeling API JSON, run traceability
 queries (which requirements are unsatisfied? unverified? allocated where?),
-validate, and diff. It targets the OMG SysML v2 standard, not any vendor tool.
+validate, diff, and **execute verification**: analyses bound to registered
+engines run for real, and their metrics check the model's requirements. It
+targets the OMG SysML v2 standard, not any vendor tool. Docs:
+https://jman4162.github.io/sysml2kit/
 
 ## What it does
 
@@ -70,8 +79,15 @@ validate, and diff. It targets the OMG SysML v2 standard, not any vendor tool.
 - **Traceability queries**: unsatisfied/unverified requirements, allocation
   tables, requirement-to-part trace matrices.
 - **Validation and diff**: rule-based model checks and element-level diffs.
+- **Verification execution**: `verificationBinding` metadata binds an
+  analysis case to an engine from the `sysml2kit.engines` entry-point group;
+  `sysml2kit verify` runs it and checks each requirement with margins, and
+  can write results back into the model with provenance.
+- **Mermaid views**: ownership-tree and requirement-trace diagrams.
+- **MCP server**: nine tools for agents (`sysml2kit mcp serve`).
 - **API client**: a thin HTTP client for the OMG Systems Modeling API and
-  Services endpoints.
+  Services endpoints, plus a docker compose harness running the pilot
+  implementation for live round-trip testing.
 
 ## Install
 
@@ -79,6 +95,8 @@ validate, and diff. It targets the OMG SysML v2 standard, not any vendor tool.
 pip install sysml2kit            # core: build, write, query, validate, diff
 pip install "sysml2kit[parse]"   # + read .sysml files (sysmlpy backend)
 pip install "sysml2kit[graph]"   # + NetworkX export
+pip install "sysml2kit[mcp]"     # + MCP server for agents
+pip install "sysml2kit[verify]"  # + YAML verification-binding configs
 ```
 
 ## Quick start
@@ -117,9 +135,13 @@ sysml2kit
 ├── query         # traceability queries
 ├── validation    # rule-based checks (S2K001...)
 ├── diff          # element-level model diff
+├── views         # mermaid diagrams (trace, tree)
+├── verify        # verification bindings, engine registry, runner
 ├── api           # Systems Modeling API HTTP client
 ├── backends      # parser backends (sysmlpy behind the [parse] extra)
 ├── interop       # tool-agnostic requirement extraction
+├── mcp           # MCP server (behind the [mcp] extra)
+├── graph, units, workspace   # NetworkX export, pint helpers, path safety
 └── cli           # `sysml2kit` command line
 ```
 
@@ -129,13 +151,31 @@ The spec pin, element subset, and known deviations are documented in
 
 Domain content lives outside the kit. For antenna/RF systems engineering, see
 [sysml2kit-rf-library](https://github.com/jman4162/sysml2kit-rf-library), a
-SysML v2 model library consumed through this package.
+SysML v2 model library consumed through this package. Downstream bridges are
+merged in [phased-array-systems](https://github.com/jman4162/phased-array-systems)
+(`interop.sysml`: requirement sets and the `phased-array-systems` verification
+engine) and [aedl](https://github.com/jman4162/aedl-electromagnetic-design-agent)
+(`aedl.interop`: bound-form requirements).
 
 ## For agents
 
-The CLI (`sysml2kit show | validate | diff | export`) is the current
-automation surface. An MCP server is planned for v0.2 under
-`sysml2kit.mcp`.
+An MCP server ships behind the `mcp` extra with nine tools: `model_show`,
+`model_validate`, `model_diff`, `model_export`, `model_diagram`,
+`requirements_trace`, `requirements_extract`, `requirements_verify`, `library_load`. Artifacts are
+returned as file paths, not payloads.
+
+```bash
+pip install "sysml2kit[mcp,parse]"
+sysml2kit mcp serve            # stdio; --transport http also supported
+```
+
+```json
+{"mcpServers": {"sysml2kit": {"command": "sysml2kit", "args": ["mcp", "serve"]}}}
+```
+
+The CLI covers the same operations for shell use:
+`sysml2kit show | validate | diff | export | fmt | verify | api | mcp serve`
+(`export --to mermaid` renders diagrams).
 
 ## Development
 

{sysml2kit-0.1.0 → sysml2kit-0.3.0}/README.md

@@ -4,20 +4,25 @@
 [![PyPI](https://img.shields.io/pypi/v/sysml2kit)](https://pypi.org/project/sysml2kit/)
 [![Python](https://img.shields.io/pypi/pyversions/sysml2kit)](https://pypi.org/project/sysml2kit/)
 [![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-jman4162.github.io-blue)](https://jman4162.github.io/sysml2kit/)
 
 API-first Python tooling for building, querying, validating, and automating
 SysML v2 models.
 
-> **Status: pre-alpha.** The 0.1.x line has a working core (model, writer,
-> interchange, queries, validation, diff, API client, parse backend); the API
-> may still move between minor versions. Pin an exact version if you depend
-> on it.
+> **Status: pre-alpha.** The 0.3.x line covers the full loop: model, writer,
+> interchange, queries, validation, diff, mermaid views, parse backend, MCP
+> server, API client with a live-server harness, and verification execution.
+> The API may still move between minor versions; pin an exact version if you
+> depend on it. Changes: [CHANGELOG.md](CHANGELOG.md).
 
 `sysml2kit` is the requirements/architecture/traceability layer for
 engineering automation stacks: build a system model in Python, emit standard
 SysML v2 textual notation and Systems Modeling API JSON, run traceability
 queries (which requirements are unsatisfied? unverified? allocated where?),
-validate, and diff. It targets the OMG SysML v2 standard, not any vendor tool.
+validate, diff, and **execute verification**: analyses bound to registered
+engines run for real, and their metrics check the model's requirements. It
+targets the OMG SysML v2 standard, not any vendor tool. Docs:
+https://jman4162.github.io/sysml2kit/
 
 ## What it does
 
@@ -34,8 +39,15 @@ validate, and diff. It targets the OMG SysML v2 standard, not any vendor tool.
 - **Traceability queries**: unsatisfied/unverified requirements, allocation
   tables, requirement-to-part trace matrices.
 - **Validation and diff**: rule-based model checks and element-level diffs.
+- **Verification execution**: `verificationBinding` metadata binds an
+  analysis case to an engine from the `sysml2kit.engines` entry-point group;
+  `sysml2kit verify` runs it and checks each requirement with margins, and
+  can write results back into the model with provenance.
+- **Mermaid views**: ownership-tree and requirement-trace diagrams.
+- **MCP server**: nine tools for agents (`sysml2kit mcp serve`).
 - **API client**: a thin HTTP client for the OMG Systems Modeling API and
-  Services endpoints.
+  Services endpoints, plus a docker compose harness running the pilot
+  implementation for live round-trip testing.
 
 ## Install
 
@@ -43,6 +55,8 @@ validate, and diff. It targets the OMG SysML v2 standard, not any vendor tool.
 pip install sysml2kit            # core: build, write, query, validate, diff
 pip install "sysml2kit[parse]"   # + read .sysml files (sysmlpy backend)
 pip install "sysml2kit[graph]"   # + NetworkX export
+pip install "sysml2kit[mcp]"     # + MCP server for agents
+pip install "sysml2kit[verify]"  # + YAML verification-binding configs
 ```
 
 ## Quick start
@@ -81,9 +95,13 @@ sysml2kit
 ├── query         # traceability queries
 ├── validation    # rule-based checks (S2K001...)
 ├── diff          # element-level model diff
+├── views         # mermaid diagrams (trace, tree)
+├── verify        # verification bindings, engine registry, runner
 ├── api           # Systems Modeling API HTTP client
 ├── backends      # parser backends (sysmlpy behind the [parse] extra)
 ├── interop       # tool-agnostic requirement extraction
+├── mcp           # MCP server (behind the [mcp] extra)
+├── graph, units, workspace   # NetworkX export, pint helpers, path safety
 └── cli           # `sysml2kit` command line
 ```
 
@@ -93,13 +111,31 @@ The spec pin, element subset, and known deviations are documented in
 
 Domain content lives outside the kit. For antenna/RF systems engineering, see
 [sysml2kit-rf-library](https://github.com/jman4162/sysml2kit-rf-library), a
-SysML v2 model library consumed through this package.
+SysML v2 model library consumed through this package. Downstream bridges are
+merged in [phased-array-systems](https://github.com/jman4162/phased-array-systems)
+(`interop.sysml`: requirement sets and the `phased-array-systems` verification
+engine) and [aedl](https://github.com/jman4162/aedl-electromagnetic-design-agent)
+(`aedl.interop`: bound-form requirements).
 
 ## For agents
 
-The CLI (`sysml2kit show | validate | diff | export`) is the current
-automation surface. An MCP server is planned for v0.2 under
-`sysml2kit.mcp`.
+An MCP server ships behind the `mcp` extra with nine tools: `model_show`,
+`model_validate`, `model_diff`, `model_export`, `model_diagram`,
+`requirements_trace`, `requirements_extract`, `requirements_verify`, `library_load`. Artifacts are
+returned as file paths, not payloads.
+
+```bash
+pip install "sysml2kit[mcp,parse]"
+sysml2kit mcp serve            # stdio; --transport http also supported
+```
+
+```json
+{"mcpServers": {"sysml2kit": {"command": "sysml2kit", "args": ["mcp", "serve"]}}}
+```
+
+The CLI covers the same operations for shell use:
+`sysml2kit show | validate | diff | export | fmt | verify | api | mcp serve`
+(`export --to mermaid` renders diagrams).
 
 ## Development
 

{sysml2kit-0.1.0 → sysml2kit-0.3.0}/SPEC.md

@@ -46,6 +46,27 @@ not drop elements the profile lacks classes for.
 - **Documentation is a field** (`Element.doc`), not an owned `Documentation`
   element; the writer emits `doc /* ... */` bodies.
 
+## Text parse fidelity (sysmlpy backend, 0.36.x)
+
+The backend parses via ``sysmlpy.load_grammar_antlr`` and walks the raw
+ANTLR dict (the wrapper-object loader rebuilds usage bodies lossily and is
+not used). What survives a text round trip:
+
+| Round-trips | Lost upstream (sysmlpy visitor discards it) |
+|---|---|
+| names, short names | `dependency A to B;` statements (how the writer emits verify/derive) |
+| docs (package/part/requirement scope) | `allocate X to Y;` endpoints |
+| feature typing, incl. cross-package | `connect a.pa to b.pb;` endpoints |
+| multiplicity | `verification` case usages (dropped entirely) |
+| attribute values with units | value provenance (`source`/`confidence` have no textual slot) |
+| requirement subject and text | |
+| satisfy (package level and inside part bodies) | |
+
+Consequence: **satisfy traceability survives text; verify/derive/allocate
+require the JSON interchange.** The losses are pinned by tests in
+`tests/test_backend_fidelity.py` so an upstream sysmlpy fix surfaces as a
+test failure.
+
 ## Identity and ownership
 
 - Every element has a UUID `element_id`, mapping to the API JSON `@id`.
@@ -56,6 +77,33 @@ not drop elements the profile lacks classes for.
 - `Model.assign_stable_ids()` rewrites ids as UUIDv5 hashes of qualified
   names so generated interchange files diff cleanly under version control.
 
+## Verification binding convention
+
+A ``MetadataUsage`` named ``verificationBinding`` annotating an
+``AnalysisCaseUsage`` binds that analysis to an executable engine. Values
+(flat scalars, per the metadata model):
+
+| key | type | meaning |
+|---|---|---|
+| ``engine`` | str, required | registry name, e.g. ``"phased-array-systems"`` |
+| ``configRef`` | str, optional | ``.yaml``/``.yml``/``.json`` payload file next to the model file (resolved relative to its directory, containment-checked; no ``..``) |
+| ``payload.<dotted>`` | scalar, optional | override deep-merged over the loaded config; dotted keys expand to nested dicts |
+
+Engines resolve **by name** against a registry populated from the
+``sysml2kit.engines`` entry-point group and explicit caller registration.
+Model text never names importable code paths — models are data. The runner
+does not interpret payload contents; each engine owns its payload schema
+(engines needing a config plus scalar arguments define reserved top-level
+keys such as ``config``/``args``).
+
+Results written back by ``sysml2kit.verify.apply_results`` are attributes on
+the analysis (``source`` starts with ``sysml2kit.verify``) and a
+``verificationVerdict`` metadata on each requirement; both replace prior
+same-named results, so reruns do not accumulate.
+
+Bindings are an interchange-JSON feature: metadata values round-trip through
+JSON, while textual-notation fidelity for metadata is not yet pinned.
+
 ## Provenance on values
 
 `AttributeValue` carries optional `source` and `confidence` fields, following

sysml2kit-0.3.0/docker/compose.yaml

@@ -0,0 +1,35 @@
+# Local Systems Modeling API server (the OMG pilot implementation) for
+# live-client testing:  docker compose -f docker/compose.yaml up -d
+# then scripts/wait_for_api.sh and  pytest -m api  with
+# SYSML2KIT_API_URL=http://localhost:9000.
+#
+# The app image is the MBSE-mashup containerization of the pilot, pinned by
+# digest (tag 244c221a..., pushed 2025-12-12). Its entrypoint rewrites
+# persistence.xml from the JDBC_*/HIBERNATE_* env vars; hbm2ddl=update
+# creates the schema on first boot. amd64-only: Apple-silicon hosts run it
+# under emulation (the platform key below).
+services:
+  db:
+    image: postgres:16
+    environment:
+      POSTGRES_PASSWORD: mysecretpassword
+      POSTGRES_DB: sysml2
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U postgres -d sysml2"]
+      interval: 5s
+      timeout: 3s
+      retries: 24
+
+  api:
+    image: mbsemashup/sysmlv2-api.pilotimpl@sha256:ac5607986dd529fc98a55aa391ac9f51b275c36f74f946285121c896f7e914c6
+    platform: linux/amd64
+    depends_on:
+      db:
+        condition: service_healthy
+    ports:
+      - "9000:9000"
+    environment:
+      JDBC_URL: jdbc:postgresql://db:5432/sysml2
+      JDBC_USER: postgres
+      JDBC_PASSWORD: mysecretpassword
+      HIBERNATE_HBM2DDL: update

sysml2kit-0.3.0/docs/api-client.md

@@ -0,0 +1,49 @@
+# API client
+
+`sysml2kit.api.SysMLApiClient` is a hand-written httpx client for the OMG
+Systems Modeling API and Services endpoints (the REST binding any conformant
+model server exposes).
+
+```python
+from sysml2kit.api import SysMLApiClient
+
+with SysMLApiClient("https://models.example.com", token="…") as client:
+    for project in client.list_projects():
+        print(project.id, project.name)
+    model = client.list_elements(project_id, commit_id)  # -> sysml2kit Model
+    client.push_model(project_id, model, message="update")
+```
+
+Covered in v0.1: `list_projects`, `get_project`, `list_branches`,
+`list_commits`, `get_commit`, `get_element`, `list_elements` (returns a
+`Model` via the interchange reader), `create_project`, and `push_model`
+(POSTs a commit whose change set inserts the model's records). Branch
+management and merges are not covered yet.
+
+Failures raise `ApiError(status, detail)`. The client sends the bearer token
+to whatever base URL you configure; use HTTPS.
+
+## Local live server and the pilot dialect
+
+`docker compose -f docker/compose.yaml up -d` starts the pilot
+implementation (sha-pinned image + postgres); `scripts/wait_for_api.sh`
+polls until it answers, and `SYSML2KIT_API_URL=http://localhost:9000
+pytest -m api` runs the live round-trip suite (a weekly advisory workflow
+does the same in CI). The CLI mirrors the client:
+
+```bash
+export SYSML2KIT_API_URL=http://localhost:9000
+sysml2kit api projects
+sysml2kit api push model.json --project demo --create
+sysml2kit api pull demo -o pulled.json
+```
+
+The pilot speaks the full abstract syntax, so `push_model` adapts records on
+the way out and the interchange reader tolerates the differences on the way
+back. What survives a server round trip: element kinds, names, short names,
+requirement text. What does not (documented degradations — full fidelity
+lives in interchange JSON files): ownership (the pilot models it as
+OwningMembership elements and ignores our owner key), verify/derive kinds
+(pushed as `Dependency`), multiplicity and doc strings (dropped), and
+element ids (the server mints its own, so stable-id workflows are
+local-file-only).

{sysml2kit-0.1.0 → sysml2kit-0.3.0}/docs/backends.md

@@ -15,14 +15,19 @@ model = backend.parse_files([path_a, path_b])
 
 `pip install sysml2kit[parse]` installs
 [sysmlpy](https://github.com/mycr0ft/sysmlpy) (MIT, ANTLR4-based). The
-adapter maps its parse tree into the pragmatic profile; constructs the
-profile lacks come back as `OpaqueElement` with a logged warning.
-
-Fidelity: sysmlpy 0.36 does not surface typing, multiplicity, or attribute
-values on its wrapper objects, so those fields are empty after a parse.
-Names, kinds, docs, and ownership round-trip; the writer-emit → parse → 
-compare test in CI pins exactly that contract. Use JSON interchange when you
-need full fidelity.
+backend parses with `sysmlpy.load_grammar_antlr` and walks the raw ANTLR
+dict — sysmlpy's own wrapper loader rebuilds usage bodies lossily, so the
+wrappers are not used.
+
+Fidelity: names, short names, docs, feature typing (including
+cross-package), multiplicity, attribute values with units, requirement
+subjects, and satisfy statements survive a text parse. What cannot
+round-trip is what sysmlpy's visitor discards before we see it: `dependency`
+statements (how the writer emits verify/derive), `allocate` and `connect`
+endpoints, and `verification` cases (filed upstream as sysmlpy #4 and #5).
+The fidelity table lives in SPEC.md and is pinned by
+`tests/test_backend_fidelity.py`. Use JSON interchange when you need the
+full traceability graph.
 
 The dependency is capped (`sysmlpy>=0.36.2,<0.37`) because it has a single
 maintainer; bumps are deliberate, after reading the release notes.

{sysml2kit-0.1.0 → sysml2kit-0.3.0}/docs/cli.md

@@ -12,8 +12,13 @@ sysml2kit diff old.json new.json --by-name  # match by qualified name, not id
 sysml2kit export model.sysml --to json -o model.json
 sysml2kit export model.json --to sysml
 sysml2kit export model.json --to json --stable-ids  # UUIDv5 ids for committing
+sysml2kit export model.json --to mermaid --diagram trace  # or tree
+sysml2kit fmt model.sysml                 # refuses lossy rewrites; --lossy overrides
+sysml2kit fmt model.sysml --check         # CI mode: exit 1 if it would change
+sysml2kit mcp serve                       # MCP server (mcp extra)
 sysml2kit version
 ```
 
 Exit codes: `validate` returns 1 when any error-severity issue is found;
-`diff` returns 1 when the models differ. Both suit CI gates.
+`diff` returns 1 when the models differ; `fmt --check` returns 1 when the
+file would change. All suit CI gates.

sysml2kit-0.3.0/docs/mcp.md

@@ -0,0 +1,34 @@
+# MCP server
+
+`pip install "sysml2kit[mcp]"` and run:
+
+```bash
+sysml2kit mcp serve                    # stdio (default)
+sysml2kit mcp serve --transport http   # streamable HTTP
+```
+
+Client config:
+
+```json
+{"mcpServers": {"sysml2kit": {"command": "sysml2kit", "args": ["mcp", "serve"]}}}
+```
+
+Every tool takes model file paths (`.json` interchange always works;
+`.sysml` needs the `parse` extra), returns a JSON dict with a `status` key,
+and reports failures as `{"error": ..., "status": "failed"}` instead of
+raising. Artifacts are returned as file paths, not payloads.
+
+| Tool | What it does |
+|---|---|
+| `model_show(path, traceability)` | Element tree, kind counts, optional trace matrix |
+| `model_validate(path)` | S2K rule issues with severity counts |
+| `model_diff(path_a, path_b, by_name)` | Element-level differences (capped list) |
+| `model_export(path, out, to, stable_ids)` | Convert to interchange JSON or `.sysml` |
+| `model_diagram(path, out, kind)` | Write a mermaid `.mmd` (trace or tree view) |
+| `requirements_trace(path)` | Matrix plus unsatisfied/unverified lists |
+| `requirements_extract(path)` | `RequirementSpec` list (the adapter payload) |
+| `library_load(name, out)` | Write a packaged rf-library model as JSON |
+
+A typical agent loop: write a `.sysml` file, `model_validate` it, fix issues,
+`requirements_trace` to check coverage, `model_export --stable-ids` to commit
+the interchange form, `model_diagram` to explain the result.

{sysml2kit-0.1.0 → sysml2kit-0.3.0}/docs/quickstart.md

@@ -13,18 +13,21 @@ model = Model()
 pkg = builder.pkg(model, "Vehicle")
 battery = builder.part(model, "battery", owner=pkg)
 range_req = builder.req(
-    model, "REQ-001", "Range", owner=pkg,
+    model,
+    "REQ-001",
+    "Range",
+    owner=pkg,
     text="The vehicle shall travel at least 400 km on one charge.",
 )
 builder.satisfy(model, source=battery, target=range_req)
 
-print(unverified_requirements(model))   # [REQ-001] - nothing verifies it yet
-print(trace_matrix(model).render())     # requirement-by-part grid
+print(unverified_requirements(model))  # [REQ-001] - nothing verifies it yet
+print(trace_matrix(model).render())  # requirement-by-part grid
 for issue in validate(model):
     print(issue.rule_id, issue.severity, issue.message)
 
-print(write_model(model))               # SysML v2 textual notation
-write_json(model, "vehicle.json")       # Systems Modeling API interchange
+print(write_model(model))  # SysML v2 textual notation
+write_json(model, "vehicle.json")  # Systems Modeling API interchange
 ```
 
 The same operations from the command line:

sysml2kit-0.3.0/docs/verification.md

@@ -0,0 +1,87 @@
+# Verification execution
+
+`sysml2kit.verify` closes the loop the traceability queries only describe:
+it runs the analyses a model's verify links point at and checks each
+requirement against real metrics.
+
+## The binding convention
+
+An analysis case becomes executable when it carries a `verificationBinding`
+metadata (see SPEC.md for the normative statement):
+
+```python
+from sysml2kit.model import builder
+
+analysis = builder.analysis(model, "pasStudy", owner=pkg, subject=terminal)
+builder.verify(model, source=analysis, target=link_margin_req, owner=pkg)
+builder.metadata(
+    model,
+    analysis,
+    {"engine": "phased-array-systems", "configRef": "study.yaml"},
+    name="verificationBinding",
+)
+```
+
+- `engine` names an entry in the engine registry — never a code path.
+  Models are data; the registry decides what runs.
+- `configRef` points at a YAML/JSON payload next to the model file.
+- `payload.<dotted>` values override entries in the loaded config
+  (`payload.scenario.range_km: 500`).
+
+## Engines
+
+An engine is a callable: payload dict in, flat metrics mapping out.
+Packages ship engines through the `sysml2kit.engines` entry-point group:
+
+```toml
+[project.entry-points."sysml2kit.engines"]
+phased-array-systems = "phased_array_systems.interop.sysml:run_study"
+```
+
+Installing such a package makes its engine available by name. The CLI also
+accepts operator-supplied engines (`--engine name=module:function`), and
+library callers register directly on an `EngineRegistry`.
+
+## Running
+
+```bash
+sysml2kit verify model.json --report run.json
+sysml2kit verify model.json --write-back -o annotated.json
+```
+
+```python
+from sysml2kit.verify import run_verification, apply_results
+
+run = run_verification(model, model_path=path)
+print(run.passed)
+for verdict in run.requirements:
+    print(verdict.requirement_id, verdict.status, verdict.margin)
+apply_results(model, run)  # record results into the model, idempotent
+```
+
+Each requirement verdict carries the metric key, operator, threshold,
+actual value, and margin; `passed` is true only when every must-severity
+requirement passes and no engine errored. Metrics that are absent or
+non-numeric yield `unknown`, which does not pass. Engine exceptions are
+captured per analysis, never raised.
+
+Write-back records each checked metric as an attribute on its analysis with
+a provenance `source` (`sysml2kit.verify <engine>==<version> <timestamp>`)
+and a `verificationVerdict` metadata on each requirement, replacing prior
+results so reruns do not accumulate.
+
+Over MCP, the `requirements_verify` tool runs the same flow with
+entry-point engines only, returning `passed`, must-failures, and the report
+path.
+
+## End to end with the RF library
+
+With `phased-array-systems` and `sysml2kit-rf-library` installed:
+
+```bash
+MODEL=$(python -c 'import sysml2kit_rf_library as m; print(m.models_dir())')/interchange/satcom_terminal_pas.json
+sysml2kit verify "$MODEL" --report run.json
+```
+
+runs a phased-array study and checks link margin, EIRP, sidelobes, prime
+power, and cost against the model's thresholds.