feat(libs): vendor the extension libraries pinned to OpenSysML-Extensions-Library, with an engine contract

.github/workflows/extension-libraries-upstream.yml

@@ -0,0 +1,97 @@
+name: Extension libraries upstream
+
+# Advisory: does the extension-libraries upstream's ref still run under
+# OpenSysML? It syncs the ref into the vendored directory and runs the whole
+# suite. It is scheduled rather than a required check: it downloads from
+# upstream and takes minutes, so a failure here surfaces what broke without
+# blocking pull requests. It never pushes and never opens issues.
+on:
+  schedule:
+    - cron: '41 4 * * *'
+  workflow_dispatch:
+    inputs:
+      ref:
+        description: 'Extension-libraries ref to sync (branch or tag)'
+        required: true
+        default: main
+
+permissions:
+  contents: read
+
+jobs:
+  upstream:
+    name: OpenSysML against upstream extension libraries
+    runs-on: ubuntu-latest
+    timeout-minutes: 120
+    env:
+      REF: ${{ inputs.ref || 'main' }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Go
+        uses: actions/setup-go@v5
+        with:
+          go-version-file: go.mod
+          cache: true
+
+      - name: Install Z3
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y z3
+          z3 --version
+
+      - 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: Sync the upstream ref
+        id: sync
+        run: |
+          out="$(scripts/sync-extension-libraries.sh --ref "$REF" | tee /dev/stderr)"
+          sha="$(sed -n 's/^Resolved .* to \([0-9a-f]*\)$/\1/p' <<<"$out" | tail -1)"
+          {
+            echo "### Synced upstream \`$REF\` at \`$sha\`"
+            echo '```'
+            git status --porcelain -- "internal/workspace/libs/stdlib/OpenSysML Libraries/"
+            echo '```'
+          } >> "$GITHUB_STEP_SUMMARY"
+
+      - name: Check the library snapshot
+        id: snapshot
+        run: |
+          if make stdlib-snapshot-check; then
+            echo "Snapshot unchanged." >> "$GITHUB_STEP_SUMMARY"
+          else
+            echo "Snapshot regenerated for the synced libraries." >> "$GITHUB_STEP_SUMMARY"
+            make stdlib-snapshot
+          fi
+
+      - name: Run the test suite
+        id: tests
+        run: |
+          go test ./...
+          go test -C tools ./...
+
+      - name: Report the verdict
+        if: always()
+        run: |
+          if [ "${{ steps.tests.outcome }}" = "success" ]; then
+            echo "Upstream \`$REF\` runs clean under OpenSysML." >> "$GITHUB_STEP_SUMMARY"
+          else
+            {
+              echo "**Upstream \`$REF\` breaks OpenSysML.**"
+              echo ""
+              echo "| step | outcome |"
+              echo "| --- | --- |"
+              echo "| sync | ${{ steps.sync.outcome }} |"
+              echo "| snapshot | ${{ steps.snapshot.outcome }} |"
+              echo "| tests | ${{ steps.tests.outcome }} |"
+            } >> "$GITHUB_STEP_SUMMARY"
+          fi
+          git checkout -- "internal/workspace/libs/stdlib/OpenSysML Libraries/" 2>/dev/null || true

.github/workflows/pr.yml

@@ -72,6 +72,12 @@ jobs:
           BASE_REF: ${{ github.base_ref }}
         run: scripts/ci-changed-areas.sh "origin/$BASE_REF" HEAD | tee -a "$GITHUB_OUTPUT"
 
+      # The vendored copy is checked in this job, not static-and-integrity: the
+      # changed-areas filter may skip that job for a non-Go change, but drift
+      # between the vendored libraries and their pin must always fail.
+      - name: Check the vendored extension libraries against their pin
+        run: make extension-libraries-check
+
   race-tests:
     name: Go race tests (${{ matrix.shard }})
     needs: changes

Makefile

@@ -1,4 +1,4 @@
-.PHONY: all build build-sysml build-prod build-wasm-prod build-lsp build-grpc build-engine build-core build-syntax build-sysml-wasm build-release-wasm build-wasm build-wasm-wasip1 build-wasm-js wasm-check static-check windows-versioninfo-check man man-check install-tree pgo-profile conformance conformance-pkg conformance-rust conformance-julia conformance-matlab test test-shard coverage lint clean install help ontology-table ontology-table-check python-metamodel python-metamodel-check fuml-expected python-test python-coverage scripts-coverage node-coverage python-install proto proto-buf python-proto proto-ts proto-rust proto-lint proto-breaking vscode-grammar vscode-build vscode-package docs docs-install docs-serve docs-engine-assets docs-landing-assets docs-counts docs-check changelog-check changelog-render self-model
+.PHONY: all build extension-libraries-check extension-libraries-sync build-sysml build-prod build-wasm-prod build-lsp build-grpc build-engine build-core build-syntax build-sysml-wasm build-release-wasm build-wasm build-wasm-wasip1 build-wasm-js wasm-check static-check windows-versioninfo-check man man-check install-tree pgo-profile conformance conformance-pkg conformance-rust conformance-julia conformance-matlab test test-shard coverage lint clean install help ontology-table ontology-table-check python-metamodel python-metamodel-check fuml-expected python-test python-coverage scripts-coverage node-coverage python-install proto proto-buf python-proto proto-ts proto-rust proto-lint proto-breaking vscode-grammar vscode-build vscode-package docs docs-install docs-serve docs-engine-assets docs-landing-assets docs-counts docs-check changelog-check changelog-render self-model
 
 # Version information
 # Only release tags describe a build; the moving `nightly` tag is not a version.
@@ -315,6 +315,12 @@ test-short: ## Run Go tests without race detection
 	go test -v ./...
 	go test -C $(TOOLS_DIR) -v ./...
 
+extension-libraries-check: ## Check the vendored extension libraries match their upstream pin
+	./scripts/sync-extension-libraries.sh --check
+
+extension-libraries-sync: ## Re-vendor the extension libraries from the pinned upstream commit
+	./scripts/sync-extension-libraries.sh
+
 stdlib-snapshot: ## Regenerate the embedded snapshot of the bundled library after editing $(LIBS_DIR)/stdlib
 	go generate ./$(LIBS_DIR)
 

README.md

@@ -399,7 +399,7 @@ github.com/Open-MBEE/OpenSysML
 - **Parser:** hand-written recursive descent (no framework overhead, full error recovery, sub-millisecond parses)
 - **Grammar source:** OMG pilot Xtext grammars (`SysML.xtext` and `KerMLExpressions`)
 - **Spec compliance:** [OMG SysML v2.1 Beta 1 / KerML 1.1](https://www.omg.org/spec/SysML/2.0) (2026-08 release)
-- **Standard library:** 94 files from [SysML v2 Pilot Implementation 2026-08](https://github.com/Systems-Modeling/SysML-v2-Pilot-Implementation/releases/tag/2026-08), byte-identical, plus the eleven non-normative `OpenSysML Libraries/` extensions (`OpenSysMLMathFunctions`, `DocumentQueries`, `IdentityMetadata`, `DiagramLayout`, [`OOSEM`](docs/project/oosem-library.md), [`MOSA`](docs/project/mosa-library.md), `StateSpaceIntegration`, `Stochastic`, `RandomFunctions`, `Simulation` and `MigrationMetadata`)
+- **Standard library:** 94 files from [SysML v2 Pilot Implementation 2026-08](https://github.com/Systems-Modeling/SysML-v2-Pilot-Implementation/releases/tag/2026-08), byte-identical, plus the non-normative `OpenSysML Libraries/` extensions (`OpenSysMLMathFunctions`, `DocumentQueries`, `IdentityMetadata`, `DiagramLayout`, [`OOSEM`](docs/project/oosem-library.md), [`MOSA`](docs/project/mosa-library.md), `StateSpaceIntegration`, `Stochastic`, `RandomFunctions`, `Simulation`, `AnalysisRecords`, `StateMachines`, `SysMLValidation` and `MigrationMetadata`). The extensions are maintained upstream at [Open-MBEE/OpenSysML-Extensions-Library](https://github.com/Open-MBEE/OpenSysML-Extensions-Library) — for any SysML v2 tool — and vendored here pinned by `scripts/extension-libraries-pin.sh` ([pin, sync and contract](docs/project/extension-libraries.md))
 - **CI/CD:** GitHub Actions checks pull requests; CircleCI builds and tests `main` and `develop` and publishes releases from tags
 
 ## Releases

changes/unreleased/extension-libraries-upstream.changed.md

@@ -0,0 +1 @@
+- The non-normative `OpenSysML Libraries/` extension libraries are now maintained upstream at [Open-MBEE/OpenSysML-Extensions-Library](https://github.com/Open-MBEE/OpenSysML-Extensions-Library); the bundled copy is pinned by `scripts/extension-libraries-pin.sh`, refreshed by `scripts/sync-extension-libraries.sh` (`make extension-libraries-sync`), checked for drift on every pull request (`make extension-libraries-check`), and carries `engine-contract.json` recording the qualified names the engine binds.

docs/guide/04-repl.md

@@ -214,7 +214,10 @@ specialized view is marked `(from <view>)`. A concern the viewpoint frames but t
 not is reported as `violated`. A concern that states no condition, or names one that does not
 resolve, is reported as `unevaluable` with the reason, not as a pass. These verdicts, and
 the way a nested view's framing is treated, are this implementation's own decisions, because
-SysML v2 leaves verification verdict semantics non-normative.
+SysML v2 leaves verification verdict semantics non-normative. (The extension
+libraries these documents name are maintained upstream at
+[Open-MBEE/OpenSysML-Extensions-Library](https://github.com/Open-MBEE/OpenSysML-Extensions-Library)
+and vendored here pinned.)
 
 ```
 sysml> package Demo {

docs/guide/06-behavior.md

@@ -993,7 +993,10 @@ in ten* — and by a duration — *the settle takes between one and eighty secon
 has no notation for either. OpenSysML supplies one as an extension library, in standard SysML v2
 that any other tool reads as ordinary metadata and a function call: two library packages,
 `Stochastic` and `RandomFunctions` under `internal/workspace/libs/stdlib/OpenSysML Libraries/`, both
-marked NON-NORMATIVE, with the vendored OMG files untouched. What they state is *modeled*
+marked NON-NORMATIVE, with the vendored OMG files untouched. The extension libraries are
+maintained upstream at
+[Open-MBEE/OpenSysML-Extensions-Library](https://github.com/Open-MBEE/OpenSysML-Extensions-Library)
+and vendored here pinned. What they state is *modeled*
 randomness, and the runtime keeps it apart from the scheduling kind: a weighted branch is drawn
 by its weights, a scheduling choice never is, and the two draw from two independent streams,
 fixed by two independent seeds.

docs/internals/architecture.md

@@ -664,7 +664,7 @@ See [the guide](../guide/) for VS Code configuration.
 | Standard library bundling | ✅ Complete |
 | LSP server implementation | ✅ Complete |
 
-**Parser coverage:** 106/106 bundled library files parse cleanly — the 94 official SysML v2 standard library files and the 12 non-normative OpenSysML extensions: `OpenSysML Libraries/OpenSysMLMathFunctions.kerml`, `DocumentQueries.sysml`, `IdentityMetadata.sysml`, `OOSEM.sysml`, `DiagramLayout.sysml`, `MOSA.sysml`, `RandomFunctions.kerml`, `Simulation.sysml`, `StateSpaceIntegration.sysml`, `Stochastic.sysml`, `AnalysisRecords.sysml` and `MigrationMetadata.sysml`. Conformance verified by [stdlib_conformance_test.go](../../internal/workspace/libs/stdlib_conformance_test.go). Grammar reference available at [OMG Xtext grammar](https://github.com/Systems-Modeling/SysML-v2-Pilot-Implementation/tree/master/org.omg.kerml.xtext/src/org/omg/kerml/xtext).
+**Parser coverage:** 106/106 bundled library files parse cleanly — the 94 official SysML v2 standard library files and the 12 non-normative OpenSysML extensions: `OpenSysML Libraries/OpenSysMLMathFunctions.kerml`, `DocumentQueries.sysml`, `IdentityMetadata.sysml`, `OOSEM.sysml`, `DiagramLayout.sysml`, `MOSA.sysml`, `RandomFunctions.kerml`, `Simulation.sysml`, `StateSpaceIntegration.sysml`, `Stochastic.sysml`, `AnalysisRecords.sysml` and `MigrationMetadata.sysml`. The extensions are maintained upstream at [Open-MBEE/OpenSysML-Extensions-Library](https://github.com/Open-MBEE/OpenSysML-Extensions-Library) and vendored here pinned by `scripts/extension-libraries-pin.sh`; `engine-contract.json` beside them records the names the engine binds. Conformance verified by [stdlib_conformance_test.go](../../internal/workspace/libs/stdlib_conformance_test.go). Grammar reference available at [OMG Xtext grammar](https://github.com/Systems-Modeling/SysML-v2-Pilot-Implementation/tree/master/org.omg.kerml.xtext/src/org/omg/kerml/xtext).
 
 ---
 

docs/manual/introduction.md

@@ -46,7 +46,10 @@ model → queries → document plan → document tree → Markdown or HTML → (
 Everything the engine understands is declared in one bundled library package,
 `DocumentQueries`. It is a non-normative OpenSysML extension — the types are
 ordinary SysML v2 declarations, so a model using them still parses everywhere,
-but only OpenSysML gives them document semantics.
+but only OpenSysML gives them document semantics. The extension libraries are
+maintained upstream at
+[Open-MBEE/OpenSysML-Extensions-Library](https://github.com/Open-MBEE/OpenSysML-Extensions-Library)
+and vendored here pinned.
 
 **Query operations** (each a `calc def` taking and returning ordered element
 sequences):

docs/manual/recording-analysis-runs.md

@@ -169,7 +169,9 @@ calc def TimedRuns :> DocumentQueries::Query {
 ## The AnalysisRecords library
 
 `internal/workspace/libs/stdlib/OpenSysML Libraries/AnalysisRecords.sysml`, a
-non-normative OpenSysML extension bundled like `DocumentQueries`, declares the
+non-normative OpenSysML extension bundled like `DocumentQueries` (maintained upstream at
+[Open-MBEE/OpenSysML-Extensions-Library](https://github.com/Open-MBEE/OpenSysML-Extensions-Library)
+and vendored here pinned), declares the
 vocabulary the records are written in:
 
 - `RecordedRun` — the metadata annotation a record carries: `runAt` (the UTC

docs/manual/troubleshooting.md

@@ -113,7 +113,9 @@ position; they are tracked in the project's compliance record.
 
 - **The vocabulary is non-normative.** `DocumentQueries` is an OpenSysML
   extension; other SysML v2 tools will parse models that use it but will not
-  render documents from them.
+  render documents from them. The extension libraries are maintained upstream
+  at [Open-MBEE/OpenSysML-Extensions-Library](https://github.com/Open-MBEE/OpenSysML-Extensions-Library)
+  and vendored here pinned.
 - **Query-generated runs cannot cross-reference.** Column runs restyle
   query-produced text and can link to external URLs, but `Ref`-style
   cross-references to other content blocks apply to statically-authored runs

docs/project/diagram-layout-annotations.md

@@ -47,7 +47,8 @@ model changes: its renderings are byte-identical to what they were.
 Six metadata definitions, shipped as a non-normative OpenSysML library extension in the
 same tier as `IdentityMetadata` (`internal/workspace/libs/stdlib/OpenSysML
 Libraries/DiagramLayout.sysml`, counted by the stdlib conformance gate with the other
-extensions):
+extensions; maintained upstream at Open-MBEE/OpenSysML-Extensions-Library and vendored
+here pinned by `scripts/extension-libraries-pin.sh`):
 
 ```sysml
 standard library package DiagramLayout {

docs/project/element-identity-annotations.md

@@ -51,7 +51,9 @@ update of the same element rather than a delete and a create.
 ## The metadata library
 
 Two metadata definitions, shipped as a non-normative OpenSysML library extension (the
-stdlib already carries two such files; the conformance gate counts them separately):
+stdlib already carries two such files; the conformance gate counts them separately;
+maintained upstream at Open-MBEE/OpenSysML-Extensions-Library and vendored here pinned
+by `scripts/extension-libraries-pin.sh`):
 
 ```sysml
 standard library package IdentityMetadata {

docs/project/extension-libraries.md

@@ -0,0 +1,42 @@
+# Extension libraries — pin, sync and engine contract
+
+The non-normative OpenSysML extension libraries (`OpenSysMLMathFunctions`,
+`DocumentQueries`, `IdentityMetadata`, `DiagramLayout`, `OOSEM`, `MOSA`,
+`StateSpaceIntegration`, `Stochastic`, `RandomFunctions`, `Simulation`,
+`AnalysisRecords`, `MigrationMetadata`, `StateMachines` and `SysMLValidation`)
+are maintained upstream at
+[Open-MBEE/OpenSysML-Extensions-Library](https://github.com/Open-MBEE/OpenSysML-Extensions-Library),
+with their history imported from this repository. Other tools get them from
+that repository or from the `.kpar` project archive each upstream release
+attaches.
+
+OpenSysML consumes them as a vendored copy at
+`internal/workspace/libs/stdlib/OpenSysML Libraries/`:
+
+- `scripts/extension-libraries-pin.sh` records the repository and the commit
+  the copy was taken from (`EXTENSIONS_REPO`, `EXTENSIONS_REF`,
+  `EXTENSIONS_COMMIT`, each environment-overridable).
+- `scripts/sync-extension-libraries.sh` rewrites the copy from the pin.
+  `--check` reports drift without writing (run by `make
+  extension-libraries-check`, which CI runs on every pull request); `--ref
+  REF` syncs a branch or tag instead of the pin; `--source DIR` syncs a local
+  upstream checkout. An upstream holding no libraries or no
+  `engine-contract.json` is refused, and a file
+  the upstream does not carry — `README.md` aside, which the vendored copy
+  owns — is an error, so edits are never made here: they go upstream, the pin
+  is bumped, and the sync re-runs.
+- `engine-contract.json`, synced beside the libraries, is the machine-read
+  contract: the qualified names the engine binds — the functions the runtime
+  registry implements, the metadata and features it reads, the document
+  elements the doc and query plans compile, and the names the SysML v1
+  migrator writes. `internal/exec/runtime/engine_contract_test.go` holds the
+  registry to the manifest's `function` entries;
+  `tests/hygiene/engine_contract_test.go` derives every extension-qualified
+  name the code binds and requires it to be a manifest entry. Breaking the
+  contract upstream requires a `contract` bump, a coordinated OpenSysML pull
+  request that re-pins, and a MAJOR upstream release.
+- `.github/workflows/extension-libraries-upstream.yml` is the advisory
+  nightly: it syncs the upstream `main` (or a dispatch-given ref), checks the
+  library snapshot and runs the whole suite in both Go modules (`./...` and
+  `tools`), so an upstream change that
+  breaks OpenSysML surfaces within a day. It is not a required check.

docs/project/mosa-library.md

@@ -1,6 +1,6 @@
 # MOSA library — design
 
-Status: **implemented.** `internal/workspace/libs/stdlib/OpenSysML Libraries/MOSA.sysml` is bundled
+Status: **implemented.** `internal/workspace/libs/stdlib/OpenSysML Libraries/MOSA.sysml` — maintained upstream at Open-MBEE/OpenSysML-Extensions-Library and vendored here pinned by `scripts/extension-libraries-pin.sh` — is bundled
 with the other OpenSysML extensions, enters the same conformance, strict-notation and snapshot
 gates, and is exercised by `examples/mosa-demo/mosa-demo.sysml` (`TestExamplesAnalyseCleanly`).
 `passes.MOSAPass` audits models written against it.

docs/project/oosem-library.md

@@ -1,8 +1,9 @@
 # OOSEM library — design
 
 Status: **implemented.** `internal/workspace/libs/stdlib/OpenSysML Libraries/OOSEM.sysml` is bundled
-with the other OpenSysML extensions, enters the same conformance, strict-notation and snapshot
-gates, and is exercised by `examples/oosem-demo/oosem-demo.sysml`
+with the other OpenSysML extensions — maintained upstream at Open-MBEE/OpenSysML-Extensions-Library
+and vendored here pinned by `scripts/extension-libraries-pin.sh` — enters the same conformance,
+strict-notation and snapshot gates, and is exercised by `examples/oosem-demo/oosem-demo.sysml`
 (`TestExamplesAnalyseCleanly`). Both the library and the example also validate cleanly under the
 pinned OMG pilot implementation, so the notation they use is standard SysML v2.
 

docs/project/pilot-differential.md

@@ -102,6 +102,9 @@ build/pilot-sysml-validator/validate-sysml-batch model.sysml \
     "internal/workspace/libs/stdlib/OpenSysML Libraries"
 ```
 
+The extensions under it are maintained upstream at Open-MBEE/OpenSysML-Extensions-Library and
+vendored here pinned by `scripts/extension-libraries-pin.sh`.
+
 This harness still hands each language to its own bridge (a `.kerml` file of a root goes to
 `validate-kerml`), so the committed baseline's verdicts are unchanged by this; only the bridge's
 source digest in its provenance moved.