[devin-ai-integration]

What and why

The API JSON differential's pilot bridge (scripts/pilot-json-exporter/ExportJSON.java) read only the pinned sysml.library, so a member whose naming feature, type or redefined feature lives in this repository's own libraries (internal/workspace/libs/stdlib/OpenSysML Libraries/: DocumentQueries, AnalysisRecords, OpenSysMLRenderings, MOSA, OOSEM, …) stayed unnamed on the pilot's side and never really compared with ours. The bridge now takes --extension-library <dir> (repeatable, the same option and loading order as the two validator bridges: .kerml then .sysml, read as library resources after the standard library, which stays first and is still the launcher's default). The referee passes the directory explicitly — the one the pilot differential already hands its validators, diff.LibrariesHandedOver (the libraries inside the standard-library root OpenSysML itself loads, so both sides resolve the same text) — and the baseline records it as the opensysml-libraries input, so a run is reproducible from its command line and an edit under the libraries is a provenance mismatch.

• tools/referee/apijson: pilotArgs spells the bridge's command line; provenance records the libraries input; the committed baseline is re-recorded.
• tools/referee/diff: exports LibrariesHandedOver, LibrariesInput, RelativeTo for the sibling referee.
• docs/project/api-json-differential.md: bridge description, refreshed figures, the referee-limitation section replaced by the measured movement and its three disagreement shapes, launch-ready gap rows 41–43.

Specification basis

No behaviour of the implementation changes; the bridge and the referee do. The adjudication below cites KerML 1.1 Beta 2 (doc/1-Kernel_Modeling_Language.pdf) for each disagreement the newly resolved comparisons expose; no row of docs/project/spec-compliance.md moves.

How it was verified

Movement (-lost-against the run before the change, all roots, fresh XDG_CACHE_HOME)

root	matched before → after	lost	gained	gained, ours-only before	gained, absent before	largest gained metaclasses
examples/sysml-v2-training	7287 → 7287	0	0	0	0	—
examples/pilot-corpora/sysml-examples	25778 → 25778	0	0	0	0	—
examples/pilot-corpora/sysml-validation	9246 → 9246	0	0	0	0	—
examples/pilot-corpora/kerml-examples	6387 → 6387	0	0	0	0	—
examples/spec-examples	6980 → 6980	0	0	0	0	—
tests/testdata	1201 → 1201	0	0	0	0	— (2 properties move to present-equal)
examples	23379 → 26005	0	2626	914	1712	FeatureValue 300, OwningMembership 298, FeatureTyping 266, Redefinition 240, LiteralString 203
tools/referee/diff/testdata	53 → 53	0	0	0	0	—
docs/manual/examples	6663 → 7020	0	357	357	0	FeatureValue 87, Redefinition 87, AttributeUsage 84, LiteralString 84, Feature 3

"ours-only before" is a key the pilot keyed structurally (…/AttributeUsage[0]) because it could not name the member; "absent before" is a key of examples/mosa-demo/mosa-demo.sysml or examples/oosem-demo/oosem-demo.sysml, which the pilot could not export at all. Totals: 86974 → 89957 matched (+2983), ours-only 29497 → 28511, pilot-only 40387 → 38863; properties present-equal +22010, present-different +2394, ours-missing +36881, pilot-missing +2574 (the new matches bring their whole property sets into the comparison; the ours-missing growth is the existing gap rows measured on more elements). pilotLibraryElements 5236 → 30926 (the pilot writes our library elements as library elements; the referee leaves them out as it does the standard library's).

Adjudication of what the newly resolved comparisons show

Every property of the 2983 gained elements that is not present-equal/absent-both was listed per element and bucketed. Newly present-equal: the names, qualified names, owners, memberships, the redefining side of the redefinitions, values and literals of the gained members (+22010). Newly ours-missing (+36881) and pilot-missing (+2574) are only the existing rows (isLibraryElement, memberElementId, owningType, … on our side; Relationship::owner null and value/redefines outside the metamodel's spelling on the pilot's) on more elements. Newly present-different (+2394) reduce to three shapes, all pre-existing on the scorecard and none a derivation we get wrong; the two whole files add every shape the scorecard already carries for user models (quoted qualifiedName segments with spaces, structural ordinals of unnamed members, connector-end naming).

shape	rows	counts (manual-examples + examples)	spec	verdict
A reference into this repository's libraries spelled as a name, {"@ref": "caption"}, where the pilot writes the element	Redefinition.redefinedFeature/general/target/subsettedFeature/relatedElement; FeatureTyping.type/…; MetadataUsage.type; ViewUsage.type; FeatureReferenceExpression.referent + its Membership.memberElement; ReferenceSubsetting.referencedFeature on the two render members	87 + 240 redefinitions; 0 + 157 typings (MOSA/OOSEM metadata and view definitions); 0 + 123 metadata usages; 0 + 16 views; 0 + 28 enumeration-literal referents; 0 + 2 renderings	Redefinition::redefinedFeature : Feature (KerML 8.3.3.3.8), FeatureTyping::type (8.3.3.3.7), Element::elementId (8.3.2.1.2) — the API's JSON refers to an element by its id	Pilot right. Cause: internal/translate/export/rdf_identity.go libraryElement gives a library symbol an IRI only when identity.Of(...).Source == SourceNormative (the pilot's standard-library XMI); our libraries have no norm, so api_json_out.go falls back to {"@ref": name} and libraryNames states none of their elements. Not small (identity for a second library tier, writer and readers) → gap row 41.
Order of ownedRelationship on a usage that both redefines and has a value: pilot [Redefinition, FeatureValue], ours [FeatureValue, Redefinition]	AttributeUsage.ownedRelationship, ReferenceUsage.ownedRelationship, RenderingUsage.ownedRelationship	84 + 191; 3 + 94; 0 + 2	Element::ownedRelationship : Relationship [0..*] {ordered} (KerML 8.3.2.1.2); the notation adds owned relationships as parsed, redefines x before = …	The pilot's order is the notation's. Pre-existing shape (2047 on the row before). Writer ordering across every usage with a value → gap row 42.
The pilot's FeatureReferenceExpression owns a Membership of its referent that ours does not write	FeatureReferenceExpression.ownedMembership/ownedRelationship	3 + 71	deriveFeatureReferenceExpressionReferent: referent = memberElement of the first non-ParameterMembership ownedMembership (KerML 8.3.4.8.5)	Pilot right; the Membership is part of the abstract syntax. Pre-existing (2031 before) → gap row 43.

No disagreement about naming: every gained member is named identically on both sides (that is what made it match), including #majorSystemComponent-style prefixes (<majorSystemComponent> MajorSystemComponentMetadata), which both sides resolve to the definition — ours merely spells the typing target by the short name as written (shape 1).

Pilot diagnostics on the OpenSysML Libraries

None. The bridge exports every root with the sixteen library files loaded and reports no error on them; the pilot's batch validator (validate-sysml-batch, one resource set, both languages) over the same directory exits 0 with no diagnostic (a control model with an unresolved type produces two errors and exit 1 through the same launcher). Two files the pilot previously could not export at all (examples/mosa-demo/mosa-demo.sysml, examples/oosem-demo/oosem-demo.sysml: "eResource() is null" on an element of an unloaded MOSA/OOSEM library) now export; pilotFailed 58 → 56.

Reproducibility

Second fresh-cache run with -check: -check exits 0, and the second run's pilot-apijson-diff.json is byte-identical (cmp) to the committed baseline and to the first run's.

In-flight work and overlaps

• feat(export): own the referent Membership of a FeatureReferenceExpression where the notation places it #1331 (feat/feature-reference-membership) merged this branch and feat(identity): fix ids for OpenSysML's own library elements so references link by id #1332 into itself, re-recorded the baseline over the combined tree and has landed on develop (3e04a2950), so everything here is already on develop: after the last merge of develop this branch's tree is identical to develop's (empty diff), and the baseline is develop's own re-record.
• feat(identity): fix ids for OpenSysML's own library elements so references link by id #1332 (feat/extension-library-identity, fixed ids for this repository's own library elements so references into them link by id) was based on this branch and has been merged into it (8d2e3ffc7); its record and baseline (90023 matched, present-different 45688, gap row 41 closed for those libraries) are part of this PR now.
• develop at 5db0f7415 (the restated verbatim writer and the performance work) is merged in as a merge commit and the baseline re-recorded over the merged tree with a fresh cache: against the baseline feat(identity): fix ids for OpenSysML's own library elements so references link by id #1332 recorded, only develop's own drift moves — the api-json-writer source digest, one examples/spec-examples type mismatch (1742 → 1743) and three sysx: extension properties (146858 → 146861), the same movement develop's own re-record shows; 0 matches lost, no scorecard row moves. A second fresh -check reproduces it byte for byte.
• feat(tools): record the API JSON writer's source digest in the differential baseline #1325 has landed on develop (2de4131af), which is merged in last as a no-op merge commit (the tree is unchanged; the merge only gives the branch a single merge base with develop). This PR's own changes are its bridge, referee, baseline, record and changelog commits plus the provenance.go merge resolution.
• feat(referee): list the api-json matches a run lost and gained, and record why naming-feature keys cost manual-examples 171 #1323 (fix/api-json-naming-feature-keys), whose -lost-against diagnostic and referee-limitation paragraph this PR uses and replaces, was merged in first and has since landed on develop; the PR now targets develop.
• feat(tools): record the API JSON writer's source digest in the differential baseline #1325 (feat/api-json-writer-provenance; at 3ea1ef04b, a59c9506d, 0fc1a0873, which hands the referee its build checkout, and finally e5f3a4c8a) and develop (c5a59e138 with feat(vscode): zoom, pan and fit, selection highlighting, relationship filters and auto layout in the diagram panel #1318, then f9f6d953f with feat(referee): list the api-json matches a run lost and gained, and record why naming-feature keys cost manual-examples 171 #1323, then 2de4131af with feat(tools): record the API JSON writer's source digest in the differential baseline #1325) are merged in as merge commits; provenance.go was resolved so provenance(checkout, built, libraries) records the api-json-writer digest from the build checkout and the opensysml-libraries input together. The baseline was re-recorded over the merged tree with a fresh cache: 0 matches lost, 0 gained against the previous run, every count and scorecard row identical — only the tools list (two entries) and the recording date moved; a second fresh -check reproduces it.
• fix(tools): re-record the API JSON differential baseline after the errata overlay change #1321/docs(project): re-record the API JSON differential baseline over current develop #1322 (docs-only re-records) are superseded by feat(corpus): gate the specification's own textual-notation examples #1302; feat(export): owned absence and evaluator-derived properties in API JSON #1232 (writer changes) is untouched.
• Recent sessions and PR-less remote branches touching the bridge or the referee: none beyond the sessions behind feat(tools): derived-property differential of API JSON against the pilot's export #1306, fix(tools): re-record the API JSON differential baseline after the errata overlay change #1321, feat(referee): list the api-json matches a run lost and gained, and record why naming-feature keys cost manual-examples 171 #1323 and feat(tools): record the API JSON writer's source digest in the differential baseline #1325.

Gate

go build ./..., go vet ./..., gofmt -l . (empty), go test -C tools ./..., make lint, make docs-counts, python3 scripts/changelog.py check all pass. go test ./... passes; two budget-bound packages (cmd/sysml, tests/codegen) hit the 10-minute default timeout while make lint ran alongside the suite and pass when re-run alone (302 s and 338 s). The referee's own tests (tools/referee/apijson, tools/referee/diff, tools/oracle/baseline) pass, including the new pilotArgs and libraries-provenance tests; the pilot JSON exporter was rebuilt with ./scripts/download-pilot-json-exporter.sh and both differential runs went through it.

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/5b0ba95a3c33450b84f2c55eaafa4771
Open in Devin Desktop: https://nasa-jpl-demo.devinenterprise.com/desktop/session/5b0ba95a3c33450b84f2c55eaafa4771?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

[devin-ai-integration]

Devin Review found 1 potential issue.

2 flags not posted on this PR by your GitHub settings — view them in Devin Review. (Configure)