feat(migrate): translate opaque JavaScript/English bodies, guards, swimlane names and clock reads to executable v2

[devin-ai-integration]

What and why

The v1 → v2 migrator wrote activities and state machines in executable v2 but kept every OpaqueAction, OpaqueExpression, OpaqueBehavior and guard body a Cameo author had written in JavaScript or "English" as a comment, unless it already happened to parse as v2 with visible names. That left retry loops unguarded and clock bookkeeping dead. This PR translates a bounded subset of those languages into executable v2, resolves the names they use through the swimlane (ActivityPartition.represents) they sit in, gives simtime an executable form, and cleans up the report for the constructs this exposes.

Opaque-language subset (internal/translate/migrate/opaque.go, new): a lexer/parser/translator for JavaScript / ECMAScript / Java / empty-language bodies and English guards. A script label is read only when every word of it is JavaScript, ECMAScript, JS, Rhino or Nashorn plus at most one version (Javascript Rhino, JavaScript (Nashorn) 1.8, ECMAScript 2015); a Java label is Java plus at most one version; any other word (JavaScript Expression Language, ECMAScript for XML, JavaCC, JSON) is a language the translator does not read.

• Statements: x = e, x += e (-=, *=, /=), sequences separated by ;/newlines, var/let/const x = e for a declared local (a const is never assigned again, nor is an in parameter).
• Expressions: integer/real/boolean/string literals, identifiers and dotted members, + - * / % (a Java / on two whole operands is OpenSysMLMathFunctions::quotient(x, y), the exact quotient truncated toward zero; refused when the types cannot tell), comparisons, && || !, parentheses, trivially mappable ?:, Math.min/max/abs/floor/ceil/round/sqrt/pow → RealFunctions::… (Math.min/max variadic in JavaScript, folded pairwise — one argument is itself, none is refused as an infinity — and exactly two arguments in Java; Math.round(x) as floor(x + 0.5), JavaScript's half-up; Math.ceil(x) as OpenSysMLMathFunctions::ceiling(x), exact at the least Integer where -floor(-x) overflows), string escapes decoded as JavaScript reads them (legacy octal escapes and characters the notation cannot spell are refused), java.util.Collections.max/min(s) → max/min on a collection. A Java body's a.equals(b) on strings is a == b (the comparison of content), and its ==/!= with a string operand is refused, since Java compares strings there by identity; JavaScript string == is a value comparison and translates as it stands.
• English: TRUE/FALSE/true/false, a property name — spaces and all: a run of words between operators is one name (not Guide Star Lost and i < Retries), refused whole when nothing visible is called that — not X, X and Y, X or Y, comparisons written with =/==, parentheses. English has no calls: Math.sqrt(t) > 3 or name.equals(other) is a construct refusal, never dispatched to the script function table.
• Everything else is a typed refusal carrying the offending token (refusedLanguage/Syntax/Construct/Call/Name/Type/Context): loops, calls outside the table, new, string methods, regexes, non-simple declarations, this. in unknown context, type-incompatible operands. A refusal of a recognized language is final — the body is never re-read as v2 syntax. A translation is emitted only when every name resolves, the types agree where known, and the result parses with the v2 parser.

Swimlane context (swimlane.go, new): partitions are indexed through node and inPartition; represents is resolved as a property (this.tcs, nested this.a.b) or classifier (this). Names in a body or guard resolve against the represented object first, then the activity's parameters/locals, then the owning block. Unset, dangling, absent, untyped and unwritable representations and nodes outside any partition each get a defined behavior and a note; a partition is reported mapped only when a name was actually resolved through it. A partition representing a collection (cells : Gauge[2]), or a dotted name through a multi-valued feature, is a collection from that step on: arithmetic on it, a scalar assigned from it and a write through it are refused naming the carrier, and a call in such a lane runs in the caller's context with the report saying why; only java.util.Collections.max/min reductions accept it.

Clock (translate.go, internal/exec/runtime/clock_read.go): the SimulationConfig.timeVariableName (default simtime) is read as localClock.currentTime; the runtime evaluates currentTime on the standard Clocks::Clock against the shared runtime.Clock, so -observe this.Time_Acq_Total and %runs report the migrated attribute. Assigning currentTime is refused with ErrClockNotAssignable; a redefinition of it (attribute now :>> currentTime;) is recognised by the redefinition chain, not the name, so it reads the clock and refuses the write alike, bare or through a part. A calc def result expression is checked against the single return/output parameter's type; a behavior with several outputs is refused as a result expression. A DurationObservation whose two events are nodes of the activity (an initial node counts as a start, stamped right after start, before the activity's wait) becomes a pair of [0..1] attributes with no default, the start instant and the elapsed clock, assigned only when a run reaches each event, so an unreached observation is blank in %runs/-observe rather than 0.0 (observation.go, new); every other shape — including a flag asking for the end of an initial, final or control node — says why it is not.

Where it lands: opaque/value/structural-feature actions → assign statements (multi-statement bodies as a sequence); guards → if on the succession; OpaqueExpression defaults → attribute defaults; JavaScript constraints → constraint def expressions over the ConstraintBlock's parameters; JavaScript OpaqueBehaviors → calc def / action bodies. Symbolic durations (ditSetup s) resolve through the same lookup.

Report hygiene: a CallBehaviorAction with no behavior, no pins and only a DurationConstraint is a leaf step and is mapped ("a step with a duration and no further behavior"); calls with pins or an unresolved behavior stay unmapped with a pin-oriented reason. A UML region with no vertex is not written (nothing could enter it, and the runtime correctly refuses a region with no initial state) and is reported approximated — this is the change to states.go, kept to the seven lines in regions() with the helper in region.go.

XMI: stereotypes whose profile schema namespace ends in .xmi (SimulationProfile.xmi) were mistaken for XMI bookkeeping and dropped. The shared reader on develop now recognizes only the metamodel namespaces (IsXMINamespace/IsUMLNamespace); this PR pins that with TestStereotypeUnderSchemaNamespace in internal/core/xmi/sysmlv1. It surfaces «Refines», «TMT_Requirement», … in the report (see the Dependency row below).

Runtime: OpenSysMLMathFunctions::quotient(x, y) joins the non-normative extension library (integerQuotient: exact Integer quotient truncated toward zero, ErrDivisionByZero for y == 0, ErrArithmeticOverflow for the least Integer by -1 rather than a wrapped result; conformance calc_integer_quotient, TestRuntimeRobustnessIntegerQuotient, snapshot regenerated). perform members of an action def performed as a classifier behavior run as steps of the performance; a non-behavior named as an action fails with ErrNotABehavior (this moved two refused rows of docs/project/analysis-library-census.json).

TMT proof (TMT-2024x.mdzip)

Header (this PR's base, feature/v1-state-interaction-fidelity, → this PR, same TMT-2024x.mdzip): 28113 mapped, 10367 approximated, 5656 unmapped → 28625 mapped, 10319 approximated, 5192 unmapped (1713 skipped as profile/library/notation content and 764 unreferenced elements in both); both outputs validate with 0 errors.

Metaclass	mapped	approximated	unmapped
ActivityPartition	0 → 15	104 → 89	0
CallBehaviorAction	295 → 499	199 → 432	670 → 233
«TODO_Owner» CallBehaviorAction	2	1 → 2	2 → 1
Constraint	0 → 26	3 → 0	37 → 14
ControlFlow	2295 → 2337	100 → 58	33
«Probability» ControlFlow	31 → 33	52 → 50	0
DecisionNode	70 → 91	83 → 62	0
OpaqueAction	0 → 136	178 → 42	0
ObjectFlow	453 → 465	353 → 341	116
DurationConstraint	0	185 → 188	44 → 41
Slot	9880 → 9933	53 → 0	1100
«ValueProperty» Property	416 → 417	54 → 53	0

Every other row is identical on the base and here: ValueSpecificationAction (approximated for structural reasons, 4 now carry translated values), OpaqueBehavior (translated bodies are written as state entry/do bodies and stay approximated; toolkit calls outside the table and empty bodies keep their comments), DurationObservation (all 380 observe no event; the report says so), Region and Dependency (the vertex-less-region and XMI-namespace fixes are on the base).

Execution: bin/sysml tmt.sysml -action "'Acquire Target with IRIS and NFIRAOS - Logical' 'Acquire Target with IRIS and NFIRAOS'" -runs 100 -seed 1 -observe clock -observe this.Time_Acq_Total — on the base output all 100 runs complete but this.Time_Acq_Total stays at its 0.0 default (the Time_Acq_Total = simtime - Time_Acq_Total body is a comment); here this.Time_Acq_Total = clock in every run: min 19.4 s, mean 141.5 s, p50 116.8 s, max 455.5 s. (These differ from the figures over a develop base because the base writes the model's own «Probability» values — p = ProbabilityBTOOP, 1.0 - ProbabilityBTOOP, … — where even splits were written before.) The retry loop is exercised on the seeds whose draws reach it: -runs 1 -seed 6 -trace shows this.TCS.i := 1, guard i >= Retries (Retries -> 2) false, retry, this.TCS.i := i + 1 -> 2, guard true, exit. Lamp::'Lamp Ohm Law' (V = R * i) is written as constraint def 'Lamp Ohm Law' { in attribute V, i, R : ScalarValues::Real; V == R * i } and, with -seed 1 (the base's draw policy refuses an unseeded uniform), evaluates true for (12.0, 6.0, 2.0), false for i = 5.0, and %validate of an instantiated Lamp reports the constraint true/false the same way.

Cameo's stored snapshots for the same activity: Group 0 mean 96.6 s (6 runs, 80–119 s), Group 1 157 s, Groups 3/6 ≈ 210 s. The OpenSysML numbers differ and are not tuned: which per-group SimulationConfig applies (probabilities and durations) is selected by the simulation-configuration work this PR is stacked on.

Known limitations

• Bare min(a,b)/max(a,b) (no Math.) and other toolkit calls (ALH.*) are refused, as are UML Expression trees and bodies that are not expressions.
• A DurationObservation with no events (all 380 in TMT) cannot be timed; the referring DurationConstraint keeps its own value.
• -observe reports features of the run's performer; features of nested parts (this.TCS.i) are read through -trace or the REPL.
• OpaqueBehaviors written as state entry/do bodies stay approximated even when translated, because the state body is still an approximation of the v1 behavior call.
• A configured clock name is recognized model-wide: SimulationConfig does not say which bodies its executionTarget reaches, so any visible feature of that name shadows it, but a name configured for one activity is also recognized in another.
• Two non-nesting partitions representing different objects give a node no partition to resolve through; its names fall back to the activity and its block, and both report lines say so.
• A part whose multiplicity is not written in numbers (banks : Bank[1..n]) may hold one object or several: a name read through it, a partition representing it, and a partition whose object is reached through it are refused with the part named, never read as one object (the written v2 feature holds one value, as the base migrator writes it, so a default of that feature is checked as one value).
• Type checks between non-scalars need the migrator to know both types: a feature typed by a value type of unknown base, or by a proxy, is trusted to fit. The whole number -9223372036854775808 is refused because the magnitude is read before its sign.
• Whole-number arithmetic is the exact arithmetic of a v2 Integer: where a JavaScript Number would round a result beyond 2⁵³ or a Java int/long would wrap, the translation does not reproduce that; the modeler's Integer-typed feature keeps the exact value. Only literals are refused for range (above 2⁵³ − 1 in JavaScript, beyond int64 anywhere). Math.floor/ceil/round return the library's Integer: exact through the whole Integer range, and a whole Real at or beyond 2⁶³ or below −2⁶³ is a typed arithmetic-overflow error at run time, never a wrapped Integer.
• A two-event DurationObservation with no firstEvent flags spans both nodes whole (first's start to second's end); UML 2.5.1 gives firstEvent ([0..2]) no default. Explicit flags are honored per event.
• The branch adds no package: every new file lives in an existing translate (internal/translate/migrate) or exec (internal/exec/runtime) package, so the layering gate's packageLayer, permitted and tolerated tables are unchanged, and no ratcheted baseline moved.

Specification basis

Kernel Semantic Library Clocks.kerml (Clock::currentTime, Clocks::universalClock) and Occurrences.kerml (Occurrence::localClock) for the clock read; SysML v2 textual notation for assign, succession guards (if), constraint def and calc def bodies for the translated output; UML 2.5.1 ActivityPartition::represents, OpaqueAction/OpaqueExpression/OpaqueBehavior bodies and DurationObservation::event for the source. Adds the Clock::currentTime and action-def-performance rows to docs/project/spec-compliance.md.

How it was verified

• gofmt -l . (empty), go vet ./..., make lint, go build ./..., go test ./... (81 packages ok).
• Corpus gates with the corpora downloaded: OPENSYSML_REQUIRE_TRAINING_CORPUS=1 OPENSYSML_REQUIRE_PILOT_CORPORA=1 OPENSYSML_REQUIRE_PILOT_LIBRARY_XMI=1 go test -count=1 ./tests/corpus ./tests/identity -run 'TestTrainingExamples|TestPilotCorpora|TestPilotLibraryXMI|TestCorpusRoundTrip' ok.
• make docs-check (0 broken links), python3 scripts/changelog.py check, python3 scripts/check-doc-ids.py, go run -C tools ./cmd/doc-counts -check.
• New tests: opaque_test.go (translator table + refusals), opaque_migration_test.go and fixtures acquisition.xmi, plant.xmi, reactor.xmi (partitions incl. nested/unset/dangling/absent/untyped/unwritable/no-partition, JS assignments, English guards, clock reads, non-default timeVariableName, DurationObservation shapes, constraint bodies, calc bodies, refusals), empty_region_test.go (under tests/migrate), internal/translate/xmi/sysmlv1/xmi_test.go (TestStereotypeUnderSchemaNamespace), runtime conformance clock_read_local_clock_elapsed, clock_read_redefined_current_time and performed_action_def_perform_members_are_steps, robustness robustness_clock_read_test.go (TestRuntimeRobustnessClockRead).
• By hand: the TMT migration, validation, 100-run execution, retry trace and constraint evaluation above.

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

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring