feat(python): generated metaclass classes and a standalone metamodel JSON reader

[devin-ai-integration]

Depends on #865 and must merge after it. This branch is stacked on feature/ontology-pilot-metamodel (the regenerated 20250201 metamodel table); until #865 merges, the diff against develop includes its commits. If #865 merges first, this branch is rebased onto develop. develop is merged in to keep the branch mergeable.

What and why

Adds a read-only Python view of the SysML/KerML metamodel, separate from opensysml.generate (which builds classes for a user's model definitions):

• tools/gen/pymetamodel generates client/python/opensysml/metamodel/_generated.py from the ontology table: one class per metaclass (175) with the spec parents as real Python bases (C3 checked in the generator), each of the 415 properties declared once on its defining class with its JSON key, range, many/ordered and derived flags, the 7 enumerations as str enums, REGISTRY, and a header naming the metamodel version and pilot commit. make python-metamodel-check (-check) runs in CircleCI and GitHub Actions next to the ontology table check.
• Naming follows the naming report: snake_case primary with the camelCase spelling bound to the same descriptor (no __getattr__), is_ kept on booleans, trailing _ only for hard keywords, tuple[T, ...] for multi-valued reads, builtins.type[...] in annotations, per-class JSON_KEYS with from_json_key/json_key, and a closed RUNTIME_MEMBERS set (METACLASS, JSON_KEYS, from_json_key, json_key, json_id, json_type, json_value, graph, metaclass_name). The generator fails if a spec name meets a runtime member or a name the class bodies reference, if two related classes declare one name, or if C3 fails.
• opensysml.metamodel.read_json (and opensysml.read_json) reads a file path, bytes, a mapping or a list of element mappings: the API element form (array or single object, @id/@type, {"@id"} references), DataVersion (identity/payload) and Commit (change) envelopes, sysml-toolkit full/compact JSON, and sysml:/SysML-IRI-prefixed types. It indexes by @id and wraps and resolves lazily. graph.all(PartUsage), graph[id] and graph.roots() are provided. An unknown @type falls back to the nearest known ancestor via an optional supertypes mapping, else Element, and keeps the written type in json_type. An absent key raises NotSupplied (never []/None; only explicit null/[] mean empty); a dangling @id or an @ref raises UnresolvedReference on access; wrong shapes, non-finite reals and a reference to an element outside the property's range raise MalformedValue/MalformedDocument; read_json(..., check_ranges=False) skips the range check and returns such targets as written. A standalone DataVersion envelope is unwrapped like an array entry, and roots() excludes namespaces with an owningRelationship, owner or owningNamespace. No notation conversion, no service contact, no write-back.
• Ontology table: records the metamodel's enumerations and literals. The reader relies on feat(ontology): generate the metamodel table from the pilot's SysML.ecore (20250201) #865's Many fix for the two features whose ecore upper bound is 2 (MultiplicityRange::bound, Flow::flowEnd), because the toolkit writes bound as an array.
• Docs: a new task page, docs/clients/python/metamodel.md ("Metamodel classes and JSON", in the nav after Typed classes), with the scope-note example, how it differs from opensysml.generate, naming, inputs, and what OpenSysML's api-json export does and does not carry; a matching section in the Python API reference; pointers from the typed-classes page and the clients guide.

Operations are left out. Follow-ups: metamodel operations (e.g. Namespace::resolve, Type::inheritedMemberships), engine-served derived properties, loading JSON into the engine.

Apollo 11 measurements

All 28 .sysml files of airbus/apollo-11-sysml-v2; Python 3.12, read_json(path), median of 3 fresh processes; memory is process RSS.

Source	Elements	Size	read_json	RSS after read (Δ over import)	Peak RSS
OpenSysML sysml -convert api-json	30,894	41.1 MB	0.30 s	166 MB (+127 MB)	265 MB
sysml-toolkit 0.10.0 --to full-json --lib <pilot sysml.library>	39,173	92.6 MB	0.96 s	405 MB (+365 MB)	574 MB

Reading every effective property of every element once (wrapping all elements: 0.14 s / 0.16 s):

Source	Property reads	NotSupplied	of derived reads	of owned reads	UnresolvedReference	MalformedValue
OpenSysML api-json	1,699,332	83.98 %	87.99 %	74.98 %	1,478	58
toolkit full-json	1,867,547	0.03 % (512, all operand)	0.04 %	0.00 %	47,722	1,333

MalformedValue counts references whose target is outside the property's range, read from the files as written. api-json: 57 ConstructorExpression::function pointing to an AttributeDefinition and 1 InvocationExpression::function pointing to a CalculationUsage; neither target is a Function. toolkit full-json: 369 membershipOwningNamespace and 369 owningNamespace pointing to a Dependency, which is not a Namespace; 296 RequirementDefinition::result and 296 subjectParameter, plus 3 AnalysisCaseDefinition::result, pointing to the definition itself rather than to a Feature. With check_ranges=False both sources read with 0 MalformedValue and the other columns unchanged.

The api-json export carries owned properties plus some derived ones (ownedFeature, owner, qualifiedName, …) but not feature, inheritedFeature or definition, and type on 1,813 of 3,789 usages. It also writes no null and no [] (0 of either on Apollo), so unset owned properties (an unnamed element's declaredName, aliasIds, documentation, ownedElement, …) are absent too — that is most of the 75 % owned-read rate. Unresolved references in both sources point at standard-library elements the document does not include.

Specification basis

SysML v2 / KerML metamodel 20250201 as published in the pilot implementation's SysML.ecore (tag 2026-08, commit 692170b7). The Many fix follows the ecore upperBound (any value other than 1 is multi-valued). No behaviour row in docs/project/spec-compliance.md moves.

How it was verified

• go build ./..., go vet ./..., gofmt -l . (empty), go test ./...; go test -C tools ./gen/ontology ./gen/pymetamodel (drift, and each generator failure rule on synthetic tables); make ontology-table-check python-metamodel-check; RDF corpus round trip with the corpora required.
• tests/test_metamodel.py: alias identity for every class and key, each descriptor declared once, RUNTIME_MEMBERS equals the base's public names and is disjoint from every spec key and snake name, json_key(from_json_key(k)) == k everywhere, metadata spot checks.
• tests/test_metamodel_typing.py: mypy --strict and pyright strict over a usage file (with negative lines that must error) and the package; CI installs pinned mypy/pyright and sets OPENSYSML_REQUIRE_TYPECHECKERS=1.
• tests/test_metamodel_reader.py / test_metamodel_toolkit.py: an api-json export made by the service in the test, a checked-in toolkit full-json fixture (sysml-sdk's Apache-2.0 bigger.sysml, converted with sysml-toolkit 0.10.0, credited in its README), and hand-built documents covering envelopes, unknown types, dangling references, NotSupplied, explicit empties and malformed input.
• make docs-check, python3 scripts/changelog.py check; wheel listing includes the metamodel package and py.typed.

Checklist

• make test and make lint pass locally
• 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 (compliance rows need nothing: the census is counted at docs build)
• 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/49a79b80527e41829b7d7050fa1043b3
Open in Devin Desktop: https://nasa-jpl-demo.devinenterprise.com/desktop/session/49a79b80527e41829b7d7050fa1043b3?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