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

[devin-ai-integration]

What and why

The non-normative OpenSysML Libraries/ extensions are now maintained at Open-MBEE/OpenSysML-Extensions-Library, so other SysML v2 tools can consume them. That repository imported them with their history in Open-MBEE/OpenSysML-Extensions-Library#1. OpenSysML keeps a vendored copy at the same path: go install and the module proxy must build without fetching another repository, and the embed, element identity and stdlib.snapshot stay as they are. This PR does not change any .sysml or .kerml byte, so the snapshot is not regenerated.

• Pin: scripts/extension-libraries-pin.sh holds EXTENSIONS_REPO, EXTENSIONS_REF and EXTENSIONS_COMMIT, currently main at 4213d77dc89ad89e79591e425536d6ef9e9dab89.

• Sync: scripts/sync-extension-libraries.sh fetches the pinned commit (--depth 1), verifies its sha and rewrites the directory from upstream libraries/*.{sysml,kerml} plus engine-contract.json.

  • --ref REF syncs a branch or tag instead of the pin; --source DIR syncs a local checkout.
  • It refuses an upstream with no libraries or no engine-contract.json, before writing anything. Any file in the directory that is neither upstream nor README.md is an error.

• Drift check: make extension-libraries-check runs the sync with --check. It runs in pr.yml's changes job, so the changed-areas filter can't skip it. CircleCI gates only main/develop merges, not PRs, so it needs no change. make extension-libraries-sync re-vendors.

• Engine contract: engine-contract.json comes from upstream and lists the 125 qualified names the engine binds, each with a kind:

  • function, with parameters in order;
  • metadata, with the features the engine reads;
  • document, element or package;
  • a migratorEmitted flag on names the SysML v1 migrator writes into user models.

  Two tests keep the manifest and the engine in step:

  • internal/exec/runtime/engine_contract_test.go: every registry function in an extension package is a manifest function entry with identical parameters, and every manifest function in a package the registry implements is registered.
  • tests/hygiene/engine_contract_test.go: parses all non-test Go under internal/, cmd/ and tools/ and constant-folds string literals, + concatenations and package-level string consts. Every extension-qualified name it finds must be in the manifest. A manifest entry no code derives is stale, unless its package composes names under a Pkg:: prefix (DiagramLayout, DocumentQueries and StateMachines), which the derivation can't enumerate.

  Upstream CI resolves every entry against the libraries with the pinned OMG pilot. It fails a PR that removes or renames an entry or changes its parameters unless contract is bumped, which means a MAJOR release and a re-pin here.

• Advisory upstream tracking: .github/workflows/extension-libraries-upstream.yml runs nightly and on workflow_dispatch (with an input ref, default main).

  • It syncs upstream main, not the pin, checks or regenerates the snapshot, and runs go test ./... and go test -C tools ./....
  • The step summary records the synced sha, and on failure which step failed.
  • It is not a required check, never pushes, and never opens issues.

• Docs:

  • README.md in the vendored directory: edits go upstream.
  • New page docs/project/extension-libraries.md covering pin, sync, drift check, contract and the nightly.
  • Pointers to the upstream repository in the root README and the guide, manual and project pages that describe the libraries.
  • Changelog fragment.

Merge order

Open-MBEE/OpenSysML-Extensions-Library#1 has merged, and the pin points at its merge commit on main, so this PR has no remaining upstream dependency.

How it was verified

• go build ./..., go vet ./..., gofmt -l . (empty) and go test ./... pass, as do make docs-check, python3 scripts/changelog.py check, make extension-libraries-check and make stdlib-snapshot-check.
• Each guardrail fails when it should (scratch edits, reverted):
  • Adding a non-test string "Simulation::Bogus" fails the hygiene test.
  • Deleting a vendored manifest entry fails the hygiene test and the drift check.
  • Renaming a registry parameter (log's base → b) fails the runtime test: registry [x b] != manifest [x base].
• The upstream workflow's command sequence ran locally with --ref main: the sync was clean and the snapshot unchanged.
• An upstream tree without engine-contract.json is refused and leaves the vendored directory untouched.

Checklist

• make test and make lint pass locally (go test ./... + go vet/gofmt gates)
• Tests added or updated for the change
• Documentation extended where it already covers the surface (see CONTRIBUTING.md)
• Changelog entry added as changes/unreleased/<slug>.<section>.md, not as an edit to CHANGELOG.md
• baselines regenerated and make docs-counts run if a gate count moved (no gate count moved)
• No internal work-item labels (waves, slices, F4, K5) in the body, docs, or changelog

Link to Devin session: https://nasa-jpl-demo.devinenterprise.com/sessions/bf0cf4d7769a49a8adfee6bfd87860f3
Open in Devin Desktop: https://nasa-jpl-demo.devinenterprise.com/desktop/session/bf0cf4d7769a49a8adfee6bfd87860f3?variant=devin
Requested by: @HuiJun

[devin-ai-integration]

I'll fix CI failures and address comments from users with write access. I'll skip comments containing "(aside)".

• Disable automatic comment, CI, and merge conflict monitoring