feat: import the OpenSysML extension libraries with their history, plus pilot-pinned validation CI

.github/workflows/ci.yml

@@ -0,0 +1,113 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    name: Validate the extension libraries
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Fetch the pull request base
+        if: github.event_name == 'pull_request'
+        run: git fetch origin "${{ github.base_ref }}"
+
+      - name: Set up Java
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '21'
+
+      - name: Cache the pilot validator
+        uses: actions/cache@v4
+        with:
+          path: build/pilot-validator
+          key: pilot-validator-${{ hashFiles('scripts/pilot-pin.sh', 'scripts/download-pilot-validator.sh', 'scripts/download-pilot-sysml-validator.sh', 'scripts/verify-pilot-pin.sh') }}
+          restore-keys: pilot-validator-
+
+      - name: Verify the pilot pin
+        run: ./scripts/verify-pilot-pin.sh
+
+      - name: Validate the libraries
+        run: ./scripts/validate-libraries.sh
+
+      - name: Check the README library table
+        run: ./scripts/check-readme-table.sh
+
+      - name: Check the engine contract
+        run: |
+          if [ "${{ github.event_name }}" = "pull_request" ]; then
+            ./scripts/check-engine-contract.sh --base "origin/${{ github.base_ref }}"
+          else
+            ./scripts/check-engine-contract.sh
+          fi
+
+      - name: Build the project archive
+        run: ./scripts/build-kpar.py --version "0.0.0-dev.${{ github.run_number }}+${GITHUB_SHA::7}" --output opensysml-extension-libraries-dev.kpar
+
+      - name: Upload the project archive
+        uses: actions/upload-artifact@v4
+        with:
+          name: opensysml-extension-libraries-dev
+          path: opensysml-extension-libraries-dev.kpar
+
+  opensysml-mirror:
+    name: OpenSysML against these libraries (advisory)
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    timeout-minutes: 90
+    steps:
+      - name: Check out this repository
+        uses: actions/checkout@v4
+        with:
+          path: extensions
+
+      - name: Check out OpenSysML
+        uses: actions/checkout@v4
+        with:
+          repository: Open-MBEE/OpenSysML
+          ref: develop
+          path: opensysml
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: opensysml/go.mod
+
+      - name: Install z3
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y z3
+
+      - name: Install cvc5
+        run: |
+          curl -fsSL --proto '=https' --proto-redir '=https' -o /tmp/cvc5.zip \
+            https://github.com/cvc5/cvc5/releases/download/cvc5-1.3.4/cvc5-Linux-x86_64-static.zip
+          echo "dcdbfada0ce493ee98259c0816e0daafc561c223aadb3af298c2968e73ea39c6  /tmp/cvc5.zip" | sha256sum --check --strict
+          unzip -p /tmp/cvc5.zip '*/bin/cvc5' > /tmp/cvc5-bin
+          sudo install -m 0755 /tmp/cvc5-bin /usr/local/bin/cvc5
+          cvc5 --version | head -1
+
+      - name: Run OpenSysML against these libraries
+        env:
+          EXTENSIONS_DIR: ${{ github.workspace }}/extensions
+        run: |
+          cd "$GITHUB_WORKSPACE/opensysml"
+          if [ ! -f scripts/sync-extension-libraries.sh ]; then
+            echo "OpenSysML does not yet vendor from this repository (no sync-extension-libraries.sh); skipping."
+            exit 0
+          fi
+          scripts/sync-extension-libraries.sh --source "$EXTENSIONS_DIR"
+          make stdlib-snapshot-check || make stdlib-snapshot
+          go test ./internal/workspace/libs/... ./internal/exec/... ./internal/ir/... ./internal/doc/... ./internal/semantic/... ./internal/check/... ./internal/translate/... ./tests/hygiene/...

.github/workflows/release.yml

@@ -0,0 +1,46 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v[0-9]+.[0-9]+.[0-9]+'
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    name: Build and attach the project archive
+    runs-on: ubuntu-latest
+    timeout-minutes: 60
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Java
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: '21'
+
+      - name: Verify the pilot pin
+        run: ./scripts/verify-pilot-pin.sh
+
+      - name: Validate the libraries
+        run: ./scripts/validate-libraries.sh
+
+      - name: Build the project archive
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          ./scripts/build-kpar.py --version "$version" --output "opensysml-extension-libraries-${version}.kpar"
+
+      - name: Create the release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          kpar="opensysml-extension-libraries-${version}.kpar"
+          gh release create "$GITHUB_REF_NAME" "$kpar" \
+            --verify-tag \
+            --title "OpenSysML Extension Libraries $GITHUB_REF_NAME" \
+            --notes "KerML 10.3 project archive of the extension libraries at $GITHUB_REF_NAME, validated against the pinned OMG SysML v2 Pilot Implementation."

.gitignore

@@ -0,0 +1,2 @@
+build/
+*.kpar

CONTRIBUTING.md

@@ -0,0 +1,49 @@
+# Contributing
+
+## Proposing a library
+
+Open an issue or pull request stating the library's purpose, its intended
+consumers, and its portability (any SysML v2 tool, or an executing engine).
+
+## Naming
+
+- UpperCamelCase; the package name equals the file stem.
+- One top-level `library package` per file.
+- Never reuse an OMG standard-library package name.
+- `.kerml` only for KerML-only content; everything else is `.sysml`.
+
+## Documentation
+
+- A top-level `doc` that says NON-NORMATIVE and what the library is for.
+- Every public definition documented.
+
+## Validation
+
+- `./scripts/validate-libraries.sh` must pass on the pinned pilot with 0
+  errors and 0 warnings.
+- `validation/allowed-warnings.txt` only shrinks: never add an entry.
+- Never write `standard library package` — that keyword is reserved for the
+  OMG standard library and the pilot validator warns on it.
+- A README table row is required; CI checks the table against `libraries/`.
+- State the semver impact of your change in the pull request (see Versioning
+  in the README).
+
+## The engine contract
+
+`engine-contract.json` records the qualified names OpenSysML binds to.
+Changing or removing a manifest entry is a breaking change: it needs
+`contract` bumped, a coordinated Open-MBEE/OpenSysML pull request that
+re-pins its vendored copy, and a MAJOR release. New engine bindings are added
+to the manifest by the OpenSysML-side pull request that introduces them —
+upstream there first.
+
+## Review
+
+At least one maintainer approval. Changes OpenSysML's runtime depends on need
+a matching OpenSysML pull request that re-pins its vendored copy; edits to
+that vendored copy are not accepted in OpenSysML — they come here.
+
+## Bumping the pilot pin
+
+Edit `scripts/pilot-pin.sh` (`PILOT_TAG` and `PILOT_COMMIT` together) and
+re-run `./scripts/verify-pilot-pin.sh` and `./scripts/validate-libraries.sh`.

README.md

@@ -0,0 +1,110 @@
+# OpenSysML Extension Libraries
+
+A community repository of **non-normative** SysML v2 / KerML extension
+libraries. They are maintained here and consumed by
+[OpenSysML](https://github.com/Open-MBEE/OpenSysML) and any other SysML v2
+tool. They are **not** part of the OMG standard library; some of them are
+proposed for standardization (DiagramLayout, IdentityMetadata and
+MigrationMetadata say so in their doc text).
+
+A model that uses one of these libraries is valid SysML v2 that depends on a
+non-normative OpenSysML library; other tools resolve it when given the
+`libraries/` folder (OpenSysML bundles the same files as its
+`OpenSysML Libraries` folder).
+
+## The libraries
+
+| Library | File | Description | Portability |
+|---|---|---|---|
+| AnalysisRecords | AnalysisRecords.sysml | Metadata a run, sweep or sample records itself with: when it ran, the tool and command, verdicts and evaluations. | Executing engine |
+| DiagramLayout | DiagramLayout.sysml | Diagram geometry: element placement, edge waypoints and the drawing extent. | Any SysML v2 tool |
+| DocumentQueries | DocumentQueries.sysml | Calc definitions (OwnedElements, Descendants, Ancestors, …) that document views evaluate to select elements. | Executing engine |
+| IdentityMetadata | IdentityMetadata.sysml | Binds notation to repository element identity. | Any SysML v2 tool |
+| MOSA | MOSA.sysml | Modular Open Systems Approach (10 U.S.C. § 4401) vocabulary. | Any SysML v2 tool |
+| MigrationMetadata | MigrationMetadata.sysml | What a migration from another modelling language had to make up because the source left it unstated. | Any SysML v2 tool |
+| OOSEM | OOSEM.sysml | Object-Oriented Systems Engineering Method artefacts, viewpoints and product views. | Any SysML v2 tool |
+| OpenSysMLMathFunctions | OpenSysMLMathFunctions.kerml | exp, ln, log, atan2, ceiling and the Integer quotient the Kernel Function Library omits. | Executing engine |
+| RandomFunctions | RandomFunctions.kerml | Seeded random draws: uniform, uniformInteger, triangular, normal. | Executing engine |
+| Simulation | Simulation.sysml | How a behavior is meant to be run: run count, draw resolution, clock, Monte Carlo. | Executing engine |
+| StateMachines | StateMachines.sysml | Pseudostates (choice, junction, shallow/deep history) the grammar has no production for. | Executing engine |
+| StateSpaceIntegration | StateSpaceIntegration.sysml | Fixed-step (Euler/RK4) running of StateSpaceRepresentation dynamics. | Executing engine |
+| Stochastic | Stochastic.sysml | Probability metadata for branches; a tool unaware of it runs the branches as an unweighted choice. | Executing engine |
+| SysMLValidation | SysMLValidation.sysml | KerML/SysML abstract-syntax validation constraints over the reflective metamodel. | Executing engine |
+
+Portability "Executing engine" means an executing engine gives the library its
+behavior; the libraries still parse and resolve in any tool — only their
+behavior needs an engine.
+
+## Layout
+
+`libraries/` is flat: one `library package` per file, and the file stem equals
+the package name. SysML resolves libraries by package name, not path, so any
+tool can load the directory as-is. The folder these files used to live in,
+`OpenSysML Libraries/`, was OpenSysML's library-tier folder; the history here
+was imported from Open-MBEE/OpenSysML, and old `#N` references in commit
+messages point at that repository.
+
+## Using the libraries
+
+Every tool also needs the OMG standard library (`sysml.library`).
+
+- **OMG pilot batch validator** —
+  `validate-sysml-batch --library <sysml.library> libraries <your model dir>`
+  (`validate-sysml --library DIR [--root DIR] FILE|DIR...`). The validator in
+  this repository (`./scripts/download-pilot-sysml-validator.sh`) builds the
+  same program.
+- **Pilot Eclipse** — import this repository into the workspace as a project
+  alongside `sysml.library`, so the editor indexes it the same way.
+- **SysON** — import the `.sysml` files into the project, or into a library
+  project it references if your SysON version supports that; see SysON's
+  documentation. SysON does not execute behavior, so the portable libraries
+  are the ones that matter there.
+- **sysml-toolkit** —
+  `sysmlv2 check --lib <sysml.library> libraries/*.sysml libraries/*.kerml model.sysml`,
+  or pass the release `.kpar` (the CLI expands `.kpar` inputs).
+- **OpenSysML** — bundled: it vendors a pinned copy at
+  `internal/workspace/libs/stdlib/OpenSysML Libraries/`, pinned by
+  `scripts/extension-libraries-pin.sh` and refreshed by
+  `scripts/sync-extension-libraries.sh`. Edits land here first.
+
+## Versioning
+
+Releases are semver tags `vX.Y.Z` on `main`:
+
+- **MAJOR** — removing or renaming a library or a public element, or changing
+  its meaning.
+- **MINOR** — adding a library or element.
+- **PATCH** — documentation and doc-comment changes and fixes that keep names
+  and meaning.
+
+Each release attaches a `.kpar` project archive. Consumers pin a tag or
+commit.
+
+## Engine contract
+
+`engine-contract.json` lists the qualified names in `libraries/` that
+OpenSysML's engine binds to — the functions its runtime registry implements,
+the metadata and features it reads, the DocumentQueries elements its document
+and query plans compile, and the names the SysML v1 migrator writes into user
+models. OpenSysML binds by qualified name, so those names are an API: removing,
+renaming or changing an entry is a breaking change and needs `contract`
+bumped, a coordinated Open-MBEE/OpenSysML pull request that re-pins its
+vendored copy, and a MAJOR release. Additions are MINOR.
+
+`./scripts/check-engine-contract.sh` validates the manifest and resolves every
+entry against `libraries/` on the pinned pilot; in pull requests it also diffs
+the manifest against the base and fails on unannounced breaking changes.
+
+## Validation
+
+`./scripts/validate-libraries.sh` runs the pinned OMG pilot batch validator
+(`scripts/pilot-pin.sh`) over `libraries/` and requires zero errors and zero
+warnings. Four warnings are temporarily allow-listed in
+`validation/allowed-warnings.txt` — the four files that still declare
+`standard library package`; an upstream change to `library package` is being
+ported and those entries will be deleted. The allow-list only shrinks.
+
+## License
+
+Apache-2.0. Every library was authored in OpenSysML; no OMG material is
+redistributed here.