feat: make the repository a KerML 10.3 project interchange

.github/workflows/ci.yml

@@ -45,6 +45,9 @@ jobs:
       - name: Check the README library table
         run: ./scripts/check-readme-table.sh
 
+      - name: Check the project manifests against the tree
+        run: ./scripts/write-project-meta.py --check
+
       - name: Check the engine contract
         run: |
           if [ "${{ github.event_name }}" = "pull_request" ]; then
@@ -54,13 +57,13 @@ jobs:
           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
+        run: ./scripts/build-kpar.py --output opensysml-extensions-library.kpar
 
       - name: Upload the project archive
         uses: actions/upload-artifact@v4
         with:
-          name: opensysml-extension-libraries-dev
-          path: opensysml-extension-libraries-dev.kpar
+          name: opensysml-extensions-library-${{ github.sha }}
+          path: opensysml-extensions-library.kpar
 
   opensysml-mirror:
     name: OpenSysML against these libraries (advisory)

.github/workflows/release.yml

@@ -23,6 +23,18 @@ jobs:
           distribution: temurin
           java-version: '21'
 
+      - name: Assert the tag equals the committed project version
+        run: |
+          version="$(python3 -c 'import json; print(json.load(open(".project.json"))["version"])')"
+          if [ "v${version}" != "$GITHUB_REF_NAME" ]; then
+            echo "error: tag $GITHUB_REF_NAME does not equal .project.json version ${version}; bump the version in a release-prep commit and tag that" >&2
+            exit 1
+          fi
+          echo "tag $GITHUB_REF_NAME matches .project.json version ${version}"
+
+      - name: Check the project manifests against the tree
+        run: ./scripts/write-project-meta.py --check
+
       - name: Verify the pilot pin
         run: ./scripts/verify-pilot-pin.sh
 
@@ -32,15 +44,15 @@ jobs:
       - name: Build the project archive
         run: |
           version="${GITHUB_REF_NAME#v}"
-          ./scripts/build-kpar.py --version "$version" --output "opensysml-extension-libraries-${version}.kpar"
+          ./scripts/build-kpar.py --version "$version" --output "opensysml-extensions-library-${version}.kpar"
 
       - name: Create the release
         env:
           GH_TOKEN: ${{ github.token }}
         run: |
           version="${GITHUB_REF_NAME#v}"
-          kpar="opensysml-extension-libraries-${version}.kpar"
+          kpar="opensysml-extensions-library-${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."
+            --title "OpenSysML Extensions Library $GITHUB_REF_NAME" \
+            --notes "KerML 10.3 project archive derived from the .project.json and .meta.json of this tag, validated against the pinned OMG SysML v2 Pilot Implementation. The tag's tree is the same project: depend on it as pkg:git/github.com/Open-MBEE/OpenSysML-Extensions-Library with versionConstraint ${version}."

.meta.json

@@ -0,0 +1,92 @@
+{
+  "checksum": {
+    "LICENSE": {
+      "algorithm": "SHA256",
+      "value": "c71d239df91726fc519c6eb72d318ec65820627232b2f796219e87dcf35d0ab4"
+    },
+    "libraries/AnalysisRecords.sysml": {
+      "algorithm": "SHA256",
+      "value": "ffdd07b031da3d1eba483a915aca2b773d7d1044895fc5e0788f1c97ec21e297"
+    },
+    "libraries/DiagramLayout.sysml": {
+      "algorithm": "SHA256",
+      "value": "8d55d0b0e3da5d7474eedfeaa035f4af774a7e4ba71a7a78b2f2d94fa07244e0"
+    },
+    "libraries/DocumentQueries.sysml": {
+      "algorithm": "SHA256",
+      "value": "aa60929736008efde216af31a14482817abc221a67e53c337173f53b59d63322"
+    },
+    "libraries/IdentityMetadata.sysml": {
+      "algorithm": "SHA256",
+      "value": "3463931816369ca9bc1f0bf8bc96eb2bece9e6ced8f8b3ff48a4fc964a9a2aab"
+    },
+    "libraries/MOSA.sysml": {
+      "algorithm": "SHA256",
+      "value": "e07bdb6c8c6f856cb5236132e8295913342db06cc7806865f545a86e8f44dfae"
+    },
+    "libraries/MigrationMetadata.sysml": {
+      "algorithm": "SHA256",
+      "value": "4bafea415e043bb14c8dd1858753e1bc318808ff8c8294523cdc12ebea0e319c"
+    },
+    "libraries/OOSEM.sysml": {
+      "algorithm": "SHA256",
+      "value": "7845c981b51ff99b9204a26493d5a07396f9007a2cf51c6ca7583125bfd31abf"
+    },
+    "libraries/OpenSysMLMathFunctions.kerml": {
+      "algorithm": "SHA256",
+      "value": "8230dfbdd7376430ab819f29e50f4333933535db750b8ddda6d9252a7981d0be"
+    },
+    "libraries/OpenSysMLRenderings.sysml": {
+      "algorithm": "SHA256",
+      "value": "1dc65b8af7d997047557b3297b8ac1b7e095ef992084e108f35e220a67518825"
+    },
+    "libraries/RandomFunctions.kerml": {
+      "algorithm": "SHA256",
+      "value": "50793e1e940b377777a931d102f86770b02576b019e6bfb7b8c33384cd78fbc7"
+    },
+    "libraries/Simulation.sysml": {
+      "algorithm": "SHA256",
+      "value": "2d755bca5e71702953e342ac75e567380cd8210600a895b6c5f741230e0aa951"
+    },
+    "libraries/StateActivity.kerml": {
+      "algorithm": "SHA256",
+      "value": "84b7e3d4f4ea1a9efbb1d1d343c42f7afb32cc1cc580b68e7ec9bed16c328460"
+    },
+    "libraries/StateMachines.sysml": {
+      "algorithm": "SHA256",
+      "value": "5421ef73696d9ee1d115323cf80a7c2f712a2f1d9e4aebd866e5c2613a3e2e86"
+    },
+    "libraries/StateSpaceIntegration.sysml": {
+      "algorithm": "SHA256",
+      "value": "c324cef90d06cbfef168cb0b05a6bafbff2dd9e729b3e4fc49b16e49b0dfcb50"
+    },
+    "libraries/Stochastic.sysml": {
+      "algorithm": "SHA256",
+      "value": "ed8b80b41f51012b2030be960afc1c97698370ff5263c5d28dc4063d37a46e88"
+    },
+    "libraries/SysMLValidation.sysml": {
+      "algorithm": "SHA256",
+      "value": "9e00f049209584092dc8bcb398b736c08e6a39b1db667a8a744de3df72a543bf"
+    }
+  },
+  "created": "2026-10-25T17:57:00Z",
+  "index": {
+    "AnalysisRecords": "libraries/AnalysisRecords.sysml",
+    "DiagramLayout": "libraries/DiagramLayout.sysml",
+    "DocumentQueries": "libraries/DocumentQueries.sysml",
+    "IdentityMetadata": "libraries/IdentityMetadata.sysml",
+    "MOSA": "libraries/MOSA.sysml",
+    "MigrationMetadata": "libraries/MigrationMetadata.sysml",
+    "OOSEM": "libraries/OOSEM.sysml",
+    "OpenSysMLMathFunctions": "libraries/OpenSysMLMathFunctions.kerml",
+    "OpenSysMLRenderings": "libraries/OpenSysMLRenderings.sysml",
+    "RandomFunctions": "libraries/RandomFunctions.kerml",
+    "Simulation": "libraries/Simulation.sysml",
+    "StateActivity": "libraries/StateActivity.kerml",
+    "StateMachines": "libraries/StateMachines.sysml",
+    "StateSpaceIntegration": "libraries/StateSpaceIntegration.sysml",
+    "Stochastic": "libraries/Stochastic.sysml",
+    "SysMLValidation": "libraries/SysMLValidation.sysml"
+  },
+  "metamodel": "https://www.omg.org/spec/SysML/20250201"
+}

.project.json

@@ -0,0 +1,19 @@
+{
+  "name": "OpenSysML Extensions Library",
+  "publisher": "Open-MBEE",
+  "description": "Community non-normative SysML v2 and KerML extension libraries: diagram layout, identity and migration metadata, MOSA and OOSEM vocabularies, document queries, renderings, simulation, state machines, stochastic and state-space extensions, math and random functions, and validation constraints.",
+  "version": "1.0.0",
+  "license": "Apache-2.0",
+  "website": "https://github.com/Open-MBEE/OpenSysML-Extensions-Library",
+  "usage": [
+    {"resource": "https://www.omg.org/spec/KerML/20250201/Data-Type-Library.kpar"},
+    {"resource": "https://www.omg.org/spec/KerML/20250201/Function-Library.kpar"},
+    {"resource": "https://www.omg.org/spec/KerML/20250201/Semantic-Library.kpar"},
+    {"resource": "https://www.omg.org/spec/SysML/20250201/Analysis-Domain-Library.kpar"},
+    {"resource": "https://www.omg.org/spec/SysML/20250201/Cause-and-Effect-Domain-Library.kpar"},
+    {"resource": "https://www.omg.org/spec/SysML/20250201/Metadata-Domain-Library.kpar"},
+    {"resource": "https://www.omg.org/spec/SysML/20250201/Quantities-and-Units-Domain-Library.kpar"},
+    {"resource": "https://www.omg.org/spec/SysML/20250201/Requirement-Derivation-Domain-Library.kpar"},
+    {"resource": "https://www.omg.org/spec/SysML/20250201/Systems-Library.kpar"}
+  ]
+}

CONTRIBUTING.md

@@ -34,6 +34,12 @@ with a filter) expresses the same diagram.
 - 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/`.
+- Run `./scripts/write-project-meta.py` after changing anything under
+  `libraries/` or `LICENSE` and commit the regenerated `.meta.json`; CI runs
+  it with `--check` and fails when a checksum, the root-namespace index or
+  `.project.json`'s fields and `usage` list drift from the tree. The `usage`
+  list is derived from the imports and qualified references in the units, so
+  a new dependency on an OMG standard-library archive is added there.
 - State the semver impact of your change in the pull request (see Versioning
   in the README).
 
@@ -52,6 +58,15 @@ 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.
 
+## Releasing
+
+1. Open a release-prep pull request that sets `version` in `.project.json` to
+   the version the tag will carry (semver per the README); `.meta.json` does
+   not change. CI checks the field.
+2. After it merges, a maintainer tags that commit `vX.Y.Z`. `release.yml`
+   fails when the tag does not equal the committed `version`, otherwise builds
+   the `.kpar` from the manifests and attaches it to the GitHub release.
+
 ## Bumping the pilot pin
 
 Edit `scripts/pilot-pin.sh` (`PILOT_TAG` and `PILOT_COMMIT` together) and

README.md

@@ -39,6 +39,15 @@ behavior needs an engine.
 
 ## Layout
 
+The repository is a KerML 10.3 project interchange: `.project.json` at the
+root names the project (`OpenSysML Extensions Library`, publisher `Open-MBEE`,
+its `version`, and the OMG standard-library archives the units use) and
+`.meta.json` indexes the root namespace each unit declares with a SHA-256
+checksum per file, both in the OMG format any SysML v2 tool reads. A tagged
+commit of the tree *is* the project; the release `.kpar` is the same files
+archived. `./scripts/write-project-meta.py --check` fails in CI when either
+manifest drifts from the tree.
+
 `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,
@@ -48,6 +57,34 @@ messages point at that repository.
 
 ## Using the libraries
 
+### As a package
+
+A project depends on this library by naming the repository and a tag in its
+own `.project.json` (KerML 1.0 §10.3, Table 12):
+
+```json
+{
+  "name": "MyModel",
+  "version": "0.1.0",
+  "usage": [
+    {"resource": "pkg:git/github.com/Open-MBEE/OpenSysML-Extensions-Library", "versionConstraint": "1.0.0"}
+  ]
+}
+```
+
+The IRI is `pkg:git/<host>/<path>`, optionally `@<version>`; a plain clone
+URL with `@<version>` is accepted by package managers and normalised to it. A
+package manager installs the repository tree at tag `v1.0.0` (or the release's
+`.kpar`, which holds the same files) into the project's library directory,
+`lib/` beside `.project.json`, and the tool resolves `import DiagramLayout::*`
+from there; the tool itself never fetches. The `usage` entries of this library's own
+`.project.json` name the OMG archives
+(`https://www.omg.org/spec/KerML/20250201/<Library>.kpar`,
+`https://www.omg.org/spec/SysML/20250201/<Library>.kpar`) its units import,
+so a manager installs the standard library the same way.
+
+### Per tool
+
 Every tool also needs the OMG standard library (`sysml.library`).
 
 - **OMG pilot batch validator** —
@@ -68,10 +105,11 @@ Every tool also needs the OMG standard library (`sysml.library`).
   `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. A newer
-  revision than the bundled one is read as a project interchange archive:
-  name the release `.kpar` beside the model
-  (`sysml -validate model.sysml opensysml-extension-libraries.kpar`) or put it
-  under a `-library-root` directory.
+  revision than the bundled one is read as a project: name the release `.kpar`
+  beside the model (`sysml -validate model.sysml opensysml-extensions-library-1.0.0.kpar`),
+  or install the tag's tree or the `.kpar` under `lib/` beside the model's
+  `.project.json`, which names it as
+  `pkg:git/github.com/Open-MBEE/OpenSysML-Extensions-Library` (`sysml -validate <project>`).
 
 ## Versioning
 
@@ -83,8 +121,17 @@ Releases are semver tags `vX.Y.Z` on `main`:
 - **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.
+The tag equals `.project.json`'s `version`: a release-prep commit bumps the
+`version` field (and nothing else need change — `.meta.json` carries no
+version), then the maintainer tags `vX.Y.Z` on that commit. The release
+workflow refuses a tag that does not equal the committed `version`, re-checks
+the manifests against the tree, builds
+`opensysml-extensions-library-X.Y.Z.kpar` with `./scripts/build-kpar.py
+--version X.Y.Z` and attaches it to the GitHub release. The archive is derived
+from the tag's tree and its two manifests, so the tree a package manager
+installs from GitHub and the `.kpar` are one project; the build is
+byte-deterministic (sorted entries, deflate, 1980-01-01 dates). Consumers pin
+a tag through `versionConstraint`.
 
 ## Engine contract