Skip to content

v0.54.0

Choose a tag to compare

@github-actions github-actions released this 12 Sep 13:26
· 252 commits to master since this release
54659e1

[0.54.0] - 2026-09-12

Bug Fixes

  • Unblock Marketplace publishing — drop internal Markdown API, gate CI on verifyPlugin (jetbrains)- Eliminate Markdown preview layout jump on kuml fence render (jetbrains)- Close fail-open gaps in guard/OCL evaluation (activity-guard,ocl)- Close STM guard-evaluation fail-open gap (ADR-0015 parity) (ocl-guard)- Close worker-pool shutdown leak + symlink-escape hardening (script-sandbox)- OkfDocumentWriter leaked canonicalized File into relativePath computation (workspace)

Chore

  • Ignore Eclipse/IDE-style bin/ compiled-output directories (gitignore)- Bump 13 stable Gradle dependencies/plugins, revert kuiver 0.4.1 (deps)- Bump major-version dependencies (koog, lsp4j, gradle-plugin-publish, rsyntaxtextarea, pdfbox) (deps)- Bump kuiver 0.3.0 -> 0.4.1, migrate KuiverGraphAdapter (deps)- September 2026 Gradle dependency freshness sweep (deps)- Bump version to 0.54.0 (release)

Documentation

  • Fill in v0.53.0 gaps (tool-calling, app icon, view mode, Ollama models) (changelog)

Features

  • Add --with-source flag to publish kUML DSL source next to every handbook diagram (asciidoc)

Other

  • Implement C4DslPrinter and Sysml2DslPrinter for ScriptSerializer

Closes the two ScriptSerializer TODO stubs that made C4 and SysML 2 agent
edits invisible in the desktop editor: an agent could modify a C4Model or
Sysml2Model in memory, but ScriptSerializer had no printer to turn the
edited model back into a re-parseable *.kuml.kts script, so the change
never reached the DSL source shown to the user. C4DslPrinter
(kuml-core-dsl) and Sysml2DslPrinter (kuml-metamodel-sysml2) close that
gap, mirroring UmlModelDslPrinter: they reconstruct valid scripts from a
C4Model / Sysml2Model and document every known non-round-tripping field
(C4 element ids, C4Model.description, Container/ComponentDiagram
best-effort reconstruction, AttributeUsage.defaultExpression,
dangling/foreign ids) with visible // TODO markers instead of silently
dropping data.

Review and security-audit findings fixed during this wave:

  • Deployment-node layout hints were silently dropped instead of
    surfacing as a TODO. DeploymentNodeScope has no layout { … } DSL entry
    point, so printDeploymentNode only emits a TODO comment for
    GRID_COL/GRID_ROW/PINNED/etc. metadata now, restoring the printer's
    "every unreachable field becomes a TODO" invariant for the one C4
    element type that was missing it.
  • The layout-hint import gate (hasAnyLayoutHints) counted deployment-node
    metadata even though deployment nodes can never emit an actual
    layout { … } call, producing an unused import dev.kuml.core.dsl.layout.layout line for models whose only layout
    hints lived on a deployment node. Renamed to
    hasAnyPrintableLayoutHints() and excluded deployment nodes from the
    gate.
  • Security: C4Element.id and Sysml2Definition.name/.id are unvalidated
    strings that may contain embedded newlines. Several diagnostic
    // TODO / // NOTE comments interpolated these values raw (outside
    quote()) into single-line Kotlin comments — an id/name containing '\n'
    followed by attacker-controlled text could terminate the comment early
    and have that text reappear as live, uncommented code in the generated
    script. Added a sanitizeForComment() helper (String and
    Collection overloads) in both printers, escaping \n, \r and the
    Unicode NEL/LS/PS separators, applied at every raw interpolation site
    in TODO/NOTE comments (endpoint ids, missing/extra id diffs,
    usage/feature names, dangling owner/lifeline ids).

Verified via ./gradlew clean :kuml-core:kuml-core-dsl:check :kuml-metamodel:kuml-metamodel-sysml2:check --no-build-cache --rerun-tasks (520 + 112 tests green, ktlint/detekt clean), plus new
unit tests for each fix above (C4DslPrinterTest, Sysml2DslPrinterTest,
ScriptSerializerTest round-tripping through the real KumlScriptHost
compiler).

Co-Authored-By: Claude Sonnet 5 noreply@anthropic.com- Close C4 DSL completeness gap per ADR-0017 (Wave A, 5 non-round-tripping fields)

Task: C4DslPrinter's own "Known non-round-tripping fields" KDoc section
documented five DSL gaps below the C4 metamodel's actual capability. Per
ADR-0017 (DSL completeness must match supported metamodel standards), a
documented-but-unfixed gap like this counts as a bug, not an optional
enhancement — so this wave closed all five:

  • c4Model(name, description, block)'s description was accepted but silently
    discarded; C4ModelBuilder now stores it on C4Model.description.
  • containerInstance(name, containerId) dropped containerId on the floor;
    C4Container gained instanceOf: ElementId?, and the printer round-trips it
    as containerId = .id (a live expression, since C4 ids aren't
    user-pinnable across script-eval runs).
  • The C4 Code level (C4CodeElement) had no DSL entry point at all; added
    ComponentScope.codeElement(name) { ... }, with C4Component gaining
    codeElements: List mirroring the existing parent-list pattern.
  • DeploymentNodeScope couldn't use layout { ... } grid hints, unlike every
    other C4 element scope; now extends LayoutHintsScope.
  • ContainerDiagramBuilder/ComponentDiagramBuilder had no include(...) escape
    hatch for pulling in elements the coarse show*/exclude() flags can't
    reach, unlike SystemContextDiagramBuilder; added it, and rewrote
    C4DslPrinter's reconstruction logic for both diagram types to use it
    exactly instead of falling back to a TODO whenever avoidable.

Review loop: the round-trip test additions (real ScriptHost re-evaluation,
not hand-built LayoutResult fixtures) surfaced a pre-existing, previously
undetected printer bug independent of this wave's new fields — a top-level
C4DeploymentNode was printed as a bare "c4vN = deploymentNode(...)"
assignment with no matching val/lateinit var declaration, so the generated
script failed to compile whenever a root deployment node was ever
reassigned. Fixed by giving top-level deployment nodes their own fresh val
declaration, mirroring person/softwareSystem. Also required reordering
C4DslPrinter's top-level print order (persons/software systems always
before deployment nodes, stable sort) so a containerInstance(...)'s
referenced container variable is always already assigned by the time the
generated script reads it.

Security-audit loop: no exploitable findings against this wave's own
SSRF/DoS/crypto/resource-leak/logging checklist — the new surface (DSL
builder fields, a printer re-ordering, one new include() overload) has no
network, filesystem, or credential-handling contact. Approved without
follow-up fix commits (confirmed via reflog: feature/c4-dsl-gap-fixes carries
a single commit end to end).

Verification: new/updated tests in C4ModelBuilderTest, LayoutHintsTest,
ContainerDiagramBuilderTest, ComponentDiagramBuilderTest, C4DslPrinterTest,
and the real-script-host round-trip in ScriptSerializerTest. ktlint and
detekt clean; kuml-core-dsl:jvmTest (539 tests) and kuml-desktop:jvmTest
both green.

Co-Authored-By: Claude Sonnet 5 noreply@anthropic.com- Close SysML 2 DSL completeness gap per ADR-0017 (Wave B)

ADR-0017 requires that any capability the SysML 2 metamodel supports be
fully reachable through the .kuml.kts DSL builder layer; a gap between
metamodel and DSL counts as a bug, not an optional enhancement.
Sysml2DslPrinter's "Known non-round-tripping data" KDoc had documented
three such DSL-builder gaps below the metamodel's actual capability.
This wave closes all three:

  • isAbstract is now settable on attributeDef/portDef/connectionDef, the
    three definition builders that previously lacked it (all other 9
    definition types already had the parameter).
  • specializesId is now available on all 12 definition builders
    (previously only partDef), mirroring the existing single,
    self-specific-specialization pattern exactly. More than one
    specialization, or a foreign (non-self) specificId, on a definition
    remains unreachable through the DSL by construction and still
    surfaces as a // TODO when hand-crafted data forces it — no longer
    documented as a DSL completeness gap, since it can no longer occur
    via normal DSL use.
  • 8 of the 21 Sysml2Usage subtypes gained DSL constructors: actorUsage/
    useCaseUsage/requirementUsage/stateUsage/actionUsage/
    activityPartitionUsage/lifelineUsage/constraintUsage, each with an
    object-taking overload and an ...ById(...) id-only sibling, mirroring
    the existing transition/controlFlow/objectFlow pattern. IncludeUsage/
    ExtendUsage remain intentionally unsupported.

New/updated tests across Sysml2DslTest and Sysml2DslPrinterTest, plus an
extended real-script-host round-trip in ScriptSerializerTest exercising
isAbstract and the new actorUsage(...) constructor. Review and security-
audit loops for this wave completed without requiring further code
changes beyond the implementation above (no defect-fix commits exist on
the feature branch history). ./gradlew clean check passes across the
whole monorepo (1984 tasks, 0 failures, 0 errors), verified with
--no-build-cache --rerun-tasks.

Squash-merge of local feature/sysml2-dsl-gap-fixes (single commit
419963c5) onto master; branch deleted locally, never pushed.

Co-Authored-By: Claude Sonnet 5 noreply@anthropic.com- UML association renderers ignored non-navigable ends (ADR-0017)- Add UmlAssociationClass (ADR-0017, Wave D)

UML 2.5 treats the association class as standard vocabulary (§11.5.3): a
single model element with genuine double nature — simultaneously a
classifier (attributes, operations, inheritance) and a relationship
(connects two classifiers like an association). kUML had no such concept;
per ADR-0017 this was a bug, not a nice-to-have.

Form decision: one thing, one name, one id. UmlAssociationClass implements
both UmlClassifier and UmlRelationship (plus Stereotypable) directly,
instead of coupling a UmlClass to a separate UmlAssociation plus a
synthetic link object. The two-object approach would have given the same
UML concept two identities in the model — two ids that can drift apart,
and an invalid intermediate state (class without its association, or vice
versa) that the type system wouldn't rule out. A Maven-Central-published
API shouldn't have to walk that redundancy back after its first release.

Implements: metamodel type + associationClass(...) DSL builder (3
overloads, full class body, both association ends), printer support in
both dialects, layout-bridge registration (node + 2 edges + an invisible
ELK-gravity anchor edge so the class box lands near its association
line), and full SVG rendering (class box, association line with
navigability/aggregation/labels, dashed tether from box to the line's
arc-length midpoint). StructuralValidator now flags dangling association-
class endpoint references.

Real findings from review, fixed before merge (not hypothetical — each
reproduced a wrong rendering or compile-time trap first):

  • AnyKumlModel.toKumlModel() emitted every association class twice: it
    matched both the elements and relationships filterIsInstance buckets,
    since it implements both UmlNamedElement and UmlRelationship. Fixed by
    deduping by id when concatenating into KumlDiagram.elements.
  • KumlSvgRenderer's tether pass targeted ELK's raw self-loop route
    instead of the widened C-loop route for self-association-classes, and
    iterated diagram.elements instead of flatElementIndex, so association
    classes nested inside packageOf { ... } silently got no tether drawn.
    Fixed both.
  • UmlLayoutBridge's sub-package member loop (2 levels of packageOf
    nesting) matched the !is UmlRelationship filter and dropped an
    association class entirely instead of registering it as a node + 2
    edges. Fixed.
  • InterpreterUmlModelDslPrinter.printAssociationClass referenced an
    association end's val identifier by identOf alone; a forward reference
    between two association classes emitted a reference to a
    not-yet-declared val. Now checks declaredSoFar first and falls back to
    a TODO marker.
  • Added direct StructuralValidatorTest/SelfLoopRouterTest coverage for
    the DANGLING_REFERENCE and self-loop-detection branches the wave
    introduced, so these paths have tests independent of the fixes above.
  • Documented the source-breaking change: UmlRelationship and
    UmlClassifier are public sealed interfaces in a Maven-Central-published
    module, so any exhaustive when on either in third-party code needs a
    new is UmlAssociationClass branch after this update (compile-time
    only, no runtime or binary break).

Explicitly out of scope for this wave (documented in CHANGELOG.md, not
just a footnote): codegen (Java/Kotlin/TS/C#/C++/Exposed, JPA-M2M,
UML-to-ERM) still filters on is UmlClass and silently skips association
classes with no error.

All touched modules verified green via ./gradlew clean check
--no-build-cache --rerun-tasks, plus ktlintCheck across every touched
module.

Co-Authored-By: Claude Sonnet 5 noreply@anthropic.com- Add live simulation of state machines to kUML Desktop

Task: wire the existing StateMachineRuntime/sandbox stack into the
Desktop app so UML STATE and SysML-2 STM diagrams can be stepped
through interactively (Werkzeuge > Simulieren, Ctrl+R) instead of
only being renderable as static SVG — a SimulationBar (step /
auto-advance / reset / event list), a scrubbable SimulationTracePane,
and live DOM-patched highlight rings on the existing Batik SVG so
zoom/pan state survives each step.

Review-loop findings fixed before merge:

  • Auto-advance kept firing events against a model the editor had
    since diverged from; staleness is now re-derived every tick (a new
    STALE stop reason) instead of being captured once per composition.
  • Scrubbing back from a finished run left Step/event/Auto-Advance
    buttons disabled; SimulationSession.isTerminated now also checks
    widgetState.isScrubbing so the documented fork-and-continue
    workflow actually unlocks them again.
  • statusFor() let a GuardWarning incorrectly override a successful
    Transitioned from an unrelated unguarded transition (only a silent
    Stayed should ever be overridden); the GuardTimeout/GuardFailed
    split matched on a bare "timed out" substring instead of
    TimeLimitedGuardEvaluator.TIMEOUT_MESSAGE_PREFIX, now locked down
    by a test.
  • The "Weitere..." freeform event row wasn't disabled on simulation
    termination, unlike every other send affordance.
  • Added missing test coverage for SimulationSession's reset/scrubTo/
    clearDiscardedStepsNotice/statusFor mapping and for
    SimulationHighlightPatcher's previously-untested document-less
    guard branches; removed the now-dead Strings.simRestart.

Security-audit finding fixed before merge (resource-leak class):

  • A second Ctrl+R during the async simulation start could leak a
    second TimeLimitedGuardEvaluator thread pool. MainWindow.
    startSimulation() now has a simulationStarting guard, also
    reflected in the Werkzeuge > Simulieren menu item's enabled state,
    so only one start can be in flight at a time.

ktlint and detekt clean; full jvmTest suites green across all four
touched modules (1145 tests, 0 failures).

Co-Authored-By: Claude Sonnet 5 noreply@anthropic.com- Make OKF Knowledge Workspace documents editable in kUML Desktop

Extends the read-only OKF-Workspace viewer (ADR-0011) with an editable
mode: MarkdownDocPane is replaced by DocumentEditorPane (reusing the
main .kuml.kts editor's RSyntaxTextArea via a new shared SyntaxTextEditor),
frontmatter type gets a validated dropdown over the OkfType vocabulary
(OkfDocumentParser/OkfDocumentWriter + FrontmatterWriter round-trip the
raw buffer instead of a lossy re-serialization), and saving goes through
OkfSaveGate + WorkspaceWriteGuard to enforce OkfValidator rules and
workspace-root path containment before any atomic write. WorkspaceState
now rescans and rebuilds the WorkspaceGraphIndex/tree after a save
instead of treating them as build-once/read-only.

Multi-agent pipeline (4-agent convention): Opus planned the
persistence/validation-gate design after the UI/UX design-team session
(editable-by-default text buffer as single source of truth, frontmatter
dropdown as a projection onto it, per Alan Kay's resolution of the
Rams/Norman disagreement). Sonnet implemented on a local feature branch.

Review loop ran 6 rounds before approval, catching real defects at each
step rather than rubber-stamping fix reports:

  • round 1-2: token race between concurrent loads, save routing through
    the wrong document, lost undo history, line-ending drift
  • round 3: isDirty staying true for ~300ms after a successful save,
    "discard changes" only resetting a flag instead of the buffer, a
    stale type-badge in the tree
  • round 4 (critical): the round-3 fix removed the dialog window that had
    accidentally been masking a save/select race — saving document A while
    clicking document B in the tree could silently overwrite A's on-disk
    content with B's buffer; reproduced empirically 5/5 runs with a
    temporary probe test before being fixed with a selection-token guard
  • round 5: single-quote frontmatter values not round-tripping, select()
    picking up a stale OkfDocument instance after a save
  • round 6: approved after verifying round 4/5 fixes hold under a fresh
    adversarial pass; two new minor findings (stuck isRendering flag,
    a narrower selection-identity edge case) fixed in the final commit

Security audit approved with the workspace-root containment guard and
atomic-write path confirmed; trust-dialog gating on workspace open is
unchanged.

1383+ tests green (kuml-workspace, kuml-desktop, kuml-cli, kuml-examples),
including new WorkspaceStateEditingTest, WorkspaceWriteGuardTest,
OkfDocumentWriterTest, OkfSaveGateTest, FrontmatterWriterTest coverage
for the race conditions and validation gate found during review.

Co-Authored-By: Claude Sonnet 5 noreply@anthropic.com- Add sample-support-ticket-process OKF demo workspace

Second fictional OKF Knowledge-Workspace example (ADR-0011) alongside
sample-association-charter, for manual UI testing of kUML Desktop's
workspace viewer/editor with different domain content and diagram
variety. Includes a UmlStateMachine document (Ticket-Lebenszyklus)
well-suited to exercise the Desktop's State-Machine-Simulation feature
directly inside a Knowledge Workspace.

Validated with the local CLI build: kuml workspace validate reports
no findings, kuml workspace render renders all 3 diagram documents
cleanly (the two BPMN gateway warnings match the same benign pattern
already present in sample-association-charter's own BPMN diagram).

Co-Authored-By: Claude Sonnet 5 noreply@anthropic.com- Add "New Workspace…" dialog to kUML Desktop (FT-Desktop-New-Workspace)

Task: kuml-desktop could only open existing OKF workspaces via the File
menu; there was no in-app way to scaffold a brand-new one (Knowledge or
Engineering mode), forcing users out to the CLI's kuml workspace init.

To let kuml-desktop scaffold without depending on kuml-cli, extracted the
generic {{var}} template engine (TemplateEngine/TemplateFile/Scaffolder)
out of kuml-cli into a new standalone module kuml-scaffold, and moved
WorkspaceInitSpec/WorkspaceScaffolder out of kuml-cli into
kuml-docs:kuml-workspace (as dev.kuml.workspace.scaffold). Both moves are
mechanical (internal -> public under explicitApi(), package rename only);
kuml workspace init and kuml plugin init behavior is unchanged,
covered by the existing CLI-level tests plus tests migrated alongside the
moved types. Added a "New Workspace…" File-menu item and dialog
(NewWorkspaceFormState pure logic + NewWorkspaceDialog Compose UI) that
lets the user pick a name, mode and parent directory, then hands the
scaffolded directory to the existing open-workspace path (trust gate +
mode dispatch included). Also closed a pre-existing native-image gap:
workspace-templates/.* was never registered for GraalVM reachability
metadata, unlike the already-registered plugin-templates/.*.

Review and security-audit loop found two real issues, both fixed before
merge:

  • Review: NewWorkspaceFormState.canCreate treated WRITE_FAILED as a
    blocking error, so a failed scaffold attempt (transient I/O error, AV
    lock, full disk) left the "Erstellen" button permanently disabled with
    no way to retry short of changing the name or target directory (both
    of which change what gets created). Fixed by excluding WRITE_FAILED
    from the blocking-error set and clearing runtimeError at the start of
    every create attempt and on every field/mode change.
  • Security audit: the new kuml-scaffold module (org.jetbrains.kotlin.jvm,
    internal build-only module) was about to be silently published to
    Maven Central on the next release because it wasn't in
    build.gradle.kts's nonPublishedModules set. Added it to that set before
    it could ship as an unintended public artifact.

Verified: kuml-scaffold:check, kuml-docs:kuml-workspace:check,
kuml-cli:check, kuml-desktop:check and a full
./gradlew clean check --no-build-cache --rerun-tasks all green
(7362 tests), plus a follow-up kuml-desktop:check run (214 tasks,
0 detekt findings, all 13 NewWorkspaceFormTest cases including the new
retry-path invariant).

Co-Authored-By: Claude Sonnet 5 noreply@anthropic.com- Add TokenFlowEngine: model-agnostic simulate for BPMN process + UML Activity

Task: kuml simulate previously refused BPMN process diagrams outright and
required a UmlStateMachine, leaving UML Activity and BPMN process diagrams
unexecutable. This adds kuml-runtime-tokenflow, a model-agnostic token-flow
engine shared across UML Activity, BPMN process, and (via a bridge) SysML 2
ACT, producing one common trace format so downstream consumers
(BpmnTokenTimelineBuilder, TraceFlavourDetector, ActivityTraceReplayer) work
unchanged. kuml simulate now executes both diagram kinds with new
--max-tokens/--time-budget-ms/--process/--interactive support.

Real findings fixed during review and security-audit loops on this branch:

Review loop:

  • GatewaySpec.defaultEdgeId was parsed but never consulted in diverge() —
    a standards-conformant BPMN default="sfX" attribute silently dropped
    the token instead of falling back; both EXCLUSIVE and INCLUSIVE diverge
    now resolve it.
  • consumeConvergence(PARALLEL) cleared all recorded join arrivals instead
    of decrementing one per incoming edge, stranding a surplus token that had
    arrived twice on the same edge before its sibling caught up. New
    ActivityInstance.consumeJoinArrivals() fixes this.
  • A plain BPMN gateway node with no explicit converging/diverging direction
    was routed through the convergence family dispatch, emitting a spurious
    JoinReached trace entry for PARALLEL/INCLUSIVE families; it now always
    behaves as a pass-through.
  • TokenFlowOutcome.Failed from engine.start() was silently swallowed instead
    of being reported as SCRIPT_ERROR.

Security-audit loop:

  • The kuml trace replay call site (Sysml2ActivityAdapter.runtimeFor) was
    the one remaining ACT execution path still using the unsandboxed default
    ActivityGuardEvaluator — no --sandbox/--guard-timeout-ms option existed
    for it at all. Sandboxing is now unconditional there too.
  • BpmnTokenFlowAdapter silently collapsed an expanded sub-process's inner
    content, loopCharacteristics, and boundary events into an opaque
    single-action node, so kuml simulate reported success on a materially
    wrong model with zero signal. These now raise hard
    UNSUPPORTED_SUBPROCESS_CONTENT / UNSUPPORTED_LOOP_CHARACTERISTICS /
    UNSUPPORTED_BOUNDARY_EVENT errors instead of a false-positive pass.
  • An INCLUSIVE diverge with no matching guard and no default edge silently
    dropped its token with no warning and exit code 0. Validation's
    NO_DEFAULT_BRANCH warning now covers INCLUSIVE (was EXCLUSIVE-only), and
    the previously-unreachable --strict-guard-coverage flag is now wired to
    the CLI to make this a hard error on request.
  • --max-steps/--max-tokens/--time-budget-ms/--guard-timeout-ms accepted 0
    or negative values, and the wall-clock deadline was computed as an
    absolute nanoClock()+budget comparison vulnerable to nanoTime overflow.
    All four flags now validate >= 1 at parse time; the deadline is now an
    overflow-safe elapsed-duration check.
  • A guard timeout/exception was indistinguishable from a guard legitimately
    evaluating false (ExitCodes.SANDBOX_TIMEOUT was declared but dead code).
    A new guardResultListener side channel lets SimulateCommand warn on guard
    failure and correctly map a sandbox timeout to SANDBOX_TIMEOUT.
  • ActivityRuntime.restoreFrom did not actually enforce the restriction its
    own KDoc claimed on snapshots with populated joinEdgeTokens; now rejected
    via MigrationException.

Also carries forward from the original implementation: ADR-0015-B2, the
underlying reason this engine has a sandboxed-guard-evaluation contract in
the first place — ActivityRuntime accepted a guardEvaluator constructor
parameter that evaluateGuard() never actually called, so a caller-supplied
TimeLimitedGuardEvaluator silently had no effect and every guard ran
unsandboxed via direct OclExpressions.evaluate. Fixed by extracting
ActivityGuardEvaluator (implements the real GuardEvaluator SPI) and wiring
evaluateGuard() through it, so kuml simulate --sandbox, kuml run, and
the MCP kuml.run.* tools all sandbox ACT guard evaluation consistently.

Verified on the feature branch: kuml-runtime-core, kuml-runtime-tokenflow,
kuml-cli, and kuml-mcp test suites (831+ tests) plus ktlintCheck all green
with --no-build-cache --rerun-tasks.

Co-Authored-By: Claude Sonnet 5 noreply@anthropic.com- Add hallucination.kuml.kts for regression testing invalid UML constructs (e.g., aggregation at inappropriate levels)