longeron 0.2.0__tar.gz

longeron-0.2.0/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

longeron-0.2.0/PKG-INFO

@@ -0,0 +1,449 @@
+Metadata-Version: 2.4
+Name: longeron
+Version: 0.2.0
+Summary: Define, execute, and replay SysML v2 models in Python: ANTLR-based parser, validator, interpreter, and diagram renderers
+Author: sanbales
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/sanbales/longeron
+Project-URL: Repository, https://github.com/sanbales/longeron
+Keywords: sysml,sysml2,kerml,mbse,systems-engineering,modeling
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: antlr4-python3-runtime==4.13.2
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov>=5; extra == "dev"
+Requires-Dist: mypy>=1.11; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Requires-Dist: pyecore>=0.15; extra == "dev"
+Requires-Dist: nbformat>=5; extra == "dev"
+Requires-Dist: nbclient>=0.10; extra == "dev"
+Requires-Dist: ipykernel>=6; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: anywidget>=0.9; extra == "dev"
+Provides-Extra: ecore
+Requires-Dist: pyecore>=0.15; extra == "ecore"
+Provides-Extra: replay
+Requires-Dist: anywidget>=0.9; extra == "replay"
+Dynamic: license-file
+
+# Longeron
+
+*The spine of your system model* — a Python package that defines,
+exports, imports, and **executes** SysML v2 models (import name:
+`sysml2`). The parsers are generated with ANTLR 4 from combined grammars
+for SysML v2 and KerML, taken from
+[hivecore-dev/hcf-runtime](https://github.com/hivecore-dev/hcf-runtime)
+(`SysML.g4`, `KerML.g4`, with local patches — see
+[Grammar patches](#grammar-patches)).
+
+> SysML® is a registered trademark of the Object Management Group. This
+> project is not affiliated with or endorsed by OMG, and is not a
+> conformance-certified implementation.
+
+## Capabilities
+
+| Verb | What you get |
+|---|---|
+| **Define** | Parse SysML v2 textual notation into a fully-typed Python object model, import a model from its JSON export, or build models programmatically from dataclasses. Multi-file workspaces merge under one root; a content-addressed cache makes warm loads ~1000x faster. |
+| **Export** | Serialize any model to JSON, back to parseable SysML v2 text, project it onto KerML, or emit OMG Systems-Modeling-API JSON records. Parse → print → parse round-trips preserve the model; JSON → model → JSON is lossless. |
+| **Validate** | `sysml2.validate()` / `sysml2 lint`: dangling references, expression-name typos, duplicate names, specialization cycles, state-machine problems. Names resolve against the vendored standard library (a bare `Real` passes with no import; a typo like `Reall` warns), and plain definitions carry their *implied* specializations (`part def` → `Parts::Part`, `action def` → `Actions::Action`, which is how `start`/`done` resolve); opt out with `stdlib=False` / `--no-stdlib`. |
+| **Execute** | Evaluate expressions, run `calc` definitions, instantiate `part` definitions (against the bundled standard library if you opt in), check constraints and requirements, run `action` definitions with succession-driven control flow, and simulate hierarchical/parallel state machines with a clock. |
+| **Visualize** | `sysml2.diagrams`: interactive ELK diagrams in JupyterLab (structure, state machines, action flow) with click-selection that resolves back to model elements. |
+| **Full loop** | Read a model, execute it, snapshot the results back into the model as bound part usages, and save (`.sysml`, `.json`, or `.kerml`). |
+
+The builder covers the full grammar: every construct the SysML grammar
+accepts (interfaces, views, flows, allocations, metadata annotations,
+satisfy/verify/frame, filtered imports, ...) maps to a model class — there
+is no lossy fallback. KerML support is asymmetric by design:
+`parse_kerml_text` validates KerML sources syntactically, and `to_kerml`
+projects SysML models onto the kernel language.
+
+## Installation
+
+```bash
+python -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+make check        # ruff + mypy + 310 tests
+```
+
+Optional: `pip install -e ".[ecore]"` enables the OMG spec-metamodel
+projection and API JSON (pyecore); `pre-commit install` wires ruff+mypy
+into every commit.
+
+### With pixi (optional)
+
+The repo also carries `[tool.pixi]` config in `pyproject.toml` (dependency
+truth stays in `[project]`; pixi adds the locked toolchain on top):
+
+```bash
+pixi run check          # lint + mypy + tests in a locked environment
+pixi run -e py310 test  # any supported Python: py310 | py311 | py312 | py313
+pixi run parsers        # regenerate ANTLR parsers -- no manual Java setup:
+                        # conda-forge's antlr 4.13.2 ships the tool + JDK
+pixi run lab            # JupyterLab in notebooks/ (vendored ipyelk extension
+                        # pre-registered -- diagrams render interactively)
+pixi run stdlib | demo | coverage | format | notebooks
+```
+
+CI runs entirely on pixi (`prefix-dev/setup-pixi`, cached by `pixi.lock`):
+a `check` job (lint + mypy + coverage), a test matrix across the four
+Python environments, and a grammar-regen job that fails if the committed
+parsers drift from the `.g4` sources. The `parsers` task is
+input/output-cached locally and produces byte-identical output.
+
+The generated ANTLR parsers are committed under `src/sysml2/_gen/`, so no
+Java toolchain is needed to install or use the package. Java is only needed
+to regenerate the parsers after a grammar change:
+
+```bash
+# any Java 11+ works; for example: mamba create -n jdk openjdk
+python scripts/generate_parsers.py
+```
+
+## Quick start
+
+```python
+import sysml2
+
+model = sysml2.loads("""
+    package Demo {
+        part def Vehicle {
+            attribute mass : Real = 1200.0;
+            attribute maxMass : Real = 2000.0;
+            part wheels : Wheel[4];
+            assert constraint massLimit { mass <= maxMass }
+        }
+        part def Wheel { attribute diameter : Real = 0.66; }
+        calc def Double { in x : Real; return : Real = 2.0 * x; }
+    }
+""")
+
+# --- export -------------------------------------------------------------
+print(sysml2.to_sysml(model))   # regenerated textual notation
+print(sysml2.to_json(model))    # structured JSON
+
+# --- execute ------------------------------------------------------------
+interp = sysml2.Interpreter(model)
+
+interp.call("Demo::Double", 21.0)            # -> 42.0
+car = interp.instantiate("Demo::Vehicle")    # attributes evaluated
+car.get("wheels")                            # -> [Instance, ...] (4 wheels)
+interp.check(car)[0].passed                  # -> True (mass <= maxMass)
+interp.evaluate("(1, 2, 3)->select { in x; x > 1 }")  # -> [2, 3]
+```
+
+Actions and state machines:
+
+```python
+model = sysml2.loads("""
+    package Ops {
+        action def Plan {
+            in distance : Real;
+            out fuel : Real;
+            assign fuel := distance * 0.08;
+        }
+        state def Machine {
+            entry; then off;
+            state off;
+            transition first off accept start then on;
+            state on;
+        }
+    }
+""")
+interp = sysml2.Interpreter(model)
+interp.run_action("Ops::Plan", inputs={"distance": 100.0}).outputs
+# -> {'fuel': 8.0}
+interp.simulate("Ops::Machine", events=["start"]).final_state
+# -> 'on'
+```
+
+A complete walk-through lives in `examples/demo.py`, and five executable
+tutorials live in [`notebooks/`](notebooks/):
+
+| Notebook | Covers |
+|---|---|
+| `01_define_and_explore` | parsing, the object model, programmatic authoring, workspaces |
+| `02_export_and_interchange` | SysML/JSON round-trips, save/load, KerML, spec metamodel, API JSON |
+| `03_calculations_and_constraints` | expressions, calcs, instantiation, constraints, requirements, the full loop |
+| `04_actions_and_states` | action graphs, hierarchical/parallel state machines, time |
+| `05_stdlib_and_validation` | the vendored standard library, `sysml2 lint` |
+| `06_interactive_diagrams` | ipyelk structure/state/action diagrams, click-selection |
+
+The notebooks are executed by the test suite (`tests/test_notebooks.py`) and
+can be refreshed with `pixi run notebooks`.
+
+```bash
+python examples/demo.py
+```
+
+### The full loop: read → run → save
+
+```python
+model = sysml2.load("examples/drone.sysml")
+interp = sysml2.Interpreter(model)
+
+# run
+flown = interp.instantiate("Drone::QuadCopter", payloadMass=0.35)
+
+# write computed values back into the model as a bound part usage
+model.find("Drone").add(interp.snapshot(flown, name="asFlown"))
+
+# save in any format (inferred from the suffix)
+sysml2.save(model, "drone_with_results.sysml")
+sysml2.save(model, "drone_with_results.json")
+sysml2.save(model, "drone_with_results.kerml")
+
+# the JSON export is lossless: reload and keep executing
+again = sysml2.load("drone_with_results.json")
+sysml2.Interpreter(again).instantiate("Drone::QuadCopter")
+```
+
+SysML or KerML text can be generated from just the JSON definition:
+
+```python
+model = sysml2.from_json(json_text)   # or sysml2.from_dict(data)
+print(sysml2.to_sysml(model))
+print(sysml2.to_kerml(model))         # kernel-language projection
+```
+
+### Multi-file projects and caching
+
+`load()` accepts a single `.sysml` file, a `.json` export, or a directory:
+
+```python
+model = sysml2.load("models/")            # every *.sysml file, merged
+model = sysml2.load_many(["lib.sysml", "app.json"])   # explicit set
+```
+
+Directory loads merge all files under one root namespace, so cross-file
+imports (`private import Units::*;`) and qualified references resolve.
+Files load in sorted path order for determinism.
+
+Built models are cached (as JSON — the same lossless schema as `to_json`,
+never pickles) in `~/.cache/sysml2` (override with `$SYSML2_CACHE_DIR`),
+keyed by source content plus a fingerprint of the generated parser and
+builder code — edits, grammar regeneration, and package upgrades invalidate
+cleanly. Caching is on by default for directories, off for single files
+(`cache=` overrides; `sysml2.clear_cache()` wipes it). Warm directory loads
+are ~1000x faster than cold parses with the ANTLR Python runtime.
+
+## Command line
+
+```bash
+sysml2 parse examples/drone.sysml                      # syntax check (file or dir)
+sysml2 export examples/drone.sysml --format sysml      # json | sysml | kerml
+sysml2 export model.json --format sysml                # JSON in, SysML out
+sysml2 export models/ --format json                    # whole directory, merged
+sysml2 calc examples/drone.sysml Drone::HoverTime capacity=5200
+sysml2 check examples/drone.sysml Drone::QuadCopter payloadMass=0.9
+sysml2 run examples/drone.sysml Drone::PlanBattery distanceKm=20
+sysml2 simulate examples/drone.sysml Drone::FlightStates --events launch,airborne
+```
+
+Every model-consuming command accepts `.sysml`, `.json`, or a directory;
+`--no-cache` bypasses the model cache.
+
+## Project layout
+
+```
+grammars/                  SysML.g4 + KerML.g4 (upstream + local patches)
+scripts/generate_parsers.py  regenerate src/sysml2/_gen from the grammars
+src/sysml2/
+    _gen/                  generated ANTLR lexers/parsers (committed)
+    parser.py              text -> parse tree, error collection
+    builder.py             parse tree -> model (the SysML front-end)
+    model.py               model element dataclasses (Literal-typed vocabularies)
+    ast.py                 expression AST + precedence-aware printer
+    export.py              model -> JSON / SysML text, save()
+    importer.py            JSON -> model (lossless round-trip)
+    workspace.py           multi-file loading + content-addressed model cache
+    kerml.py               model -> KerML projection
+    validation.py          sysml2 lint / validate()
+    stdlib.py + _stdlib/   vendored OMG standard library (+ prebuilt pickle)
+    ecore.py + _spec/      projection onto the OMG spec metamodel (pyecore)
+    api.py                 OMG Systems Modeling API JSON interchange
+    diagrams.py            interactive ELK diagrams (ipyelk)
+    render.py + _js/       headless SVG/PNG export (vendored elkjs via node)
+vendor/ipyelk/             vendored ipyelk 2.1.1 + local fixes (editable)
+    interpreter.py         evaluation, instantiation, actions, states, snapshot
+    cli.py                 the `sysml2` console command
+examples/                  drone.sysml + kernel.kerml + demo.py
+tests/                     310 pytest tests (84% coverage)
+.github/workflows/ci.yml   pixi-based: check + test matrix (3.10-3.13)
+                           + grammar-regen drift check (antlr/JDK from lock)
+Makefile                   make check = ruff + mypy + pytest (venv/pip route)
+```
+
+### How a model flows through the package
+
+1. `parser.py` runs the generated ANTLR parser and collects syntax errors.
+2. `builder.py` walks the parse tree and produces `model.py` dataclasses.
+   Expressions become compact AST nodes (`ast.py`), not parse-tree references.
+3. `export.py` renders the model to JSON or textual notation; `importer.py`
+   reads the JSON back; `kerml.py` projects onto KerML.
+4. `interpreter.py` resolves qualified names (imports, aliases,
+   specialization) and executes the model; `snapshot` converts runtime
+   instances back into model elements.
+
+## Code quality
+
+- **Typing**: modern PEP 585/604 annotations throughout; closed string
+  vocabularies (`kind`, `direction`, `visibility`, operators, ...) are
+  `typing.Literal` aliases (`model.UsageKind`, `ast.BinaryOp`, ...).
+  `mypy` runs clean over `src/sysml2` (generated code excluded).
+- **Linting**: `ruff` with `E, W, F, I, UP, B, C4, RUF` rules.
+- `make check` runs ruff + mypy + the full test suite.
+
+## Execution semantics (and their limits)
+
+This is a modeling sandbox, not a full KerML semantic engine. What executes:
+
+- **Actions**: bodies without successions run in declaration order. Bodies
+  with explicit successions (`first start then a; first a then b;`) run as
+  a control-flow graph: unreachable steps do not execute, `decide` nodes
+  choose the first satisfied guard (with `else` fallback), guarded loops
+  back-edge, and `fork`/`join` branches run sequentially in declaration
+  order (no interleaving). `accept after d` / `accept at t` advance the
+  action's clock (`ActionResult.time`); `accept when c` raises on a false
+  condition (a would-be deadlock).
+- **State machines** are hierarchical: composite states enter through their
+  own `entry; then S;` transition, inner states get the first chance to
+  consume an event, and exits cascade innermost-first. `parallel` states
+  activate all child regions concurrently (`SimulationResult.active_states`).
+  Time triggers (`accept after`/`accept at`) fire when a plain number in the
+  event list advances the simulation clock; `accept when c` transitions fire
+  as soon as their condition holds.
+- Quantities evaluate to their magnitude: `10 [SI::m]` evaluates to `10`.
+- **Standard library**: a curated subset of the official model library ships
+  with the package (all 21 Systems Library files + core Quantities/Units +
+  a KerML-kernel shim; see `sysml2/_stdlib/README.md`). Opt in with
+  `sysml2.add_standard_library(model)` or `--stdlib` on the CLI: library
+  types resolve (`Parts::Part`, `ISQ::mass`, `SI::kg`), `public import`
+  re-exports and aliases follow, and `istype` checks work against library
+  definitions. A bundled prebuilt pickle makes loading instant; the KerML
+  Kernel Libraries themselves are not loaded (KerML is parse-only), so
+  inherited library defaults that need unimplemented kernel functions
+  degrade to `None` instead of failing. The prebuilt ships as plain JSON
+  (`_stdlib/prebuilt.json`) — inspectable text, no pickles anywhere.
+- Multiplicity expansion: exact bounds (`[4]`) expand fully; ranges
+  populate their lower bound (`[0..*]` gives an empty list), which keeps
+  the library's self-referential compositions finite.
+
+## Interactive diagrams
+
+`sysml2.diagrams` renders models as interactive ELK diagrams in JupyterLab
+(see `notebooks/06_interactive_diagrams.ipynb`):
+
+```python
+from sysml2 import diagrams
+
+diagrams.structure_diagram(model)                 # defs, compartments, edges
+diagrams.state_diagram(model.find("P::Machine"))  # hierarchical states
+diagrams.action_diagram(model.find("P::Flow"))    # the executed succession graph
+diagrams.diagram(element)                          # dispatch by kind
+
+diagrams.on_select(widget, model, callback)        # clicks -> model elements
+```
+
+Node ids are qualified names, so browser selections resolve straight back to
+model elements. Layout runs in the browser (elkjs), so diagrams also build
+headlessly (tests, nbclient).
+
+The same views export to images without a browser — `sysml2.render` runs
+the vendored elkjs (0.9.3, EPL-2.0, `sysml2/_js/`) in a node subprocess and
+draws styled SVG, with PNG via cairosvg (node + cairo ship in the pixi
+environments):
+
+```python
+from sysml2 import render
+
+render.to_svg(diagrams.state_diagram(machine), "machine.svg")
+render.to_png(model, "model.png")   # builds a view automatically
+```
+
+State-machine simulations replay over that same diagram: `sysml2.replay`
+records a simulation (the `Interpreter.simulate` event protocol -- names
+send events, numbers advance the clock) and animates it in the notebook
+with play/pause, speed, and scrubbing. Active states light up green and
+fired transitions pulse orange. Needs the `replay` extra
+(`pip install "longeron[replay]"`, anywidget):
+
+```python
+from sysml2 import replay
+
+replay.replay_widget(interp, "Machines::Player",
+                     events=["play", 3600.0, "play"])
+```
+
+ipyelk is **vendored** (`vendor/ipyelk`, BSD-3-Clause, tag v2.1.1) and
+installed editable (`pip install -e vendor/ipyelk`; pixi does this
+automatically) so it can be patched as needed. Current local fixes, all
+marked `LOCAL PATCH` and tracked by `git log -- vendor/ipyelk`:
+
+1. **Headless-safe scheduling** — `Pipe.schedule_run` raised
+   `RuntimeError: no running event loop` outside Jupyter (plain scripts,
+   pytest); it now no-ops cleanly when there is no frontend to lay out for.
+2. **Prebuilt labextension grafted** — the git tree only carries TypeScript
+   sources; the built JupyterLab extension from the 2.1.1 wheel is vendored
+   under `src/_d/` so the editable install renders without a node toolchain.
+
+## Spec-metamodel projection and API interchange
+
+With the `ecore` extra installed, models project onto the OMG abstract
+syntax (the pilot implementation's `SysML.ecore`, 175 metaclasses, vendored
+under `sysml2/_spec/`):
+
+```python
+from sysml2 import ecore, api
+
+spec = ecore.to_spec(model)      # reified memberships, FeatureTyping, ...
+spec.report                       # what was covered / skipped
+spec.save_xmi("model.xmi")       # EMF XMI
+
+api.to_api_json(model)            # OMG Systems Modeling API records
+api.from_api_json(text)           # records -> spec instances
+```
+
+Both are structural prototypes: names, flags, ownership, and
+specialization/typing relationships are mapped; expression trees are not
+(counted in `SpecReport`, never silently dropped).
+
+## Grammar patches
+
+Deviations from the upstream grammars, each marked with a ``LOCAL PATCH``
+comment in the `.g4` files:
+
+1. **`import` visibility (SysML.g4).** Upstream required a visibility
+   keyword before every `import`, which rejects the spec's own examples
+   (`import ScalarValues::*;`). Aligned with KerML.g4's optional prefix.
+2. **Entry transitions (SysML.g4).** Upstream required `entry; then then S;`
+   because `targetSuccession` already contains `then`. The patch accepts the
+   spec form `entry; then S;`.
+3. **Unary operator precedence (both grammars).** Upstream parsed `-3 + 1`
+   as `-(3 + 1)` because the unary alternative sat below the binary
+   alternatives with a non-rightmost recursion. The patch moves unary above
+   the binary operators, so `-3 + 1` is `(-3) + 1`.
+4. **`@` vs `at` (SysML.g4, four sites).** In SysML, `AT` is the keyword
+   `at` (trigger times) and the `@` symbol is `AT_SIGN`; upstream used `AT`
+   in the metadata and classification rules copied from KerML (where `AT`
+   itself is `'@'`). Upstream therefore required `at Safety` instead of
+   `@Safety`, and `x at T` instead of `x @ T`.
+5. **Flow ends (SysML.g4).** `flowEndSubsetting` dropped the spec's `'.'`
+   after `QualifiedName`, so `flow from a.out to b.in` could not parse.
+
+One known deviation from the OMG spec remains, inherited from upstream: the
+grammar groups `??`/`or`/`and`/`implies` at one precedence level and
+`|`/`&`/`xor` at another, and `**` is left-associative. Parenthesize when in
+doubt; the exporter always prints round-trip-safe parentheses.
+
+## Regenerating the parsers
+
+```bash
+python scripts/generate_parsers.py
+```
+
+The script finds Java via `JAVA_HOME`, `PATH`, or a conda/mamba env, and the
+ANTLR 4.13.2 jar via `ANTLR_JAR`, `~/.m2`, or Maven Central. Regenerate
+whenever a `.g4` file changes, then run `pytest`.