From b987327c4c6b4fdaa28f203f3a1dca38c137e359 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sat, 8 Aug 2026 23:46:03 +0000
Subject: [PATCH 01/29] fix(run-local): verify the web client bundle after the
 boot, not before it
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Every page in a locally-run app rendered as a black screen, intermittently and
at the same mxcli version. `run --local` bundles the browser client at step 5b
and it succeeds; then the runtime boot runs Gradle `clean-custom-classes compile
package`, whose package pass repopulates deployment/web and takes dist/ with it.
The bundle was deleted 51 seconds after the same command wrote it.

It only bites when Gradle has work to do — a new Java action, a full recompile —
which is why an app boots fine for weeks and then stops with nothing changed.

Nothing reported it. `mxcli check` passes, the build succeeds, the runtime log
is quiet, `curl /` returns 200 with a valid HTML shell, and every OData service
answers. Only a browser sees it.

A pre-condition established before a step that rewrites the same directory is
not a post-condition, so the bundle is now verified after the boot:

  - WebClientBundled / EnsureWebClientBundle re-bundle only when it is gone,
    and say so. When Gradle had nothing to do this is a stat.
  - Re-ordering the bundle to after the boot instead was rejected: it would
    leave the app reachable-but-blank for ~30s on every cold start.
  - A failed re-bundle warns and leaves the runtime up — the app's services
    still work, only the browser is broken — and names the blank page.

`mxcli test --local` boots the same way and destroys the bundle too, which is
why a test run between a boot and a browser looked like a rendering bug. Tests
are headless, so that path reports the loss and the remedy instead of spending
~30s on a loop whose point is two seconds.

Both controls run: with the guard never firing the wipe test fails, and with it
always firing the survivor test fails.

mxcli-formula1 §35
---
 .claude/skills/fix-issue.md               |   1 +
 .claude/skills/mendix/run-local.md        |  18 +++
 cmd/mxcli/docker/localapp.go              |   6 +
 cmd/mxcli/docker/runlocal.go              |  12 ++
 cmd/mxcli/docker/webclient.go             |  78 +++++++++++-
 cmd/mxcli/docker/webclient_bundle_test.go | 144 ++++++++++++++++++++++
 6 files changed, 256 insertions(+), 3 deletions(-)
 create mode 100644 cmd/mxcli/docker/webclient_bundle_test.go

diff --git a/.claude/skills/fix-issue.md b/.claude/skills/fix-issue.md
index cb6eddabe..3d90b651d 100644
--- a/.claude/skills/fix-issue.md
+++ b/.claude/skills/fix-issue.md
@@ -424,3 +424,4 @@ extracting `OffsetExpression`/`LimitExpression`.
 | `create odata client` with credentials given as constants (`HttpUsername: '@Module.ApiUser'`) still gets HTTP 401 and an empty client, after the fix that made literal credentials work. Sharpened by the same release making a constant `ServiceUrl` mandatory — the shape the tool insists on is the shape whose credentials it will not read | `resolveCredential` trusted the visitor's isLiteral flag. `'@Module.ApiUser'` **is** a STRING_LITERAL, so the flag said "literal" and the previous code sent the fifteen characters `@Module.ApiUser` as the username — and the unresolved-credential note did not fire either, because as far as the code knew nothing was unresolved | `mdl/executor/cmd_odata.go` (`resolveCredential`, `constantReference`, `designTimeConstants`) | **A syntactic classification is not a semantic one.** The visitor can say "this was a quoted string"; only the executor can say "this quoted string names a constant". Any flag of the form isLiteral needs the consumer to ask what the literal *contains* before treating it as a value. **The fix is to resolve, not to refuse**: a constant's design-time default is exactly what Studio Pro sends on the same fetch, so reading it is the value rather than a workaround — and mxcli already has the project open. Three spellings must all work (`'v'`, `@M.C`, `'@M.C'`); a dotted literal like a password containing a dot must not be mistaken for a reference. Tests `cmd_odata_metadata_auth_test.go`. mxcli-formula1 #23 follow-up |
 | An app themed dark still shows light-mode drop shadows under the datagrid's filter-operator popover and dropdown filter lists | The generated widget layer re-pointed `.column-selectors` but not the four rules in `_datagrid-filters.scss` that bake the same two-layer shadow. Each already takes its *background* from `--bg-color-secondary`, so Atlas re-colours the panel and leaves the shadow — which is why it reads as a partial fix rather than an untouched widget | `cmd/mxcli/theme/assets/*/files/theme/web/_mxcli-widgets.scss` | **Read the selectors out of the shipped `themesource/`, not the bug report** — the fourth here is `.dropdown-container .dropdown-list`, nested under a parent the report did not name. **Verify in the compiled CSS, never the source** (the §33 rule): apply the theme to a real project, run `mxbuild --target=deploy --java-home=… --java-exe-path=…`, then grep `theme-cache/web/theme.compiled.css` and check the *line number* — the fix must land after the widget module's own rule (30794 vs 27765 here) or the cascade eats it. A theme-cache file older than the SCSS you just wrote is a stale compile, and mtime is the cheapest way to catch it. mxcli-formula1 #33 / suggested issue 4 |
 | A `MOVE` cannot be confirmed and a module's layout cannot be reviewed: `SHOW STRUCTURE` groups by document type at every depth and never names a folder, `DESCRIBE` answers for one document at a time, so checking where things ended up means opening the `.mpr` as SQLite | The read side of folders was simply never built. `MOVE`/`DROP FOLDER` write containment; nothing read it back | New `mdl/executor/cmd_list_folders.go` + grammar (`FOLDERS` lexer token, `showOrList FOLDERS (IN …)?` in `MDLCatalog.g4`, `FOLDERS` added to the `keyword` rule so it stays usable as an identifier), `mdl/ast/ast_query.go`, `mdl/visitor/visitor_query.go`, `mdl/executor/executor_query.go` | **A layout listing must show what is *not* there**: empty folders (`[0]`) and documents still at the module root, or it cannot be diffed against an intended layout — that is the whole use. Documents are indexed by `ContainerID` across every list call the backend offers, each best-effort, so a backend that cannot answer one kind yields a listing missing that kind rather than no listing. **Do not stub the hierarchy in the test** — `mkHierarchy` populates `moduleNames` but not `folderNames`, so `BuildFolderPath` returns `""` and every folder silently collapses into the module root, which looks exactly like the bug. Build it from the mock's `ListModules`/`ListUnits`/`ListFolders`, as `getHierarchy` does. Tests `cmd_list_folders_test.go`, example in `18-folder-examples.mdl`. mxcli-formula1 issue #2 |
+| Every page in a locally-run app is a black screen. `mxcli check` passes, the build reports success, the runtime log is quiet, `curl /` returns 200 with a valid HTML shell, and every OData service answers — only a browser sees it. It also comes and goes between runs of the same command at the same version | `run --local` bundles the browser client at step 5b, then the runtime boot runs Gradle `clean-custom-classes compile package`, whose package pass repopulates `deployment/web` and takes `dist/` with it — deleting the bundle 51 seconds after the same command wrote it. It only bites when Gradle has work to do (a new Java action, a full recompile), which is why the app boots fine for weeks and then stops | `cmd/mxcli/docker/webclient.go` (`WebClientBundled`, `EnsureWebClientBundle`, `ReportLostWebClientBundle`), `cmd/mxcli/docker/runlocal.go` (step 6b, after the boot), `cmd/mxcli/docker/localapp.go` (headless boots warn instead of paying ~30s) | **A pre-condition established before a step that rewrites the same directory is not a post-condition** — verify after, not before. The guard is a `stat` when the bundle survived, which is what makes it affordable at every boot; re-ordering the bundle to after the boot instead would leave the app reachable-but-blank for ~30s on every cold start. **`curl /` returning 200 is not evidence the app renders**: the shell is served by the runtime, the client by a file the shell references. The one-line check is `curl -o /dev/null -w '%{http_code}' <app>/dist/index.js`. **Do not silently pay for a repair on a path that does not need it** — `test --local` destroys the bundle too, but tests are headless, so it prints the loss and the remedy rather than spending 30s on a two-second loop. Tests `webclient_bundle_test.go`; both controls run (guard never fires → the wipe test fails; guard always fires → the survivor test fails). mxcli-formula1 §35 |
diff --git a/.claude/skills/mendix/run-local.md b/.claude/skills/mendix/run-local.md
index 81e8f4eb6..48917d3d1 100644
--- a/.claude/skills/mendix/run-local.md
+++ b/.claude/skills/mendix/run-local.md
@@ -209,6 +209,24 @@ Playwright + the devcontainer's Chromium).
   skips the bundle and just hot-reloads. It uses `CHOKIDAR_USEPOLLING` because inotify
   is silent on container filesystems.
 - Without `--watch`, a single one-shot bundle (~7 s) runs before boot.
+- **The bundle is re-checked after the boot**, because bundling before it is not
+  enough: the runtime's boot runs Gradle `clean-custom-classes compile package`,
+  and when Gradle has work to do (a new Java action, a full recompile) its package
+  pass repopulates `deployment/web` and deletes `dist/` — the bundle written
+  seconds earlier by the same command. If that happened, `run --local` says
+  `re-bundling` and rebuilds it. When Gradle had nothing to do the check is a
+  `stat` and costs nothing.
+
+**If you ever see a black page:** that is this failure, and nothing else reports
+it — `mxcli check` passes, the build succeeds, the runtime log is quiet, `curl /`
+returns **200** with a valid HTML shell, and the OData services all answer. Only a
+browser sees it. Confirm with `curl -o /dev/null -w '%{http_code}' <app>/dist/index.js`;
+a 404 there is the whole diagnosis.
+
+`mxcli test --local` boots the same way and destroys the bundle too. Tests are
+headless so it is not rebuilt for them (that would cost ~30 s on a loop whose point
+is two seconds) — the run prints a note instead, and a subsequent `run --local`
+restores it.
 
 ## Pixel-perfect page loop
 
diff --git a/cmd/mxcli/docker/localapp.go b/cmd/mxcli/docker/localapp.go
index d68874178..8842a9c4b 100644
--- a/cmd/mxcli/docker/localapp.go
+++ b/cmd/mxcli/docker/localapp.go
@@ -151,6 +151,11 @@ func StartLocalApp(opts LocalAppOptions) (*LocalApp, error) {
 
 	app := &LocalApp{Version: version, RuntimeLogPath: opts.RuntimeLogPath}
 
+	// Whether a browser bundle exists *before* this boot. The boot's Gradle
+	// packaging removes it, and this app is booted headless (tests), so the loss
+	// is only noticed later by whoever opens a browser (mxcli-formula1 §35).
+	hadWebClient := WebClientBundled(opts.DeployDir)
+
 	// 4. Build, unless the caller is reusing an existing deployment.
 	if !opts.SkipBuild {
 		fmt.Fprintln(w, "Building project (mxbuild --serve)...")
@@ -189,6 +194,7 @@ func StartLocalApp(opts LocalAppOptions) (*LocalApp, error) {
 		return nil, err
 	}
 	app.Runtime = rt
+	ReportLostWebClientBundle(opts.DeployDir, hadWebClient, w)
 	return app, nil
 }
 
diff --git a/cmd/mxcli/docker/runlocal.go b/cmd/mxcli/docker/runlocal.go
index 96023d7a2..a8725dc66 100644
--- a/cmd/mxcli/docker/runlocal.go
+++ b/cmd/mxcli/docker/runlocal.go
@@ -740,6 +740,18 @@ func RunLocal(opts LocalRunOptions) error {
 	}
 	defer rt.Stop()
 
+	// 6b. The boot's Gradle `package` pass repopulates deployment/web, and when
+	// Gradle had work to do it takes dist/ with it — deleting the bundle step 5b
+	// wrote seconds ago. Verify after the boot, because before it proves nothing
+	// (mxcli-formula1 §35). Costs a stat when the bundle survived.
+	if _, err := EnsureWebClientBundle(WebClientOptions{
+		DeployDir: opts.DeployDir, MxBuildPath: mxbuildPath, Stdout: w,
+	}); err != nil {
+		// The app is up and its services answer; only the browser is broken. Say so
+		// and keep running rather than tearing down a working runtime.
+		fmt.Fprintf(stderr, "Warning: %v\n", err)
+	}
+
 	if opts.OnReady != nil {
 		opts.OnReady(LocalAppInfo{
 			AppPort:   opts.AppPort,
diff --git a/cmd/mxcli/docker/webclient.go b/cmd/mxcli/docker/webclient.go
index 0d56cd035..364ffc314 100644
--- a/cmd/mxcli/docker/webclient.go
+++ b/cmd/mxcli/docker/webclient.go
@@ -138,10 +138,82 @@ func BuildWebClient(opts WebClientOptions) error {
 		return fmt.Errorf("web client build timed out after %s", timeout)
 	}
 
-	dist := filepath.Join(webDir, "dist", "index.js")
-	if _, err := os.Stat(dist); err != nil {
-		return fmt.Errorf("web client build reported success but %s is missing:\n%s", dist, log.String())
+	if !WebClientBundled(opts.DeployDir) {
+		return fmt.Errorf("web client build reported success but %s is missing:\n%s",
+			webClientBundlePath(opts.DeployDir), log.String())
 	}
 	fmt.Fprintf(w, "  Web client bundled in %s\n", time.Since(start).Round(time.Millisecond))
 	return nil
 }
+
+// webClientBundlePath is the one file whose absence is the black screen: the
+// shell loads, paints the theme's background, and never starts the client.
+func webClientBundlePath(deployDir string) string {
+	return filepath.Join(deployDir, "web", "dist", "index.js")
+}
+
+// WebClientBundled reports whether the deployment currently has a browser
+// bundle to serve.
+func WebClientBundled(deployDir string) bool {
+	fi, err := os.Stat(webClientBundlePath(deployDir))
+	return err == nil && !fi.IsDir() && fi.Size() > 0
+}
+
+// EnsureWebClientBundle re-bundles when the bundle is missing, and reports
+// whether it had to.
+//
+// Bundling before the runtime boots is not enough. The boot runs Gradle
+// `clean-custom-classes compile package`, and when Gradle has work to do — a new
+// Java action, a full recompile — its package pass repopulates deployment/web
+// and takes dist/ with it, deleting the bundle written seconds earlier by a
+// previous step of the same command. Nothing reports this: `mxcli check` passes,
+// the build succeeds, the runtime logs nothing, `curl /` returns 200 with a valid
+// HTML shell, and every OData service answers. Only a browser sees the black
+// screen, which is how it survives restarts (mxcli-formula1 §35).
+//
+// So the bundle is verified *after* the boot rather than trusted from before it.
+// When Gradle had nothing to do the check is a stat and costs nothing, which is
+// why this is a guard rather than a reordering — the bundle still exists before
+// the boot for the common case where the app is reachable immediately.
+func EnsureWebClientBundle(opts WebClientOptions) (bool, error) {
+	return ensureWebClientBundle(opts.DeployDir, opts.Stdout, func() error {
+		return BuildWebClient(opts)
+	})
+}
+
+// ReportLostWebClientBundle says so when a boot destroyed a bundle that existed
+// before it, and reports whether it did.
+//
+// This is the second way into §35: `mxcli test --local` boots the same way and
+// its Gradle package pass wipes the bundle too, so a test run between a `run
+// --local` and a browser leaves the app serving a black screen even though
+// nothing was rebuilt. Tests are headless and do not need the bundle, and
+// re-bundling would cost ~30s on a loop whose whole point is two seconds — so
+// this warns with the remedy instead of paying for it uninvited.
+func ReportLostWebClientBundle(deployDir string, hadBundle bool, w io.Writer) bool {
+	if w == nil || !hadBundle || WebClientBundled(deployDir) {
+		return false
+	}
+	fmt.Fprintf(w, "Note: this boot's packaging step removed the browser bundle at %s.\n"+
+		"  The app will render a blank page until it is rebuilt — re-run 'mxcli run --local' to restore it.\n",
+		webClientBundlePath(deployDir))
+	return true
+}
+
+// ensureWebClientBundle holds the decision, separated from the node invocation
+// so it can be tested without mxbuild's tooling.
+func ensureWebClientBundle(deployDir string, w io.Writer, bundle func() error) (bool, error) {
+	if w == nil {
+		w = io.Discard
+	}
+	if WebClientBundled(deployDir) {
+		return false, nil
+	}
+	fmt.Fprintln(w, "Web client bundle was removed by the boot's packaging step; re-bundling...")
+	if err := bundle(); err != nil {
+		return true, fmt.Errorf("re-bundling web client after boot: %w\n"+
+			"  The app is running but will render a blank page until %s exists.",
+			err, webClientBundlePath(deployDir))
+	}
+	return true, nil
+}
diff --git a/cmd/mxcli/docker/webclient_bundle_test.go b/cmd/mxcli/docker/webclient_bundle_test.go
new file mode 100644
index 000000000..d2c47d1ec
--- /dev/null
+++ b/cmd/mxcli/docker/webclient_bundle_test.go
@@ -0,0 +1,144 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package docker
+
+import (
+	"bytes"
+	"errors"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// writeBundle creates a deployment whose web client is bundled.
+func writeBundle(t *testing.T, deployDir, content string) {
+	t.Helper()
+	dist := filepath.Join(deployDir, "web", "dist")
+	if err := os.MkdirAll(dist, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(filepath.Join(dist, "index.js"), []byte(content), 0o644); err != nil {
+		t.Fatal(err)
+	}
+}
+
+// mxcli-formula1 §35: the boot's Gradle package pass repopulates deployment/web
+// and removes dist/, deleting the bundle a previous step of the same command
+// wrote. The app then serves a 200 HTML shell and a black screen — invisible to
+// check, build, the runtime log and curl.
+func TestEnsureWebClientBundle_RebundlesAfterThePackagingWipe(t *testing.T) {
+	deployDir := t.TempDir()
+	writeBundle(t, deployDir, "// bundled at 15:15:31")
+
+	// What the Gradle package pass does at 15:16:22.
+	if err := os.RemoveAll(filepath.Join(deployDir, "web", "dist")); err != nil {
+		t.Fatal(err)
+	}
+
+	var out bytes.Buffer
+	called := 0
+	rebuilt, err := ensureWebClientBundle(deployDir, &out, func() error {
+		called++
+		writeBundle(t, deployDir, "// re-bundled after boot")
+		return nil
+	})
+	if err != nil {
+		t.Fatalf("unexpected error: %v", err)
+	}
+	if !rebuilt || called != 1 {
+		t.Fatalf("the wipe was not repaired: rebuilt=%v calls=%d", rebuilt, called)
+	}
+	if !WebClientBundled(deployDir) {
+		t.Error("the app would still serve a blank page")
+	}
+	// Silence is what made this survive several restarts, so the repair is stated.
+	if !strings.Contains(out.String(), "re-bundling") {
+		t.Errorf("the re-bundle was not reported:\n%s", out.String())
+	}
+}
+
+// A bundle that survived the boot must not be rebuilt — the guard costs a stat
+// in the common case, which is what makes it affordable at every boot.
+func TestEnsureWebClientBundle_LeavesASurvivingBundleAlone(t *testing.T) {
+	deployDir := t.TempDir()
+	writeBundle(t, deployDir, "// bundled, and Gradle had nothing to do")
+
+	var out bytes.Buffer
+	called := 0
+	rebuilt, err := ensureWebClientBundle(deployDir, &out, func() error {
+		called++
+		return nil
+	})
+	if err != nil || rebuilt || called != 0 {
+		t.Fatalf("re-bundled a bundle that was already there: rebuilt=%v calls=%d err=%v", rebuilt, called, err)
+	}
+	if out.Len() != 0 {
+		t.Errorf("the quiet path should stay quiet, got:\n%s", out.String())
+	}
+}
+
+// A failed re-bundle must name the consequence. The runtime is up and its
+// services answer, so "the app is running" is not the whole truth.
+func TestEnsureWebClientBundle_FailureNamesTheBlankPage(t *testing.T) {
+	deployDir := t.TempDir()
+
+	_, err := ensureWebClientBundle(deployDir, nil, func() error {
+		return errors.New("rollup exploded")
+	})
+	if err == nil {
+		t.Fatal("expected an error")
+	}
+	if !strings.Contains(err.Error(), "blank page") || !strings.Contains(err.Error(), "rollup exploded") {
+		t.Errorf("error should carry both the cause and the symptom, got: %v", err)
+	}
+}
+
+// An empty dist/index.js is the same blank page as a missing one — a truncated
+// write must not read as "bundled".
+func TestWebClientBundled_RejectsAnEmptyBundle(t *testing.T) {
+	deployDir := t.TempDir()
+	writeBundle(t, deployDir, "")
+	if WebClientBundled(deployDir) {
+		t.Error("an empty bundle should not count as bundled")
+	}
+
+	// And a directory called index.js is not a bundle either.
+	other := t.TempDir()
+	if err := os.MkdirAll(filepath.Join(other, "web", "dist", "index.js"), 0o755); err != nil {
+		t.Fatal(err)
+	}
+	if WebClientBundled(other) {
+		t.Error("a directory named index.js should not count as bundled")
+	}
+}
+
+// The second way in: a headless boot (mxcli test --local) destroys a bundle a
+// previous `run --local` left behind. Tests do not need it, so the loss is
+// reported rather than paid for — but it must not be silent, which is what let
+// a test run between a boot and a browser look like a rendering bug.
+func TestReportLostWebClientBundle(t *testing.T) {
+	deployDir := t.TempDir()
+	var out bytes.Buffer
+
+	// Destroyed by this boot: say so, and name the remedy.
+	if !ReportLostWebClientBundle(deployDir, true, &out) {
+		t.Error("a destroyed bundle should be reported")
+	}
+	if !strings.Contains(out.String(), "blank page") || !strings.Contains(out.String(), "mxcli run --local") {
+		t.Errorf("the note should carry the symptom and the fix:\n%s", out.String())
+	}
+
+	// Never there to begin with: not this boot's doing, so nothing to say.
+	out.Reset()
+	if ReportLostWebClientBundle(deployDir, false, &out) || out.Len() > 0 {
+		t.Errorf("an absent bundle this boot did not destroy should be silent:\n%s", out.String())
+	}
+
+	// Survived: silent.
+	out.Reset()
+	writeBundle(t, deployDir, "// survived")
+	if ReportLostWebClientBundle(deployDir, true, &out) || out.Len() > 0 {
+		t.Errorf("a surviving bundle should be silent:\n%s", out.String())
+	}
+}

From 4551a4ea1dfe1b35c36f6919aafc4ffb091e161d Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sat, 8 Aug 2026 23:50:18 +0000
Subject: [PATCH 02/29] fix(describe): put back the page-parameter mapping
 mxcli stores implicitly
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A grid drill-down written as

  linkbutton btnWeekend (Caption: 'Weekend',
    Action: SHOW_PAGE Mod.Race_Weekend(Race: $currentObject))

described back as `show_page Mod.Race_Weekend`, with no argument.

The mapping was never missing from the model. mxcli writes a page action's
ParameterMappings as an empty array on purpose: Studio Pro infers the current
row object from the enclosing widget, and an explicit mapping whose Argument is
"$currentObject" is rejected as CE0115 (#296). That decision stands. What was
missing is its other half — DESCRIBE read only explicit mappings, so the
implicit argument had nowhere to come from. The writer's comment claimed
DESCRIBE recovered it; it did not, and now it does.

The cost is not cosmetic. DESCRIBE is what you reach for once you have stopped
trusting the model, so its output arrives already looking like a conclusion: the
mapping was dropped, that is why the page gets an empty object. It is a
plausible, wrong answer at the worst possible moment, and it cost three
debugging cycles replacing a button that was correct.

Recovery reads the target page's own declared parameters, since that is where
the information lives. Both ends are guarded: an explicit mapping still wins,
and an unresolvable page yields no arguments rather than invented ones.

Control: with recovery removed the test reproduces the reported output verbatim.

mxcli-formula1 §39
---
 .claude/skills/fix-issue.md                   |   1 +
 mdl/executor/cmd_pages_describe_output.go     |  68 +++++++++-
 .../cmd_pages_describe_pageparams_test.go     | 126 ++++++++++++++++++
 sdk/mpr/writer_widgets_action.go              |   8 +-
 4 files changed, 199 insertions(+), 4 deletions(-)
 create mode 100644 mdl/executor/cmd_pages_describe_pageparams_test.go

diff --git a/.claude/skills/fix-issue.md b/.claude/skills/fix-issue.md
index 3d90b651d..f4fc96a8b 100644
--- a/.claude/skills/fix-issue.md
+++ b/.claude/skills/fix-issue.md
@@ -425,3 +425,4 @@ extracting `OffsetExpression`/`LimitExpression`.
 | An app themed dark still shows light-mode drop shadows under the datagrid's filter-operator popover and dropdown filter lists | The generated widget layer re-pointed `.column-selectors` but not the four rules in `_datagrid-filters.scss` that bake the same two-layer shadow. Each already takes its *background* from `--bg-color-secondary`, so Atlas re-colours the panel and leaves the shadow — which is why it reads as a partial fix rather than an untouched widget | `cmd/mxcli/theme/assets/*/files/theme/web/_mxcli-widgets.scss` | **Read the selectors out of the shipped `themesource/`, not the bug report** — the fourth here is `.dropdown-container .dropdown-list`, nested under a parent the report did not name. **Verify in the compiled CSS, never the source** (the §33 rule): apply the theme to a real project, run `mxbuild --target=deploy --java-home=… --java-exe-path=…`, then grep `theme-cache/web/theme.compiled.css` and check the *line number* — the fix must land after the widget module's own rule (30794 vs 27765 here) or the cascade eats it. A theme-cache file older than the SCSS you just wrote is a stale compile, and mtime is the cheapest way to catch it. mxcli-formula1 #33 / suggested issue 4 |
 | A `MOVE` cannot be confirmed and a module's layout cannot be reviewed: `SHOW STRUCTURE` groups by document type at every depth and never names a folder, `DESCRIBE` answers for one document at a time, so checking where things ended up means opening the `.mpr` as SQLite | The read side of folders was simply never built. `MOVE`/`DROP FOLDER` write containment; nothing read it back | New `mdl/executor/cmd_list_folders.go` + grammar (`FOLDERS` lexer token, `showOrList FOLDERS (IN …)?` in `MDLCatalog.g4`, `FOLDERS` added to the `keyword` rule so it stays usable as an identifier), `mdl/ast/ast_query.go`, `mdl/visitor/visitor_query.go`, `mdl/executor/executor_query.go` | **A layout listing must show what is *not* there**: empty folders (`[0]`) and documents still at the module root, or it cannot be diffed against an intended layout — that is the whole use. Documents are indexed by `ContainerID` across every list call the backend offers, each best-effort, so a backend that cannot answer one kind yields a listing missing that kind rather than no listing. **Do not stub the hierarchy in the test** — `mkHierarchy` populates `moduleNames` but not `folderNames`, so `BuildFolderPath` returns `""` and every folder silently collapses into the module root, which looks exactly like the bug. Build it from the mock's `ListModules`/`ListUnits`/`ListFolders`, as `getHierarchy` does. Tests `cmd_list_folders_test.go`, example in `18-folder-examples.mdl`. mxcli-formula1 issue #2 |
 | Every page in a locally-run app is a black screen. `mxcli check` passes, the build reports success, the runtime log is quiet, `curl /` returns 200 with a valid HTML shell, and every OData service answers — only a browser sees it. It also comes and goes between runs of the same command at the same version | `run --local` bundles the browser client at step 5b, then the runtime boot runs Gradle `clean-custom-classes compile package`, whose package pass repopulates `deployment/web` and takes `dist/` with it — deleting the bundle 51 seconds after the same command wrote it. It only bites when Gradle has work to do (a new Java action, a full recompile), which is why the app boots fine for weeks and then stops | `cmd/mxcli/docker/webclient.go` (`WebClientBundled`, `EnsureWebClientBundle`, `ReportLostWebClientBundle`), `cmd/mxcli/docker/runlocal.go` (step 6b, after the boot), `cmd/mxcli/docker/localapp.go` (headless boots warn instead of paying ~30s) | **A pre-condition established before a step that rewrites the same directory is not a post-condition** — verify after, not before. The guard is a `stat` when the bundle survived, which is what makes it affordable at every boot; re-ordering the bundle to after the boot instead would leave the app reachable-but-blank for ~30s on every cold start. **`curl /` returning 200 is not evidence the app renders**: the shell is served by the runtime, the client by a file the shell references. The one-line check is `curl -o /dev/null -w '%{http_code}' <app>/dist/index.js`. **Do not silently pay for a repair on a path that does not need it** — `test --local` destroys the bundle too, but tests are headless, so it prints the loss and the remedy rather than spending 30s on a two-second loop. Tests `webclient_bundle_test.go`; both controls run (guard never fires → the wipe test fails; guard always fires → the survivor test fails). mxcli-formula1 §35 |
+| `DESCRIBE PAGE` reports a drill-down button as `linkbutton b (Caption: 'Weekend', Action: show_page Mod.Page)` — the `(Race: $currentObject)` argument is gone. The model is fine (`mx check` is clean, and an unmapped required page parameter is a consistency error, so it could not have built), but the description reads as a diagnosis mid-hunt and costs cycles fixing a button that was correct | mxcli deliberately writes `ParameterMappings` as an empty array for a page action, because Studio Pro infers the row object from the enclosing widget and rejects an explicit `$currentObject` Argument as CE0115 (#296). That decision was right; its other half was missing. `renderClientActionMDL` read only explicit mappings, and the writer's comment *asserted* DESCRIBE recovered the implicit one — it never did | `mdl/executor/cmd_pages_describe_output.go` (`pageActionParameters`, `targetPageParameterNames`), stale comment corrected in `sdk/mpr/writer_widgets_action.go` | **When a writer stores something implicitly, the reader owes it an explicit reconstruction — and a comment claiming the reader already does is worth nothing until a test says so.** Recover from the *target page's* declared parameters, not from the action, since that is where the information actually lives. Guard both ends: an explicit mapping still wins (recovery fills a gap, it does not override Studio Pro), and an unresolvable page yields no arguments rather than invented ones — a description that omits an argument is recoverable, one that names a parameter that does not exist is not. **A lossy DESCRIBE is costliest exactly when it is most used**, because DESCRIBE is what you reach for once you have stopped trusting the model. Tests `cmd_pages_describe_pageparams_test.go`; the control (explicit-only) reproduces the reported output verbatim. mxcli-formula1 §39 |
diff --git a/mdl/executor/cmd_pages_describe_output.go b/mdl/executor/cmd_pages_describe_output.go
index 563f5882b..3cbff7d17 100644
--- a/mdl/executor/cmd_pages_describe_output.go
+++ b/mdl/executor/cmd_pages_describe_output.go
@@ -1077,7 +1077,7 @@ func renderClientActionMDL(ctx *ExecContext, action map[string]any) string {
 		if formSettings, ok := action["FormSettings"].(map[string]any); ok {
 			if pageName, ok := formSettings["Form"].(string); ok && pageName != "" {
 				result := "show_page " + pageName
-				params := extractPageParameters(ctx, formSettings)
+				params := pageActionParameters(ctx, formSettings, pageName)
 				if params != "" {
 					result += "(" + params + ")"
 				}
@@ -1087,7 +1087,7 @@ func renderClientActionMDL(ctx *ExecContext, action map[string]any) string {
 		if pageSettings, ok := action["PageSettings"].(map[string]any); ok {
 			if pageName, ok := pageSettings["Form"].(string); ok && pageName != "" {
 				result := "show_page " + pageName
-				params := extractPageParameters(ctx, pageSettings)
+				params := pageActionParameters(ctx, pageSettings, pageName)
 				if params != "" {
 					result += "(" + params + ")"
 				}
@@ -1159,6 +1159,70 @@ func getPageQualifiedName(ctx *ExecContext, pageID model.ID) string {
 	return ""
 }
 
+// pageActionParameters renders a SHOW_PAGE action's argument list, recovering the
+// implicit mapping when the model stores none.
+//
+// A page action written by mxcli deliberately stores ParameterMappings as an
+// empty array: Studio Pro infers the current row object from the enclosing
+// widget, and an explicit mapping whose Argument is "$currentObject" is rejected
+// as CE0115 "parameters do not match" (issue #296). Nothing was wrong with that
+// decision — what was missing is its other half. DESCRIBE read only the explicit
+// mappings, so `SHOW_PAGE P(Race: $currentObject)` came back as `show_page P`,
+// and the description read as a diagnosis: the mapping was dropped, that is why
+// the page gets an empty object. It was not dropped, and Mendix could not have
+// built the page if it were — an unmapped required page parameter is a
+// consistency error. Three debugging cycles were spent replacing a button that
+// was correct (mxcli-formula1 §39).
+//
+// DESCRIBE is what you reach for once you have stopped trusting the model, so a
+// lossy DESCRIBE is costliest exactly when it is most used.
+func pageActionParameters(ctx *ExecContext, settings map[string]any, pageName string) string {
+	if explicit := extractPageParameters(ctx, settings); explicit != "" {
+		return explicit
+	}
+	// No stored mapping: the target page's own parameters are the mapping, each
+	// bound to the row object the enclosing widget supplies.
+	var params []string
+	for _, name := range targetPageParameterNames(ctx, pageName) {
+		params = append(params, mdlIdent(name)+": $currentObject")
+	}
+	return strings.Join(params, ", ")
+}
+
+// targetPageParameterNames returns the parameter names declared by a page, by
+// qualified name. Returns nil when the page cannot be resolved — a description
+// that omits an argument is better than one that invents a name.
+func targetPageParameterNames(ctx *ExecContext, qualifiedName string) []string {
+	module, name, ok := strings.Cut(qualifiedName, ".")
+	if !ok || module == "" || name == "" {
+		return nil
+	}
+	allPages, err := ctx.Backend.ListPages()
+	if err != nil {
+		return nil
+	}
+	h, err := getHierarchy(ctx)
+	if err != nil {
+		return nil
+	}
+	for _, p := range allPages {
+		if p == nil || !strings.EqualFold(p.Name, name) {
+			continue
+		}
+		if !strings.EqualFold(h.GetModuleName(h.FindModuleID(p.ContainerID)), module) {
+			continue
+		}
+		var names []string
+		for _, param := range p.Parameters {
+			if param != nil && param.Name != "" {
+				names = append(names, param.Name)
+			}
+		}
+		return names
+	}
+	return nil
+}
+
 // extractPageParameters extracts page parameter mappings from a FormSettings/PageSettings object.
 // Returns formatted string like "Product: $currentObject" or empty string if no params.
 func extractPageParameters(ctx *ExecContext, settings map[string]any) string {
diff --git a/mdl/executor/cmd_pages_describe_pageparams_test.go b/mdl/executor/cmd_pages_describe_pageparams_test.go
new file mode 100644
index 000000000..e9c38459d
--- /dev/null
+++ b/mdl/executor/cmd_pages_describe_pageparams_test.go
@@ -0,0 +1,126 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package executor
+
+import (
+	"testing"
+
+	"github.com/mendixlabs/mxcli/mdl/backend/mock"
+	"github.com/mendixlabs/mxcli/model"
+	"github.com/mendixlabs/mxcli/sdk/pages"
+)
+
+// pageParamFixture builds a module with a target page that declares one
+// parameter — the drill-down page a grid's link button opens.
+func pageParamFixture(t *testing.T, params ...string) *ExecContext {
+	t.Helper()
+	mod := mkModule("Formula1Frontend")
+
+	target := &pages.Page{
+		BaseElement: model.BaseElement{ID: "pg-weekend"},
+		ContainerID: mod.ID,
+		Name:        "Race_Weekend",
+	}
+	for i, p := range params {
+		target.Parameters = append(target.Parameters, &pages.PageParameter{
+			BaseElement: model.BaseElement{ID: model.ID("pp-" + p)},
+			ContainerID: target.ID,
+			Name:        p,
+			IsRequired:  i == 0,
+		})
+	}
+
+	mb := &mock.MockBackend{
+		IsConnectedFunc: func() bool { return true },
+		ListModulesFunc: func() ([]*model.Module, error) { return []*model.Module{mod}, nil },
+		ListPagesFunc:   func() ([]*pages.Page, error) { return []*pages.Page{target}, nil },
+	}
+	ctx, _ := newMockCtx(t, withBackend(mb))
+	return ctx
+}
+
+// showPageAction is the BSON mxcli writes for SHOW_PAGE: ParameterMappings is a
+// deliberately empty array, because Studio Pro infers the row object from the
+// enclosing widget and rejects an explicit "$currentObject" Argument as CE0115.
+func showPageAction(page string, mappings []any) map[string]any {
+	settings := map[string]any{
+		"$Type": "Forms$FormSettings",
+		"Form":  page,
+	}
+	if mappings != nil {
+		settings["ParameterMappings"] = mappings
+	}
+	return map[string]any{
+		"$Type":        "Forms$FormAction",
+		"FormSettings": settings,
+	}
+}
+
+// mxcli-formula1 §39: `SHOW_PAGE P(Race: $currentObject)` described back as
+// `show_page P`. The mapping was never in the model — mxcli stores it implicitly
+// on purpose — but DESCRIBE had no compensating recovery, so its output read as
+// a diagnosis ("the mapping was dropped, that is why the page gets an empty
+// object") in the middle of a hunt for an unrelated bug. Three cycles were spent
+// replacing a button that was correct.
+func TestRenderShowPageAction_RecoversTheImplicitParameter(t *testing.T) {
+	ctx := pageParamFixture(t, "Race")
+
+	got := renderClientActionMDL(ctx, showPageAction("Formula1Frontend.Race_Weekend", nil))
+	want := "show_page Formula1Frontend.Race_Weekend(Race: $currentObject)"
+	if got != want {
+		t.Errorf("DESCRIBE lost the page parameter:\n got: %s\nwant: %s", got, want)
+	}
+}
+
+// A page with several parameters gets all of them, in declaration order.
+func TestRenderShowPageAction_RecoversEveryParameter(t *testing.T) {
+	ctx := pageParamFixture(t, "Race", "Season")
+
+	got := renderClientActionMDL(ctx, showPageAction("Formula1Frontend.Race_Weekend", nil))
+	want := "show_page Formula1Frontend.Race_Weekend(Race: $currentObject, Season: $currentObject)"
+	if got != want {
+		t.Errorf("got:  %s\nwant: %s", got, want)
+	}
+}
+
+// A page that takes no parameters must not grow an argument list.
+func TestRenderShowPageAction_NoParametersStaysBare(t *testing.T) {
+	ctx := pageParamFixture(t)
+
+	got := renderClientActionMDL(ctx, showPageAction("Formula1Frontend.Race_Weekend", nil))
+	if want := "show_page Formula1Frontend.Race_Weekend"; got != want {
+		t.Errorf("got:  %s\nwant: %s", got, want)
+	}
+}
+
+// An unresolvable page yields no arguments rather than invented ones: a
+// description that omits an argument is recoverable, one that names a parameter
+// that does not exist is not.
+func TestRenderShowPageAction_UnknownPageInventsNothing(t *testing.T) {
+	ctx := pageParamFixture(t, "Race")
+
+	got := renderClientActionMDL(ctx, showPageAction("OtherModule.Gone", nil))
+	if want := "show_page OtherModule.Gone"; got != want {
+		t.Errorf("got:  %s\nwant: %s", got, want)
+	}
+}
+
+// An explicit mapping in the model still wins — recovery fills a gap, it does
+// not override what Studio Pro actually stored.
+func TestRenderShowPageAction_ExplicitMappingWins(t *testing.T) {
+	ctx := pageParamFixture(t, "Race")
+
+	mappings := []any{
+		int32(3),
+		map[string]any{
+			"$Type":     "Forms$PageParameterMapping",
+			"Parameter": "Formula1Frontend.Race_Weekend.Race",
+			"Argument":  "$SelectedRace",
+		},
+	}
+	got := renderClientActionMDL(ctx, showPageAction("Formula1Frontend.Race_Weekend", mappings))
+	want := "show_page Formula1Frontend.Race_Weekend(Race: $SelectedRace)"
+	if got != want {
+		t.Errorf("an explicit mapping was overwritten:\n got: %s\nwant: %s", got, want)
+	}
+}
diff --git a/sdk/mpr/writer_widgets_action.go b/sdk/mpr/writer_widgets_action.go
index 4fadebab8..c7ec8942d 100644
--- a/sdk/mpr/writer_widgets_action.go
+++ b/sdk/mpr/writer_widgets_action.go
@@ -86,8 +86,12 @@ func serializeClientAction(action pages.ClientAction) bson.D {
 		// "$currentObject" makes Studio Pro report CE0115 "parameters do not match" — a
 		// widget's current-row object is represented by an inferred WidgetValue, not an
 		// Argument expression (issue #296; re-confirmed against mxbuild 11.12.1 for
-		// FINDINGS #56 — DESCRIBE recovers the implicit $currentObject instead, see
-		// renderClientActionMDL).
+		// FINDINGS #56).
+		//
+		// The other half of this decision lives in DESCRIBE, which must put the
+		// argument back from the target page's own parameters — see
+		// pageActionParameters. It did not, for a long time, and this comment
+		// asserted that it did (mxcli-formula1 §39).
 		formSettings := bson.D{
 			{Key: "$ID", Value: idToBsonBinary(generateUUID())},
 			{Key: "$Type", Value: "Forms$FormSettings"},

From 28ce82130dbcb63b663699f6fdd3f20148feaa3f Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sat, 8 Aug 2026 23:54:54 +0000
Subject: [PATCH 03/29] fix(odata): stop deleting a published service's role
 grants on modify
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`create or modify odata service` silently revoked the service's access, so the
next build failed with "At least one allowed role must be selected for the
published OData service to be accessible." Grants are made by a separate
statement and cannot be re-stated in the create script, so nothing in the
script could put them back — only a manual re-grant, until the next modify.

serializePublishedODataService never wrote AllowedModuleRoles. The document is
serialized wholesale and written with updateUnit, so a field the serializer
omits is not left alone: it is deleted. A wholesale re-serialization makes the
writer's field list a data-retention policy, and this one was missing an entry.

The array uses storage marker 1 (BY_NAME references) — the same shape the
working GRANT path writes via makeMendixStringArray, rather than a marker
reasoned out from an unrelated type.

An earlier pass looked for this loss at model level, found the grants present
and correctly carried through the modify branch, and recorded it as "reported
but does not reproduce". That conclusion was wrong: the loss only exists after
the round trip to BSON, which a model-level check cannot see. The carry-through
guard added then was a no-op; it is kept for a caller that clears the slice, and
its comment now says which layer actually held the bug.

Control: with the field omitted again the test reproduces the empty-grants
document.

mxcli-formula1 §26
---
 .claude/skills/fix-issue.md  |  1 +
 mdl/executor/cmd_odata.go    | 13 ++++---
 sdk/mpr/writer_odata.go      | 17 +++++++++
 sdk/mpr/writer_odata_test.go | 68 ++++++++++++++++++++++++++++++++++++
 4 files changed, 94 insertions(+), 5 deletions(-)

diff --git a/.claude/skills/fix-issue.md b/.claude/skills/fix-issue.md
index f4fc96a8b..dbe856ecf 100644
--- a/.claude/skills/fix-issue.md
+++ b/.claude/skills/fix-issue.md
@@ -426,3 +426,4 @@ extracting `OffsetExpression`/`LimitExpression`.
 | A `MOVE` cannot be confirmed and a module's layout cannot be reviewed: `SHOW STRUCTURE` groups by document type at every depth and never names a folder, `DESCRIBE` answers for one document at a time, so checking where things ended up means opening the `.mpr` as SQLite | The read side of folders was simply never built. `MOVE`/`DROP FOLDER` write containment; nothing read it back | New `mdl/executor/cmd_list_folders.go` + grammar (`FOLDERS` lexer token, `showOrList FOLDERS (IN …)?` in `MDLCatalog.g4`, `FOLDERS` added to the `keyword` rule so it stays usable as an identifier), `mdl/ast/ast_query.go`, `mdl/visitor/visitor_query.go`, `mdl/executor/executor_query.go` | **A layout listing must show what is *not* there**: empty folders (`[0]`) and documents still at the module root, or it cannot be diffed against an intended layout — that is the whole use. Documents are indexed by `ContainerID` across every list call the backend offers, each best-effort, so a backend that cannot answer one kind yields a listing missing that kind rather than no listing. **Do not stub the hierarchy in the test** — `mkHierarchy` populates `moduleNames` but not `folderNames`, so `BuildFolderPath` returns `""` and every folder silently collapses into the module root, which looks exactly like the bug. Build it from the mock's `ListModules`/`ListUnits`/`ListFolders`, as `getHierarchy` does. Tests `cmd_list_folders_test.go`, example in `18-folder-examples.mdl`. mxcli-formula1 issue #2 |
 | Every page in a locally-run app is a black screen. `mxcli check` passes, the build reports success, the runtime log is quiet, `curl /` returns 200 with a valid HTML shell, and every OData service answers — only a browser sees it. It also comes and goes between runs of the same command at the same version | `run --local` bundles the browser client at step 5b, then the runtime boot runs Gradle `clean-custom-classes compile package`, whose package pass repopulates `deployment/web` and takes `dist/` with it — deleting the bundle 51 seconds after the same command wrote it. It only bites when Gradle has work to do (a new Java action, a full recompile), which is why the app boots fine for weeks and then stops | `cmd/mxcli/docker/webclient.go` (`WebClientBundled`, `EnsureWebClientBundle`, `ReportLostWebClientBundle`), `cmd/mxcli/docker/runlocal.go` (step 6b, after the boot), `cmd/mxcli/docker/localapp.go` (headless boots warn instead of paying ~30s) | **A pre-condition established before a step that rewrites the same directory is not a post-condition** — verify after, not before. The guard is a `stat` when the bundle survived, which is what makes it affordable at every boot; re-ordering the bundle to after the boot instead would leave the app reachable-but-blank for ~30s on every cold start. **`curl /` returning 200 is not evidence the app renders**: the shell is served by the runtime, the client by a file the shell references. The one-line check is `curl -o /dev/null -w '%{http_code}' <app>/dist/index.js`. **Do not silently pay for a repair on a path that does not need it** — `test --local` destroys the bundle too, but tests are headless, so it prints the loss and the remedy rather than spending 30s on a two-second loop. Tests `webclient_bundle_test.go`; both controls run (guard never fires → the wipe test fails; guard always fires → the survivor test fails). mxcli-formula1 §35 |
 | `DESCRIBE PAGE` reports a drill-down button as `linkbutton b (Caption: 'Weekend', Action: show_page Mod.Page)` — the `(Race: $currentObject)` argument is gone. The model is fine (`mx check` is clean, and an unmapped required page parameter is a consistency error, so it could not have built), but the description reads as a diagnosis mid-hunt and costs cycles fixing a button that was correct | mxcli deliberately writes `ParameterMappings` as an empty array for a page action, because Studio Pro infers the row object from the enclosing widget and rejects an explicit `$currentObject` Argument as CE0115 (#296). That decision was right; its other half was missing. `renderClientActionMDL` read only explicit mappings, and the writer's comment *asserted* DESCRIBE recovered the implicit one — it never did | `mdl/executor/cmd_pages_describe_output.go` (`pageActionParameters`, `targetPageParameterNames`), stale comment corrected in `sdk/mpr/writer_widgets_action.go` | **When a writer stores something implicitly, the reader owes it an explicit reconstruction — and a comment claiming the reader already does is worth nothing until a test says so.** Recover from the *target page's* declared parameters, not from the action, since that is where the information actually lives. Guard both ends: an explicit mapping still wins (recovery fills a gap, it does not override Studio Pro), and an unresolvable page yields no arguments rather than invented ones — a description that omits an argument is recoverable, one that names a parameter that does not exist is not. **A lossy DESCRIBE is costliest exactly when it is most used**, because DESCRIBE is what you reach for once you have stopped trusting the model. Tests `cmd_pages_describe_pageparams_test.go`; the control (explicit-only) reproduces the reported output verbatim. mxcli-formula1 §39 |
+| `create or modify odata service` silently revokes the service's access; the next build fails with "At least one allowed role must be selected for the published OData service to be accessible." Re-granting fixes it until the next modify | `serializePublishedODataService` never wrote `AllowedModuleRoles`. The document is serialized wholesale and written with `updateUnit`, so a field the serializer omits is not left alone — it is deleted. The grants were read correctly and carried through the executor, then dropped one layer down | `sdk/mpr/writer_odata.go` (`AllowedModuleRoles`, marker 1 / BY_NAME, matching the working `GRANT` path's `makeMendixStringArray`); stale executor comment corrected in `mdl/executor/cmd_odata.go` | **A wholesale re-serialization deletes every field it does not write, so the writer's field list is a data-retention policy.** Audit it against the parser, not against the struct — the round trip is the contract. **Where you look decides what you conclude**: an earlier pass looked for this loss at model level, found the value present and carried, and recorded "reported but does not reproduce" — the loss only exists after the BSON round trip, so a model-level check could never have seen it. When a report says a value disappears, reproduce at the persistence boundary before disbelieving it. For the marker, copy the shape from the code path that already works (`GRANT` writes marker 1 and builds fine) instead of reasoning from an unrelated type. Tests `writer_odata_test.go`; the control (field omitted again) reproduces the empty-grants document. mxcli-formula1 §26 |
diff --git a/mdl/executor/cmd_odata.go b/mdl/executor/cmd_odata.go
index bbdf8034b..dd82768bb 100644
--- a/mdl/executor/cmd_odata.go
+++ b/mdl/executor/cmd_odata.go
@@ -1397,11 +1397,14 @@ func createODataService(ctx *ExecContext, stmt *ast.CreateODataServiceStmt) erro
 					// with "At least one allowed role must be selected for the
 					// published OData service to be accessible."
 					//
-					// A guard, not a fix for an observed defect: the loss was
-					// reported (mxcli-formula1 #26) but did not reproduce on
-					// 11.12.1 — grants survived a modify on both the current and
-					// the previous build. Kept because the invariant is real and
-					// the cost is a slice copy; if it never fires, nothing is lost.
+					// The reported loss (mxcli-formula1 §26) was real, and this
+					// carry-through was never what fixed it: the grants were read
+					// and carried correctly, then dropped one layer down, because
+					// serializePublishedODataService did not write the field at
+					// all. Looking for the loss at model level and concluding "does
+					// not reproduce" was the mistake — the round trip to BSON is
+					// where a wholesale re-serialization deletes what it omits.
+					// Kept as a guard for a caller that clears the slice.
 					if len(svc.AllowedModuleRoles) == 0 && len(existingRoles) > 0 {
 						svc.AllowedModuleRoles = existingRoles
 					}
diff --git a/sdk/mpr/writer_odata.go b/sdk/mpr/writer_odata.go
index e79557311..2dc5ff74c 100644
--- a/sdk/mpr/writer_odata.go
+++ b/sdk/mpr/writer_odata.go
@@ -238,6 +238,22 @@ func (w *Writer) serializePublishedODataService(svc *model.PublishedODataService
 		authTypes = append(authTypes, at)
 	}
 
+	// AllowedModuleRoles: BY_NAME references, storage marker 1 — the same array
+	// shape the working GRANT path writes (makeMendixStringArray).
+	//
+	// This document is serialized wholesale and written with updateUnit, so a
+	// field the serializer omits is not left alone: it is deleted. Omitting it
+	// silently revoked a service's access on every `create or modify`, and the
+	// next build failed with "At least one allowed role must be selected for the
+	// published OData service to be accessible." Grants are made by a separate
+	// statement (`grant access on odata service …`) and cannot be re-stated in
+	// the create script, so nothing in the script could put them back
+	// (mxcli-formula1 §26).
+	allowedRoles := bson.A{int32(1)}
+	for _, name := range svc.AllowedModuleRoles {
+		allowedRoles = append(allowedRoles, name)
+	}
+
 	// Serialize entity types and build ID map for entity set pointers.
 	// Issue #595: key by qualified entity name (et.Entity), not ExposedName.
 	// PublishedEntitySet.EntityTypeName holds the qualified name, so keying
@@ -289,6 +305,7 @@ func (w *Writer) serializePublishedODataService(svc *model.PublishedODataService
 		{Key: "PublishAssociations", Value: svc.PublishAssociations},
 		{Key: "UseGeneralization", Value: svc.UseGeneralization},
 		{Key: "AuthenticationMicroflow", Value: svc.AuthMicroflow},
+		{Key: "AllowedModuleRoles", Value: allowedRoles},
 		{Key: "AuthenticationTypes", Value: authTypes},
 		{Key: "EntityTypes", Value: entityTypes},
 		{Key: "EntitySets", Value: entitySets},
diff --git a/sdk/mpr/writer_odata_test.go b/sdk/mpr/writer_odata_test.go
index fdc446a7e..f2d530258 100644
--- a/sdk/mpr/writer_odata_test.go
+++ b/sdk/mpr/writer_odata_test.go
@@ -389,3 +389,71 @@ func assertField(t *testing.T, m map[string]any, key, expected string) {
 		t.Errorf("field %q: expected %q, got %q", key, expected, s)
 	}
 }
+
+// mxcli-formula1 §26: `create or modify odata service` silently revoked the
+// service's access, and the next build failed with "At least one allowed role
+// must be selected for the published OData service to be accessible."
+//
+// The grants were read correctly and carried through the executor — and then
+// dropped here. This document is serialized wholesale and written with
+// updateUnit, so a field the serializer omits is not left alone, it is deleted.
+// Because grants are made by a separate statement (`grant access on odata
+// service …`) and cannot be re-stated in the create script, nothing in the
+// script could put them back.
+func TestSerializePublishedODataService_KeepsAllowedModuleRoles(t *testing.T) {
+	w := &Writer{}
+	svc := &model.PublishedODataService{
+		BaseElement:        model.BaseElement{ID: "svc-roles"},
+		Name:               "CustomerAPI",
+		ServiceName:        "CustomerAPI",
+		AllowedModuleRoles: []string{"MyModule.User", "MyModule.Admin"},
+	}
+
+	data, err := w.serializePublishedODataService(svc)
+	if err != nil {
+		t.Fatalf("serialize failed: %v", err)
+	}
+	var raw map[string]any
+	if err := bson.Unmarshal(data, &raw); err != nil {
+		t.Fatalf("unmarshal failed: %v", err)
+	}
+
+	// Storage marker 1 (BY_NAME references) — the same array shape the working
+	// GRANT path writes via makeMendixStringArray, and extractBsonArray only
+	// strips markers 2 and 3, so the marker is still element 0 here.
+	roles := extractBsonArray(raw["AllowedModuleRoles"])
+	if len(roles) != 3 {
+		t.Fatalf("AllowedModuleRoles: expected marker + 2 grants, got %v — the service is now inaccessible and the build fails", roles)
+	}
+	if m, _ := roles[0].(int32); m != 1 {
+		t.Errorf("storage marker = %v, want 1 (BY_NAME)", roles[0])
+	}
+	for i, want := range []string{"MyModule.User", "MyModule.Admin"} {
+		if got, _ := roles[i+1].(string); got != want {
+			t.Errorf("role %d = %q, want %q", i, got, want)
+		}
+	}
+}
+
+// A service with no grants must still carry the field, as an empty versioned
+// array — the absence of the key and an empty list are different documents.
+func TestSerializePublishedODataService_EmptyRolesStillWritesTheField(t *testing.T) {
+	w := &Writer{}
+	data, err := w.serializePublishedODataService(&model.PublishedODataService{
+		BaseElement: model.BaseElement{ID: "svc-noroles"},
+		Name:        "Bare",
+	})
+	if err != nil {
+		t.Fatalf("serialize failed: %v", err)
+	}
+	var raw map[string]any
+	if err := bson.Unmarshal(data, &raw); err != nil {
+		t.Fatalf("unmarshal failed: %v", err)
+	}
+	if _, present := raw["AllowedModuleRoles"]; !present {
+		t.Error("AllowedModuleRoles must be present even when empty")
+	}
+	if arr := extractBsonArray(raw["AllowedModuleRoles"]); len(arr) != 1 {
+		t.Errorf("expected the bare marker and no grants, got %v", arr)
+	}
+}

From 01ef224ffe5b1db12f2f30ab80461bba058dd91a Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sat, 8 Aug 2026 23:58:20 +0000
Subject: [PATCH 04/29] fix(init): keep .ai-context/skills/ in step with the
 binary that serves them
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The skills are embedded in mxcli and written exactly once, by `mxcli init`, so
upgrading the binary did nothing to them: a project initialised on Monday still
served Monday's guidance from Tuesday's mxcli, with no warning. Confirmed with a
binary rebuilt at 12:05 beside skills stamped the previous day.

Stale guidance is worse than missing guidance — an agent reads it with the same
confidence either way, and the point of shipping skills inside the binary is
that the two versions agree.

Fixed where the files are consumed rather than where they are authored: the
SessionStart bootstrap script already runs on every session and can fetch the
binary, so it is the one place guaranteed to execute immediately before an agent
reads them. It now runs `mxcli init --sync-skills`, a new flag that refreshes
only .ai-context/skills/ and exits.

Two properties make an every-session job acceptable:

  - it writes only the files that differ, so mtimes keep meaning "when did this
    guidance last move" (a test asserts an unchanged skill is not rewritten);
  - it is silent when the project is already current.

It is never fatal — a skills refresh must not block a session. A test asserts
the bootstrap calls it before the exec'd setup, since a step ordered after an
exec never runs.

Control: with write-once restored, the stale file survives the sync.

mxcli-formula1 §16
---
 .claude/skills/fix-issue.md        |   1 +
 cmd/mxcli/init.go                  |  16 ++++
 cmd/mxcli/init_hook.go             |   7 ++
 cmd/mxcli/init_skills_sync.go      |  87 +++++++++++++++++
 cmd/mxcli/init_skills_sync_test.go | 145 +++++++++++++++++++++++++++++
 5 files changed, 256 insertions(+)
 create mode 100644 cmd/mxcli/init_skills_sync.go
 create mode 100644 cmd/mxcli/init_skills_sync_test.go

diff --git a/.claude/skills/fix-issue.md b/.claude/skills/fix-issue.md
index dbe856ecf..b20627d10 100644
--- a/.claude/skills/fix-issue.md
+++ b/.claude/skills/fix-issue.md
@@ -427,3 +427,4 @@ extracting `OffsetExpression`/`LimitExpression`.
 | Every page in a locally-run app is a black screen. `mxcli check` passes, the build reports success, the runtime log is quiet, `curl /` returns 200 with a valid HTML shell, and every OData service answers — only a browser sees it. It also comes and goes between runs of the same command at the same version | `run --local` bundles the browser client at step 5b, then the runtime boot runs Gradle `clean-custom-classes compile package`, whose package pass repopulates `deployment/web` and takes `dist/` with it — deleting the bundle 51 seconds after the same command wrote it. It only bites when Gradle has work to do (a new Java action, a full recompile), which is why the app boots fine for weeks and then stops | `cmd/mxcli/docker/webclient.go` (`WebClientBundled`, `EnsureWebClientBundle`, `ReportLostWebClientBundle`), `cmd/mxcli/docker/runlocal.go` (step 6b, after the boot), `cmd/mxcli/docker/localapp.go` (headless boots warn instead of paying ~30s) | **A pre-condition established before a step that rewrites the same directory is not a post-condition** — verify after, not before. The guard is a `stat` when the bundle survived, which is what makes it affordable at every boot; re-ordering the bundle to after the boot instead would leave the app reachable-but-blank for ~30s on every cold start. **`curl /` returning 200 is not evidence the app renders**: the shell is served by the runtime, the client by a file the shell references. The one-line check is `curl -o /dev/null -w '%{http_code}' <app>/dist/index.js`. **Do not silently pay for a repair on a path that does not need it** — `test --local` destroys the bundle too, but tests are headless, so it prints the loss and the remedy rather than spending 30s on a two-second loop. Tests `webclient_bundle_test.go`; both controls run (guard never fires → the wipe test fails; guard always fires → the survivor test fails). mxcli-formula1 §35 |
 | `DESCRIBE PAGE` reports a drill-down button as `linkbutton b (Caption: 'Weekend', Action: show_page Mod.Page)` — the `(Race: $currentObject)` argument is gone. The model is fine (`mx check` is clean, and an unmapped required page parameter is a consistency error, so it could not have built), but the description reads as a diagnosis mid-hunt and costs cycles fixing a button that was correct | mxcli deliberately writes `ParameterMappings` as an empty array for a page action, because Studio Pro infers the row object from the enclosing widget and rejects an explicit `$currentObject` Argument as CE0115 (#296). That decision was right; its other half was missing. `renderClientActionMDL` read only explicit mappings, and the writer's comment *asserted* DESCRIBE recovered the implicit one — it never did | `mdl/executor/cmd_pages_describe_output.go` (`pageActionParameters`, `targetPageParameterNames`), stale comment corrected in `sdk/mpr/writer_widgets_action.go` | **When a writer stores something implicitly, the reader owes it an explicit reconstruction — and a comment claiming the reader already does is worth nothing until a test says so.** Recover from the *target page's* declared parameters, not from the action, since that is where the information actually lives. Guard both ends: an explicit mapping still wins (recovery fills a gap, it does not override Studio Pro), and an unresolvable page yields no arguments rather than invented ones — a description that omits an argument is recoverable, one that names a parameter that does not exist is not. **A lossy DESCRIBE is costliest exactly when it is most used**, because DESCRIBE is what you reach for once you have stopped trusting the model. Tests `cmd_pages_describe_pageparams_test.go`; the control (explicit-only) reproduces the reported output verbatim. mxcli-formula1 §39 |
 | `create or modify odata service` silently revokes the service's access; the next build fails with "At least one allowed role must be selected for the published OData service to be accessible." Re-granting fixes it until the next modify | `serializePublishedODataService` never wrote `AllowedModuleRoles`. The document is serialized wholesale and written with `updateUnit`, so a field the serializer omits is not left alone — it is deleted. The grants were read correctly and carried through the executor, then dropped one layer down | `sdk/mpr/writer_odata.go` (`AllowedModuleRoles`, marker 1 / BY_NAME, matching the working `GRANT` path's `makeMendixStringArray`); stale executor comment corrected in `mdl/executor/cmd_odata.go` | **A wholesale re-serialization deletes every field it does not write, so the writer's field list is a data-retention policy.** Audit it against the parser, not against the struct — the round trip is the contract. **Where you look decides what you conclude**: an earlier pass looked for this loss at model level, found the value present and carried, and recorded "reported but does not reproduce" — the loss only exists after the BSON round trip, so a model-level check could never have seen it. When a report says a value disappears, reproduce at the persistence boundary before disbelieving it. For the marker, copy the shape from the code path that already works (`GRANT` writes marker 1 and builds fine) instead of reasoning from an unrelated type. Tests `writer_odata_test.go`; the control (field omitted again) reproduces the empty-grants document. mxcli-formula1 §26 |
+| `.ai-context/skills/` still carries the previous release's guidance after the mxcli binary is upgraded — binary rebuilt at 12:05, skills stamped the day before — with no warning that they disagree | The skills are embedded in the binary and written exactly once, by `mxcli init`. Nothing re-ran init on upgrade, and nothing compared what was on disk against what the binary carried | New `cmd/mxcli/init_skills_sync.go` (`syncAIContextSkills`, `reportSkillSync`), `--sync-skills` flag in `cmd/mxcli/init.go`, and a sync step in the SessionStart bootstrap in `cmd/mxcli/init_hook.go` | **Stale guidance is worse than missing guidance**, because an agent reads it with identical confidence either way — so the failure mode is silent and confident. Fix it where it is consumed, not where it is authored: the SessionStart bootstrap already runs on every session and can fetch the binary, so it is the one place guaranteed to execute immediately before an agent reads the files. Two properties keep an every-session job acceptable: **write only what differs** (an mtime that moves every session makes "when did this last change" unanswerable — a test asserts the mtime holds) and **stay silent when current**. Never fatal: a skills refresh must not block a session, hence `|| true`. A test asserts the bootstrap script actually calls it *before* the exec'd setup, since a step ordered after an `exec` never runs. Tests `init_skills_sync_test.go`; the control (write-once) leaves the stale file in place. mxcli-formula1 §16 |
diff --git a/cmd/mxcli/init.go b/cmd/mxcli/init.go
index ca43f9a5c..1ed8d93cf 100644
--- a/cmd/mxcli/init.go
+++ b/cmd/mxcli/init.go
@@ -22,6 +22,7 @@ var (
 	initAllTools         bool
 	initListTools        bool
 	initContainerRuntime string
+	initSyncSkills       bool
 )
 
 const mendixGitignore = `# Mendix project
@@ -135,6 +136,20 @@ Container Runtime:
 			os.Exit(1)
 		}
 
+		// --sync-skills: refresh only the embedded skills and exit. The rest of
+		// init is interactive-ish and writes tool configs; this is the part that
+		// must follow a binary upgrade, and the SessionStart bootstrap runs it
+		// unattended on every session (mxcli-formula1 §16).
+		if initSyncSkills {
+			res, err := syncAIContextSkills(absDir)
+			if err != nil {
+				fmt.Fprintf(os.Stderr, "Error syncing skills: %v\n", err)
+				os.Exit(1)
+			}
+			reportSkillSync(os.Stdout, res)
+			return
+		}
+
 		// Find .mpr file. With none here, look one level down: a solution repo
 		// keeps each app in its own folder, and running `mxcli init` from the
 		// root used to write everything at the root against an invented
@@ -696,6 +711,7 @@ func init() {
 	initCmd.Flags().BoolVar(&initAllTools, "all-tools", false, "Initialize for all supported AI tools")
 	initCmd.Flags().BoolVar(&initListTools, "list-tools", false, "List supported AI tools and exit")
 	initCmd.Flags().StringVar(&initContainerRuntime, "container-runtime", "docker", "Container runtime for devcontainer (docker or podman)")
+	initCmd.Flags().BoolVar(&initSyncSkills, "sync-skills", false, "Refresh .ai-context/skills/ from this binary and exit (quiet when already current)")
 }
 
 // findMprFilesInSubdirs returns the .mpr files one level below dir, sorted, so
diff --git a/cmd/mxcli/init_hook.go b/cmd/mxcli/init_hook.go
index 007f740a6..dd1ea962d 100644
--- a/cmd/mxcli/init_hook.go
+++ b/cmd/mxcli/init_hook.go
@@ -66,6 +66,13 @@ if [ ! -x ./mxcli ]; then
   chmod +x ./mxcli
 fi
 
+# Keep .ai-context/skills/ in step with this binary. The skills are embedded in
+# mxcli and written once by 'mxcli init', so upgrading the binary used to leave
+# yesterday's guidance in place with no warning — and an agent reads stale
+# guidance with the same confidence as current guidance. Quiet when already
+# current; never fatal, since a skills refresh must not block the session.
+./mxcli init --sync-skills . || true
+
 exec ./mxcli run --local --setup --ensure-db -p "$MPR"
 `
 
diff --git a/cmd/mxcli/init_skills_sync.go b/cmd/mxcli/init_skills_sync.go
new file mode 100644
index 000000000..bdf188396
--- /dev/null
+++ b/cmd/mxcli/init_skills_sync.go
@@ -0,0 +1,87 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package main
+
+import (
+	"bytes"
+	"fmt"
+	"io"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"sort"
+)
+
+// init_skills_sync.go keeps a project's .ai-context/skills/ in step with the
+// mxcli binary that serves it.
+//
+// The skills are embedded in the binary and written once by `mxcli init`.
+// Upgrading the binary therefore did nothing to them: a project initialised on
+// Monday still served Monday's guidance from Tuesday's mxcli, with no warning —
+// confirmed with a binary rebuilt at 12:05 beside skills stamped the previous
+// day (mxcli-formula1 §16). Stale guidance is worse than missing guidance,
+// because an agent reads it with the same confidence either way, and the whole
+// point of shipping skills in the binary is that the two versions agree.
+//
+// These files are generated, never user-edited (the sources live in the mxcli
+// repo), so refreshing is a copy, not a merge. The SessionStart bootstrap script
+// runs it on every session — the moment before an agent would read them.
+
+// skillSyncResult reports what a refresh did.
+type skillSyncResult struct {
+	Total   int      // skills the binary carries
+	Changed []string // names whose on-disk content differed (added or updated)
+}
+
+// Stale reports whether anything on disk disagreed with the binary.
+func (r skillSyncResult) Stale() bool { return len(r.Changed) > 0 }
+
+// syncAIContextSkills rewrites <projectDir>/.ai-context/skills/ from the binary's
+// embedded copies, reporting which files differed. Writing only the files that
+// changed keeps mtimes meaningful, so "when did this guidance last move" stays
+// answerable from the filesystem.
+func syncAIContextSkills(projectDir string) (skillSyncResult, error) {
+	var res skillSyncResult
+	skillsDir := filepath.Join(projectDir, ".ai-context", "skills")
+
+	entries, err := fs.ReadDir(skillsFS, "skills")
+	if err != nil {
+		return res, fmt.Errorf("reading embedded skills: %w", err)
+	}
+	if err := os.MkdirAll(skillsDir, 0o755); err != nil {
+		return res, fmt.Errorf("creating %s: %w", skillsDir, err)
+	}
+
+	for _, e := range entries {
+		if e.IsDir() {
+			continue
+		}
+		want, err := skillsFS.ReadFile("skills/" + e.Name())
+		if err != nil {
+			return res, fmt.Errorf("reading embedded skill %s: %w", e.Name(), err)
+		}
+		res.Total++
+
+		target := filepath.Join(skillsDir, e.Name())
+		if have, readErr := os.ReadFile(target); readErr == nil && bytes.Equal(have, want) {
+			continue
+		}
+		if err := os.WriteFile(target, want, 0o644); err != nil {
+			return res, fmt.Errorf("writing %s: %w", target, err)
+		}
+		res.Changed = append(res.Changed, e.Name())
+	}
+	sort.Strings(res.Changed)
+	return res, nil
+}
+
+// reportSkillSync prints a one-line summary, and nothing at all when the project
+// was already current — this runs on every session start, so silence is the
+// common case and the only acceptable one.
+func reportSkillSync(w io.Writer, res skillSyncResult) {
+	if !res.Stale() {
+		return
+	}
+	fmt.Fprintf(w, "Refreshed %d of %d skill file(s) in .ai-context/skills/ to match this mxcli: %v\n",
+		len(res.Changed), res.Total, res.Changed)
+}
diff --git a/cmd/mxcli/init_skills_sync_test.go b/cmd/mxcli/init_skills_sync_test.go
new file mode 100644
index 000000000..d53ffb1f9
--- /dev/null
+++ b/cmd/mxcli/init_skills_sync_test.go
@@ -0,0 +1,145 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package main
+
+import (
+	"bytes"
+	"io/fs"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// embeddedSkillNames returns the skills this binary carries.
+func embeddedSkillNames(t *testing.T) []string {
+	t.Helper()
+	entries, err := fs.ReadDir(skillsFS, "skills")
+	if err != nil {
+		t.Fatalf("reading embedded skills: %v", err)
+	}
+	var names []string
+	for _, e := range entries {
+		if !e.IsDir() {
+			names = append(names, e.Name())
+		}
+	}
+	if len(names) == 0 {
+		t.Fatal("no embedded skills; the embed directive is broken")
+	}
+	return names
+}
+
+// mxcli-formula1 §16: a project initialised on Monday still served Monday's
+// skills from Tuesday's binary — the files are written once by `mxcli init` and
+// nothing re-wrote them on upgrade. Stale guidance, no warning.
+func TestSyncAIContextSkills_RefreshesStaleGuidance(t *testing.T) {
+	dir := t.TempDir()
+	names := embeddedSkillNames(t)
+
+	// A project initialised by an older binary: the file exists, with content
+	// that binary shipped.
+	skillsDir := filepath.Join(dir, ".ai-context", "skills")
+	if err := os.MkdirAll(skillsDir, 0o755); err != nil {
+		t.Fatal(err)
+	}
+	stale := filepath.Join(skillsDir, names[0])
+	if err := os.WriteFile(stale, []byte("# guidance from an older mxcli\n"), 0o644); err != nil {
+		t.Fatal(err)
+	}
+
+	res, err := syncAIContextSkills(dir)
+	if err != nil {
+		t.Fatalf("sync failed: %v", err)
+	}
+	if !res.Stale() {
+		t.Fatal("the stale file was not detected")
+	}
+	if res.Total != len(names) {
+		t.Errorf("Total = %d, want %d", res.Total, len(names))
+	}
+
+	// Every embedded skill now matches the binary, not just the one that existed.
+	for _, n := range names {
+		want, err := skillsFS.ReadFile("skills/" + n)
+		if err != nil {
+			t.Fatal(err)
+		}
+		got, err := os.ReadFile(filepath.Join(skillsDir, n))
+		if err != nil {
+			t.Fatalf("%s missing after sync: %v", n, err)
+		}
+		if !bytes.Equal(got, want) {
+			t.Errorf("%s still disagrees with the binary", n)
+		}
+	}
+
+	var out bytes.Buffer
+	reportSkillSync(&out, res)
+	if !strings.Contains(out.String(), names[0]) {
+		t.Errorf("the refresh should name what it changed:\n%s", out.String())
+	}
+}
+
+// This runs on every session start, so an up-to-date project must be silent and
+// must not rewrite files — an mtime that moves on every session makes "when did
+// this guidance last change" unanswerable.
+func TestSyncAIContextSkills_CurrentProjectIsSilentAndUntouched(t *testing.T) {
+	dir := t.TempDir()
+
+	first, err := syncAIContextSkills(dir)
+	if err != nil {
+		t.Fatalf("first sync failed: %v", err)
+	}
+	if len(first.Changed) != first.Total {
+		t.Fatalf("a fresh project should write every skill: %d of %d", len(first.Changed), first.Total)
+	}
+
+	skillsDir := filepath.Join(dir, ".ai-context", "skills")
+	probe := filepath.Join(skillsDir, first.Changed[0])
+	before, err := os.Stat(probe)
+	if err != nil {
+		t.Fatal(err)
+	}
+
+	second, err := syncAIContextSkills(dir)
+	if err != nil {
+		t.Fatalf("second sync failed: %v", err)
+	}
+	if second.Stale() {
+		t.Errorf("a current project reported changes: %v", second.Changed)
+	}
+
+	after, err := os.Stat(probe)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if !after.ModTime().Equal(before.ModTime()) {
+		t.Error("an unchanged skill was rewritten; mtime no longer means anything")
+	}
+
+	var out bytes.Buffer
+	reportSkillSync(&out, second)
+	if out.Len() != 0 {
+		t.Errorf("the common path must be silent, got:\n%s", out.String())
+	}
+}
+
+// The SessionStart bootstrap must actually run the sync, or the fix ships
+// without the thing that triggers it.
+func TestBootstrapScript_SyncsSkillsBeforeSetup(t *testing.T) {
+	script := bootstrapScriptTemplate
+	sync := strings.Index(script, "init --sync-skills")
+	setup := strings.Index(script, "run --local --setup")
+	switch {
+	case sync < 0:
+		t.Fatal("the bootstrap script does not refresh skills")
+	case setup < 0:
+		t.Fatal("the bootstrap script no longer runs setup")
+	case sync > setup:
+		t.Error("skills are refreshed after the exec'd setup, so never")
+	}
+	if !strings.Contains(script[sync:], "|| true") {
+		t.Error("a failed skills refresh must not block the session")
+	}
+}

From 054f780a74c2fc976c38cd1a43780a57a951df13 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 9 Aug 2026 00:04:29 +0000
Subject: [PATCH 05/29] fix(odata): publish the query-option opt-out instead of
 always claiming true
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`publish entity … (TopSupported: No)` parsed, described back as No, and
published as Yes: serializeEntitySet hardcoded all three QueryOptions to true
and never read the *bool fields the model already carried. The AST, model and
DESCRIBE halves of the feature had shipped without the writer half — which is
exactly the shape a DESCRIBE round-trip test cannot catch, since DESCRIBE reads
the model, not the published document.

For a microflow-backed resource this claim is load-bearing rather than
decorative. Mendix applies no query options to a read-microflow resource: it
hands the request to the microflow and returns what comes back. The annotation
is therefore the only thing a client has to go on, and an over-claim is not
cosmetic — a client that believes $top works reads a whole collection as though
it were a page.

nil keeps Mendix's own default of true; only an explicit false opts out, which
is what the model's comment already promised.

Control: with the constants restored the test reproduces the over-claim.

mxcli-formula1 §20
---
 .claude/skills/fix-issue.md  |  1 +
 sdk/mpr/writer_odata.go      | 17 +++++++--
 sdk/mpr/writer_odata_test.go | 69 ++++++++++++++++++++++++++++++++++++
 3 files changed, 84 insertions(+), 3 deletions(-)

diff --git a/.claude/skills/fix-issue.md b/.claude/skills/fix-issue.md
index b20627d10..ecdca9568 100644
--- a/.claude/skills/fix-issue.md
+++ b/.claude/skills/fix-issue.md
@@ -428,3 +428,4 @@ extracting `OffsetExpression`/`LimitExpression`.
 | `DESCRIBE PAGE` reports a drill-down button as `linkbutton b (Caption: 'Weekend', Action: show_page Mod.Page)` — the `(Race: $currentObject)` argument is gone. The model is fine (`mx check` is clean, and an unmapped required page parameter is a consistency error, so it could not have built), but the description reads as a diagnosis mid-hunt and costs cycles fixing a button that was correct | mxcli deliberately writes `ParameterMappings` as an empty array for a page action, because Studio Pro infers the row object from the enclosing widget and rejects an explicit `$currentObject` Argument as CE0115 (#296). That decision was right; its other half was missing. `renderClientActionMDL` read only explicit mappings, and the writer's comment *asserted* DESCRIBE recovered the implicit one — it never did | `mdl/executor/cmd_pages_describe_output.go` (`pageActionParameters`, `targetPageParameterNames`), stale comment corrected in `sdk/mpr/writer_widgets_action.go` | **When a writer stores something implicitly, the reader owes it an explicit reconstruction — and a comment claiming the reader already does is worth nothing until a test says so.** Recover from the *target page's* declared parameters, not from the action, since that is where the information actually lives. Guard both ends: an explicit mapping still wins (recovery fills a gap, it does not override Studio Pro), and an unresolvable page yields no arguments rather than invented ones — a description that omits an argument is recoverable, one that names a parameter that does not exist is not. **A lossy DESCRIBE is costliest exactly when it is most used**, because DESCRIBE is what you reach for once you have stopped trusting the model. Tests `cmd_pages_describe_pageparams_test.go`; the control (explicit-only) reproduces the reported output verbatim. mxcli-formula1 §39 |
 | `create or modify odata service` silently revokes the service's access; the next build fails with "At least one allowed role must be selected for the published OData service to be accessible." Re-granting fixes it until the next modify | `serializePublishedODataService` never wrote `AllowedModuleRoles`. The document is serialized wholesale and written with `updateUnit`, so a field the serializer omits is not left alone — it is deleted. The grants were read correctly and carried through the executor, then dropped one layer down | `sdk/mpr/writer_odata.go` (`AllowedModuleRoles`, marker 1 / BY_NAME, matching the working `GRANT` path's `makeMendixStringArray`); stale executor comment corrected in `mdl/executor/cmd_odata.go` | **A wholesale re-serialization deletes every field it does not write, so the writer's field list is a data-retention policy.** Audit it against the parser, not against the struct — the round trip is the contract. **Where you look decides what you conclude**: an earlier pass looked for this loss at model level, found the value present and carried, and recorded "reported but does not reproduce" — the loss only exists after the BSON round trip, so a model-level check could never have seen it. When a report says a value disappears, reproduce at the persistence boundary before disbelieving it. For the marker, copy the shape from the code path that already works (`GRANT` writes marker 1 and builds fine) instead of reasoning from an unrelated type. Tests `writer_odata_test.go`; the control (field omitted again) reproduces the empty-grants document. mxcli-formula1 §26 |
 | `.ai-context/skills/` still carries the previous release's guidance after the mxcli binary is upgraded — binary rebuilt at 12:05, skills stamped the day before — with no warning that they disagree | The skills are embedded in the binary and written exactly once, by `mxcli init`. Nothing re-ran init on upgrade, and nothing compared what was on disk against what the binary carried | New `cmd/mxcli/init_skills_sync.go` (`syncAIContextSkills`, `reportSkillSync`), `--sync-skills` flag in `cmd/mxcli/init.go`, and a sync step in the SessionStart bootstrap in `cmd/mxcli/init_hook.go` | **Stale guidance is worse than missing guidance**, because an agent reads it with identical confidence either way — so the failure mode is silent and confident. Fix it where it is consumed, not where it is authored: the SessionStart bootstrap already runs on every session and can fetch the binary, so it is the one place guaranteed to execute immediately before an agent reads the files. Two properties keep an every-session job acceptable: **write only what differs** (an mtime that moves every session makes "when did this last change" unanswerable — a test asserts the mtime holds) and **stay silent when current**. Never fatal: a skills refresh must not block a session, hence `|| true`. A test asserts the bootstrap script actually calls it *before* the exec'd setup, since a step ordered after an `exec` never runs. Tests `init_skills_sync_test.go`; the control (write-once) leaves the stale file in place. mxcli-formula1 §16 |
+| `publish entity … (TopSupported: No)` (or `SkipSupported`/`Countable`) parses, `DESCRIBE` reads it back as `No`, and the published `$metadata` still advertises `true`. A client then believes paging works when nothing implements it | `serializeEntitySet` hardcoded all three `QueryOptions` to `true`, ignoring the `*bool` fields the model already carried — the AST/model/DESCRIBE half of the feature shipped without the writer half | `sdk/mpr/writer_odata.go` (`boolOrTrue`, entity-set `QueryOptions`) | **A capability annotation on a microflow-backed resource is load-bearing, not decorative.** Mendix applies *no* query options to a read-microflow resource — it hands the request over and returns what comes back — so the annotation is the only thing a client has to go on, and an over-claim is not cosmetic: the client reads a whole collection believing it is a page. **Check the writer whenever a property round-trips correctly through DESCRIBE**: DESCRIBE reads the model, so a model-only feature describes perfectly and publishes wrong, and the round-trip test everyone reaches for cannot see it. A tri-state `*bool` needs an explicit nil policy at the boundary (`nil` = the platform default, only an explicit `false` opts out) or the pointer is pointless. Tests `writer_odata_test.go`; the control (hardcoded true) reproduces the over-claim. mxcli-formula1 §20 |
diff --git a/sdk/mpr/writer_odata.go b/sdk/mpr/writer_odata.go
index 2dc5ff74c..6e2e4f5f1 100644
--- a/sdk/mpr/writer_odata.go
+++ b/sdk/mpr/writer_odata.go
@@ -323,6 +323,10 @@ func (w *Writer) serializePublishedODataService(svc *model.PublishedODataService
 	return marshalUnitIDFirst(doc)
 }
 
+// boolOrTrue resolves a tri-state query option: nil keeps Mendix's default of
+// true, and only an explicit false turns the capability off.
+func boolOrTrue(p *bool) bool { return p == nil || *p }
+
 // serializePublishedEntityType converts a PublishedEntityType to a BSON map.
 func serializePublishedEntityType(et *model.PublishedEntityType) bson.D {
 	// Serialize child members. Pass the owning entity's qualified name so
@@ -361,12 +365,19 @@ func serializePublishedEntitySet(es *model.PublishedEntitySet, entityTypeID stri
 		// entity set to be considered valid. Without it the second
 		// published entity in a multi-entity service fails to resolve
 		// its key (CE6585) — see Studio Pro reference dump.
+		// nil means "not specified" and keeps Mendix's own default of true; only
+		// an explicit false turns one off. These were hardcoded true, so
+		// `publish entity … (TopSupported: No)` parsed, described back as No, and
+		// was published as Yes — mxcli asserting a capability the author had
+		// explicitly disowned. For a microflow-backed resource the claim is
+		// especially load-bearing: Mendix applies no query options itself, so the
+		// annotation is the only thing a client has to go on (mxcli-formula1 §20).
 		{Key: "QueryOptions", Value: bson.D{
 			{Key: "$ID", Value: idToBsonBinary(generateUUID())},
 			{Key: "$Type", Value: "ODataPublish$QueryOptions"},
-			{Key: "Countable", Value: true},
-			{Key: "SkipSupported", Value: true},
-			{Key: "TopSupported", Value: true},
+			{Key: "Countable", Value: boolOrTrue(es.Countable)},
+			{Key: "SkipSupported", Value: boolOrTrue(es.SkipSupported)},
+			{Key: "TopSupported", Value: boolOrTrue(es.TopSupported)},
 		}},
 	}
 
diff --git a/sdk/mpr/writer_odata_test.go b/sdk/mpr/writer_odata_test.go
index f2d530258..8d2b3ea11 100644
--- a/sdk/mpr/writer_odata_test.go
+++ b/sdk/mpr/writer_odata_test.go
@@ -457,3 +457,72 @@ func TestSerializePublishedODataService_EmptyRolesStillWritesTheField(t *testing
 		t.Errorf("expected the bare marker and no grants, got %v", arr)
 	}
 }
+
+// The query-option annotations were hardcoded true, so `publish entity …
+// (TopSupported: No)` parsed, described back as No, and published as Yes.
+//
+// For a microflow-backed resource this claim is load-bearing rather than
+// decorative: Mendix applies no query options itself, so the annotation is the
+// only thing a client has to go on — and a client that believes $top works, when
+// nothing implements it, silently reads a whole collection as though it were a
+// page (mxcli-formula1 §20).
+func TestSerializePublishedODataService_HonoursQueryOptionOptOut(t *testing.T) {
+	no := false
+	yes := true
+	w := &Writer{}
+	svc := &model.PublishedODataService{
+		BaseElement: model.BaseElement{ID: "svc-qo"},
+		Name:        "LiveAPI",
+		EntitySets: []*model.PublishedEntitySet{
+			{
+				BaseElement:    model.BaseElement{ID: "es-off"},
+				ExposedName:    "Drivers",
+				EntityTypeName: "M.Driver",
+				Countable:      &no,
+				SkipSupported:  &no,
+				TopSupported:   &no,
+			},
+			{
+				BaseElement:    model.BaseElement{ID: "es-mixed"},
+				ExposedName:    "Races",
+				EntityTypeName: "M.Race",
+				Countable:      &yes,
+				// SkipSupported/TopSupported unspecified: Mendix's default of true.
+			},
+		},
+	}
+
+	data, err := w.serializePublishedODataService(svc)
+	if err != nil {
+		t.Fatalf("serialize failed: %v", err)
+	}
+	var raw map[string]any
+	if err := bson.Unmarshal(data, &raw); err != nil {
+		t.Fatalf("unmarshal failed: %v", err)
+	}
+
+	sets := extractBsonArray(raw["EntitySets"])
+	if len(sets) != 2 {
+		t.Fatalf("expected 2 entity sets, got %d", len(sets))
+	}
+	opts := func(i int) map[string]any {
+		set, _ := sets[i].(map[string]any)
+		qo, _ := set["QueryOptions"].(map[string]any)
+		if qo == nil {
+			t.Fatalf("entity set %d has no QueryOptions", i)
+		}
+		return qo
+	}
+
+	for _, key := range []string{"Countable", "SkipSupported", "TopSupported"} {
+		if v, _ := opts(0)[key].(bool); v {
+			t.Errorf("Drivers.%s = true, but the author said No — mxcli is advertising a capability nothing implements", key)
+		}
+	}
+	// Unspecified must still mean Mendix's default, not false.
+	for _, key := range []string{"Countable", "SkipSupported", "TopSupported"} {
+		if v, _ := opts(1)[key].(bool); !v {
+			t.Errorf("Races.%s = false; unspecified must keep Mendix's default of true", key)
+		}
+	}
+}

From 18795da840a87430dd54802736125ca4fb10d145 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 9 Aug 2026 00:34:43 +0000
Subject: [PATCH 06/29] feat(check): flag a read microflow that cannot keep its
 resource's promises
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A published OData resource backed by a read microflow could silently return
the wrong thing, twice over:

  - `?$top=5` returned the whole collection with a 200, because Mendix applies
    NO query options to a read-microflow resource — it hands over the request
    and returns what comes back. TopSupported/SkipSupported describe the
    microflow, not the platform, and default to true when unspecified.
  - a client re-reading a row it holds sends `?$filter=key eq '…'` unprompted.
    With no branch for it the request falls through to the collection default
    and the client adopts the FIRST row as that object's identity. No error:
    well-formed request, valid collection, correct $count, 200.

Both are promises the service makes on the microflow's behalf, and nothing
checked either. MDL-ODATA02 flags a declared KEY the microflow cannot answer;
MDL-ODATA03 flags capabilities it cannot implement.

The read path has no other way to be safe. Unlike an OData action or an
insert/update/delete microflow, a read microflow has no System.HttpResponse
parameter and cannot answer 400, so declaring `TopSupported: No` is its only
substitute for the refusal it cannot send. That contract is now documented per
capability in odata-data-sharing.md and in `mxcli syntax odata.publish`, which
neither covered before.

Both rules fire on one provable condition — the microflow takes no
System.HttpRequest parameter, so it cannot see a key or a query option at all.
A microflow that does take it gets the benefit of the doubt: proving which
options it parses needs real analysis, and a rule that guesses gets switched
off.

The rule shipped dead once during development: the visitor stores ReadMode as
`MICROFLOW Module.Name` upper-cased and the prefix match was case-sensitive.
Caught by running it against a real script rather than a hand-built AST, and
now pinned by its own test.

Swept mdl-examples/ and the skill MDL blocks for false positives: 0 failures.

mxcli-formula1 §37, §20 (suggested issues 2 and 3)
---
 .claude/skills/fix-issue.md                   |   1 +
 .claude/skills/mendix/odata-data-sharing.md   | 107 ++++++++++
 cmd/mxcli/cmd_check.go                        |   6 +
 cmd/mxcli/syntax/features_integration.go      |  19 +-
 .../doctype-tests/10-odata-examples.mdl       |  73 +++++++
 mdl/executor/validate_odata_read_contract.go  | 187 ++++++++++++++++++
 .../validate_odata_read_contract_test.go      | 143 ++++++++++++++
 7 files changed, 535 insertions(+), 1 deletion(-)
 create mode 100644 mdl/executor/validate_odata_read_contract.go
 create mode 100644 mdl/executor/validate_odata_read_contract_test.go

diff --git a/.claude/skills/fix-issue.md b/.claude/skills/fix-issue.md
index ecdca9568..dbf8db33b 100644
--- a/.claude/skills/fix-issue.md
+++ b/.claude/skills/fix-issue.md
@@ -429,3 +429,4 @@ extracting `OffsetExpression`/`LimitExpression`.
 | `create or modify odata service` silently revokes the service's access; the next build fails with "At least one allowed role must be selected for the published OData service to be accessible." Re-granting fixes it until the next modify | `serializePublishedODataService` never wrote `AllowedModuleRoles`. The document is serialized wholesale and written with `updateUnit`, so a field the serializer omits is not left alone — it is deleted. The grants were read correctly and carried through the executor, then dropped one layer down | `sdk/mpr/writer_odata.go` (`AllowedModuleRoles`, marker 1 / BY_NAME, matching the working `GRANT` path's `makeMendixStringArray`); stale executor comment corrected in `mdl/executor/cmd_odata.go` | **A wholesale re-serialization deletes every field it does not write, so the writer's field list is a data-retention policy.** Audit it against the parser, not against the struct — the round trip is the contract. **Where you look decides what you conclude**: an earlier pass looked for this loss at model level, found the value present and carried, and recorded "reported but does not reproduce" — the loss only exists after the BSON round trip, so a model-level check could never have seen it. When a report says a value disappears, reproduce at the persistence boundary before disbelieving it. For the marker, copy the shape from the code path that already works (`GRANT` writes marker 1 and builds fine) instead of reasoning from an unrelated type. Tests `writer_odata_test.go`; the control (field omitted again) reproduces the empty-grants document. mxcli-formula1 §26 |
 | `.ai-context/skills/` still carries the previous release's guidance after the mxcli binary is upgraded — binary rebuilt at 12:05, skills stamped the day before — with no warning that they disagree | The skills are embedded in the binary and written exactly once, by `mxcli init`. Nothing re-ran init on upgrade, and nothing compared what was on disk against what the binary carried | New `cmd/mxcli/init_skills_sync.go` (`syncAIContextSkills`, `reportSkillSync`), `--sync-skills` flag in `cmd/mxcli/init.go`, and a sync step in the SessionStart bootstrap in `cmd/mxcli/init_hook.go` | **Stale guidance is worse than missing guidance**, because an agent reads it with identical confidence either way — so the failure mode is silent and confident. Fix it where it is consumed, not where it is authored: the SessionStart bootstrap already runs on every session and can fetch the binary, so it is the one place guaranteed to execute immediately before an agent reads the files. Two properties keep an every-session job acceptable: **write only what differs** (an mtime that moves every session makes "when did this last change" unanswerable — a test asserts the mtime holds) and **stay silent when current**. Never fatal: a skills refresh must not block a session, hence `|| true`. A test asserts the bootstrap script actually calls it *before* the exec'd setup, since a step ordered after an `exec` never runs. Tests `init_skills_sync_test.go`; the control (write-once) leaves the stale file in place. mxcli-formula1 §16 |
 | `publish entity … (TopSupported: No)` (or `SkipSupported`/`Countable`) parses, `DESCRIBE` reads it back as `No`, and the published `$metadata` still advertises `true`. A client then believes paging works when nothing implements it | `serializeEntitySet` hardcoded all three `QueryOptions` to `true`, ignoring the `*bool` fields the model already carried — the AST/model/DESCRIBE half of the feature shipped without the writer half | `sdk/mpr/writer_odata.go` (`boolOrTrue`, entity-set `QueryOptions`) | **A capability annotation on a microflow-backed resource is load-bearing, not decorative.** Mendix applies *no* query options to a read-microflow resource — it hands the request over and returns what comes back — so the annotation is the only thing a client has to go on, and an over-claim is not cosmetic: the client reads a whole collection believing it is a page. **Check the writer whenever a property round-trips correctly through DESCRIBE**: DESCRIBE reads the model, so a model-only feature describes perfectly and publishes wrong, and the round-trip test everyone reaches for cannot see it. A tri-state `*bool` needs an explicit nil policy at the boundary (`nil` = the platform default, only an explicit `false` opts out) or the pointer is pointless. Tests `writer_odata_test.go`; the control (hardcoded true) reproduces the over-claim. mxcli-formula1 §20 |
+| A published OData resource backed by a read microflow silently returns the wrong thing: `?$top=5` yields the whole collection with a 200, and a client re-reading a held row by key gets the collection default and adopts the FIRST row as that object's identity. No error anywhere — well-formed request, valid collection, correct `$count`, 200 | Two promises the service makes on the microflow's behalf and nothing checked: the `KEY` in `expose (…)`, and the `TopSupported`/`SkipSupported` annotations (which default to **true** when unspecified). Mendix applies no query options to a read-microflow resource — it hands over the request and returns what comes back | New `mdl/executor/validate_odata_read_contract.go` (MDL-ODATA02 key promise, MDL-ODATA03 capability over-claim), wired in `cmd/mxcli/cmd_check.go`; the response contract documented in `.claude/skills/mendix/odata-data-sharing.md` | **A read microflow cannot answer 400** — unlike an OData action or an insert/update/delete microflow, the read capability has no `System.HttpResponse` parameter ([docs](https://docs.mendix.com/refguide/published-odata-entity/#custom-http-response)). Its contract is therefore *declarative*: declaring `TopSupported: No` is the read path's only substitute for the refusal it cannot send. **Pick a trigger you can prove**: both rules fire only when the microflow takes no `System.HttpRequest` parameter, because then it provably cannot see a key or a query option; a microflow that does take it gets the benefit of the doubt, since proving *which* options it parses needs real analysis and a rule that guesses gets switched off. **Verify a check rule against a real parse, never a hand-built AST** — the visitor stores `ReadMode` as `MICROFLOW Module.Name` **upper-cased**, so a case-sensitive prefix match made the whole rule dead while it still looked right; the casing is now pinned by its own test. Tests `validate_odata_read_contract_test.go`, examples in `10-odata-examples.mdl` (both correct shapes: request-aware, and honestly declared). mxcli-formula1 §37/§20, suggested issues 2 and 3 |
diff --git a/.claude/skills/mendix/odata-data-sharing.md b/.claude/skills/mendix/odata-data-sharing.md
index a61793172..555172595 100644
--- a/.claude/skills/mendix/odata-data-sharing.md
+++ b/.claude/skills/mendix/odata-data-sharing.md
@@ -474,6 +474,113 @@ Two things worth knowing before you write this:
 `PublishAssociations` must stay at its default (Yes) here: a non-persistable
 entity cannot publish its ID, so object-id mode can never build for it.
 
+## HTTP Status Codes and Errors: What Each Capability Can Do
+
+**The read path and the write path have different powers, and the difference is
+the single most expensive thing to get wrong here.** Read this before designing
+any microflow-backed resource.
+
+| Capability | Can set the HTTP status code? | How |
+|---|---|---|
+| OData **action** (published microflow) | **Yes** | add a `System.HttpResponse` parameter |
+| Entity **Insertable / Updatable / Deletable** microflow | **Yes** | add a `System.HttpResponse` parameter |
+| Entity **Readable** microflow | **No** | not offered — the read capability has no documented `HttpResponse` parameter |
+
+Sources: [published-odata-microflow §4](https://docs.mendix.com/refguide/published-odata-microflow/#4-customizing-the-outgoing-http-response),
+[published-odata-entity, custom HTTP response](https://docs.mendix.com/refguide/published-odata-entity/#custom-http-response).
+The custom-response section names Insertable, Updatable and Deletable; the
+Readable section never references it.
+
+### Writing a status code (action / insert / update / delete)
+
+```sql
+create microflow Api.InsertRow (
+  $Row: Api.Row,
+  $HttpResponse: System.HttpResponse
+)
+begin
+  if $Row/RowKey = empty then
+    change $HttpResponse (StatusCode = 400, Content = '{"error":"rowKey is required"}');
+    return;
+  end if;
+  ...
+end;
+```
+
+Three rules the platform imposes:
+
+- **`ReasonPhrase` is ignored.** Setting it is dead code; put the explanation in
+  `Content`.
+- **`204` always produces an empty body.** Setting `Content` alongside it is
+  discarded.
+- **Changing status or content makes the whole response come from
+  `HttpResponse`** — headers included. Changing *only* headers merges them with
+  the defaults instead.
+- `Transfer-Encoding` and `Date` cannot be changed.
+
+### The read path cannot refuse, so it must not over-promise
+
+A read microflow has no way to answer `400`. Its only exits are to throw (a
+blunt `500`) or to return data. That has two consequences, and both are design
+obligations rather than nice-to-haves:
+
+**1. Declare capabilities you do not implement as `No`.** Mendix applies *no*
+query options to a read-microflow resource — it hands over the request and
+returns whatever comes back — so `TopSupported` / `SkipSupported` / `Countable`
+are claims about your microflow, not about the platform. A resource that
+advertises `TopSupported: Yes` and ignores `$top` returns the entire collection
+with a `200`, and the client believes it received a page.
+
+```sql
+publish entity Api.Row as 'Rows' (
+  ReadMode: microflow Api.Read_Rows,
+  -- Only claim what Read_Rows actually parses out of the URI:
+  TopSupported: No,
+  SkipSupported: No,
+  Countable: No
+)
+```
+
+Declaring `No` is the read path's substitute for the `400` it cannot send.
+
+**2. Answer a lookup by your own KEY.** A client holding a row re-reads it by
+key, unprompted, and Mendix's own OData client sends the `$filter` spelling:
+
+```
+?$filter=rowKey eq '1036-c'     ← what the runtime actually sends
+/Rows('1036-c')                 ← bare path key
+/Rows(rowKey='1036-c')          ← named path key
+```
+
+If the microflow parses only its collection filter, the key request falls through
+to the collection default and the client adopts the **first row** as the identity
+of the object it is displaying. There is no error: the request is well-formed,
+the response is a valid collection, the count is right, the status is `200`. Two
+different objects are then on screen at once, and nothing distinguishes them
+until one travels to another page.
+
+So: `expose ( … (KEY) )` is a promise the *service* makes on the *microflow's*
+behalf. Branch key → id → filter → default, or do not declare the KEY.
+
+The request itself always arrives on `System.HttpRequest`:
+
+```sql
+create microflow Api.Read_Rows (
+  $Request:  System.HttpRequest,
+  $Response: System.ODataResponse    -- required while Countable is Yes
+)
+returns List of Api.Row
+begin
+  log info 'URI=' + $Request/Uri;    -- the whole query string, URL-encoded
+  ...
+end;
+```
+
+Mendix validates field names before the microflow runs (`$filter=secretColumn eq 'x'`
+is a `400` from the platform), so the microflow only ever sees names that exist
+in the published metadata. That is defence in depth, not a substitute for a
+whitelist — it constrains the *name*, not what you do with it.
+
 ## Step-by-Step: Read-Write API with Microflow Handlers
 
 For write operations (insert, update, delete), the OData service delegates to microflows that map between the view entity and the underlying persistent entities.
diff --git a/cmd/mxcli/cmd_check.go b/cmd/mxcli/cmd_check.go
index 89705bbb7..2c83275ab 100644
--- a/cmd/mxcli/cmd_check.go
+++ b/cmd/mxcli/cmd_check.go
@@ -183,6 +183,12 @@ Examples:
 		// the model quietly lacked what the author asked for.
 		violations = append(violations, executor.ValidateODataProperties(prog)...)
 
+		// Flag a microflow-backed OData resource whose read microflow cannot keep
+		// the promises the service makes for it. A read microflow has no
+		// System.HttpResponse parameter, so it cannot answer 400 — its contract
+		// has to be declared correctly up front, and nothing else checks that.
+		violations = append(violations, executor.ValidateODataReadContract(prog)...)
+
 		// Flag a page whose widgets point at a page created further down the same
 		// script. `exec` resolves page references in statement order and is not
 		// transactional, so this fails after earlier statements are already
diff --git a/cmd/mxcli/syntax/features_integration.go b/cmd/mxcli/syntax/features_integration.go
index 506a6e8a2..24e6e34d8 100644
--- a/cmd/mxcli/syntax/features_integration.go
+++ b/cmd/mxcli/syntax/features_integration.go
@@ -111,7 +111,24 @@ func init() {
 			"--\n" +
 			"-- While Countable is Yes (the default) the read microflow must take a\n" +
 			"-- $Response: System.ODataResponse parameter and set its Count; with\n" +
-			"-- Countable: No it takes no parameters at all.",
+			"-- Countable: No it takes no parameters at all.\n" +
+			"\n" +
+			"-- HTTP STATUS CODES. An OData action, and an insert/update/delete\n" +
+			"-- microflow, may take a $HttpResponse: System.HttpResponse parameter and\n" +
+			"-- set StatusCode/Content. A READ microflow may not — it cannot answer\n" +
+			"-- 400, so its contract has to be declared correctly instead:\n" +
+			"--\n" +
+			"--   * Mendix applies NO query options to a read-microflow resource. It\n" +
+			"--     returns exactly what the microflow returns, so TopSupported and\n" +
+			"--     SkipSupported describe YOUR microflow. Leaving them unspecified\n" +
+			"--     publishes Yes. Declare No for anything you do not parse.\n" +
+			"--   * A declared KEY promises a lookup by that key. A client holding a\n" +
+			"--     row re-reads it as `?$filter=key eq '…'` on its own; answer it, or\n" +
+			"--     the client adopts the first row of your collection default as that\n" +
+			"--     object's identity, silently and with a 200.\n" +
+			"--\n" +
+			"-- Take a $Request: System.HttpRequest parameter to see the query string.\n" +
+			"-- MDL-ODATA02 and MDL-ODATA03 flag a read microflow that takes none.",
 		Example: "create persistent entity Shop.Customer (\n" +
 			"  Email: string(200) unique error 'unique' required error 'required',\n" +
 			"  Name:  string(200)\n" +
diff --git a/mdl-examples/doctype-tests/10-odata-examples.mdl b/mdl-examples/doctype-tests/10-odata-examples.mdl
index 4e63b5491..10655aa0e 100644
--- a/mdl-examples/doctype-tests/10-odata-examples.mdl
+++ b/mdl-examples/doctype-tests/10-odata-examples.mdl
@@ -539,6 +539,79 @@ begin
 end;
 /
 
+-- ############################################################################
+-- LEVEL 8.75: A microflow-backed resource declares its own contract
+-- ############################################################################
+--
+-- Mendix applies NO query options to a read-microflow resource: it hands the
+-- request to the microflow and returns exactly what comes back. And unlike an
+-- OData action or an insert/update/delete microflow, a read microflow has no
+-- System.HttpResponse parameter, so it cannot answer 400 either.
+--
+-- So the read path's contract is declarative. Two ways to be correct, both
+-- shown here, and MDL-ODATA02/03 flag anything in between.
+
+create non-persistent entity OdTest.LiveRow ( RowKey: string(60), Label: string(200) );
+
+-- (a) Take the request and honour it. mxcli cannot tell WHICH options a
+--     microflow parses, so taking $Request is enough to earn its silence — the
+--     branch key -> filter -> default is the author's job.
+create microflow OdTest.Read_LiveRows (
+  $Request:  System.HttpRequest,
+  $Response: System.ODataResponse
+)
+returns List of OdTest.LiveRow as $Rows
+begin
+  -- $Request/Uri carries the whole query string, URL-encoded:
+  --   ?$filter=rowKey eq '1036-c'   <- a client re-reading a row it holds
+  --   ?$top=20&$skip=40             <- paging the client believes works
+  $Rows = create list of OdTest.LiveRow;
+  return $Rows;
+end;
+/
+
+-- (b) Or declare an honest contract: no KEY to answer, no paging claimed.
+create microflow OdTest.Read_AllRows ()
+returns List of OdTest.LiveRow as $Rows
+begin
+  $Rows = create list of OdTest.LiveRow;
+  return $Rows;
+end;
+/
+
+create odata service OdTest.LiveAPI (
+  path: 'odata/live/',
+  version: '1.0.0',
+  ODataVersion: OData4,
+  namespace: 'OdTest.LiveAPI',
+  ServiceName: 'LiveAPI'
+)
+{
+  publish entity OdTest.LiveRow as 'Rows' (
+    ReadMode: microflow OdTest.Read_LiveRows,
+    InsertMode: not_supported, UpdateMode: not_supported, DeleteMode: not_supported
+  )
+  expose ( RowKey as 'rowKey' (KEY), Label as 'label' )
+};
+
+-- The honest variant: nothing is claimed, so nothing is promised. Note there is
+-- no KEY — declaring one would promise a lookup Read_AllRows cannot answer.
+create odata service OdTest.BulkAPI (
+  path: 'odata/bulk/',
+  version: '1.0.0',
+  ODataVersion: OData4,
+  namespace: 'OdTest.BulkAPI',
+  ServiceName: 'BulkAPI'
+)
+{
+  publish entity OdTest.LiveRow as 'AllRows' (
+    ReadMode: microflow OdTest.Read_AllRows,
+    InsertMode: not_supported, UpdateMode: not_supported, DeleteMode: not_supported,
+    Countable: false, TopSupported: false, SkipSupported: false
+  )
+  expose ( RowKey as 'rowKey', Label as 'label' )
+};
+
 -- ############################################################################
 -- LEVEL 8.8: DROP (cleanup)
 -- ############################################################################
diff --git a/mdl/executor/validate_odata_read_contract.go b/mdl/executor/validate_odata_read_contract.go
new file mode 100644
index 000000000..daeaa94f6
--- /dev/null
+++ b/mdl/executor/validate_odata_read_contract.go
@@ -0,0 +1,187 @@
+// SPDX-License-Identifier: Apache-2.0
+
+// Check-time validation of what a microflow-backed OData resource promises.
+//
+// A read microflow cannot refuse a request. Mendix hands it the raw request and
+// returns whatever comes back, and — unlike an OData action or an
+// insert/update/delete microflow — the read capability has no System.HttpResponse
+// parameter, so there is no way to answer 400. Its only exits are to throw (a
+// blunt 500) or to return data.
+//
+// That makes the read path's contract declarative: whatever it cannot do at
+// request time has to be stated up front, in the published metadata. These rules
+// check the statement against the microflow it names.
+//
+// Both fire on one provable condition — the microflow does not take a
+// System.HttpRequest parameter — because without the request it cannot see a
+// key, a $filter, a $top or a $skip at all. A microflow that does take the
+// request gets the benefit of the doubt: proving *which* options it parses would
+// need real analysis, and a rule that guesses is a rule people switch off.
+//
+// mxcli-formula1 §37 (the KEY promise) and §20 (capabilities Mendix does not
+// apply itself).
+package executor
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/mendixlabs/mxcli/mdl/ast"
+	"github.com/mendixlabs/mxcli/mdl/linter"
+)
+
+const (
+	// httpRequestType is the parameter that carries the query string.
+	httpRequestType = "System.HttpRequest"
+	// odataDocsCustomResponse is the reference for what each capability may do.
+	odataDocsCustomResponse = "https://docs.mendix.com/refguide/published-odata-entity/#custom-http-response"
+)
+
+// ValidateODataReadContract flags read microflows that cannot keep the promises
+// their published resource makes for them.
+func ValidateODataReadContract(prog *ast.Program) []linter.Violation {
+	if prog == nil {
+		return nil
+	}
+	flows := microflowsByName(prog)
+
+	var out []linter.Violation
+	for _, stmt := range prog.Statements {
+		svc, ok := stmt.(*ast.CreateODataServiceStmt)
+		if !ok {
+			continue
+		}
+		for _, e := range svc.Entities {
+			if e == nil {
+				continue
+			}
+			mf, named := readModeMicroflow(e.ReadMode)
+			if !named {
+				continue // ReadFromDatabase and friends: Mendix does the work
+			}
+			// Only a microflow defined in this same script can be inspected. A
+			// reference to one that already exists in the project is not
+			// evidence of anything, so say nothing.
+			decl, found := flows[strings.ToLower(mf)]
+			if !found || takesHTTPRequest(decl) {
+				continue
+			}
+			where := fmt.Sprintf("publish entity %s as %q in %s",
+				e.Entity.String(), e.ExposedName, svc.Name.String())
+			out = append(out, keyPromiseViolations(where, e, mf)...)
+			out = append(out, capabilityViolations(where, e, mf)...)
+		}
+	}
+	return out
+}
+
+// keyPromiseViolations flags a declared KEY the read microflow is never told
+// about (MDL-ODATA02).
+func keyPromiseViolations(where string, e *ast.PublishedEntityDef, mf string) []linter.Violation {
+	var keys []string
+	for _, m := range e.Members {
+		if m == nil || !m.IsPartOfKey {
+			continue
+		}
+		// The exposed name is what a client filters on, so that is the name to
+		// put in the message; fall back to the model name when none was given.
+		name := m.ExposedName
+		if name == "" {
+			name = m.Name
+		}
+		keys = append(keys, name)
+	}
+	if len(keys) == 0 {
+		return nil
+	}
+	return []linter.Violation{{
+		RuleID:   "MDL-ODATA02",
+		Severity: linter.SeverityWarning,
+		Message: fmt.Sprintf("%s: declares KEY %s, but %s never sees the request (no %s parameter) and so cannot answer a lookup by that key",
+			where, strings.Join(keys, ", "), mf, httpRequestType),
+		Suggestion: fmt.Sprintf(
+			"A client holding a row re-reads it by key on its own — Mendix's OData client sends `?$filter=%s eq '…'`. "+
+				"With no branch for it the request falls through to the collection default, the client adopts the FIRST row as that object's identity, and there is no error: valid collection, right count, 200. "+
+				"Give %s a `$Request: %s` parameter and branch key → filter → default, or drop the KEY.",
+			keys[0], mf, httpRequestType),
+	}}
+}
+
+// capabilityViolations flags query options advertised to clients that the read
+// microflow cannot implement (MDL-ODATA03).
+func capabilityViolations(where string, e *ast.PublishedEntityDef, mf string) []linter.Violation {
+	// nil means "not specified", which publishes Mendix's default of true — so
+	// silence is a claim, and that is exactly what makes this worth flagging.
+	var claimed []string
+	if boolOrTrueAST(e.TopSupported) {
+		claimed = append(claimed, "TopSupported")
+	}
+	if boolOrTrueAST(e.SkipSupported) {
+		claimed = append(claimed, "SkipSupported")
+	}
+	if len(claimed) == 0 {
+		return nil
+	}
+	return []linter.Violation{{
+		RuleID:   "MDL-ODATA03",
+		Severity: linter.SeverityWarning,
+		Message: fmt.Sprintf("%s: advertises %s, but %s never sees the request (no %s parameter), so no paging is applied",
+			where, strings.Join(claimed, " and "), mf, httpRequestType),
+		Suggestion: fmt.Sprintf(
+			"Mendix applies no query options to a read-microflow resource — it returns exactly what the microflow returns — so these annotations describe %s, not the platform. "+
+				"A client asking for $top=5 gets the whole collection with a 200 and believes it received a page. "+
+				"Either parse them from `$Request/Uri`, or declare `TopSupported: No, SkipSupported: No`. "+
+				"Declaring No is the read path's substitute for the 400 it cannot send: the read capability has no System.HttpResponse parameter (%s).",
+			mf, odataDocsCustomResponse),
+	}}
+}
+
+// microflowsByName indexes the microflows this script defines, lower-cased.
+func microflowsByName(prog *ast.Program) map[string]*ast.CreateMicroflowStmt {
+	out := map[string]*ast.CreateMicroflowStmt{}
+	for _, stmt := range prog.Statements {
+		if mf, ok := stmt.(*ast.CreateMicroflowStmt); ok {
+			out[strings.ToLower(mf.Name.String())] = mf
+		}
+	}
+	return out
+}
+
+// readModeMicroflow extracts the microflow name from a ReadMode, and reports
+// whether the mode names one at all.
+//
+// The visitor stores this as `MICROFLOW Module.Name`, upper-cased, so the prefix
+// is matched case-insensitively — a case-sensitive check silently matched
+// nothing and the whole rule was dead, which is why it is verified against a
+// real parse rather than a hand-built AST.
+func readModeMicroflow(readMode string) (string, bool) {
+	trimmed := strings.TrimSpace(readMode)
+	const prefix = "microflow"
+	if len(trimmed) < len(prefix) || !strings.EqualFold(trimmed[:len(prefix)], prefix) {
+		return "", false
+	}
+	name := strings.TrimSpace(trimmed[len(prefix):])
+	return name, name != ""
+}
+
+// takesHTTPRequest reports whether a microflow can see the request at all. A
+// System.* parameter is a qualified name, which the parser cannot tell apart
+// from an enumeration, so both refs are checked (see CLAUDE.md on the
+// TypeEnumeration/TypeEntity ambiguity).
+func takesHTTPRequest(mf *ast.CreateMicroflowStmt) bool {
+	if mf == nil {
+		return false
+	}
+	for _, p := range mf.Parameters {
+		for _, ref := range []*ast.QualifiedName{p.Type.EntityRef, p.Type.EnumRef} {
+			if ref != nil && strings.EqualFold(ref.String(), httpRequestType) {
+				return true
+			}
+		}
+	}
+	return false
+}
+
+// boolOrTrueAST resolves a tri-state query option: nil publishes Mendix's
+// default of true.
+func boolOrTrueAST(p *bool) bool { return p == nil || *p }
diff --git a/mdl/executor/validate_odata_read_contract_test.go b/mdl/executor/validate_odata_read_contract_test.go
new file mode 100644
index 000000000..0ffd64a91
--- /dev/null
+++ b/mdl/executor/validate_odata_read_contract_test.go
@@ -0,0 +1,143 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package executor
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/mendixlabs/mxcli/mdl/visitor"
+)
+
+// readContractScript builds a service whose read microflow takes params and
+// whose published entity carries entityProps and members.
+func readContractScript(params, entityProps, members string) string {
+	return `create module T;
+create non-persistent entity T.Row (K: string(20));
+
+CREATE MICROFLOW T.Read_Rows (` + params + `)
+  RETURNS List of T.Row AS $Rows
+BEGIN
+  $Rows = CREATE LIST OF T.Row;
+  RETURN $Rows;
+END;
+
+create odata service T.Api (
+  path: 'odata/t/',
+  version: '1.0.0',
+  ODataVersion: OData4,
+  namespace: 'T.Api',
+  ServiceName: 'Api'
+)
+{
+  publish entity T.Row as 'Rows' (
+    ReadMode: microflow T.Read_Rows,
+    InsertMode: not_supported, UpdateMode: not_supported, DeleteMode: not_supported` + entityProps + `
+  )
+  expose ( ` + members + ` )
+};
+`
+}
+
+func odataReadRuleIDs(t *testing.T, script string) []string {
+	t.Helper()
+	prog, errs := visitor.Build(script)
+	if len(errs) > 0 {
+		t.Fatalf("parsing the script: %v", errs)
+	}
+	var ids []string
+	for _, v := range ValidateODataReadContract(prog) {
+		ids = append(ids, v.RuleID)
+	}
+	return ids
+}
+
+func hasODataReadRule(ids []string, id string) bool {
+	for _, got := range ids {
+		if got == id {
+			return true
+		}
+	}
+	return false
+}
+
+// mxcli-formula1 §37: the resource declares a KEY, the read microflow is never
+// told about it, and a client holding a row re-reads it by key — gets the
+// collection default, and adopts the first row as that object's identity. No
+// error: valid collection, right count, 200. Fifteen restart cycles.
+func TestODataReadContract_FlagsAKeyTheMicroflowCannotAnswer(t *testing.T) {
+	ids := odataReadRuleIDs(t, readContractScript(
+		"$Response: System.ODataResponse", "", "K as 'k' (KEY)"))
+	if !hasODataReadRule(ids, "MDL-ODATA02") {
+		t.Errorf("the unanswerable KEY was not flagged, got %v", ids)
+	}
+}
+
+// §20: Mendix applies no query options to a read-microflow resource, so an
+// unspecified TopSupported still publishes `true` and the client believes it
+// received a page when it received the whole collection.
+func TestODataReadContract_FlagsCapabilitiesNothingImplements(t *testing.T) {
+	ids := odataReadRuleIDs(t, readContractScript(
+		"$Response: System.ODataResponse", "", "K as 'k'"))
+	if !hasODataReadRule(ids, "MDL-ODATA03") {
+		t.Errorf("the unimplementable paging claim was not flagged, got %v", ids)
+	}
+	if hasODataReadRule(ids, "MDL-ODATA02") {
+		t.Errorf("no KEY was declared, so the key rule must stay quiet: %v", ids)
+	}
+}
+
+// A microflow that takes the request gets the benefit of the doubt. Proving
+// WHICH options it parses would need real analysis, and a rule that guesses is
+// a rule people switch off.
+func TestODataReadContract_SilentWhenTheMicroflowSeesTheRequest(t *testing.T) {
+	ids := odataReadRuleIDs(t, readContractScript(
+		"$Request: System.HttpRequest, $Response: System.ODataResponse", "", "K as 'k' (KEY)"))
+	if len(ids) != 0 {
+		t.Errorf("a request-aware microflow must not be flagged, got %v", ids)
+	}
+}
+
+// An honest contract — no KEY, capabilities declared off — is the other way to
+// be correct, and is the only one available to a microflow that cannot parse a
+// URI. It must be silent, or the rule punishes the fix it recommends.
+func TestODataReadContract_SilentWhenTheContractIsHonest(t *testing.T) {
+	ids := odataReadRuleIDs(t, readContractScript(
+		"", ",\n    Countable: false, TopSupported: false, SkipSupported: false", "K as 'k'"))
+	if len(ids) != 0 {
+		t.Errorf("an honestly declared resource must not be flagged, got %v", ids)
+	}
+}
+
+// ReadFromDatabase is Mendix's own implementation; the microflow rules do not
+// apply to it at all.
+func TestODataReadContract_IgnoresNonMicroflowReadModes(t *testing.T) {
+	script := strings.Replace(
+		readContractScript("", "", "K as 'k' (KEY)"),
+		"ReadMode: microflow T.Read_Rows", "ReadMode: source", 1)
+	if ids := odataReadRuleIDs(t, script); len(ids) != 0 {
+		t.Errorf("a database-backed resource must not be flagged, got %v", ids)
+	}
+}
+
+// A microflow this script does not define cannot be inspected — it may well
+// take the request. Silence, not a guess.
+func TestODataReadContract_SilentWhenTheMicroflowIsNotInThisScript(t *testing.T) {
+	script := strings.Replace(
+		readContractScript("$Response: System.ODataResponse", "", "K as 'k' (KEY)"),
+		"ReadMode: microflow T.Read_Rows", "ReadMode: microflow Other.Read_Elsewhere", 1)
+	if ids := odataReadRuleIDs(t, script); len(ids) != 0 {
+		t.Errorf("an unknown microflow must not be flagged, got %v", ids)
+	}
+}
+
+// The visitor stores ReadMode as `MICROFLOW Module.Name`, upper-cased. A
+// case-sensitive prefix match made the whole rule dead while every unit test
+// built on a hand-made AST still passed, so the casing is pinned here.
+func TestODataReadContract_MatchesTheVisitorsReadModeCasing(t *testing.T) {
+	name, named := readModeMicroflow("MICROFLOW T.Read_Rows")
+	if !named || name != "T.Read_Rows" {
+		t.Errorf("readModeMicroflow(%q) = (%q, %v); the visitor writes it upper-cased",
+			"MICROFLOW T.Read_Rows", name, named)
+	}
+}

From 6aa7c33ae665a936393f371d630f4a5bdb109139 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 9 Aug 2026 00:52:57 +0000
Subject: [PATCH 07/29] feat(log): drive the runtime's per-node log levels
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Everything logs at INFO, so the detail you need is usually not in the log at
all — and raising the whole runtime to TRACE is unusable on a busy app. The
M2EE admin API has exposed per-node levels all along; nothing in mxcli drove
them.

  mxcli log list [--filter x] [--json]
  mxcli log set <node> <level>
  mxcli log set A=TRACE B=DEBUG        # one admin call, applied together

This was proposed as `mxcli odata trace`, for "what is my published resource
being asked?". It is deliberately not that: set_log_level takes a LIST of nodes
and the runtime reports 57 of them, so the primitive is subsystem-agnostic and a
per-subsystem command would have wrapped it one subsystem at a time. The OData
knowledge lives in the skill instead — including the finding that there is NO
log node for a published OData service (ODataConsume is the client side), so
that particular question still needs a LOG in the read microflow. That gap is
Mendix's.

Every API fact was probed against a live 11.12.1 runtime, because the HTTP
response for an AdminException says only "See logging output for details" — the
real message is in the runtime log:

  - get_log_settings requires one of node/subscriber/sort in params
  - sort accepts exactly "node" and "subscriber"
  - set_log_level takes {"nodes":[{name,level}],"force":bool}
  - force means "allow a node that does not exist yet", and permanently
    registers the name — so it is opt-in and an unknown node is an error by
    default, making a typo an error rather than a setting that never applies
  - an invalid level is refused

A level typo is caught locally with the valid set named, rather than becoming an
AdminException whose detail the caller never sees. "Cannot reach the admin API"
is distinguished from "the runtime refused the request", so the connection hint
does not appear on an unknown-node error and bury the sentence that matters.

Verified end-to-end against a booted runtime: both argument forms, multi-node in
one call, a typo refused, --force accepted, and an unreachable port.

mxcli-formula1 suggested issue 4
---
 .claude/skills/fix-issue.md              |   1 +
 .claude/skills/mendix/analyze-runtime.md |  43 +++++
 cmd/mxcli/cmd_log.go                     | 203 +++++++++++++++++++++++
 cmd/mxcli/cmd_log_test.go                |  84 ++++++++++
 cmd/mxcli/docker/loglevels.go            | 156 +++++++++++++++++
 cmd/mxcli/docker/loglevels_test.go       |  57 +++++++
 6 files changed, 544 insertions(+)
 create mode 100644 cmd/mxcli/cmd_log.go
 create mode 100644 cmd/mxcli/cmd_log_test.go
 create mode 100644 cmd/mxcli/docker/loglevels.go
 create mode 100644 cmd/mxcli/docker/loglevels_test.go

diff --git a/.claude/skills/fix-issue.md b/.claude/skills/fix-issue.md
index dbf8db33b..f8aedabe7 100644
--- a/.claude/skills/fix-issue.md
+++ b/.claude/skills/fix-issue.md
@@ -430,3 +430,4 @@ extracting `OffsetExpression`/`LimitExpression`.
 | `.ai-context/skills/` still carries the previous release's guidance after the mxcli binary is upgraded — binary rebuilt at 12:05, skills stamped the day before — with no warning that they disagree | The skills are embedded in the binary and written exactly once, by `mxcli init`. Nothing re-ran init on upgrade, and nothing compared what was on disk against what the binary carried | New `cmd/mxcli/init_skills_sync.go` (`syncAIContextSkills`, `reportSkillSync`), `--sync-skills` flag in `cmd/mxcli/init.go`, and a sync step in the SessionStart bootstrap in `cmd/mxcli/init_hook.go` | **Stale guidance is worse than missing guidance**, because an agent reads it with identical confidence either way — so the failure mode is silent and confident. Fix it where it is consumed, not where it is authored: the SessionStart bootstrap already runs on every session and can fetch the binary, so it is the one place guaranteed to execute immediately before an agent reads the files. Two properties keep an every-session job acceptable: **write only what differs** (an mtime that moves every session makes "when did this last change" unanswerable — a test asserts the mtime holds) and **stay silent when current**. Never fatal: a skills refresh must not block a session, hence `|| true`. A test asserts the bootstrap script actually calls it *before* the exec'd setup, since a step ordered after an `exec` never runs. Tests `init_skills_sync_test.go`; the control (write-once) leaves the stale file in place. mxcli-formula1 §16 |
 | `publish entity … (TopSupported: No)` (or `SkipSupported`/`Countable`) parses, `DESCRIBE` reads it back as `No`, and the published `$metadata` still advertises `true`. A client then believes paging works when nothing implements it | `serializeEntitySet` hardcoded all three `QueryOptions` to `true`, ignoring the `*bool` fields the model already carried — the AST/model/DESCRIBE half of the feature shipped without the writer half | `sdk/mpr/writer_odata.go` (`boolOrTrue`, entity-set `QueryOptions`) | **A capability annotation on a microflow-backed resource is load-bearing, not decorative.** Mendix applies *no* query options to a read-microflow resource — it hands the request over and returns what comes back — so the annotation is the only thing a client has to go on, and an over-claim is not cosmetic: the client reads a whole collection believing it is a page. **Check the writer whenever a property round-trips correctly through DESCRIBE**: DESCRIBE reads the model, so a model-only feature describes perfectly and publishes wrong, and the round-trip test everyone reaches for cannot see it. A tri-state `*bool` needs an explicit nil policy at the boundary (`nil` = the platform default, only an explicit `false` opts out) or the pointer is pointless. Tests `writer_odata_test.go`; the control (hardcoded true) reproduces the over-claim. mxcli-formula1 §20 |
 | A published OData resource backed by a read microflow silently returns the wrong thing: `?$top=5` yields the whole collection with a 200, and a client re-reading a held row by key gets the collection default and adopts the FIRST row as that object's identity. No error anywhere — well-formed request, valid collection, correct `$count`, 200 | Two promises the service makes on the microflow's behalf and nothing checked: the `KEY` in `expose (…)`, and the `TopSupported`/`SkipSupported` annotations (which default to **true** when unspecified). Mendix applies no query options to a read-microflow resource — it hands over the request and returns what comes back | New `mdl/executor/validate_odata_read_contract.go` (MDL-ODATA02 key promise, MDL-ODATA03 capability over-claim), wired in `cmd/mxcli/cmd_check.go`; the response contract documented in `.claude/skills/mendix/odata-data-sharing.md` | **A read microflow cannot answer 400** — unlike an OData action or an insert/update/delete microflow, the read capability has no `System.HttpResponse` parameter ([docs](https://docs.mendix.com/refguide/published-odata-entity/#custom-http-response)). Its contract is therefore *declarative*: declaring `TopSupported: No` is the read path's only substitute for the refusal it cannot send. **Pick a trigger you can prove**: both rules fire only when the microflow takes no `System.HttpRequest` parameter, because then it provably cannot see a key or a query option; a microflow that does take it gets the benefit of the doubt, since proving *which* options it parses needs real analysis and a rule that guesses gets switched off. **Verify a check rule against a real parse, never a hand-built AST** — the visitor stores `ReadMode` as `MICROFLOW Module.Name` **upper-cased**, so a case-sensitive prefix match made the whole rule dead while it still looked right; the casing is now pinned by its own test. Tests `validate_odata_read_contract_test.go`, examples in `10-odata-examples.mdl` (both correct shapes: request-aware, and honestly declared). mxcli-formula1 §37/§20, suggested issues 2 and 3 |
+| No way to see what a running app's subsystem is doing: everything logs at `INFO`, the detail is not in the log at all, and raising the whole runtime to `TRACE` is unusable on a busy app | Nothing in mxcli drove the runtime's per-node log levels, though the M2EE admin API has exposed them all along | New `cmd/mxcli/docker/loglevels.go` (`GetLogSettings`, `SetLogLevels`, `NormalizeLogLevel`, `MatchLogNodes`), `cmd/mxcli/cmd_log.go` (`mxcli log list` / `log set`), documented in `.claude/skills/mendix/analyze-runtime.md` | **Probe an undocumented API before designing the command around it.** Every fact here came from a live 11.12.1 runtime: `get_log_settings` requires one of `node`/`subscriber`/`sort`; `sort` accepts only `node` and `subscriber`; `set_log_level` takes `{"nodes":[{name,level}],"force":bool}`. **The HTTP response for an AdminException says only "See logging output for details" — the actual message ("Please specify node, subscriber or sort option in params", "Unknown sort option: name", "Unknown LogNode X. Use the 'force' parameter…") is in the runtime log**, so probe with the runtime log open or you learn nothing. `force` means "allow a node that does not exist yet" and **permanently registers the name**, so a typo becomes a real empty node — hence it is opt-in, and an unknown node is an error by default. **Resist the subsystem-specific command**: this was proposed as `mxcli odata trace`, but `set_log_level` takes a list of nodes and the runtime reports 57, so the primitive is generic and the OData knowledge belongs in docs. Distinguish "cannot reach the admin API" from "the runtime refused the request" (`ErrAdminUnreachable`) or the wrong hint buries the real one. Tests `cmd_log_test.go`, `loglevels_test.go`; verified end-to-end against a booted runtime (both arg forms, multi-node, typo refused, `--force` accepted, unreachable port). mxcli-formula1 suggested issue 4 |
diff --git a/.claude/skills/mendix/analyze-runtime.md b/.claude/skills/mendix/analyze-runtime.md
index b2f2397ea..e16d6b977 100644
--- a/.claude/skills/mendix/analyze-runtime.md
+++ b/.claude/skills/mendix/analyze-runtime.md
@@ -44,6 +44,49 @@ Gotchas:
 - A spike in "Executing N database synchronization command(s)" on an *unchanged* model
   is a red flag (see the `create or modify` data-loss class of bug).
 
+### Turning up one subsystem: `mxcli log`
+
+Everything logs at `INFO` by default, so the detail you need usually is not in the
+file at all — and raising the whole runtime to `TRACE` is unusable. Logging is
+publish/subscribe: code publishes to a named **LogNode**, and each node has its
+own level.
+
+```bash
+mxcli log list                          # every node and its level (57 on a blank 11.12 app)
+mxcli log list --filter connectionbus   # narrow it — nobody remembers the exact names
+mxcli log set ConnectionBus_Queries TRACE
+mxcli log set ConnectionBus_Queries=TRACE Connector=DEBUG   # one admin call
+mxcli log set ConnectionBus_Queries INFO                    # put it back
+```
+
+Levels: `NONE CRITICAL ERROR WARNING INFO DEBUG TRACE`.
+
+This needs a **running** app (it goes through the M2EE admin API), and the change
+lasts as long as the process — it is a debugging knob, not project configuration.
+
+Nodes worth knowing:
+
+| Question | Node |
+|---|---|
+| What SQL is being run | `ConnectionBus_Queries` (and `_Retrieve`, `_Update`) |
+| Database sync at startup | `ConnectionBus_Synchronize` |
+| Consumed OData / REST calls | `ODataConsume`, `REST Consume` |
+| Microflow execution | `MicroflowEngine`, `ActionManager` |
+| Scheduled events / queues | `SystemTask`, `TaskQueue` |
+| Java/JS action wiring | `Connector` |
+
+**`--force` creates the node, permanently.** Without it an unknown node is refused,
+which is what you want — a typo should be an error. With it the name is registered
+for the life of the process, so a typo becomes a real (empty) node that shows up in
+`log list` from then on. Use it only to pre-register a node that has not published
+yet.
+
+**There is no log node for a *published* OData service.** `ODataConsume` is the
+client side only. So "what is my published resource being asked?" cannot be
+answered by raising a node — put `LOG INFO 'URI=' + $Request/Uri` in the read
+microflow instead (see `odata-data-sharing.md`). That gap is Mendix's, not
+mxcli's.
+
 ## 2. Metrics — throughput and database pressure
 
 `--metrics` registers a Prometheus registry, served at
diff --git a/cmd/mxcli/cmd_log.go b/cmd/mxcli/cmd_log.go
new file mode 100644
index 000000000..a86bfcf9f
--- /dev/null
+++ b/cmd/mxcli/cmd_log.go
@@ -0,0 +1,203 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package main
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"os"
+	"strings"
+	"text/tabwriter"
+
+	"github.com/mendixlabs/mxcli/cmd/mxcli/docker"
+	"github.com/spf13/cobra"
+)
+
+// cmd_log.go exposes the runtime's log-node levels.
+//
+// This started life as a proposal for `mxcli odata trace`, to answer "what is my
+// published OData resource actually being asked?" — a question that cost an
+// afternoon because the URI is only visible at TRACE across the whole runtime.
+// But `set_log_level` is subsystem-agnostic: it takes a list of nodes, and the
+// runtime this was built against reports 57 of them. A per-subsystem command
+// would have wrapped a generic primitive one subsystem at a time.
+//
+// So the command is generic, and the OData-specific knowledge (which node to
+// raise) lives in the skill instead.
+
+var logCmd = &cobra.Command{
+	Use:   "log",
+	Short: "Inspect and set the runtime's log levels",
+	Long: `Read and change the log level of the running app's log nodes.
+
+Logging inside the Mendix runtime is publish/subscribe: code publishes to a
+named LogNode, and a subscriber records what it receives at or above that node's
+level. Raising one node is how you see a subsystem's detail without drowning in
+everything else — TRACE across the whole runtime is unusable on a busy app.
+
+Levels, most to least severe:
+  NONE  CRITICAL  ERROR  WARNING  INFO  DEBUG  TRACE
+
+This talks to the M2EE admin API, so it needs a running app whose admin port is
+reachable — typically one started by 'mxcli run --local'.
+
+Examples:
+  # What nodes exist, and at what level
+  mxcli log list
+
+  # Just the ones that look relevant
+  mxcli log list --filter connectionbus
+
+  # Raise one node, then put it back
+  mxcli log set ConnectionBus_Queries TRACE
+  mxcli log set ConnectionBus_Queries INFO
+
+  # Several at once — one admin call, applied together
+  mxcli log set ConnectionBus_Queries=TRACE Connector=DEBUG
+
+  # A node that has not published yet (Mendix allows pre-registering a level)
+  mxcli log set MyModule.MyNode TRACE --force`,
+}
+
+var logListCmd = &cobra.Command{
+	Use:   "list",
+	Short: "List log nodes and their current levels",
+	Run: func(cmd *cobra.Command, args []string) {
+		filter, _ := cmd.Flags().GetString("filter")
+		asJSON, _ := cmd.Flags().GetBool("json")
+
+		levels, err := docker.GetLogSettings(logAdminOptions(cmd))
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "Error: %v\n%s", err, logConnectionHint(cmd, err))
+			os.Exit(1)
+		}
+		levels = docker.MatchLogNodes(levels, filter)
+
+		if asJSON {
+			out, _ := json.MarshalIndent(levels, "", "  ")
+			fmt.Println(string(out))
+			return
+		}
+		if len(levels) == 0 {
+			if filter != "" {
+				fmt.Printf("No log node matches %q.\n", filter)
+			} else {
+				fmt.Println("No log nodes reported.")
+			}
+			return
+		}
+		w := tabwriter.NewWriter(os.Stdout, 0, 0, 2, ' ', 0)
+		fmt.Fprintln(w, "NODE\tLEVEL\tSUBSCRIBER")
+		for _, l := range levels {
+			fmt.Fprintf(w, "%s\t%s\t%s\n", l.Node, l.Level, l.Subscriber)
+		}
+		w.Flush()
+		fmt.Printf("\n(%d node/subscriber pair(s))\n", len(levels))
+	},
+}
+
+var logSetCmd = &cobra.Command{
+	Use:   "set <node> <level> | <node>=<level>...",
+	Short: "Set the log level of one or more nodes",
+	Long: `Set the level of one or more log nodes, in a single admin call.
+
+Two spellings, because both read naturally:
+
+  mxcli log set ConnectionBus_Queries TRACE
+  mxcli log set ConnectionBus_Queries=TRACE Connector=DEBUG
+
+An unknown node is refused, so a typo is an error rather than a setting that
+silently never takes effect. Pass --force to set a level for a node that does
+not exist yet — Mendix supports pre-registering one, which is how you capture a
+subsystem's very first messages.`,
+	Args: cobra.MinimumNArgs(1),
+	Run: func(cmd *cobra.Command, args []string) {
+		force, _ := cmd.Flags().GetBool("force")
+
+		levels, err := parseLogSetArgs(args)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "Error: %v\n", err)
+			os.Exit(1)
+		}
+		if err := docker.SetLogLevels(logAdminOptions(cmd), levels, force); err != nil {
+			fmt.Fprintf(os.Stderr, "Error: %v\n%s", err, logConnectionHint(cmd, err))
+			os.Exit(1)
+		}
+		for _, l := range levels {
+			up, _ := docker.NormalizeLogLevel(l.Level)
+			fmt.Printf("%s -> %s\n", l.Node, up)
+		}
+	},
+}
+
+// parseLogSetArgs accepts either `<node> <level>` or repeated `<node>=<level>`.
+// Mixing the two is refused rather than guessed at: `log set A=TRACE B DEBUG`
+// has two readings and neither is obviously right.
+func parseLogSetArgs(args []string) ([]docker.LogNodeLevel, error) {
+	hasPairs := false
+	for _, a := range args {
+		if strings.Contains(a, "=") {
+			hasPairs = true
+		}
+	}
+
+	if !hasPairs {
+		if len(args) != 2 {
+			return nil, fmt.Errorf("expected '<node> <level>' or '<node>=<level>...', got %d argument(s)", len(args))
+		}
+		if _, err := docker.NormalizeLogLevel(args[1]); err != nil {
+			return nil, err
+		}
+		return []docker.LogNodeLevel{{Node: args[0], Level: args[1]}}, nil
+	}
+
+	var out []docker.LogNodeLevel
+	for _, a := range args {
+		node, level, ok := strings.Cut(a, "=")
+		if !ok || node == "" || level == "" {
+			return nil, fmt.Errorf("%q is not '<node>=<level>' — do not mix the two forms in one command", a)
+		}
+		if _, err := docker.NormalizeLogLevel(level); err != nil {
+			return nil, err
+		}
+		out = append(out, docker.LogNodeLevel{Node: node, Level: level})
+	}
+	return out, nil
+}
+
+func logAdminOptions(cmd *cobra.Command) docker.M2EEOptions {
+	host, _ := cmd.Flags().GetString("admin-host")
+	port, _ := cmd.Flags().GetInt("admin-port")
+	pass, _ := cmd.Flags().GetString("admin-pass")
+	return docker.M2EEOptions{Host: host, Port: port, Token: pass, Direct: true}
+}
+
+// logConnectionHint names the most likely cause when nothing is listening — but
+// ONLY then. The runtime rejecting a request (an unknown node, a bad level) is
+// not a connection problem, and telling someone to start an app they clearly
+// already have running buries the sentence that matters.
+func logConnectionHint(cmd *cobra.Command, err error) string {
+	if !errors.Is(err, docker.ErrAdminUnreachable) {
+		return ""
+	}
+	host, _ := cmd.Flags().GetString("admin-host")
+	port, _ := cmd.Flags().GetInt("admin-port")
+	return fmt.Sprintf("  Log levels come from a RUNNING app's admin API (%s:%d).\n"+
+		"  Start one with 'mxcli run --local -p <app.mpr>', or point at another with --admin-host/--admin-port/--admin-pass.\n",
+		host, port)
+}
+
+func init() {
+	logCmd.PersistentFlags().String("admin-host", "127.0.0.1", "M2EE admin API host")
+	logCmd.PersistentFlags().Int("admin-port", 8090, "M2EE admin API port")
+	logCmd.PersistentFlags().String("admin-pass", envOr("MXCLI_ADMIN_PASS", "mxcli-local-dev"), "M2EE admin password")
+
+	logListCmd.Flags().String("filter", "", "Only nodes whose name contains this (case-insensitive)")
+	logListCmd.Flags().Bool("json", false, "Output as JSON")
+	logSetCmd.Flags().Bool("force", false, "Allow a node the runtime does not know yet (it is refused otherwise)")
+
+	logCmd.AddCommand(logListCmd)
+	logCmd.AddCommand(logSetCmd)
+	rootCmd.AddCommand(logCmd)
+}
diff --git a/cmd/mxcli/cmd_log_test.go b/cmd/mxcli/cmd_log_test.go
new file mode 100644
index 000000000..87a710e09
--- /dev/null
+++ b/cmd/mxcli/cmd_log_test.go
@@ -0,0 +1,84 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package main
+
+import (
+	"strings"
+	"testing"
+)
+
+// Both spellings exist because both read naturally, and the two-argument form is
+// what anyone types first.
+func TestParseLogSetArgs_BothForms(t *testing.T) {
+	got, err := parseLogSetArgs([]string{"ConnectionBus_Queries", "TRACE"})
+	if err != nil {
+		t.Fatalf("two-arg form: %v", err)
+	}
+	if len(got) != 1 || got[0].Node != "ConnectionBus_Queries" || got[0].Level != "TRACE" {
+		t.Errorf("two-arg form parsed as %+v", got)
+	}
+
+	got, err = parseLogSetArgs([]string{"A=TRACE", "B=debug"})
+	if err != nil {
+		t.Fatalf("pair form: %v", err)
+	}
+	if len(got) != 2 || got[0].Node != "A" || got[1].Node != "B" || got[1].Level != "debug" {
+		t.Errorf("pair form parsed as %+v", got)
+	}
+}
+
+// `log set A=TRACE B DEBUG` has two readings and neither is obviously right, so
+// it is refused rather than guessed at.
+func TestParseLogSetArgs_RefusesMixedForms(t *testing.T) {
+	_, err := parseLogSetArgs([]string{"A=TRACE", "B", "DEBUG"})
+	if err == nil {
+		t.Fatal("mixed forms should be refused")
+	}
+	if !strings.Contains(err.Error(), "do not mix") {
+		t.Errorf("the error should say why: %v", err)
+	}
+}
+
+// A bad level is caught before the round trip, with the valid set named. The
+// runtime's own rejection ("Unknown LogLevel VERBOSE") reaches the caller as a
+// bare AdminException whose detail is only in the runtime log.
+func TestParseLogSetArgs_RejectsAnUnknownLevelLocally(t *testing.T) {
+	for _, args := range [][]string{
+		{"Connector", "VERBOSE"},
+		{"Connector=VERBOSE"},
+	} {
+		_, err := parseLogSetArgs(args)
+		if err == nil {
+			t.Fatalf("%v: an unknown level should be refused", args)
+		}
+		if !strings.Contains(err.Error(), "TRACE") {
+			t.Errorf("%v: the error should list the valid levels, got %v", args, err)
+		}
+	}
+}
+
+// Levels are case-insensitive on input and upper-cased on the wire, since that
+// is what the runtime accepts.
+func TestParseLogSetArgs_LevelCasing(t *testing.T) {
+	got, err := parseLogSetArgs([]string{"Connector", "trace"})
+	if err != nil {
+		t.Fatalf("lower-case level rejected: %v", err)
+	}
+	if len(got) != 1 {
+		t.Fatalf("got %+v", got)
+	}
+}
+
+// A single argument is neither form; say so rather than reaching the runtime
+// with half a request.
+func TestParseLogSetArgs_RejectsIncompleteInput(t *testing.T) {
+	if _, err := parseLogSetArgs([]string{"Connector"}); err == nil {
+		t.Error("a lone node name should be refused")
+	}
+	if _, err := parseLogSetArgs([]string{"=TRACE"}); err == nil {
+		t.Error("an empty node name should be refused")
+	}
+	if _, err := parseLogSetArgs([]string{"Connector="}); err == nil {
+		t.Error("an empty level should be refused")
+	}
+}
diff --git a/cmd/mxcli/docker/loglevels.go b/cmd/mxcli/docker/loglevels.go
new file mode 100644
index 000000000..db097e96e
--- /dev/null
+++ b/cmd/mxcli/docker/loglevels.go
@@ -0,0 +1,156 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package docker
+
+import (
+	"errors"
+	"fmt"
+	"sort"
+	"strings"
+)
+
+// ErrAdminUnreachable marks a failure to reach the admin API at all, as opposed
+// to the runtime rejecting the request. The two need different advice: "start an
+// app" versus "that node does not exist", and printing both makes the real one
+// harder to see.
+var ErrAdminUnreachable = errors.New("admin API unreachable")
+
+// loglevels.go drives the runtime's log-node levels through the M2EE admin API.
+//
+// Every fact below was established against a live 11.12.1 runtime, because the
+// admin API is barely documented and guesses here are expensive:
+//
+//   - `get_log_settings` exists but REQUIRES one of `node`, `subscriber` or
+//     `sort` in params. With none it answers "Please specify node, subscriber or
+//     sort option in params" — an AdminException, not a usage hint, and the
+//     detail is only in the runtime log rather than the HTTP response.
+//   - `sort` accepts exactly "node" and "subscriber". Everything else
+//     ("name", "all", "level", "nodes", …) is "Unknown sort option".
+//   - `set_log_level` takes `{"nodes":[{"name":…,"level":…}], "force":bool}`.
+//   - `force` means "allow a node that does not exist yet". Without it an
+//     unknown node is REFUSED ("Unknown LogNode X. Use the 'force' parameter…"),
+//     which makes the default the typo-safe one — so mxcli does not pass it
+//     unless asked. Mendix supports pre-registering a level for a node that has
+//     not published yet, which is what force is for.
+//   - An invalid level is refused ("Unknown LogLevel VERBOSE").
+//
+// The response for an AdminException carries no detail ("See logging output for
+// details"), so a failure here is reported with the request that caused it.
+type LogLevel string
+
+// The levels the runtime accepts, most to least severe. Verified against
+// SetLoglevelAction's rejection of anything outside this set.
+var logLevels = []string{"NONE", "CRITICAL", "ERROR", "WARNING", "INFO", "DEBUG", "TRACE"}
+
+// NormalizeLogLevel upper-cases and validates a level, so a typo is caught here
+// with the valid set rather than by an AdminException whose detail is in a log
+// file the caller is not reading.
+func NormalizeLogLevel(level string) (string, error) {
+	up := strings.ToUpper(strings.TrimSpace(level))
+	for _, l := range logLevels {
+		if up == l {
+			return up, nil
+		}
+	}
+	return "", fmt.Errorf("unknown log level %q; valid levels are %s",
+		level, strings.Join(logLevels, ", "))
+}
+
+// LogNodeLevel is one node and its level for a subscriber.
+type LogNodeLevel struct {
+	Node       string
+	Subscriber string
+	Level      string
+}
+
+// GetLogSettings returns every log node with its level, one row per
+// node/subscriber pair, sorted by node then subscriber so output is stable.
+func GetLogSettings(opts M2EEOptions) ([]LogNodeLevel, error) {
+	resp, err := CallM2EE(opts, "get_log_settings", map[string]any{"sort": "node"})
+	if err != nil {
+		return nil, fmt.Errorf("%w: %v", ErrAdminUnreachable, err)
+	}
+	if resp.Result != 0 {
+		return nil, fmt.Errorf("reading log settings: %s", resp.M2EEError())
+	}
+	// feedback is {node: {subscriber: level}}.
+	var out []LogNodeLevel
+	for node, v := range resp.Feedback() {
+		subs, ok := v.(map[string]any)
+		if !ok {
+			continue
+		}
+		for sub, lvl := range subs {
+			s, _ := lvl.(string)
+			out = append(out, LogNodeLevel{Node: node, Subscriber: sub, Level: s})
+		}
+	}
+	sort.Slice(out, func(i, j int) bool {
+		if !strings.EqualFold(out[i].Node, out[j].Node) {
+			return strings.ToLower(out[i].Node) < strings.ToLower(out[j].Node)
+		}
+		return out[i].Subscriber < out[j].Subscriber
+	})
+	return out, nil
+}
+
+// SetLogLevels sets levels for the given nodes in a single admin call — the
+// action takes a list, so a multi-node change is one round trip and lands
+// together rather than partially.
+//
+// force allows a node the runtime does not know yet. Without it an unknown node
+// is refused, which is the behaviour worth having by default: a mistyped node
+// name should be an error, not a silently pre-registered setting that never
+// takes effect.
+func SetLogLevels(opts M2EEOptions, levels []LogNodeLevel, force bool) error {
+	if len(levels) == 0 {
+		return fmt.Errorf("no nodes given")
+	}
+	nodes := make([]map[string]any, 0, len(levels))
+	var described []string
+	for _, l := range levels {
+		lvl, err := NormalizeLogLevel(l.Level)
+		if err != nil {
+			return err
+		}
+		nodes = append(nodes, map[string]any{"name": l.Node, "level": lvl})
+		described = append(described, l.Node+"="+lvl)
+	}
+	params := map[string]any{"nodes": nodes}
+	if force {
+		params["force"] = true
+	}
+
+	resp, err := CallM2EE(opts, "set_log_level", params)
+	if err != nil {
+		return fmt.Errorf("%w: %v", ErrAdminUnreachable, err)
+	}
+	if resp.Result != 0 {
+		// The HTTP response for an AdminException says only "See logging output
+		// for details", so name the request and the likeliest cause instead of
+		// passing that through as if it were an explanation.
+		hint := ""
+		if !force {
+			hint = "\n  If the node does not exist yet, pass --force — the runtime refuses an unknown node otherwise."
+		}
+		return fmt.Errorf("setting log level (%s): %s%s",
+			strings.Join(described, ", "), resp.M2EEError(), hint)
+	}
+	return nil
+}
+
+// MatchLogNodes returns the nodes whose name contains the (case-insensitive)
+// pattern. An empty pattern matches everything.
+func MatchLogNodes(all []LogNodeLevel, pattern string) []LogNodeLevel {
+	if pattern == "" {
+		return all
+	}
+	needle := strings.ToLower(pattern)
+	var out []LogNodeLevel
+	for _, l := range all {
+		if strings.Contains(strings.ToLower(l.Node), needle) {
+			out = append(out, l)
+		}
+	}
+	return out
+}
diff --git a/cmd/mxcli/docker/loglevels_test.go b/cmd/mxcli/docker/loglevels_test.go
new file mode 100644
index 000000000..07cb87d24
--- /dev/null
+++ b/cmd/mxcli/docker/loglevels_test.go
@@ -0,0 +1,57 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package docker
+
+import (
+	"strings"
+	"testing"
+)
+
+// The runtime rejects anything outside this set with "Unknown LogLevel X", whose
+// detail never reaches the HTTP response — so the check happens here.
+func TestNormalizeLogLevel(t *testing.T) {
+	for in, want := range map[string]string{
+		"trace": "TRACE", "TRACE": "TRACE", " Debug ": "DEBUG", "none": "NONE",
+	} {
+		got, err := NormalizeLogLevel(in)
+		if err != nil || got != want {
+			t.Errorf("NormalizeLogLevel(%q) = (%q, %v), want %q", in, got, err, want)
+		}
+	}
+	for _, bad := range []string{"VERBOSE", "FINE", "", "warn"} {
+		if _, err := NormalizeLogLevel(bad); err == nil {
+			t.Errorf("NormalizeLogLevel(%q) should fail", bad)
+		}
+	}
+}
+
+// Listing 57 nodes is unusable without a filter; matching is case-insensitive
+// and substring, because nobody remembers "ConnectionBus_Synchronize" exactly.
+func TestMatchLogNodes(t *testing.T) {
+	all := []LogNodeLevel{
+		{Node: "ConnectionBus_Queries", Level: "INFO"},
+		{Node: "Connector", Level: "INFO"},
+		{Node: "Jetty", Level: "INFO"},
+	}
+	if got := MatchLogNodes(all, ""); len(got) != 3 {
+		t.Errorf("an empty filter should match everything, got %d", len(got))
+	}
+	got := MatchLogNodes(all, "connect")
+	if len(got) != 2 {
+		t.Fatalf("case-insensitive substring match failed: %+v", got)
+	}
+	if got[0].Node != "ConnectionBus_Queries" || got[1].Node != "Connector" {
+		t.Errorf("unexpected matches: %+v", got)
+	}
+	if got := MatchLogNodes(all, "nope"); len(got) != 0 {
+		t.Errorf("no match expected, got %+v", got)
+	}
+}
+
+// An empty node list must not reach the admin API as a well-formed no-op.
+func TestSetLogLevels_RejectsEmptyInput(t *testing.T) {
+	err := SetLogLevels(M2EEOptions{}, nil, false)
+	if err == nil || !strings.Contains(err.Error(), "no nodes") {
+		t.Errorf("expected a no-nodes error, got %v", err)
+	}
+}

From 5b62444559fa64f4510d5c2afaf79a5890177f20 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 9 Aug 2026 01:05:39 +0000
Subject: [PATCH 08/29] =?UTF-8?q?docs(log):=20correct=20the=20published-OD?=
 =?UTF-8?q?ata=20node=20=E2=80=94=20it=20exists,=20per=20app?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The previous commit claimed there is no log node for a published OData service,
and that "what is my published resource being asked?" therefore still needed a
LOG in the read microflow. That was wrong.

`OData Publish` — with a space — exists whenever the project publishes a
service, and at TRACE it logs the full incoming URI:

  TRACE - OData Publish: Incoming request from 127.0.0.1: GET .../Rows?$top=5&$filter=rowKey eq 'abc'
  DEBUG - OData Publish: Responding to client with status code 400.

which is precisely the question the command was built for.

The mistake is worth naming, because it is the same one in a new place: the node
list is a property of the APP, not of Mendix. Nodes appear once something
registers them. The first probe ran against a project with zero OData services,
saw 57 nodes and no publish node, and generalised. Adding one service makes it
58. Enumerating a platform's capabilities from one sample app and calling the
result "Mendix does not have this" is exactly what `log list` against your own
app is for — the command was right, the conclusion drawn beside it was not.

The same probe also showed Mendix rejecting `$filter` on a property not declared
Filterable, with 400 "Property 'x' is non-filterable", BEFORE the read microflow
runs — so the platform does enforce declared filterability, which is more than
§20 credited it with. What it still does not do is apply $top/$skip/$orderby for
a read-microflow resource.

Corrected in analyze-runtime.md (node table + a section on the publish node),
odata-data-sharing.md, the command's own help, and the fix-issue row.

mxcli-formula1 suggested issue 4
---
 .claude/skills/fix-issue.md                 |  2 +-
 .claude/skills/mendix/analyze-runtime.md    | 33 +++++++++++++++++----
 .claude/skills/mendix/odata-data-sharing.md | 20 +++++++++++--
 cmd/mxcli/cmd_log.go                        | 19 +++++++++---
 4 files changed, 62 insertions(+), 12 deletions(-)

diff --git a/.claude/skills/fix-issue.md b/.claude/skills/fix-issue.md
index f8aedabe7..67beba8a0 100644
--- a/.claude/skills/fix-issue.md
+++ b/.claude/skills/fix-issue.md
@@ -430,4 +430,4 @@ extracting `OffsetExpression`/`LimitExpression`.
 | `.ai-context/skills/` still carries the previous release's guidance after the mxcli binary is upgraded — binary rebuilt at 12:05, skills stamped the day before — with no warning that they disagree | The skills are embedded in the binary and written exactly once, by `mxcli init`. Nothing re-ran init on upgrade, and nothing compared what was on disk against what the binary carried | New `cmd/mxcli/init_skills_sync.go` (`syncAIContextSkills`, `reportSkillSync`), `--sync-skills` flag in `cmd/mxcli/init.go`, and a sync step in the SessionStart bootstrap in `cmd/mxcli/init_hook.go` | **Stale guidance is worse than missing guidance**, because an agent reads it with identical confidence either way — so the failure mode is silent and confident. Fix it where it is consumed, not where it is authored: the SessionStart bootstrap already runs on every session and can fetch the binary, so it is the one place guaranteed to execute immediately before an agent reads the files. Two properties keep an every-session job acceptable: **write only what differs** (an mtime that moves every session makes "when did this last change" unanswerable — a test asserts the mtime holds) and **stay silent when current**. Never fatal: a skills refresh must not block a session, hence `|| true`. A test asserts the bootstrap script actually calls it *before* the exec'd setup, since a step ordered after an `exec` never runs. Tests `init_skills_sync_test.go`; the control (write-once) leaves the stale file in place. mxcli-formula1 §16 |
 | `publish entity … (TopSupported: No)` (or `SkipSupported`/`Countable`) parses, `DESCRIBE` reads it back as `No`, and the published `$metadata` still advertises `true`. A client then believes paging works when nothing implements it | `serializeEntitySet` hardcoded all three `QueryOptions` to `true`, ignoring the `*bool` fields the model already carried — the AST/model/DESCRIBE half of the feature shipped without the writer half | `sdk/mpr/writer_odata.go` (`boolOrTrue`, entity-set `QueryOptions`) | **A capability annotation on a microflow-backed resource is load-bearing, not decorative.** Mendix applies *no* query options to a read-microflow resource — it hands the request over and returns what comes back — so the annotation is the only thing a client has to go on, and an over-claim is not cosmetic: the client reads a whole collection believing it is a page. **Check the writer whenever a property round-trips correctly through DESCRIBE**: DESCRIBE reads the model, so a model-only feature describes perfectly and publishes wrong, and the round-trip test everyone reaches for cannot see it. A tri-state `*bool` needs an explicit nil policy at the boundary (`nil` = the platform default, only an explicit `false` opts out) or the pointer is pointless. Tests `writer_odata_test.go`; the control (hardcoded true) reproduces the over-claim. mxcli-formula1 §20 |
 | A published OData resource backed by a read microflow silently returns the wrong thing: `?$top=5` yields the whole collection with a 200, and a client re-reading a held row by key gets the collection default and adopts the FIRST row as that object's identity. No error anywhere — well-formed request, valid collection, correct `$count`, 200 | Two promises the service makes on the microflow's behalf and nothing checked: the `KEY` in `expose (…)`, and the `TopSupported`/`SkipSupported` annotations (which default to **true** when unspecified). Mendix applies no query options to a read-microflow resource — it hands over the request and returns what comes back | New `mdl/executor/validate_odata_read_contract.go` (MDL-ODATA02 key promise, MDL-ODATA03 capability over-claim), wired in `cmd/mxcli/cmd_check.go`; the response contract documented in `.claude/skills/mendix/odata-data-sharing.md` | **A read microflow cannot answer 400** — unlike an OData action or an insert/update/delete microflow, the read capability has no `System.HttpResponse` parameter ([docs](https://docs.mendix.com/refguide/published-odata-entity/#custom-http-response)). Its contract is therefore *declarative*: declaring `TopSupported: No` is the read path's only substitute for the refusal it cannot send. **Pick a trigger you can prove**: both rules fire only when the microflow takes no `System.HttpRequest` parameter, because then it provably cannot see a key or a query option; a microflow that does take it gets the benefit of the doubt, since proving *which* options it parses needs real analysis and a rule that guesses gets switched off. **Verify a check rule against a real parse, never a hand-built AST** — the visitor stores `ReadMode` as `MICROFLOW Module.Name` **upper-cased**, so a case-sensitive prefix match made the whole rule dead while it still looked right; the casing is now pinned by its own test. Tests `validate_odata_read_contract_test.go`, examples in `10-odata-examples.mdl` (both correct shapes: request-aware, and honestly declared). mxcli-formula1 §37/§20, suggested issues 2 and 3 |
-| No way to see what a running app's subsystem is doing: everything logs at `INFO`, the detail is not in the log at all, and raising the whole runtime to `TRACE` is unusable on a busy app | Nothing in mxcli drove the runtime's per-node log levels, though the M2EE admin API has exposed them all along | New `cmd/mxcli/docker/loglevels.go` (`GetLogSettings`, `SetLogLevels`, `NormalizeLogLevel`, `MatchLogNodes`), `cmd/mxcli/cmd_log.go` (`mxcli log list` / `log set`), documented in `.claude/skills/mendix/analyze-runtime.md` | **Probe an undocumented API before designing the command around it.** Every fact here came from a live 11.12.1 runtime: `get_log_settings` requires one of `node`/`subscriber`/`sort`; `sort` accepts only `node` and `subscriber`; `set_log_level` takes `{"nodes":[{name,level}],"force":bool}`. **The HTTP response for an AdminException says only "See logging output for details" — the actual message ("Please specify node, subscriber or sort option in params", "Unknown sort option: name", "Unknown LogNode X. Use the 'force' parameter…") is in the runtime log**, so probe with the runtime log open or you learn nothing. `force` means "allow a node that does not exist yet" and **permanently registers the name**, so a typo becomes a real empty node — hence it is opt-in, and an unknown node is an error by default. **Resist the subsystem-specific command**: this was proposed as `mxcli odata trace`, but `set_log_level` takes a list of nodes and the runtime reports 57, so the primitive is generic and the OData knowledge belongs in docs. Distinguish "cannot reach the admin API" from "the runtime refused the request" (`ErrAdminUnreachable`) or the wrong hint buries the real one. Tests `cmd_log_test.go`, `loglevels_test.go`; verified end-to-end against a booted runtime (both arg forms, multi-node, typo refused, `--force` accepted, unreachable port). mxcli-formula1 suggested issue 4 |
+| No way to see what a running app's subsystem is doing: everything logs at `INFO`, the detail is not in the log at all, and raising the whole runtime to `TRACE` is unusable on a busy app | Nothing in mxcli drove the runtime's per-node log levels, though the M2EE admin API has exposed them all along | New `cmd/mxcli/docker/loglevels.go` (`GetLogSettings`, `SetLogLevels`, `NormalizeLogLevel`, `MatchLogNodes`), `cmd/mxcli/cmd_log.go` (`mxcli log list` / `log set`), documented in `.claude/skills/mendix/analyze-runtime.md` | **Probe an undocumented API before designing the command around it.** Every fact here came from a live 11.12.1 runtime: `get_log_settings` requires one of `node`/`subscriber`/`sort`; `sort` accepts only `node` and `subscriber`; `set_log_level` takes `{"nodes":[{name,level}],"force":bool}`. **The HTTP response for an AdminException says only "See logging output for details" — the actual message ("Please specify node, subscriber or sort option in params", "Unknown sort option: name", "Unknown LogNode X. Use the 'force' parameter…") is in the runtime log**, so probe with the runtime log open or you learn nothing. `force` means "allow a node that does not exist yet" and **permanently registers the name**, so a typo becomes a real empty node — hence it is opt-in, and an unknown node is an error by default. **Resist the subsystem-specific command**: this was proposed as `mxcli odata trace`, but `set_log_level` takes a list of nodes, so the primitive is generic and the OData knowledge belongs in docs. **The node list is a property of the APP, not of Mendix** — a node appears only once something registers it. A first pass concluded "there is no log node for a published OData service" from a project that had none; adding one service turns 57 nodes into 58 and `OData Publish` (with a space) appears, logging the full incoming URI at TRACE — exactly the question that motivated the command. Enumerating capabilities against one sample app and generalising is the trap; `log list` against *this* app is the answer. Distinguish "cannot reach the admin API" from "the runtime refused the request" (`ErrAdminUnreachable`) or the wrong hint buries the real one. Tests `cmd_log_test.go`, `loglevels_test.go`; verified end-to-end against a booted runtime (both arg forms, multi-node, typo refused, `--force` accepted, unreachable port). mxcli-formula1 suggested issue 4 |
diff --git a/.claude/skills/mendix/analyze-runtime.md b/.claude/skills/mendix/analyze-runtime.md
index e16d6b977..1d41fd3dc 100644
--- a/.claude/skills/mendix/analyze-runtime.md
+++ b/.claude/skills/mendix/analyze-runtime.md
@@ -71,6 +71,7 @@ Nodes worth knowing:
 | What SQL is being run | `ConnectionBus_Queries` (and `_Retrieve`, `_Update`) |
 | Database sync at startup | `ConnectionBus_Synchronize` |
 | Consumed OData / REST calls | `ODataConsume`, `REST Consume` |
+| **Published** OData requests (the incoming URI) | `OData Publish` — note the space; only exists if the project publishes a service |
 | Microflow execution | `MicroflowEngine`, `ActionManager` |
 | Scheduled events / queues | `SystemTask`, `TaskQueue` |
 | Java/JS action wiring | `Connector` |
@@ -81,11 +82,33 @@ for the life of the process, so a typo becomes a real (empty) node that shows up
 `log list` from then on. Use it only to pre-register a node that has not published
 yet.
 
-**There is no log node for a *published* OData service.** `ODataConsume` is the
-client side only. So "what is my published resource being asked?" cannot be
-answered by raising a node — put `LOG INFO 'URI=' + $Request/Uri` in the read
-microflow instead (see `odata-data-sharing.md`). That gap is Mendix's, not
-mxcli's.
+**Nodes appear only once something registers them**, so the list is a property of
+*this* app, not of Mendix. A blank 11.12 app reports 57; adding one published
+OData service makes it 58. This is why `log list` is the first step rather than a
+remembered name — and why `--force` exists for a node that has not registered yet.
+
+### Seeing what a published OData resource is asked
+
+`OData Publish` — **note the space** — is the node, and it exists only when the
+project publishes a service. At TRACE it logs the full incoming URI, which is the
+question `$filter`/`$top`/key-lookup bugs turn on:
+
+```bash
+mxcli log set "OData Publish" TRACE
+# GET /odata/f1/Rows?$top=5&$filter=rowKey eq 'abc'
+```
+```
+TRACE - OData Publish: Incoming request from 127.0.0.1: GET .../Rows?$top=5&$filter=rowKey eq 'abc'
+DEBUG - OData Publish: Responding to client with status code 400.
+```
+
+`ODataConsume` is the *client* side — a different node for a different direction.
+
+That same probe showed Mendix rejecting `$filter` on a property not declared
+`Filterable`, with a **400 "Property 'rowKey' is non-filterable"**, before the read
+microflow ran. So the platform does enforce the filterability you declare in
+`expose (…)`; what it does *not* do is apply `$top`/`$skip`/`$orderby` for a
+read-microflow resource (see `odata-data-sharing.md`).
 
 ## 2. Metrics — throughput and database pressure
 
diff --git a/.claude/skills/mendix/odata-data-sharing.md b/.claude/skills/mendix/odata-data-sharing.md
index 555172595..10cd97774 100644
--- a/.claude/skills/mendix/odata-data-sharing.md
+++ b/.claude/skills/mendix/odata-data-sharing.md
@@ -576,9 +576,25 @@ begin
 end;
 ```
 
+To watch what clients actually send, raise the **`OData Publish`** log node (note
+the space; it exists only when the project publishes a service):
+
+```bash
+mxcli log set "OData Publish" TRACE
+```
+```
+TRACE - OData Publish: Incoming request from 127.0.0.1: GET .../Rows?$top=5&$filter=rowKey eq 'abc'
+DEBUG - OData Publish: Responding to client with status code 400.
+```
+
+That is the fastest way to see a client re-reading a row by key, and it needs no
+change to the model. `ODataConsume` is the client side, a different node.
+
 Mendix validates field names before the microflow runs (`$filter=secretColumn eq 'x'`
-is a `400` from the platform), so the microflow only ever sees names that exist
-in the published metadata. That is defence in depth, not a substitute for a
+is a `400` from the platform), and it enforces `Filterable`: filtering on a property
+you did not declare filterable is rejected with `400 "Property 'x' is
+non-filterable"` before the microflow runs. So the microflow only ever sees names
+that exist in the published metadata. That is defence in depth, not a substitute for a
 whitelist — it constrains the *name*, not what you do with it.
 
 ## Step-by-Step: Read-Write API with Microflow Handlers
diff --git a/cmd/mxcli/cmd_log.go b/cmd/mxcli/cmd_log.go
index a86bfcf9f..74ed9f71e 100644
--- a/cmd/mxcli/cmd_log.go
+++ b/cmd/mxcli/cmd_log.go
@@ -23,8 +23,12 @@ import (
 // runtime this was built against reports 57 of them. A per-subsystem command
 // would have wrapped a generic primitive one subsystem at a time.
 //
-// So the command is generic, and the OData-specific knowledge (which node to
-// raise) lives in the skill instead.
+// So the command is generic, and the OData-specific knowledge lives in the skill
+// instead — including the answer to the original question: `OData Publish` (with
+// a space) logs the full incoming URI at TRACE, and exists only when the project
+// publishes a service. An earlier note here claimed no such node existed; it was
+// written against a project that had no OData service, which is exactly the
+// mistake `log list` is meant to prevent.
 
 var logCmd = &cobra.Command{
 	Use:   "log",
@@ -56,8 +60,15 @@ Examples:
   # Several at once — one admin call, applied together
   mxcli log set ConnectionBus_Queries=TRACE Connector=DEBUG
 
-  # A node that has not published yet (Mendix allows pre-registering a level)
-  mxcli log set MyModule.MyNode TRACE --force`,
+  # A name with a space needs quoting
+  mxcli log set "OData Publish" TRACE
+
+  # A node that has not registered yet (Mendix allows pre-registering a level)
+  mxcli log set MyModule.MyNode TRACE --force
+
+The node list belongs to THIS app, not to Mendix: a node appears once something
+registers it, so a blank app reports 57 and publishing one OData service makes it
+58. Start from 'log list' rather than a remembered name.`,
 }
 
 var logListCmd = &cobra.Command{

From ff97412ef7e4fee26160bdbc8f19922307ee8ec3 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 9 Aug 2026 01:06:38 +0000
Subject: [PATCH 09/29] fix(pages): qualify an association datasource's name,
 which wrote an unloadable page
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Upstream #854 reported a cross-module association datasource writing an empty
DestinationEntity, which Mendix resolves to null so the .mpr will not open.
That half no longer reproduces — the destination resolves through
CrossAssociations, and an unresolved one is refused.

The association half of the same EntityRefStep was still written as authored.
Both halves are BY_NAME references and Mendix nulls either one it cannot find,
so a bare `Order_Line` produced the identical unopenable project, one property
over:

  ArgumentNullException at EntityRefStep.set_AssociationId

The explicit-destination form is what made it reachable: supplying the
destination satisfies the empty-DestinationEntity guard, so nothing else stood
between a bare name and the crash — and `Assoc/Module.Entity` is exactly the
spelling that guard's error message tells the author to use.

Qualify a bare association with the context entity's module, the rule
attribute-path hops already follow, and verify an author-supplied destination's
association exists rather than taking it on trust (a misspelling would
otherwise be written qualified-but-nonexistent and null the same way).

Verified on Mendix 11.13.0: all five spellings resolve and mx check reports 0
errors. The pre-fix binary reproduces the crash on the same script.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_013uQvFDd5R4eNqqita59jM8
---
 .claude/skills/fix-issue.md                   |   1 +
 .../854-assoc-datasource-qualified-name.mdl   |  82 +++++++++
 ...cmd_pages_builder_assoc_datasource_test.go | 166 ++++++++++++++++++
 mdl/executor/cmd_pages_builder_v3.go          |  25 ++-
 4 files changed, 273 insertions(+), 1 deletion(-)
 create mode 100644 mdl-examples/bug-tests/854-assoc-datasource-qualified-name.mdl
 create mode 100644 mdl/executor/cmd_pages_builder_assoc_datasource_test.go

diff --git a/.claude/skills/fix-issue.md b/.claude/skills/fix-issue.md
index 85535a966..044d182f0 100644
--- a/.claude/skills/fix-issue.md
+++ b/.claude/skills/fix-issue.md
@@ -427,3 +427,4 @@ extracting `OffsetExpression`/`LimitExpression`.
 | `create odata client` with credentials given as constants (`HttpUsername: '@Module.ApiUser'`) still gets HTTP 401 and an empty client, after the fix that made literal credentials work. Sharpened by the same release making a constant `ServiceUrl` mandatory — the shape the tool insists on is the shape whose credentials it will not read | `resolveCredential` trusted the visitor's isLiteral flag. `'@Module.ApiUser'` **is** a STRING_LITERAL, so the flag said "literal" and the previous code sent the fifteen characters `@Module.ApiUser` as the username — and the unresolved-credential note did not fire either, because as far as the code knew nothing was unresolved | `mdl/executor/cmd_odata.go` (`resolveCredential`, `constantReference`, `designTimeConstants`) | **A syntactic classification is not a semantic one.** The visitor can say "this was a quoted string"; only the executor can say "this quoted string names a constant". Any flag of the form isLiteral needs the consumer to ask what the literal *contains* before treating it as a value. **The fix is to resolve, not to refuse**: a constant's design-time default is exactly what Studio Pro sends on the same fetch, so reading it is the value rather than a workaround — and mxcli already has the project open. Three spellings must all work (`'v'`, `@M.C`, `'@M.C'`); a dotted literal like a password containing a dot must not be mistaken for a reference. Tests `cmd_odata_metadata_auth_test.go`. mxcli-formula1 #23 follow-up |
 | An app themed dark still shows light-mode drop shadows under the datagrid's filter-operator popover and dropdown filter lists | The generated widget layer re-pointed `.column-selectors` but not the four rules in `_datagrid-filters.scss` that bake the same two-layer shadow. Each already takes its *background* from `--bg-color-secondary`, so Atlas re-colours the panel and leaves the shadow — which is why it reads as a partial fix rather than an untouched widget | `cmd/mxcli/theme/assets/*/files/theme/web/_mxcli-widgets.scss` | **Read the selectors out of the shipped `themesource/`, not the bug report** — the fourth here is `.dropdown-container .dropdown-list`, nested under a parent the report did not name. **Verify in the compiled CSS, never the source** (the §33 rule): apply the theme to a real project, run `mxbuild --target=deploy --java-home=… --java-exe-path=…`, then grep `theme-cache/web/theme.compiled.css` and check the *line number* — the fix must land after the widget module's own rule (30794 vs 27765 here) or the cascade eats it. A theme-cache file older than the SCSS you just wrote is a stale compile, and mtime is the cheapest way to catch it. mxcli-formula1 #33 / suggested issue 4 |
 | A `MOVE` cannot be confirmed and a module's layout cannot be reviewed: `SHOW STRUCTURE` groups by document type at every depth and never names a folder, `DESCRIBE` answers for one document at a time, so checking where things ended up means opening the `.mpr` as SQLite | The read side of folders was simply never built. `MOVE`/`DROP FOLDER` write containment; nothing read it back | New `mdl/executor/cmd_list_folders.go` + grammar (`FOLDERS` lexer token, `showOrList FOLDERS (IN …)?` in `MDLCatalog.g4`, `FOLDERS` added to the `keyword` rule so it stays usable as an identifier), `mdl/ast/ast_query.go`, `mdl/visitor/visitor_query.go`, `mdl/executor/executor_query.go` | **A layout listing must show what is *not* there**: empty folders (`[0]`) and documents still at the module root, or it cannot be diffed against an intended layout — that is the whole use. Documents are indexed by `ContainerID` across every list call the backend offers, each best-effort, so a backend that cannot answer one kind yields a listing missing that kind rather than no listing. **Do not stub the hierarchy in the test** — `mkHierarchy` populates `moduleNames` but not `folderNames`, so `BuildFolderPath` returns `""` and every folder silently collapses into the module root, which looks exactly like the bug. Build it from the mock's `ListModules`/`ListUnits`/`ListFolders`, as `getHierarchy` does. Tests `cmd_list_folders_test.go`, example in `18-folder-examples.mdl`. mxcli-formula1 issue #2 |
+| A page written by mxcli will not open in Studio Pro, and `mx check` dies during *load* with `ArgumentNullException` at `EntityRefStep.set_AssociationId` — no page error, no CE code, the whole project is down rather than one document | An association DATASOURCE wrote the association name exactly as authored. Both halves of an `EntityRefStep` are BY_NAME and Mendix resolves either one it cannot find to null, but only `DestinationEntity` was guarded (issuetracker #14) — a bare `Order_Line` reached BSON unqualified. The **explicit-destination** form is the live trap: supplying the destination satisfies that guard, so nothing stood between a bare name and the crash — and `Assoc/Module.Entity` is exactly what the guard's error tells the author to write | `mdl/executor/cmd_pages_builder_v3.go` (`buildDataSourceV3`, `case "association"`: qualify via `resolveAssociationPathIn`, then verify an author-supplied destination's association exists via `associationEndpoints`) | **Guard every BY_NAME half of a ref, not the one that was reported.** #854 reported the destination; the association beside it failed identically and was reachable through the fix's own advice. **Diff the two properties in the dump** (`grep -A1 '"Key": "(Association\|DestinationEntity)"'`) rather than reading the exception name — the loader reports whichever it touches first. **Hold the input constant across builds**: the pre-fix binary was first run with bare names and post-fix with qualified ones, which "reproduced" nothing; re-running the *same qualified* script on both is what isolated cross-module (`""`) from same-module (resolved). `mx check` exits 0 on this failure — assert on the `contains: N errors` line, never `$?`. Tests `cmd_pages_builder_assoc_datasource_test.go`, example `mdl-examples/bug-tests/854-assoc-datasource-qualified-name.mdl`. upstream #854 follow-on |
diff --git a/mdl-examples/bug-tests/854-assoc-datasource-qualified-name.mdl b/mdl-examples/bug-tests/854-assoc-datasource-qualified-name.mdl
new file mode 100644
index 000000000..ab29cf1b6
--- /dev/null
+++ b/mdl-examples/bug-tests/854-assoc-datasource-qualified-name.mdl
@@ -0,0 +1,82 @@
+-- ============================================================================
+-- Upstream #854 (follow-on): an association DATASOURCE wrote the association
+-- name unqualified, making the .mpr unloadable
+-- ============================================================================
+--
+-- #854 itself — a cross-module association datasource writing
+-- `DestinationEntity: ""` — no longer reproduces: the destination now resolves
+-- through `CrossAssociations` (f0d1aea) and an unresolved one is refused
+-- outright (18de30b, see it-14-assoc-destination-entity.mdl).
+--
+-- What survived is the OTHER half of the same EntityRefStep. Both halves are
+-- BY_NAME references and Mendix resolves either one it cannot find to null, but
+-- only the destination was being guarded. A bare association name was written
+-- through verbatim:
+--
+--   System.InvalidOperationException: An error occurred when trying to set the
+--   'Association' property of a Entity ref step in a Page with ID ...
+--   ---> System.ArgumentNullException: Value cannot be null. (Parameter 'value')
+--       at ...DomainModels.Refs.EntityRefStep.set_AssociationId
+--
+-- Same unopenable project as #854, one property over. Not a build error: the
+-- loader dies before validation, so `mx check` reports nothing about the page.
+--
+-- The explicit-destination form below is the one that mattered. Supplying the
+-- destination satisfied the empty-DestinationEntity guard, so nothing else stood
+-- between a bare name and the crash — and `Assoc/Module.Entity` is precisely the
+-- spelling that guard's error message tells the author to use.
+--
+-- Fix: qualify a bare association with the context entity's module (the rule
+-- attribute-path hops already follow), and verify an author-supplied
+-- destination's association actually exists rather than taking it on trust.
+--
+-- Verified on Mendix 11.13.0: this script checks 0 errors and the project opens.
+-- ============================================================================
+
+create module M854A;
+create module M854B;
+
+create persistent entity M854A.Order (OrderNumber: String(50));
+create persistent entity M854A.Note (Body: String(200));
+create persistent entity M854B.Line (Product: String(100));
+
+-- control: both ends in the same module
+create association M854A.Order_Note from M854A.Order to M854A.Note type ReferenceSet;
+-- subject: destination lives in another module
+create association M854A.Order_Line from M854A.Order to M854B.Line type ReferenceSet;
+
+create page M854A.OrderDetail (
+  Params: { $Order: M854A.Order },
+  Title: 'Order Detail',
+  Layout: Atlas_Core.Atlas_Default
+) {
+  layoutgrid g { row r { column c (DesktopWidth: 12) {
+    dataview dvOrder (datasource: $Order) {
+      textbox tbNumber (attribute: OrderNumber, label: 'Order #')
+
+      -- bare name, same module
+      datagrid dgNotes (datasource: association Order_Note) {
+        column colBody (attribute: Body, caption: 'Note')
+      }
+
+      -- bare name, destination in another module
+      datagrid dgLines (datasource: association Order_Line) {
+        column colProduct (attribute: Product, caption: 'Product')
+      }
+
+      -- bare name + explicit destination: the guard's own suggested spelling,
+      -- and the form that used to crash the loader
+      datagrid dgLines2 (datasource: association Order_Line/M854B.Line) {
+        column colProduct2 (attribute: Product, caption: 'Product')
+      }
+
+      -- fully qualified, with and without an explicit destination
+      datagrid dgLines3 (datasource: association M854A.Order_Line) {
+        column colProduct3 (attribute: Product, caption: 'Product')
+      }
+      datagrid dgLines4 (datasource: association M854A.Order_Line/M854B.Line) {
+        column colProduct4 (attribute: Product, caption: 'Product')
+      }
+    }
+  } } }
+}
diff --git a/mdl/executor/cmd_pages_builder_assoc_datasource_test.go b/mdl/executor/cmd_pages_builder_assoc_datasource_test.go
new file mode 100644
index 000000000..12d2db2dc
--- /dev/null
+++ b/mdl/executor/cmd_pages_builder_assoc_datasource_test.go
@@ -0,0 +1,166 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package executor
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/mendixlabs/mxcli/mdl/ast"
+	"github.com/mendixlabs/mxcli/model"
+	"github.com/mendixlabs/mxcli/sdk/domainmodel"
+	"github.com/mendixlabs/mxcli/sdk/pages"
+)
+
+// upstream #854 (follow-on): an association DATASOURCE wrote the association
+// name into the EntityRefStep exactly as authored. A bare name — the spelling
+// attribute paths accept, and the spelling the unresolved-destination guard's
+// own error message suggests (`Assoc/Module.Entity`) — therefore reached BSON
+// unqualified. Mendix resolves an unqualified AssociationIdentifier to null and
+// the loader throws
+//
+//	ArgumentNullException at EntityRefStep.set_AssociationId
+//
+// so the .mpr will not open in Studio Pro and `mx check` dies before validating
+// anything. Same unopenable-project outcome as the empty DestinationEntity that
+// #854 reported; a different property of the same step.
+//
+// The explicit-destination form is the dangerous one: supplying the destination
+// satisfies the guard, so nothing else stood between a bare name and the crash.
+func TestAssociationDataSource_QualifiesAssociationName(t *testing.T) {
+	const (
+		modAID  = model.ID("mod-a")
+		modBID  = model.ID("mod-b")
+		orderID = model.ID("e-order")
+		noteID  = model.ID("e-note")
+		lineID  = model.ID("e-line")
+	)
+
+	newPB := func() *pageBuilder {
+		return &pageBuilder{
+			entityContext: "ModA.Order",
+			execCache: &executorCache{
+				hierarchy: &ContainerHierarchy{moduleNames: map[model.ID]string{
+					modAID: "ModA",
+					modBID: "ModB",
+				}},
+				domainModels: []*domainmodel.DomainModel{
+					{
+						ContainerID: modAID,
+						Entities: []*domainmodel.Entity{
+							{BaseElement: model.BaseElement{ID: orderID}, Name: "Order"},
+							{BaseElement: model.BaseElement{ID: noteID}, Name: "Note"},
+						},
+						Associations: []*domainmodel.Association{
+							{Name: "Order_Note", ParentID: orderID, ChildID: noteID, Type: domainmodel.AssociationTypeReferenceSet},
+						},
+						CrossAssociations: []*domainmodel.CrossModuleAssociation{
+							{Name: "Order_Line", ParentID: orderID, ChildRef: "ModB.Line", Type: domainmodel.AssociationTypeReferenceSet},
+						},
+					},
+					{
+						ContainerID: modBID,
+						Entities: []*domainmodel.Entity{
+							{BaseElement: model.BaseElement{ID: lineID}, Name: "Line"},
+						},
+					},
+				},
+			},
+		}
+	}
+
+	tests := []struct {
+		name      string
+		reference string
+		wantPath  string // EntityPath = "Module.Assoc/Module.DestEntity"
+	}{
+		{
+			name:      "bare same-module association",
+			reference: "Order_Note",
+			wantPath:  "ModA.Order_Note/ModA.Note",
+		},
+		{
+			name:      "bare cross-module association",
+			reference: "Order_Line",
+			wantPath:  "ModA.Order_Line/ModB.Line",
+		},
+		{
+			name:      "bare name with explicit destination (the guard's suggested spelling)",
+			reference: "Order_Line/ModB.Line",
+			wantPath:  "ModA.Order_Line/ModB.Line",
+		},
+		{
+			name:      "already-qualified name is left alone",
+			reference: "ModA.Order_Line",
+			wantPath:  "ModA.Order_Line/ModB.Line",
+		},
+		{
+			name:      "qualified name with explicit destination",
+			reference: "ModA.Order_Line/ModB.Line",
+			wantPath:  "ModA.Order_Line/ModB.Line",
+		},
+	}
+
+	for _, tc := range tests {
+		t.Run(tc.name, func(t *testing.T) {
+			ds, childCtx, err := newPB().buildDataSourceV3(&ast.DataSourceV3{
+				Type:      "association",
+				Reference: tc.reference,
+			})
+			if err != nil {
+				t.Fatalf("buildDataSourceV3(%q) = error %v", tc.reference, err)
+			}
+			src, ok := ds.(*pages.AssociationSource)
+			if !ok {
+				t.Fatalf("got %T, want *pages.AssociationSource", ds)
+			}
+			if src.EntityPath != tc.wantPath {
+				t.Errorf("EntityPath = %q, want %q", src.EntityPath, tc.wantPath)
+			}
+			// The association half must be qualified: an unqualified
+			// AssociationIdentifier is what Mendix resolves to null.
+			assoc := strings.SplitN(src.EntityPath, "/", 2)[0]
+			if !strings.Contains(assoc, ".") {
+				t.Errorf("association %q is unqualified — the .mpr will not open", assoc)
+			}
+			wantCtx := strings.SplitN(tc.wantPath, "/", 2)[1]
+			if childCtx != wantCtx {
+				t.Errorf("child entity context = %q, want %q", childCtx, wantCtx)
+			}
+		})
+	}
+}
+
+// A destination the author supplies explicitly must not be taken on trust: it
+// satisfies the empty-DestinationEntity guard, so a misspelled association would
+// otherwise be written qualified-but-nonexistent, which Mendix again resolves to
+// null. Refuse at author time instead.
+func TestAssociationDataSource_RejectsUnknownAssociation(t *testing.T) {
+	pb := &pageBuilder{
+		entityContext: "ModA.Order",
+		execCache: &executorCache{
+			hierarchy: &ContainerHierarchy{moduleNames: map[model.ID]string{
+				model.ID("mod-a"): "ModA",
+			}},
+			domainModels: []*domainmodel.DomainModel{{
+				ContainerID: model.ID("mod-a"),
+				Entities: []*domainmodel.Entity{
+					{BaseElement: model.BaseElement{ID: model.ID("e-order")}, Name: "Order"},
+				},
+			}},
+		},
+	}
+
+	for _, ref := range []string{"Order_Lnie/ModB.Line", "ModA.Order_Lnie/ModB.Line"} {
+		t.Run(ref, func(t *testing.T) {
+			_, _, err := pb.buildDataSourceV3(&ast.DataSourceV3{Type: "association", Reference: ref})
+			if err == nil {
+				t.Fatalf("buildDataSourceV3(%q) succeeded; want a refusal — "+
+					"a nonexistent association writes a null AssociationId and the project will not open", ref)
+			}
+			if !strings.Contains(err.Error(), "Order_Lnie") {
+				t.Errorf("error %q does not name the offending association", err)
+			}
+		})
+	}
+}
diff --git a/mdl/executor/cmd_pages_builder_v3.go b/mdl/executor/cmd_pages_builder_v3.go
index e2409483e..0d3e48584 100644
--- a/mdl/executor/cmd_pages_builder_v3.go
+++ b/mdl/executor/cmd_pages_builder_v3.go
@@ -793,8 +793,31 @@ func (pb *pageBuilder) buildDataSourceV3(ds *ast.DataSourceV3) (pages.DataSource
 		if idx := strings.Index(path, "/"); idx >= 0 {
 			destEntity = path[idx+1:]
 			path = path[:idx]
-		} else {
+		}
+
+		// Both halves of an EntityRefStep are BY_NAME references, and Mendix
+		// resolves either one it cannot find to null — so the association half
+		// needs the same care as the destination. A bare name (the spelling
+		// attribute paths accept, and the one the guard below suggests) reached
+		// BSON unqualified and the loader threw ArgumentNullException at
+		// `EntityRefStep.set_AssociationId`: same unopenable project as an empty
+		// DestinationEntity, a different property. Qualify with the context
+		// entity's module, exactly as attribute-path hops do (upstream #854).
+		path = pb.resolveAssociationPathIn(path, pb.entityContext)
+
+		if destEntity == "" {
 			destEntity = pb.resolveAssociationDestination(path, pb.entityContext)
+		} else if _, _, ok := pb.associationEndpoints(path); !ok {
+			// An author-supplied destination satisfies the guard below, so it is
+			// the one path where a misspelled — or wrongly-moduled — association
+			// would sail through and be written qualified-but-nonexistent, which
+			// Mendix resolves to null just the same. Verify it exists.
+			return nil, "", mdlerrors.NewValidationf(
+				"association %q for datasource %q does not exist — "+
+					"writing it would produce a project Mendix cannot open; "+
+					"a bare name is qualified with the module of the context entity (%s), "+
+					"so an association declared elsewhere must be named in full",
+				path, ds.Reference, pb.entityContext)
 		}
 
 		// An empty DestinationEntity is a by-name reference Mendix resolves to

From f1fa02bbeab11e8f52f90fd560b7e6ec383e9f9e Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 9 Aug 2026 01:14:10 +0000
Subject: [PATCH 10/29] fix(screenshot): declare the real scheme so an
 https-root app can be logged into
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Under --hub the runtime boots with the public https root URL, so it marks its
session cookies Secure and prefixes them __Host-. A headless browser reaching
the app over http then cannot hold a session, every screenshot silently shows
the login page, and rendering defects survive every other check.

The login browser context now sends X-Forwarded-Proto: http when the target is
http. On Mendix 10.24+ that header takes precedence over ApplicationRootUrl, so
the runtime drops both Secure and the __Host- prefix. This is accurate rather
than a workaround — the request genuinely is http — it is a no-op when the root
URL is already http, and real users arriving over https through the hub are
unaffected.

Verified at the layer the bug lives in, against a live 11.12.1 runtime booted
with an https root URL: the captured Playwright storage state goes from
__Host-XASSESSIONID(secure=true) to XASSESSIONID(secure=false).

The reported cause did NOT reproduce as stated, which is worth recording. On
127.0.0.1 an https root URL blocks nothing: loopback is a trustworthy origin, so
Chromium accepts Secure and __Host- cookies there, and the app rendered clean
with no console errors and no failed requests. The mechanism is real only from a
NON-loopback http origin — a container hostname, a LAN address — where the
origin is not trustworthy and the session cannot be held at all. The fix ships
because it is correct and free, not because it was shown to repair the reported
symptom.

mxcli-formula1 §38 / suggested issue 7
---
 .claude/skills/fix-issue.md               |  1 +
 .claude/skills/mendix/run-local.md        | 19 ++++++++++++++++++
 cmd/mxcli/docker/screenshot_login.go      | 15 +++++++++++++-
 cmd/mxcli/docker/screenshot_login_test.go | 24 +++++++++++++++++++++++
 4 files changed, 58 insertions(+), 1 deletion(-)

diff --git a/.claude/skills/fix-issue.md b/.claude/skills/fix-issue.md
index 67beba8a0..2a07d599e 100644
--- a/.claude/skills/fix-issue.md
+++ b/.claude/skills/fix-issue.md
@@ -431,3 +431,4 @@ extracting `OffsetExpression`/`LimitExpression`.
 | `publish entity … (TopSupported: No)` (or `SkipSupported`/`Countable`) parses, `DESCRIBE` reads it back as `No`, and the published `$metadata` still advertises `true`. A client then believes paging works when nothing implements it | `serializeEntitySet` hardcoded all three `QueryOptions` to `true`, ignoring the `*bool` fields the model already carried — the AST/model/DESCRIBE half of the feature shipped without the writer half | `sdk/mpr/writer_odata.go` (`boolOrTrue`, entity-set `QueryOptions`) | **A capability annotation on a microflow-backed resource is load-bearing, not decorative.** Mendix applies *no* query options to a read-microflow resource — it hands the request over and returns what comes back — so the annotation is the only thing a client has to go on, and an over-claim is not cosmetic: the client reads a whole collection believing it is a page. **Check the writer whenever a property round-trips correctly through DESCRIBE**: DESCRIBE reads the model, so a model-only feature describes perfectly and publishes wrong, and the round-trip test everyone reaches for cannot see it. A tri-state `*bool` needs an explicit nil policy at the boundary (`nil` = the platform default, only an explicit `false` opts out) or the pointer is pointless. Tests `writer_odata_test.go`; the control (hardcoded true) reproduces the over-claim. mxcli-formula1 §20 |
 | A published OData resource backed by a read microflow silently returns the wrong thing: `?$top=5` yields the whole collection with a 200, and a client re-reading a held row by key gets the collection default and adopts the FIRST row as that object's identity. No error anywhere — well-formed request, valid collection, correct `$count`, 200 | Two promises the service makes on the microflow's behalf and nothing checked: the `KEY` in `expose (…)`, and the `TopSupported`/`SkipSupported` annotations (which default to **true** when unspecified). Mendix applies no query options to a read-microflow resource — it hands over the request and returns what comes back | New `mdl/executor/validate_odata_read_contract.go` (MDL-ODATA02 key promise, MDL-ODATA03 capability over-claim), wired in `cmd/mxcli/cmd_check.go`; the response contract documented in `.claude/skills/mendix/odata-data-sharing.md` | **A read microflow cannot answer 400** — unlike an OData action or an insert/update/delete microflow, the read capability has no `System.HttpResponse` parameter ([docs](https://docs.mendix.com/refguide/published-odata-entity/#custom-http-response)). Its contract is therefore *declarative*: declaring `TopSupported: No` is the read path's only substitute for the refusal it cannot send. **Pick a trigger you can prove**: both rules fire only when the microflow takes no `System.HttpRequest` parameter, because then it provably cannot see a key or a query option; a microflow that does take it gets the benefit of the doubt, since proving *which* options it parses needs real analysis and a rule that guesses gets switched off. **Verify a check rule against a real parse, never a hand-built AST** — the visitor stores `ReadMode` as `MICROFLOW Module.Name` **upper-cased**, so a case-sensitive prefix match made the whole rule dead while it still looked right; the casing is now pinned by its own test. Tests `validate_odata_read_contract_test.go`, examples in `10-odata-examples.mdl` (both correct shapes: request-aware, and honestly declared). mxcli-formula1 §37/§20, suggested issues 2 and 3 |
 | No way to see what a running app's subsystem is doing: everything logs at `INFO`, the detail is not in the log at all, and raising the whole runtime to `TRACE` is unusable on a busy app | Nothing in mxcli drove the runtime's per-node log levels, though the M2EE admin API has exposed them all along | New `cmd/mxcli/docker/loglevels.go` (`GetLogSettings`, `SetLogLevels`, `NormalizeLogLevel`, `MatchLogNodes`), `cmd/mxcli/cmd_log.go` (`mxcli log list` / `log set`), documented in `.claude/skills/mendix/analyze-runtime.md` | **Probe an undocumented API before designing the command around it.** Every fact here came from a live 11.12.1 runtime: `get_log_settings` requires one of `node`/`subscriber`/`sort`; `sort` accepts only `node` and `subscriber`; `set_log_level` takes `{"nodes":[{name,level}],"force":bool}`. **The HTTP response for an AdminException says only "See logging output for details" — the actual message ("Please specify node, subscriber or sort option in params", "Unknown sort option: name", "Unknown LogNode X. Use the 'force' parameter…") is in the runtime log**, so probe with the runtime log open or you learn nothing. `force` means "allow a node that does not exist yet" and **permanently registers the name**, so a typo becomes a real empty node — hence it is opt-in, and an unknown node is an error by default. **Resist the subsystem-specific command**: this was proposed as `mxcli odata trace`, but `set_log_level` takes a list of nodes, so the primitive is generic and the OData knowledge belongs in docs. **The node list is a property of the APP, not of Mendix** — a node appears only once something registers it. A first pass concluded "there is no log node for a published OData service" from a project that had none; adding one service turns 57 nodes into 58 and `OData Publish` (with a space) appears, logging the full incoming URI at TRACE — exactly the question that motivated the command. Enumerating capabilities against one sample app and generalising is the trap; `log list` against *this* app is the answer. Distinguish "cannot reach the admin API" from "the runtime refused the request" (`ErrAdminUnreachable`) or the wrong hint buries the real one. Tests `cmd_log_test.go`, `loglevels_test.go`; verified end-to-end against a booted runtime (both arg forms, multi-node, typo refused, `--force` accepted, unreachable port). mxcli-formula1 suggested issue 4 |
+| A headless browser cannot log in to an app started with `--hub`, so every screenshot silently shows the login page and rendering defects survive every other check | Under `--hub` the runtime boots with the public **https** root URL, so it marks session cookies `Secure` and prefixes them `__Host-`; a browser on a non-trustworthy http origin cannot store them | `cmd/mxcli/docker/screenshot_login.go` — the login browser context declares `X-Forwarded-Proto: http` when the target is http (Mendix 10.24+ lets that header override `ApplicationRootUrl`) | **The reported cause did not reproduce as stated, and saying so is part of the fix.** On 11.12.1 an https root URL does *not* block a headless browser on `127.0.0.1`: loopback is a **trustworthy origin**, so Chromium accepts `Secure`/`__Host-` cookies there — the app rendered clean, no console errors, no failed requests. The mechanism is real only for a **non-loopback** http origin (a container hostname, a LAN address). Fix shipped anyway because the header is *accurate* rather than a workaround (the request genuinely is http), it costs nothing on an already-http root URL, and real users over https are unaffected. Verified at the layer the bug lives in: the captured Playwright storage state goes from `__Host-XASSESSIONID(secure=true)` to `XASSESSIONID(secure=false)`. **`curl` cannot see this class of bug and neither can a loopback browser** — when a report blames cookie flags, check whether the origin is trustworthy before believing the flags are the blocker. mxcli-formula1 §38 / suggested issue 7 |
diff --git a/.claude/skills/mendix/run-local.md b/.claude/skills/mendix/run-local.md
index 48917d3d1..626f3a132 100644
--- a/.claude/skills/mendix/run-local.md
+++ b/.claude/skills/mendix/run-local.md
@@ -228,6 +228,25 @@ headless so it is not rebuilt for them (that would cost ~30 s on a loop whose po
 is two seconds) — the run prints a note instead, and a subsequent `run --local`
 restores it.
 
+### Screenshots when the app has an https root URL (`--hub`)
+
+Under `--hub` the runtime boots with the public **https** root URL, so it marks
+its session cookies `Secure` and prefixes them `__Host-`. The screenshot login
+therefore declares the real scheme with `X-Forwarded-Proto: http`, which on
+Mendix 10.24+ takes precedence over `ApplicationRootUrl` and drops both — so the
+captured session is usable over http.
+
+Measured on 11.12.1, `__Host-XASSESSIONID (secure)` becomes `XASSESSIONID`
+(not secure). Real users still arrive over https through the hub without that
+header and still get `Secure` cookies.
+
+One correction to a common assumption: this is **not** needed for `127.0.0.1`.
+Loopback is a *trustworthy origin*, so Chromium accepts `Secure` cookies there
+and an app with an https root URL renders and logs in fine over
+`http://127.0.0.1:8080`. It matters when the browser reaches the app from a
+non-loopback host — a container name, a LAN address — where the origin is not
+trustworthy and the session cannot be held at all.
+
 ## Pixel-perfect page loop
 
 `--screenshot` captures a PNG (default `<projectDir>/.mxcli/run-local.png`) after boot
diff --git a/cmd/mxcli/docker/screenshot_login.go b/cmd/mxcli/docker/screenshot_login.go
index a9d42ca64..809ca94ee 100644
--- a/cmd/mxcli/docker/screenshot_login.go
+++ b/cmd/mxcli/docker/screenshot_login.go
@@ -64,7 +64,20 @@ const [appURL, username, password, storagePath] = process.argv.slice(3);
 const { chromium } = require(require.resolve("playwright-core", { paths: [pkgDir] }));
 (async () => {
   const b = await chromium.launch();
-  const ctx = await b.newContext();
+  // Tell the runtime the request really is http when it is. On Mendix 10.24+
+  // X-Forwarded-Proto takes precedence over ApplicationRootUrl, so this drops
+  // the Secure attribute and the __Host- prefix from the session cookies. It
+  // matters when the app boots with an https root URL (as it does under --hub)
+  // and the browser reaches it over http from a NON-loopback host: 127.0.0.1 is
+  // a trustworthy origin and keeps Secure cookies happily, but a container
+  // hostname is not, and there the session cannot be held at all.
+  //
+  // Accurate rather than a workaround — the request is http — and a no-op when
+  // the root URL is already http. Real users arrive over https through the hub
+  // without this header and still get Secure cookies.
+  const insecure = new URL(appURL).protocol === "http:";
+  const ctx = await b.newContext(
+    insecure ? { extraHTTPHeaders: { "X-Forwarded-Proto": "http" } } : {});
   const p = await ctx.newPage();
   await p.goto(appURL, { waitUntil: "load", timeout: 30000 });
   let sawForm = false;
diff --git a/cmd/mxcli/docker/screenshot_login_test.go b/cmd/mxcli/docker/screenshot_login_test.go
index 89a0bb8d7..393e5f3c4 100644
--- a/cmd/mxcli/docker/screenshot_login_test.go
+++ b/cmd/mxcli/docker/screenshot_login_test.go
@@ -80,3 +80,27 @@ func TestReadLogTail(t *testing.T) {
 		t.Errorf("readLogTail(small) = %q, %v", got, err)
 	}
 }
+
+// mxcli-formula1 suggested issue 7: under --hub the app boots with an https
+// ApplicationRootUrl, so the runtime marks its session cookies Secure and
+// __Host-. A headless browser reaching the app over http from a non-loopback
+// host cannot hold such a cookie, so login is impossible and every screenshot
+// silently shows the login page.
+//
+// Mendix 10.24+ lets X-Forwarded-Proto override ApplicationRootUrl, which is
+// both the fix and the truth: the request really is http. Verified against a
+// live 11.12.1 runtime — the captured storage state goes from
+// __Host-XASSESSIONID(secure=true) to XASSESSIONID(secure=false).
+func TestLoginScript_DeclaresHttpWhenTheTargetIsHttp(t *testing.T) {
+	if !strings.Contains(loginScript, `"X-Forwarded-Proto": "http"`) {
+		t.Error("the login context does not declare the real scheme; Secure cookies will block a non-loopback browser")
+	}
+	// Conditioned on the scheme: an https target must not be told it is http, or
+	// the runtime would downgrade cookies for a session that is genuinely secure.
+	if !strings.Contains(loginScript, `new URL(appURL).protocol === "http:"`) {
+		t.Error("the header must be conditional on an http target")
+	}
+	if !strings.Contains(loginScript, "insecure ?") {
+		t.Error("expected the context options to branch on the scheme")
+	}
+}

From cd2ac98e7eaea6ffd3c96c97b9d468b487481904 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 9 Aug 2026 02:13:11 +0000
Subject: [PATCH 11/29] fix(visitor): keep MDL comments out of the Mendix
 expressions they sit in
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

  declare $Msg String = 'a' +
    -- explain the second half
    'b';

stored the comment INSIDE the expression, and the build failed CE0117
"Error(s) in expression". Nothing before mxbuild objected: `mxcli check` passed
and DESCRIBE round-tripped the comment back out.

extractOriginalText reads the raw input stream between two token positions.
That is exactly what preserves an expression's spacing — and it also drags in
every token the lexer sent to a hidden channel. MDL's `--` and `/* */` are
`-> skip`, so they never appear in ctx.GetText() and always appear in a source
slice. Mendix expressions have neither form.

Expression sites now go through extractExpressionText, which strips MDL comments
first. Two properties matter:

  - a comment becomes whitespace, never nothing, so `1 --c\n+ 2` cannot become
    `1+ 2` and `'a'--c\n'b'` cannot weld into one token;
  - single-quoted strings are respected, because a Mendix string may legitimately
    contain `--` or `/*` and stripping those would corrupt the value. The `''`
    escape that keeps a string open is handled too.

OQL keeps extractOriginalText on purpose: `--` is legitimate SQL comment syntax
in a view entity's query, and stripping it would change a different language's
meaning.

Verified end to end against mxbuild 11.12.1 on the same project and script: 1
error before, 0 after. The control matters here — with extractExpressionText
bypassed the unit tests still passed, because they exercise the function rather
than the wiring, and only the mxbuild run showed the call sites were converted.

Swept mdl-examples/ and the 189 checkable skill MDL blocks: 0 failures.

mxcli-formula1 §34 / suggested issue 11
---
 .claude/skills/fix-issue.md                   |  1 +
 .../bug-tests/comment-in-expression.mdl       | 30 ++++++++
 mdl/visitor/visitor_helpers.go                | 76 +++++++++++++++++++
 mdl/visitor/visitor_microflow_actions.go      |  2 +-
 mdl/visitor/visitor_microflow_statements.go   | 10 +--
 mdl/visitor/visitor_strip_comments_test.go    | 58 ++++++++++++++
 6 files changed, 171 insertions(+), 6 deletions(-)
 create mode 100644 mdl-examples/bug-tests/comment-in-expression.mdl
 create mode 100644 mdl/visitor/visitor_strip_comments_test.go

diff --git a/.claude/skills/fix-issue.md b/.claude/skills/fix-issue.md
index 2a07d599e..822234933 100644
--- a/.claude/skills/fix-issue.md
+++ b/.claude/skills/fix-issue.md
@@ -432,3 +432,4 @@ extracting `OffsetExpression`/`LimitExpression`.
 | A published OData resource backed by a read microflow silently returns the wrong thing: `?$top=5` yields the whole collection with a 200, and a client re-reading a held row by key gets the collection default and adopts the FIRST row as that object's identity. No error anywhere — well-formed request, valid collection, correct `$count`, 200 | Two promises the service makes on the microflow's behalf and nothing checked: the `KEY` in `expose (…)`, and the `TopSupported`/`SkipSupported` annotations (which default to **true** when unspecified). Mendix applies no query options to a read-microflow resource — it hands over the request and returns what comes back | New `mdl/executor/validate_odata_read_contract.go` (MDL-ODATA02 key promise, MDL-ODATA03 capability over-claim), wired in `cmd/mxcli/cmd_check.go`; the response contract documented in `.claude/skills/mendix/odata-data-sharing.md` | **A read microflow cannot answer 400** — unlike an OData action or an insert/update/delete microflow, the read capability has no `System.HttpResponse` parameter ([docs](https://docs.mendix.com/refguide/published-odata-entity/#custom-http-response)). Its contract is therefore *declarative*: declaring `TopSupported: No` is the read path's only substitute for the refusal it cannot send. **Pick a trigger you can prove**: both rules fire only when the microflow takes no `System.HttpRequest` parameter, because then it provably cannot see a key or a query option; a microflow that does take it gets the benefit of the doubt, since proving *which* options it parses needs real analysis and a rule that guesses gets switched off. **Verify a check rule against a real parse, never a hand-built AST** — the visitor stores `ReadMode` as `MICROFLOW Module.Name` **upper-cased**, so a case-sensitive prefix match made the whole rule dead while it still looked right; the casing is now pinned by its own test. Tests `validate_odata_read_contract_test.go`, examples in `10-odata-examples.mdl` (both correct shapes: request-aware, and honestly declared). mxcli-formula1 §37/§20, suggested issues 2 and 3 |
 | No way to see what a running app's subsystem is doing: everything logs at `INFO`, the detail is not in the log at all, and raising the whole runtime to `TRACE` is unusable on a busy app | Nothing in mxcli drove the runtime's per-node log levels, though the M2EE admin API has exposed them all along | New `cmd/mxcli/docker/loglevels.go` (`GetLogSettings`, `SetLogLevels`, `NormalizeLogLevel`, `MatchLogNodes`), `cmd/mxcli/cmd_log.go` (`mxcli log list` / `log set`), documented in `.claude/skills/mendix/analyze-runtime.md` | **Probe an undocumented API before designing the command around it.** Every fact here came from a live 11.12.1 runtime: `get_log_settings` requires one of `node`/`subscriber`/`sort`; `sort` accepts only `node` and `subscriber`; `set_log_level` takes `{"nodes":[{name,level}],"force":bool}`. **The HTTP response for an AdminException says only "See logging output for details" — the actual message ("Please specify node, subscriber or sort option in params", "Unknown sort option: name", "Unknown LogNode X. Use the 'force' parameter…") is in the runtime log**, so probe with the runtime log open or you learn nothing. `force` means "allow a node that does not exist yet" and **permanently registers the name**, so a typo becomes a real empty node — hence it is opt-in, and an unknown node is an error by default. **Resist the subsystem-specific command**: this was proposed as `mxcli odata trace`, but `set_log_level` takes a list of nodes, so the primitive is generic and the OData knowledge belongs in docs. **The node list is a property of the APP, not of Mendix** — a node appears only once something registers it. A first pass concluded "there is no log node for a published OData service" from a project that had none; adding one service turns 57 nodes into 58 and `OData Publish` (with a space) appears, logging the full incoming URI at TRACE — exactly the question that motivated the command. Enumerating capabilities against one sample app and generalising is the trap; `log list` against *this* app is the answer. Distinguish "cannot reach the admin API" from "the runtime refused the request" (`ErrAdminUnreachable`) or the wrong hint buries the real one. Tests `cmd_log_test.go`, `loglevels_test.go`; verified end-to-end against a booted runtime (both arg forms, multi-node, typo refused, `--force` accepted, unreachable port). mxcli-formula1 suggested issue 4 |
 | A headless browser cannot log in to an app started with `--hub`, so every screenshot silently shows the login page and rendering defects survive every other check | Under `--hub` the runtime boots with the public **https** root URL, so it marks session cookies `Secure` and prefixes them `__Host-`; a browser on a non-trustworthy http origin cannot store them | `cmd/mxcli/docker/screenshot_login.go` — the login browser context declares `X-Forwarded-Proto: http` when the target is http (Mendix 10.24+ lets that header override `ApplicationRootUrl`) | **The reported cause did not reproduce as stated, and saying so is part of the fix.** On 11.12.1 an https root URL does *not* block a headless browser on `127.0.0.1`: loopback is a **trustworthy origin**, so Chromium accepts `Secure`/`__Host-` cookies there — the app rendered clean, no console errors, no failed requests. The mechanism is real only for a **non-loopback** http origin (a container hostname, a LAN address). Fix shipped anyway because the header is *accurate* rather than a workaround (the request genuinely is http), it costs nothing on an already-http root URL, and real users over https are unaffected. Verified at the layer the bug lives in: the captured Playwright storage state goes from `__Host-XASSESSIONID(secure=true)` to `XASSESSIONID(secure=false)`. **`curl` cannot see this class of bug and neither can a loopback browser** — when a report blames cookie flags, check whether the origin is trustworthy before believing the flags are the blocker. mxcli-formula1 §38 / suggested issue 7 |
+| A `--` comment written between two operands of a Mendix expression ends up **inside** the expression; the build fails **CE0117** "Error(s) in expression". `mxcli check` passes and `DESCRIBE` round-trips the comment, so nothing before mxbuild objects | `extractOriginalText` reads the raw input stream between two token positions — which is exactly what preserves an expression's spacing, and also drags in every token the lexer sent to a hidden channel. MDL's `--` and `/* */` are `-> skip`, so they never appear in `ctx.GetText()` but always appear in the source slice | `mdl/visitor/visitor_helpers.go` (`stripMDLComments`, `extractExpressionText`), applied at the six microflow-expression sites in `visitor_microflow_statements.go` / `visitor_microflow_actions.go` | **The ANTLR trap: `ctx.GetText()` excludes hidden tokens, a source-interval slice includes them.** Any code reaching for original text to preserve formatting inherits every comment in that span. **Replace a comment with whitespace, never with nothing** — `1 --c\n+ 2` must not become `1+ 2`, and `'a'--c\n'b'` must not weld into one token. **Respect single-quoted strings**: a Mendix string may legitimately contain `--` or `/*`, and stripping those corrupts the value (tested both, plus the `''` escape that keeps a string open). **Left OQL alone on purpose** — `visitor_entity.go` uses the same helper for view-entity queries, where `--` is legitimate SQL comment syntax; stripping it would change a different language's meaning. **The unit test alone would not have caught a wiring mistake**: it still passed with `extractExpressionText` bypassed, and only the mxbuild run (1 error → 0, same script, same project) proved the call sites were converted. Tests `visitor_strip_comments_test.go`, repro `mdl-examples/bug-tests/comment-in-expression.mdl`. mxcli-formula1 §34 / suggested issue 11 |
diff --git a/mdl-examples/bug-tests/comment-in-expression.mdl b/mdl-examples/bug-tests/comment-in-expression.mdl
new file mode 100644
index 000000000..8899496aa
--- /dev/null
+++ b/mdl-examples/bug-tests/comment-in-expression.mdl
@@ -0,0 +1,30 @@
+-- mxcli-formula1 suggested issue 11: an MDL comment between two operands was
+-- lifted into the Mendix expression along with the source text, and the build
+-- failed CE0117 "Error(s) in expression". Mendix expressions have no `--`.
+--
+-- Verified against mxbuild 11.12.1: 1 error before the fix, 0 after.
+
+create module CmtExpr;
+
+create microflow CmtExpr.Build ()
+returns string as $Msg
+begin
+  -- A comment between operands: the classic case.
+  declare $Msg String = 'a' +
+    -- explain the second half
+    'b';
+
+  -- A block comment mid-expression.
+  declare $N Integer = 1 /* one */ + 2;
+
+  -- A string that legitimately CONTAINS the comment markers must survive intact.
+  declare $Literal String = 'a--b' + '/*not a comment*/';
+
+  -- An escaped quote keeps the string open, so the `--` inside stays.
+  declare $Escaped String = 'it''s -- fine';
+
+  return $Msg;
+end;
+/
+
+drop module CmtExpr;
diff --git a/mdl/visitor/visitor_helpers.go b/mdl/visitor/visitor_helpers.go
index ac5337d53..3b5ff0976 100644
--- a/mdl/visitor/visitor_helpers.go
+++ b/mdl/visitor/visitor_helpers.go
@@ -616,6 +616,82 @@ func stripExpressionIdentifierQuotes(s string) string {
 	return b.String()
 }
 
+// extractExpressionText lifts a Mendix expression's source text, without the MDL
+// comments the raw input stream would otherwise carry into the model.
+//
+// Use this rather than extractOriginalText for anything stored as a Mendix
+// expression. OQL keeps extractOriginalText: `--` is a legitimate SQL comment
+// there, and stripping it would change a different language's meaning.
+func extractExpressionText(ctx antlr.ParserRuleContext) string {
+	return stripMDLComments(extractOriginalText(ctx))
+}
+
+// stripMDLComments removes MDL comments from text lifted out of the input stream.
+//
+// extractOriginalText reads the raw source between two token positions, which is
+// what preserves an expression's spacing — and also drags in anything the lexer
+// sent to a hidden channel. MDL comments are `--` to end of line and `/* … */`;
+// Mendix expressions use neither, so a comment written between two operands
+// ended up stored *inside* the expression and the build failed with CE0117
+// "Error(s) in expression" (mxcli-formula1 suggested issue 11):
+//
+//	declare $Msg String = 'a' +
+//	  -- explain the second half
+//	  'b';
+//
+// A comment is replaced by a single space rather than deleted, so `1 --c\n+ 2`
+// does not become `1+ 2`… and more importantly `'a'--c\n'b'` cannot silently
+// weld into one token.
+//
+// Single-quoted string literals are respected: a Mendix string may legitimately
+// contain `--` or `/*`, and removing those would corrupt the value.
+func stripMDLComments(s string) string {
+	if !strings.Contains(s, "--") && !strings.Contains(s, "/*") {
+		return s
+	}
+	var b strings.Builder
+	b.Grow(len(s))
+	inString := false
+	for i := 0; i < len(s); i++ {
+		c := s[i]
+		if c == '\'' {
+			if inString && i+1 < len(s) && s[i+1] == '\'' {
+				b.WriteByte(c)
+				b.WriteByte(s[i+1])
+				i++
+				continue
+			}
+			inString = !inString
+			b.WriteByte(c)
+			continue
+		}
+		if !inString && c == '-' && i+1 < len(s) && s[i+1] == '-' {
+			for i < len(s) && s[i] != '\n' {
+				i++
+			}
+			// Keep the newline itself: it is the statement's own layout, and a
+			// multi-line expression stays readable in DESCRIBE.
+			if i < len(s) {
+				b.WriteByte('\n')
+			}
+			continue
+		}
+		if !inString && c == '/' && i+1 < len(s) && s[i+1] == '*' {
+			end := strings.Index(s[i+2:], "*/")
+			if end < 0 {
+				// Unterminated: the parser would already have complained. Drop
+				// the rest rather than emit half a comment into the model.
+				break
+			}
+			i += 2 + end + 1
+			b.WriteByte(' ')
+			continue
+		}
+		b.WriteByte(c)
+	}
+	return b.String()
+}
+
 // ----------------------------------------------------------------------------
 // Microflow Statements
 // ----------------------------------------------------------------------------
diff --git a/mdl/visitor/visitor_microflow_actions.go b/mdl/visitor/visitor_microflow_actions.go
index fba6bedff..32e1c4124 100644
--- a/mdl/visitor/visitor_microflow_actions.go
+++ b/mdl/visitor/visitor_microflow_actions.go
@@ -343,7 +343,7 @@ func appendSourceExpressionSuffix(
 	expr ast.Expression,
 	suffix string,
 ) ast.Expression {
-	source := strings.TrimSpace(extractOriginalText(exprCtx.(antlr.ParserRuleContext)))
+	source := strings.TrimSpace(extractExpressionText(exprCtx.(antlr.ParserRuleContext)))
 	innerExpr := expr
 	if sourceExpr, ok := expr.(*ast.SourceExpr); ok {
 		source = sourceExpr.Source
diff --git a/mdl/visitor/visitor_microflow_statements.go b/mdl/visitor/visitor_microflow_statements.go
index 1ca597301..3394beffa 100644
--- a/mdl/visitor/visitor_microflow_statements.go
+++ b/mdl/visitor/visitor_microflow_statements.go
@@ -1163,7 +1163,7 @@ func buildRetrieveStatement(ctx parser.IRetrieveStatementContext) *ast.RetrieveS
 				if xpathExpr := xcCtx.XpathExpr(); xpathExpr != nil {
 					andExprs = append(andExprs, buildXPathSourceExpression(xpathExpr))
 					if prc, ok := xpathExpr.(antlr.ParserRuleContext); ok {
-						if source := strings.TrimSpace(extractOriginalText(prc)); source != "" {
+						if source := strings.TrimSpace(extractExpressionText(prc)); source != "" {
 							predicateSources = append(predicateSources, normalizeXPathTokens("["+source+"]"))
 						}
 					}
@@ -1221,7 +1221,7 @@ func retrieveRangeExpressionSource(exprCtx parser.IExpressionContext) string {
 		return ""
 	}
 	if prc, ok := exprCtx.(antlr.ParserRuleContext); ok {
-		if source := strings.TrimSpace(extractOriginalText(prc)); source != "" {
+		if source := strings.TrimSpace(extractExpressionText(prc)); source != "" {
 			return source
 		}
 	}
@@ -1446,7 +1446,7 @@ func buildSourceExpression(ctx parser.IExpressionContext) ast.Expression {
 	}
 	expr := buildExpression(ctx)
 	if prc, ok := ctx.(antlr.ParserRuleContext); ok {
-		if source := strings.TrimSpace(extractOriginalText(prc)); source != "" {
+		if source := strings.TrimSpace(extractExpressionText(prc)); source != "" {
 			if shouldPreserveExpressionSource(source) {
 				return &ast.SourceExpr{Expression: expr, Source: stripExpressionIdentifierQuotes(source)}
 			}
@@ -1461,7 +1461,7 @@ func buildXPathSourceExpression(ctx parser.IXpathExprContext) ast.Expression {
 	}
 	expr := buildXPathExpr(ctx)
 	if prc, ok := ctx.(antlr.ParserRuleContext); ok {
-		if source := strings.TrimSpace(extractOriginalText(prc)); source != "" {
+		if source := strings.TrimSpace(extractExpressionText(prc)); source != "" {
 			// Requote any bare [%token%] so the stored constraint passes mx check
 			// (CE0161) — the original source preserves the unquoted form (#641).
 			return &ast.SourceExpr{Expression: expr, Source: stripExpressionIdentifierQuotes(normalizeXPathTokens(source))}
@@ -1487,7 +1487,7 @@ func buildRetrieveWhereExpression(ctx parser.IExpressionContext) ast.Expression
 		}
 	}
 	if prc, ok := ctx.(antlr.ParserRuleContext); ok {
-		if source := strings.TrimSpace(extractOriginalText(prc)); source != "" {
+		if source := strings.TrimSpace(extractExpressionText(prc)); source != "" {
 			if shouldPreserveExpressionSource(source) || strings.Contains(source, "/") {
 				return &ast.SourceExpr{Expression: expr, Source: stripExpressionIdentifierQuotes(source)}
 			}
diff --git a/mdl/visitor/visitor_strip_comments_test.go b/mdl/visitor/visitor_strip_comments_test.go
new file mode 100644
index 000000000..eab6061e6
--- /dev/null
+++ b/mdl/visitor/visitor_strip_comments_test.go
@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package visitor
+
+import "testing"
+
+// mxcli-formula1 suggested issue 11: extractOriginalText reads the raw source
+// between two token positions — which is what preserves an expression's spacing,
+// and also drags in the comments the lexer sent to a hidden channel. A `--`
+// comment between two operands was stored inside the Mendix expression and the
+// build failed CE0117 "Error(s) in expression". Verified end to end: the same
+// script went from 1 error to 0 against mxbuild 11.12.1.
+func TestStripMDLComments(t *testing.T) {
+	tests := []struct {
+		name string
+		in   string
+		want string
+	}{
+		{"nothing to do", "'a' + 'b'", "'a' + 'b'"},
+		{
+			"line comment between operands",
+			"'a' +\n  -- explain\n  'b'",
+			"'a' +\n  \n  'b'",
+		},
+		{"trailing line comment", "$x + 1 -- why", "$x + 1 "},
+		{"block comment", "$x /* mid */ + 1", "$x   + 1"},
+
+		// A Mendix string may legitimately contain these. Removing them would
+		// silently corrupt the value, which is worse than the bug being fixed.
+		{"-- inside a string literal", "'a--b'", "'a--b'"},
+		{"/* inside a string literal", "'a/*b'", "'a/*b'"},
+		{"comment marker after a string", "'a--b' -- real", "'a--b' "},
+		{
+			"escaped quote keeps the string open",
+			"'it''s -- fine'",
+			"'it''s -- fine'",
+		},
+
+		// A comment becomes whitespace, never nothing: gluing the operands
+		// together would change the expression rather than clean it.
+		{"tokens must not weld", "1 --c\n+ 2", "1 \n+ 2"},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			if got := stripMDLComments(tt.in); got != tt.want {
+				t.Errorf("stripMDLComments(%q)\n got: %q\nwant: %q", tt.in, got, tt.want)
+			}
+		})
+	}
+}
+
+// An unterminated block comment is a parse error the parser reports; the
+// stripper must not emit half of it into the model.
+func TestStripMDLComments_UnterminatedBlock(t *testing.T) {
+	if got := stripMDLComments("$x + /* oops"); got != "$x + " {
+		t.Errorf("got %q", got)
+	}
+}

From 416b4ee237011a39e82f7d4d97d6d94f7dc65b63 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 9 Aug 2026 08:32:23 +0000
Subject: [PATCH 12/29] fix(check): stop recommending a remedy Mendix rejects
 (CE6585)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CI caught this: the doctype gate failed on 10-odata-examples.mdl with

  [CE6585] "Published entity 'OdTest.LiveRow' must have a key defined."
           at Published OData service 'OdTest.BulkAPI'

The example demonstrated an "honest contract" resource by omitting the KEY —
the alternative MDL-ODATA02 offers to answering a key lookup. Mendix does not
permit that: a published entity must have a key. So the rule shipped in this
branch was recommending something the platform rejects, and the example
demonstrated it.

Corrected in all three places the claim appeared: the rule's suggestion, the
example, and odata-data-sharing.md. The resulting position is sharper than the
one it replaces — query options you may decline, the key you may not. A
microflow-backed resource whose rows a client can hold must answer the key
lookup; there is no opt-out.

I validated that example with `mxcli check`, which is parse-only and cannot see
a CE code, rather than the integration gate — the same mistake made earlier in
this branch on 18-folder-examples.mdl, and already written down in fix-issue.md
at the time. The new symptom row states the rule plainly: a change to
mdl-examples/doctype-tests/ is not done until the gate has run on it.

mxcli-formula1 §37 follow-up
---
 .claude/skills/fix-issue.md                      |  1 +
 .claude/skills/mendix/odata-data-sharing.md      |  7 ++++++-
 mdl-examples/doctype-tests/10-odata-examples.mdl | 10 +++++++---
 mdl/executor/validate_odata_read_contract.go     |  4 +++-
 4 files changed, 17 insertions(+), 5 deletions(-)

diff --git a/.claude/skills/fix-issue.md b/.claude/skills/fix-issue.md
index 822234933..352b8efa4 100644
--- a/.claude/skills/fix-issue.md
+++ b/.claude/skills/fix-issue.md
@@ -433,3 +433,4 @@ extracting `OffsetExpression`/`LimitExpression`.
 | No way to see what a running app's subsystem is doing: everything logs at `INFO`, the detail is not in the log at all, and raising the whole runtime to `TRACE` is unusable on a busy app | Nothing in mxcli drove the runtime's per-node log levels, though the M2EE admin API has exposed them all along | New `cmd/mxcli/docker/loglevels.go` (`GetLogSettings`, `SetLogLevels`, `NormalizeLogLevel`, `MatchLogNodes`), `cmd/mxcli/cmd_log.go` (`mxcli log list` / `log set`), documented in `.claude/skills/mendix/analyze-runtime.md` | **Probe an undocumented API before designing the command around it.** Every fact here came from a live 11.12.1 runtime: `get_log_settings` requires one of `node`/`subscriber`/`sort`; `sort` accepts only `node` and `subscriber`; `set_log_level` takes `{"nodes":[{name,level}],"force":bool}`. **The HTTP response for an AdminException says only "See logging output for details" — the actual message ("Please specify node, subscriber or sort option in params", "Unknown sort option: name", "Unknown LogNode X. Use the 'force' parameter…") is in the runtime log**, so probe with the runtime log open or you learn nothing. `force` means "allow a node that does not exist yet" and **permanently registers the name**, so a typo becomes a real empty node — hence it is opt-in, and an unknown node is an error by default. **Resist the subsystem-specific command**: this was proposed as `mxcli odata trace`, but `set_log_level` takes a list of nodes, so the primitive is generic and the OData knowledge belongs in docs. **The node list is a property of the APP, not of Mendix** — a node appears only once something registers it. A first pass concluded "there is no log node for a published OData service" from a project that had none; adding one service turns 57 nodes into 58 and `OData Publish` (with a space) appears, logging the full incoming URI at TRACE — exactly the question that motivated the command. Enumerating capabilities against one sample app and generalising is the trap; `log list` against *this* app is the answer. Distinguish "cannot reach the admin API" from "the runtime refused the request" (`ErrAdminUnreachable`) or the wrong hint buries the real one. Tests `cmd_log_test.go`, `loglevels_test.go`; verified end-to-end against a booted runtime (both arg forms, multi-node, typo refused, `--force` accepted, unreachable port). mxcli-formula1 suggested issue 4 |
 | A headless browser cannot log in to an app started with `--hub`, so every screenshot silently shows the login page and rendering defects survive every other check | Under `--hub` the runtime boots with the public **https** root URL, so it marks session cookies `Secure` and prefixes them `__Host-`; a browser on a non-trustworthy http origin cannot store them | `cmd/mxcli/docker/screenshot_login.go` — the login browser context declares `X-Forwarded-Proto: http` when the target is http (Mendix 10.24+ lets that header override `ApplicationRootUrl`) | **The reported cause did not reproduce as stated, and saying so is part of the fix.** On 11.12.1 an https root URL does *not* block a headless browser on `127.0.0.1`: loopback is a **trustworthy origin**, so Chromium accepts `Secure`/`__Host-` cookies there — the app rendered clean, no console errors, no failed requests. The mechanism is real only for a **non-loopback** http origin (a container hostname, a LAN address). Fix shipped anyway because the header is *accurate* rather than a workaround (the request genuinely is http), it costs nothing on an already-http root URL, and real users over https are unaffected. Verified at the layer the bug lives in: the captured Playwright storage state goes from `__Host-XASSESSIONID(secure=true)` to `XASSESSIONID(secure=false)`. **`curl` cannot see this class of bug and neither can a loopback browser** — when a report blames cookie flags, check whether the origin is trustworthy before believing the flags are the blocker. mxcli-formula1 §38 / suggested issue 7 |
 | A `--` comment written between two operands of a Mendix expression ends up **inside** the expression; the build fails **CE0117** "Error(s) in expression". `mxcli check` passes and `DESCRIBE` round-trips the comment, so nothing before mxbuild objects | `extractOriginalText` reads the raw input stream between two token positions — which is exactly what preserves an expression's spacing, and also drags in every token the lexer sent to a hidden channel. MDL's `--` and `/* */` are `-> skip`, so they never appear in `ctx.GetText()` but always appear in the source slice | `mdl/visitor/visitor_helpers.go` (`stripMDLComments`, `extractExpressionText`), applied at the six microflow-expression sites in `visitor_microflow_statements.go` / `visitor_microflow_actions.go` | **The ANTLR trap: `ctx.GetText()` excludes hidden tokens, a source-interval slice includes them.** Any code reaching for original text to preserve formatting inherits every comment in that span. **Replace a comment with whitespace, never with nothing** — `1 --c\n+ 2` must not become `1+ 2`, and `'a'--c\n'b'` must not weld into one token. **Respect single-quoted strings**: a Mendix string may legitimately contain `--` or `/*`, and stripping those corrupts the value (tested both, plus the `''` escape that keeps a string open). **Left OQL alone on purpose** — `visitor_entity.go` uses the same helper for view-entity queries, where `--` is legitimate SQL comment syntax; stripping it would change a different language's meaning. **The unit test alone would not have caught a wiring mistake**: it still passed with `extractExpressionText` bypassed, and only the mxbuild run (1 error → 0, same script, same project) proved the call sites were converted. Tests `visitor_strip_comments_test.go`, repro `mdl-examples/bug-tests/comment-in-expression.mdl`. mxcli-formula1 §34 / suggested issue 11 |
+| A published OData entity with no `KEY` fails the build with **CE6585** "Published entity 'X' must have a key defined." — so any advice of the form "drop the KEY" is impossible to follow | Mendix requires every published entity to have a key. MDL-ODATA02's suggestion offered "…or drop the KEY" as the alternative to answering a key lookup, and a doctype example demonstrated that non-existent option | `mdl/executor/validate_odata_read_contract.go` (suggestion text), `mdl-examples/doctype-tests/10-odata-examples.mdl`, `.claude/skills/mendix/odata-data-sharing.md` | **Query options you may decline; the key you may not.** A microflow-backed resource whose rows a client can hold *must* answer the key lookup — there is no opt-out, which makes MDL-ODATA02's real remedy singular rather than a choice. **Verify the remedy a diagnostic recommends, not just the diagnosis** — the rule correctly identified an unanswerable KEY and then proposed something mxbuild rejects, which is worse than saying nothing. This is the second time in one session that a doctype example was validated with `mxcli check` (parse-only) instead of the integration gate; `mxcli check` cannot see CE-codes at all, so **any change to `mdl-examples/doctype-tests/` needs `go test -tags integration -run TestMxCheck_DoctypeScripts/<script>` before it is called done** — the two-minute run that would have caught both. mxcli-formula1 §37 follow-up |
diff --git a/.claude/skills/mendix/odata-data-sharing.md b/.claude/skills/mendix/odata-data-sharing.md
index 10cd97774..707f38d6f 100644
--- a/.claude/skills/mendix/odata-data-sharing.md
+++ b/.claude/skills/mendix/odata-data-sharing.md
@@ -560,7 +560,12 @@ different objects are then on screen at once, and nothing distinguishes them
 until one travels to another page.
 
 So: `expose ( … (KEY) )` is a promise the *service* makes on the *microflow's*
-behalf. Branch key → id → filter → default, or do not declare the KEY.
+behalf. Branch key → id → filter → default.
+
+**Not declaring the KEY is not a way out.** Mendix requires a published entity to
+have one — `CE6585 "Published entity 'X' must have a key defined."` — so the only
+correct resolution is to answer the lookup. (Query *options* you may decline;
+the key you may not.)
 
 The request itself always arrives on `System.HttpRequest`:
 
diff --git a/mdl-examples/doctype-tests/10-odata-examples.mdl b/mdl-examples/doctype-tests/10-odata-examples.mdl
index 10655aa0e..657bdc134 100644
--- a/mdl-examples/doctype-tests/10-odata-examples.mdl
+++ b/mdl-examples/doctype-tests/10-odata-examples.mdl
@@ -594,8 +594,12 @@ create odata service OdTest.LiveAPI (
   expose ( RowKey as 'rowKey' (KEY), Label as 'label' )
 };
 
--- The honest variant: nothing is claimed, so nothing is promised. Note there is
--- no KEY — declaring one would promise a lookup Read_AllRows cannot answer.
+-- The honest variant: no paging is claimed, so none is promised.
+--
+-- The KEY stays. Mendix REQUIRES a published entity to have one (CE6585
+-- "Published entity 'X' must have a key defined."), so "drop the KEY" is not an
+-- available remedy — a resource whose rows a client can hold must answer the
+-- key lookup, full stop. What you CAN decline is the query options.
 create odata service OdTest.BulkAPI (
   path: 'odata/bulk/',
   version: '1.0.0',
@@ -609,7 +613,7 @@ create odata service OdTest.BulkAPI (
     InsertMode: not_supported, UpdateMode: not_supported, DeleteMode: not_supported,
     Countable: false, TopSupported: false, SkipSupported: false
   )
-  expose ( RowKey as 'rowKey', Label as 'label' )
+  expose ( RowKey as 'rowKey' (KEY), Label as 'label' )
 };
 
 -- ############################################################################
diff --git a/mdl/executor/validate_odata_read_contract.go b/mdl/executor/validate_odata_read_contract.go
index daeaa94f6..bc206bfab 100644
--- a/mdl/executor/validate_odata_read_contract.go
+++ b/mdl/executor/validate_odata_read_contract.go
@@ -102,7 +102,9 @@ func keyPromiseViolations(where string, e *ast.PublishedEntityDef, mf string) []
 		Suggestion: fmt.Sprintf(
 			"A client holding a row re-reads it by key on its own — Mendix's OData client sends `?$filter=%s eq '…'`. "+
 				"With no branch for it the request falls through to the collection default, the client adopts the FIRST row as that object's identity, and there is no error: valid collection, right count, 200. "+
-				"Give %s a `$Request: %s` parameter and branch key → filter → default, or drop the KEY.",
+				"Give %s a `$Request: %s` parameter and branch key → filter → default. "+
+				"Dropping the KEY is NOT an alternative: Mendix requires a published entity to have one "+
+				"(CE6585 \"Published entity must have a key defined\"), so the lookup has to be answered.",
 			keys[0], mf, httpRequestType),
 	}}
 }

From 1ab84da1cfab73a42a116bf8313b4a825159e095 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 9 Aug 2026 09:07:11 +0000
Subject: [PATCH 13/29] docs(check): correct a test comment that outlived the
 CE6585 finding
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The fixture for MDL-ODATA03 omits the KEY to isolate it from MDL-ODATA02, and
the comment described that as "the other way to be correct". It is not: Mendix
requires a published entity to have a key (CE6585), which is the same mistake
the previous commit fixed in the rule's own suggestion text — this copy of it
was left behind.

The comment now says why the fixture is shaped that way and what it must not be
read as. Query options are declinable; the key is not.
---
 mdl/executor/validate_odata_read_contract_test.go | 12 +++++++++---
 1 file changed, 9 insertions(+), 3 deletions(-)

diff --git a/mdl/executor/validate_odata_read_contract_test.go b/mdl/executor/validate_odata_read_contract_test.go
index 0ffd64a91..5c1cb75a3 100644
--- a/mdl/executor/validate_odata_read_contract_test.go
+++ b/mdl/executor/validate_odata_read_contract_test.go
@@ -98,9 +98,15 @@ func TestODataReadContract_SilentWhenTheMicroflowSeesTheRequest(t *testing.T) {
 	}
 }
 
-// An honest contract — no KEY, capabilities declared off — is the other way to
-// be correct, and is the only one available to a microflow that cannot parse a
-// URI. It must be silent, or the rule punishes the fix it recommends.
+// Declining the query options is the one thing a URI-blind microflow CAN do
+// honestly, and the rule must stay silent for it — otherwise it punishes the fix
+// it recommends.
+//
+// The fixture omits the KEY only to isolate MDL-ODATA03 from MDL-ODATA02. Do not
+// read that as a supported shape: Mendix requires a published entity to have a
+// key (CE6585 "Published entity must have a key defined"), so a real resource
+// always declares one and must therefore answer the lookup. Query options are
+// declinable; the key is not.
 func TestODataReadContract_SilentWhenTheContractIsHonest(t *testing.T) {
 	ids := odataReadRuleIDs(t, readContractScript(
 		"", ",\n    Countable: false, TopSupported: false, SkipSupported: false", "K as 'k'"))

From 10ba2e18b16ea03f0bf5baac175dfcf2d98b54d8 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 9 Aug 2026 10:07:19 +0000
Subject: [PATCH 14/29] feat(navigation): MENU ITEM ... ICON, against a Studio
 Pro reference

A navigation menu authored in MDL had no way to carry an icon: the grammar
had no ICON clause and buildMenuItemBson hardcoded `Icon: nil`, so an
MDL-built menu was flat text beside a Studio Pro-built one.

The reason this stayed unimplemented is the interesting part. The metamodel
names the element Pages$IconCollectionIcon, but Mendix *stores* it as
Forms$IconCollectionIcon -- one more case of the "Form was the original term
for Page" rename CLAUDE.md documents for ShowFormAction. That is not
derivable from the metamodel, and inventing a $Type for a polymorphic child
is precisely the failure that builds green and leaves a document Studio Pro
cannot open. A Studio Pro-authored project supplied the reference: storage
name, the Image field (a 3-part Module.Collection.name), and the exact key
set of $ID/$Type/Image and nothing else. The written element is byte-shape
identical to Studio Pro's.

All three icon variants coexist in one real document -- IconCollectionIcon
and ImageIcon both carry an indistinguishable qualified Image (the latter
points into an *image* collection), and GlyphIcon carries a numeric Code.
Only the icon-collection form is written. DESCRIBE reads all three back and
emits a `-- icon ... is not reproducible` comment for the other two, rather
than an `icon` clause that would silently convert the variant on replay.

The icon is a STRING_LITERAL, not a qualifiedName: Atlas icon names contain
hyphens (align-center), which IDENTIFIER cannot lex.

Also fixes a read-path divergence found by running DESCRIBE against a real
project under both engines: codec.Decode returns a bare *element.Base for an
unregistered $Type but a generated struct for a registered one, so asserting
on *element.Base dropped the name for exactly the variants that exist in
practice -- legacy printed every icon, modelsdk printed none. Both engines
now agree. convertNavMenuItem is a field-by-field copy and needed the new
fields too.

Verified: mxbuild doctype gate 0 errors on both engines; the written BSON
diffed against the Studio Pro original; DESCRIBE output replayed and the
icon-collection icons survive the round trip. Each test has a revert control
proving it reports the reported symptom.

mxcli-formula1 #9
---
 .claude/skills/fix-issue.md                   |   1 +
 .claude/skills/mendix/manage-navigation.md    |  40 ++++
 cmd/mxcli/syntax/features_misc.go             |  21 +-
 docs/01-project/MDL_QUICK_REFERENCE.md        |  15 +-
 .../doctype-tests/11-navigation-examples.mdl  |  21 ++
 mdl/ast/ast_navigation.go                     |   1 +
 mdl/backend/modelsdk/navigation_icon_test.go  | 128 ++++++++++++
 mdl/backend/modelsdk/navigation_read.go       |  31 +++
 mdl/backend/modelsdk/navigation_write.go      |  16 +-
 mdl/backend/mpr/convert.go                    |   1 +
 mdl/executor/cmd_navigation.go                |  39 +++-
 mdl/executor/cmd_navigation_icon_test.go      |  82 ++++++++
 mdl/grammar/MDLParser.g4                      |   6 +-
 mdl/types/navigation.go                       |  21 +-
 mdl/visitor/visitor_navigation.go             |  12 +-
 mdl/visitor/visitor_navigation_icon_test.go   |  87 ++++++++
 sdk/mpr/parser_misc.go                        |   8 +
 sdk/mpr/writer_navigation.go                  |  29 ++-
 sdk/mpr/writer_navigation_icon_test.go        | 192 ++++++++++++++++++
 19 files changed, 725 insertions(+), 26 deletions(-)
 create mode 100644 mdl/backend/modelsdk/navigation_icon_test.go
 create mode 100644 mdl/executor/cmd_navigation_icon_test.go
 create mode 100644 mdl/visitor/visitor_navigation_icon_test.go
 create mode 100644 sdk/mpr/writer_navigation_icon_test.go

diff --git a/.claude/skills/fix-issue.md b/.claude/skills/fix-issue.md
index 28c3f6d7e..4a8467eb4 100644
--- a/.claude/skills/fix-issue.md
+++ b/.claude/skills/fix-issue.md
@@ -438,3 +438,4 @@ extracting `OffsetExpression`/`LimitExpression`.
 | A `--` comment written between two operands of a Mendix expression ends up **inside** the expression; the build fails **CE0117** "Error(s) in expression". `mxcli check` passes and `DESCRIBE` round-trips the comment, so nothing before mxbuild objects | `extractOriginalText` reads the raw input stream between two token positions — which is exactly what preserves an expression's spacing, and also drags in every token the lexer sent to a hidden channel. MDL's `--` and `/* */` are `-> skip`, so they never appear in `ctx.GetText()` but always appear in the source slice | `mdl/visitor/visitor_helpers.go` (`stripMDLComments`, `extractExpressionText`), applied at the six microflow-expression sites in `visitor_microflow_statements.go` / `visitor_microflow_actions.go` | **The ANTLR trap: `ctx.GetText()` excludes hidden tokens, a source-interval slice includes them.** Any code reaching for original text to preserve formatting inherits every comment in that span. **Replace a comment with whitespace, never with nothing** — `1 --c\n+ 2` must not become `1+ 2`, and `'a'--c\n'b'` must not weld into one token. **Respect single-quoted strings**: a Mendix string may legitimately contain `--` or `/*`, and stripping those corrupts the value (tested both, plus the `''` escape that keeps a string open). **Left OQL alone on purpose** — `visitor_entity.go` uses the same helper for view-entity queries, where `--` is legitimate SQL comment syntax; stripping it would change a different language's meaning. **The unit test alone would not have caught a wiring mistake**: it still passed with `extractExpressionText` bypassed, and only the mxbuild run (1 error → 0, same script, same project) proved the call sites were converted. Tests `visitor_strip_comments_test.go`, repro `mdl-examples/bug-tests/comment-in-expression.mdl`. mxcli-formula1 §34 / suggested issue 11 |
 | A published OData entity with no `KEY` fails the build with **CE6585** "Published entity 'X' must have a key defined." — so any advice of the form "drop the KEY" is impossible to follow | Mendix requires every published entity to have a key. MDL-ODATA02's suggestion offered "…or drop the KEY" as the alternative to answering a key lookup, and a doctype example demonstrated that non-existent option | `mdl/executor/validate_odata_read_contract.go` (suggestion text), `mdl-examples/doctype-tests/10-odata-examples.mdl`, `.claude/skills/mendix/odata-data-sharing.md` | **Query options you may decline; the key you may not.** A microflow-backed resource whose rows a client can hold *must* answer the key lookup — there is no opt-out, which makes MDL-ODATA02's real remedy singular rather than a choice. **Verify the remedy a diagnostic recommends, not just the diagnosis** — the rule correctly identified an unanswerable KEY and then proposed something mxbuild rejects, which is worse than saying nothing. This is the second time in one session that a doctype example was validated with `mxcli check` (parse-only) instead of the integration gate; `mxcli check` cannot see CE-codes at all, so **any change to `mdl-examples/doctype-tests/` needs `go test -tags integration -run TestMxCheck_DoctypeScripts/<script>` before it is called done** — the two-minute run that would have caught both. mxcli-formula1 §37 follow-up |
 | A page written by mxcli will not open in Studio Pro, and `mx check` dies during *load* with `ArgumentNullException` at `EntityRefStep.set_AssociationId` — no page error, no CE code, the whole project is down rather than one document | An association DATASOURCE wrote the association name exactly as authored. Both halves of an `EntityRefStep` are BY_NAME and Mendix resolves either one it cannot find to null, but only `DestinationEntity` was guarded (issuetracker #14) — a bare `Order_Line` reached BSON unqualified. The **explicit-destination** form is the live trap: supplying the destination satisfies that guard, so nothing stood between a bare name and the crash — and `Assoc/Module.Entity` is exactly what the guard's error tells the author to write | `mdl/executor/cmd_pages_builder_v3.go` (`buildDataSourceV3`, `case "association"`: qualify via `resolveAssociationPathIn`, then verify an author-supplied destination's association exists via `associationEndpoints`) | **Guard every BY_NAME half of a ref, not the one that was reported.** #854 reported the destination; the association beside it failed identically and was reachable through the fix's own advice. **Diff the two properties in the dump** (`grep -A1 '"Key": "(Association\|DestinationEntity)"'`) rather than reading the exception name — the loader reports whichever it touches first. **Hold the input constant across builds**: the pre-fix binary was first run with bare names and post-fix with qualified ones, which "reproduced" nothing; re-running the *same qualified* script on both is what isolated cross-module (`""`) from same-module (resolved). `mx check` exits 0 on this failure — assert on the `contains: N errors` line, never `$?`. Tests `cmd_pages_builder_assoc_datasource_test.go`, example `mdl-examples/bug-tests/854-assoc-datasource-qualified-name.mdl`. upstream #854 follow-on |
+| A navigation menu item cannot be given an icon at all — the grammar has no `ICON`, and every item mxcli writes gets `Icon: null`, so a menu authored in MDL is flat text next to one authored in Studio Pro | The syntax was never added, and the reason it stayed unadded is instructive: the metamodel names the element `Pages$IconCollectionIcon`, but Mendix **stores** it as `Forms$IconCollectionIcon` — one more instance of the "Form was the original term for Page" rename CLAUDE.md documents for `ShowFormAction`. There was no way to know that from the metamodel alone, and inventing a `$Type` for a polymorphic child is the failure mode where mxbuild builds green and Studio Pro cannot open the document | `mdl/grammar/MDLParser.g4` (`navMenuItemDef`, both alternatives), `mdl/ast/ast_navigation.go`, `mdl/visitor/visitor_navigation.go` (positional `AllSTRING_LITERAL()` — caption and icon are both string literals), `mdl/types/navigation.go`, `mdl/executor/cmd_navigation.go` (`convertMenuItemDef`, `printMenuMDL`), `sdk/mpr/writer_navigation.go` (`buildMenuIconBson`), `mdl/backend/modelsdk/navigation_write.go`, `sdk/mpr/parser_misc.go`, `mdl/backend/mpr/convert.go` (`convertNavMenuItem` is a field-by-field copy and drops anything new) | **Get the reference before writing the BSON.** A Studio Pro-authored project (`ako/mxcli-ledger`) settled in one dump what no amount of metamodel reading could: the storage name, the field (`Image`, a 3-part `Module.Collection.name`), the exact key set (`$ID`/`$Type`/`Image`, nothing more), and that **all three variants coexist** — `Forms$IconCollectionIcon{Image}`, `Forms$ImageIcon{Image}` (indistinguishable by name alone; it points into an *image* collection), `Forms$GlyphIcon{Code: int}`. Only the first is written; DESCRIBE emits a `-- icon … is not reproducible` comment for the other two rather than an `icon` clause that would convert the variant on replay. To dump a v2 unit: `grep -rl 'Menus$MenuItem' mprcontents` then `bson.Unmarshal` into a `bson.D`. **`mx check` reporting 0 errors is not the proof here** — its deserializer tolerates unknown properties; the proof is diffing the written element against the Studio Pro one (done: byte-shape identical, same key order). Icon *names* are also not guessable — `Atlas.list` and `Atlas_Filled.user-check` do not exist while `list-bullets` and `user` do; verify against the collection. **Second trap, in the read path**: `codec.Decode` returns a bare `*element.Base` for an *unregistered* `$Type` but a generated struct (which only *embeds* Base) for a registered one, so `icon.(*element.Base)` silently returns nothing for exactly the variants that exist in real projects — DESCRIBE printed every icon under `legacy` and none under `modelsdk`. Assert on `interface{ Raw() bson.Raw }`, which both shapes satisfy. A unit test passing `nil` did not reach this; **running `describe` against a real Studio Pro project under both `MXCLI_ENGINE` values did**, and that engine-vs-engine diff is the cheapest way to find a read-path divergence. Note `modelsdk/codec` is on bson **v2** while `mdl/backend/modelsdk`'s write path is on v1 — a test touching both needs an alias. Tests `sdk/mpr/writer_navigation_icon_test.go`, `mdl/visitor/visitor_navigation_icon_test.go`, `mdl/executor/cmd_navigation_icon_test.go`, `mdl/backend/modelsdk/navigation_icon_test.go`; example `mdl-examples/doctype-tests/11-navigation-examples.mdl`. mxcli-formula1 #9 |
diff --git a/.claude/skills/mendix/manage-navigation.md b/.claude/skills/mendix/manage-navigation.md
index 1f1857a05..79f04ea92 100644
--- a/.claude/skills/mendix/manage-navigation.md
+++ b/.claude/skills/mendix/manage-navigation.md
@@ -84,6 +84,45 @@ create or replace navigation Responsive
   );
 ```
 
+### Menu Icons
+
+Both `menu item` and `menu 'caption' (...)` take an optional `icon`, naming an
+entry in an **icon collection**:
+
+```sql
+create or replace navigation Responsive
+  home page MyModule.Home_Web
+  menu (
+    menu item 'Home' page MyModule.Home_Web icon 'Atlas_Core.Atlas.home';
+    menu 'Orders' icon 'Atlas_Core.Atlas.shopping-cart' (
+      menu item 'All Orders' page Orders.Order_Overview
+        icon 'Atlas_Core.Atlas.list-bullets';
+    );
+  );
+```
+
+The name is **quoted** — Atlas icon names contain hyphens (`align-center`,
+`list-bullets`), so they are not bare identifiers. Atlas_Core ships three
+collections: `Atlas` (outline), `Atlas_Filled`, and `Atlas_Styling`. List what
+is actually available in your project rather than guessing a name:
+
+```sql
+show icon collection;
+describe icon collection Atlas_Core.Atlas;
+```
+
+**Only the icon-collection form is writable.** Studio Pro can also attach a
+*glyph* icon (a numeric character code) or an *image* icon (pointing into an
+image collection). Those are different elements with different fields, so MDL
+does not write them — and `describe navigation` reports them as a comment rather
+than emitting an `icon` clause that would silently convert one into the other on
+replay:
+
+```
+menu item 'Close' page MyModule.Close;
+-- icon System.Images.Close (Forms$ImageIcon) is not reproducible by CREATE NAVIGATION; set it in Studio Pro
+```
+
 ### Clear the Menu
 
 An empty `menu ()` block removes all menu items:
@@ -209,4 +248,5 @@ create or replace navigation Responsive
 - [ ] Role references in `for` clauses are fully qualified (`Module.Role`)
 - [ ] Every `menu item` and `menu 'caption' (...)` ends with `;`
 - [ ] Sub-menu items are wrapped in `menu 'caption' ( ... );`
+- [ ] `icon` names are quoted and exist — check with `describe icon collection Module.Name`, do not guess
 - [ ] Use `describe navigation` to verify changes after applying
diff --git a/cmd/mxcli/syntax/features_misc.go b/cmd/mxcli/syntax/features_misc.go
index a2d8e5ed1..cce82c91b 100644
--- a/cmd/mxcli/syntax/features_misc.go
+++ b/cmd/mxcli/syntax/features_misc.go
@@ -79,7 +79,7 @@ DISCONNECT;`,
 		Summary: "Create or replace a navigation profile with home pages, menus, and login page",
 		Keywords: []string{
 			"create navigation", "replace navigation", "home page",
-			"login page", "not found page", "menu item",
+			"login page", "not found page", "menu item", "menu icon",
 		},
 		Syntax: `CREATE OR REPLACE NAVIGATION <profile>
   HOME PAGE Module.Page
@@ -87,18 +87,23 @@ DISCONNECT;`,
   [LOGIN PAGE Module.LoginPage]
   [NOT FOUND PAGE Module.Custom404]
   [MENU (
-    MENU ITEM 'Label' PAGE Module.Page;
-    MENU 'Group' ( ... );
-  )];`,
+    MENU ITEM 'Label' PAGE Module.Page [ICON 'Module.IconCollection.name'];
+    MENU 'Group' [ICON 'Module.IconCollection.name'] ( ... );
+  )];
+
+-- ICON names an entry in an ICON COLLECTION (Atlas_Core.Atlas,
+-- Atlas_Core.Atlas_Filled, Atlas_Core.Atlas_Styling, or your own). It is
+-- quoted because Atlas icon names contain hyphens. Browse the available
+-- names with:  SHOW ICON COLLECTION  /  DESCRIBE ICON COLLECTION Module.Name`,
 		Example: `CREATE OR REPLACE NAVIGATION Responsive
   HOME PAGE MyModule.Home_Web
   HOME PAGE MyModule.AdminDashboard FOR Administration.Administrator
   LOGIN PAGE Administration.Login
   MENU (
-    MENU ITEM 'Home' PAGE MyModule.Home_Web;
-    MENU 'Orders' (
-      MENU ITEM 'All Orders' PAGE Orders.Order_Overview;
-      MENU ITEM 'New Order' PAGE Orders.Order_New;
+    MENU ITEM 'Home' PAGE MyModule.Home_Web ICON 'Atlas_Core.Atlas.home';
+    MENU 'Orders' ICON 'Atlas_Core.Atlas.shopping-cart' (
+      MENU ITEM 'All Orders' PAGE Orders.Order_Overview ICON 'Atlas_Core.Atlas.list-bullets';
+      MENU ITEM 'New Order' PAGE Orders.Order_New ICON 'Atlas_Core.Atlas.add';
     );
   );`,
 		SeeAlso: []string{"navigation.show"},
diff --git a/docs/01-project/MDL_QUICK_REFERENCE.md b/docs/01-project/MDL_QUICK_REFERENCE.md
index 7775d3167..a2d0b61ea 100644
--- a/docs/01-project/MDL_QUICK_REFERENCE.md
+++ b/docs/01-project/MDL_QUICK_REFERENCE.md
@@ -506,13 +506,24 @@ create or replace navigation Responsive
   login page Administration.Login
   not found page MyModule.Custom404
   menu (
-    menu item 'Home' page MyModule.Home_Web;
-    menu 'Admin' (
+    menu item 'Home' page MyModule.Home_Web icon 'Atlas_Core.Atlas.home';
+    menu 'Admin' icon 'Atlas_Core.Atlas.user' (
       menu item 'Users' page Administration.Account_Overview;
     );
   );
 ```
 
+`icon` is optional and names an entry in an **icon collection** —
+`Atlas_Core.Atlas`, `Atlas_Core.Atlas_Filled`, `Atlas_Core.Atlas_Styling`, or one
+of your own. It is quoted because Atlas icon names contain hyphens
+(`align-center`). List the available names with `describe icon collection
+Atlas_Core.Atlas`.
+
+Studio Pro can also set a *glyph* icon (a numeric character code) or an *image*
+icon (pointing into an image collection). Those are different elements; MDL
+writes only the icon-collection form, and `describe navigation` marks the other
+two with a comment instead of emitting an `icon` clause that would convert them.
+
 ## Project Settings
 
 | Statement | Syntax | Notes |
diff --git a/mdl-examples/doctype-tests/11-navigation-examples.mdl b/mdl-examples/doctype-tests/11-navigation-examples.mdl
index 21c648e79..6d91b7c52 100644
--- a/mdl-examples/doctype-tests/11-navigation-examples.mdl
+++ b/mdl-examples/doctype-tests/11-navigation-examples.mdl
@@ -88,6 +88,27 @@ create or replace navigation Responsive
     );
   );
 
+-- ============================================================================
+-- ICON — a menu item's icon, named as Module.IconCollection.icon
+-- The name is quoted because Atlas icon names contain hyphens. It resolves to
+-- an icon collection (Atlas_Core.Atlas, Atlas_Core.Atlas_Filled, …), not an
+-- image collection.
+-- ============================================================================
+
+create or replace navigation Responsive
+  home page NavTest.NavTest_Home
+  login page Administration.login
+  menu (
+    menu item 'Home' page NavTest.NavTest_Home icon 'Atlas_Core.Atlas.home';
+    menu 'Admin' icon 'Atlas_Core.Atlas.user' (
+      menu item 'Users' page Administration.Account_Overview
+        icon 'Atlas_Core.Atlas_Filled.user';
+    );
+  );
+
+-- DESCRIBE round-trips the ICON clause, so this output is re-executable
+describe navigation Responsive;
+
 -- Clear the menu (empty MENU block removes all items)
 create or replace navigation Responsive
   home page NavTest.NavTest_Home
diff --git a/mdl/ast/ast_navigation.go b/mdl/ast/ast_navigation.go
index a231be948..7ce9c6715 100644
--- a/mdl/ast/ast_navigation.go
+++ b/mdl/ast/ast_navigation.go
@@ -28,5 +28,6 @@ type NavMenuItemDef struct {
 	Caption   string           // from STRING_LITERAL
 	Page      *QualifiedName   // PAGE target
 	Microflow *QualifiedName   // MICROFLOW target
+	Icon      string           // ICON 'Module.Collection.name', empty for none
 	Items     []NavMenuItemDef // Sub-items (for MENU 'caption' (...))
 }
diff --git a/mdl/backend/modelsdk/navigation_icon_test.go b/mdl/backend/modelsdk/navigation_icon_test.go
new file mode 100644
index 000000000..a16988d55
--- /dev/null
+++ b/mdl/backend/modelsdk/navigation_icon_test.go
@@ -0,0 +1,128 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package modelsdkbackend
+
+import (
+	"testing"
+
+	"github.com/mendixlabs/mxcli/mdl/types"
+	"github.com/mendixlabs/mxcli/modelsdk/codec"
+	"github.com/mendixlabs/mxcli/modelsdk/element"
+	"go.mongodb.org/mongo-driver/bson"
+	bsonv2 "go.mongodb.org/mongo-driver/v2/bson"
+)
+
+func navIconEntry(d bson.D, key string) (interface{}, bool) {
+	for _, e := range d {
+		if e.Key == key {
+			return e.Value, true
+		}
+	}
+	return nil, false
+}
+
+// Both engines write the same document, so the storage name has to agree. A
+// divergence here means MXCLI_ENGINE silently changes what lands in the .mpr —
+// and only one of the two would open in Studio Pro.
+func TestNavMenuIconBson_MatchesTheMprEngine(t *testing.T) {
+	d, ok := navMenuIconBson("Atlas_Core.Atlas.align-center").(bson.D)
+	if !ok {
+		t.Fatal("expected a bson.D")
+	}
+	if typ, _ := navIconEntry(d, "$Type"); typ != "Forms$IconCollectionIcon" {
+		t.Errorf("$Type = %v, want Forms$IconCollectionIcon", typ)
+	}
+	if img, _ := navIconEntry(d, "Image"); img != "Atlas_Core.Atlas.align-center" {
+		t.Errorf("Image = %v", img)
+	}
+	if len(d) != 3 {
+		t.Errorf("icon has %d keys, want exactly $ID/$Type/Image: %v", len(d), d)
+	}
+}
+
+func TestNavMenuIconBson_EmptyNameStaysNull(t *testing.T) {
+	if got := navMenuIconBson(""); got != nil {
+		t.Errorf("navMenuIconBson(\"\") = %v, want nil", got)
+	}
+}
+
+// The Icon must survive navMenuItemBson, not just the helper.
+func TestNavMenuItemBson_CarriesTheIconThrough(t *testing.T) {
+	item := navMenuItemBson(types.NavMenuItemSpec{
+		Caption: "Dashboard", Page: "M.Dash", Icon: "Atlas_Core.Atlas.align-center",
+	})
+	icon, present := navIconEntry(item, "Icon")
+	if !present {
+		t.Fatal("the Icon key must always be written")
+	}
+	d, ok := icon.(bson.D)
+	if !ok {
+		t.Fatalf("Icon = %#v; the authored icon was dropped", icon)
+	}
+	if img, _ := navIconEntry(d, "Image"); img != "Atlas_Core.Atlas.align-center" {
+		t.Errorf("Image = %v", img)
+	}
+}
+
+func TestMenuIconOf_NilIconYieldsNothing(t *testing.T) {
+	typeName, image := menuIconOf(nil)
+	if typeName != "" || image != "" {
+		t.Errorf("menuIconOf(nil) = (%q, %q), want empty", typeName, image)
+	}
+}
+
+// decodeIcon puts an icon document through the real codec, which is the only
+// way to get the element shape menuIconOf actually receives.
+func decodeIcon(t *testing.T, typeName string, extra bsonv2.E) element.Element {
+	t.Helper()
+	doc := bsonv2.D{{Key: "$Type", Value: typeName}, extra}
+	raw, err := bsonv2.Marshal(bsonv2.D{{Key: "Icon", Value: doc}})
+	if err != nil {
+		t.Fatalf("marshalling the fixture: %v", err)
+	}
+	el, err := codec.DecodeChild(bsonv2.Raw(raw), "Icon")
+	if err != nil {
+		t.Fatalf("decoding the icon: %v", err)
+	}
+	return el
+}
+
+// menuIconOf must read the name off a REGISTERED variant.
+//
+// This is the case a nil-only test cannot reach. The codec returns a bare
+// *element.Base for an unregistered type but a generated struct — which merely
+// embeds Base — for a registered one. An assertion on *element.Base therefore
+// fails for precisely the variants that exist in real projects, and DESCRIBE
+// dropped every Atlas icon under this engine while the legacy engine printed
+// them. Caught only by running against a real project, not by a unit test on a
+// hand-built value.
+func TestMenuIconOf_ReadsTheNameOffARegisteredVariant(t *testing.T) {
+	for _, tc := range []struct{ typeName, image string }{
+		{"Forms$IconCollectionIcon", "Atlas_Core.Atlas.align-center"},
+		{"Forms$ImageIcon", "System.Images.Close"},
+	} {
+		t.Run(tc.typeName, func(t *testing.T) {
+			el := decodeIcon(t, tc.typeName, bsonv2.E{Key: "Image", Value: tc.image})
+			gotType, gotImage := menuIconOf(el)
+			if gotType != tc.typeName {
+				t.Errorf("type = %q, want %q", gotType, tc.typeName)
+			}
+			if gotImage != tc.image {
+				t.Errorf("image = %q, want %q — the name was dropped", gotImage, tc.image)
+			}
+		})
+	}
+}
+
+// A glyph carries a Code and no name; reporting an empty image is what stops
+// DESCRIBE from emitting a lossy ICON clause for it.
+func TestMenuIconOf_GlyphHasNoName(t *testing.T) {
+	el := decodeIcon(t, "Forms$GlyphIcon", bsonv2.E{Key: "Code", Value: int32(9999)})
+	gotType, gotImage := menuIconOf(el)
+	if gotType != "Forms$GlyphIcon" {
+		t.Errorf("type = %q", gotType)
+	}
+	if gotImage != "" {
+		t.Errorf("image = %q, want empty: a glyph has no qualified name", gotImage)
+	}
+}
diff --git a/mdl/backend/modelsdk/navigation_read.go b/mdl/backend/modelsdk/navigation_read.go
index d1245bae5..b1163ee9e 100644
--- a/mdl/backend/modelsdk/navigation_read.go
+++ b/mdl/backend/modelsdk/navigation_read.go
@@ -14,6 +14,7 @@ import (
 	genPages "github.com/mendixlabs/mxcli/modelsdk/gen/pages"
 	genTexts "github.com/mendixlabs/mxcli/modelsdk/gen/texts"
 	"github.com/mendixlabs/mxcli/modelsdk/mprread"
+	"go.mongodb.org/mongo-driver/v2/bson"
 )
 
 // GetNavigation reads the Navigation$NavigationDocument unit and converts it to
@@ -170,6 +171,7 @@ func navMenuItemFromGen(el element.Element) *types.NavMenuItem {
 	item := &types.NavMenuItem{
 		Caption: textOf(mi.Caption()),
 	}
+	item.IconType, item.Icon = menuIconOf(mi.Icon())
 	resolveMenuAction(item, mi.Action())
 	for _, subEl := range mi.ItemsItems() {
 		if sub := navMenuItemFromGen(subEl); sub != nil {
@@ -182,6 +184,35 @@ func navMenuItemFromGen(el element.Element) *types.NavMenuItem {
 	return item
 }
 
+// menuIconOf reports a menu item's icon storage $Type and, for the two variants
+// that carry one, its qualified image name. Forms$GlyphIcon has a numeric Code
+// and no name, so it yields a type with an empty name — which is what keeps
+// DESCRIBE from emitting an ICON clause it cannot faithfully round-trip.
+//
+// The name is read off the element's raw BSON rather than a typed accessor,
+// because the variants decode inconsistently: an unregistered type arrives as a
+// bare *element.Base while a registered one arrives as a generated struct that
+// merely embeds it. Asserting on *element.Base therefore silently returns
+// nothing for exactly the registered variants — which is what made DESCRIBE drop
+// every Atlas icon under this engine while the legacy engine printed them. Match
+// on the Raw() method instead, which both shapes satisfy.
+func menuIconOf(icon element.Element) (typeName, image string) {
+	if icon == nil {
+		return "", ""
+	}
+	typeName = icon.TypeName()
+	raw, ok := icon.(interface{ Raw() bson.Raw })
+	if !ok {
+		return typeName, ""
+	}
+	if v, err := raw.Raw().LookupErr("Image"); err == nil {
+		if s, ok := v.StringValueOK(); ok {
+			image = s
+		}
+	}
+	return typeName, image
+}
+
 // resolveMenuAction sets the action type / target on a NavMenuItem from a gen
 // client-action element, mirroring the legacy action-type dispatch.
 func resolveMenuAction(item *types.NavMenuItem, action element.Element) {
diff --git a/mdl/backend/modelsdk/navigation_write.go b/mdl/backend/modelsdk/navigation_write.go
index 0e0ac07c3..f9f16cf62 100644
--- a/mdl/backend/modelsdk/navigation_write.go
+++ b/mdl/backend/modelsdk/navigation_write.go
@@ -227,7 +227,7 @@ func navMenuItemBson(mi types.NavMenuItemSpec) bson.D {
 		{Key: "Action", Value: navMenuAction(mi)},
 		{Key: "AlternativeText", Value: nil},
 		{Key: "Caption", Value: navCaptionBson(mi.Caption)},
-		{Key: "Icon", Value: nil},
+		{Key: "Icon", Value: navMenuIconBson(mi.Icon)},
 	}
 	subItems := bson.A{int32(1)}
 	for _, sub := range mi.Items {
@@ -237,6 +237,20 @@ func navMenuItemBson(mi types.NavMenuItemSpec) bson.D {
 	return item
 }
 
+// navMenuIconBson mirrors sdk/mpr's buildMenuIconBson: the storage name is
+// Forms$IconCollectionIcon (not the metamodel's Pages$…), and only that variant
+// is emitted. See the comment there for why GlyphIcon/ImageIcon are excluded.
+func navMenuIconBson(icon string) interface{} {
+	if icon == "" {
+		return nil
+	}
+	return bson.D{
+		{Key: "$ID", Value: navID()},
+		{Key: "$Type", Value: "Forms$IconCollectionIcon"},
+		{Key: "Image", Value: icon},
+	}
+}
+
 func navCaptionBson(text string) bson.D {
 	return bson.D{
 		{Key: "$ID", Value: navID()},
diff --git a/mdl/backend/mpr/convert.go b/mdl/backend/mpr/convert.go
index fa2e0648e..4807166f9 100644
--- a/mdl/backend/mpr/convert.go
+++ b/mdl/backend/mpr/convert.go
@@ -233,6 +233,7 @@ func convertNavProfile(in *mpr.NavigationProfile) *types.NavigationProfile {
 func convertNavMenuItem(in *mpr.NavMenuItem) *types.NavMenuItem {
 	mi := &types.NavMenuItem{
 		Caption: in.Caption, Page: in.Page, Microflow: in.Microflow, ActionType: in.ActionType,
+		Icon: in.Icon, IconType: in.IconType,
 	}
 	if in.Items != nil {
 		mi.Items = make([]*types.NavMenuItem, len(in.Items))
diff --git a/mdl/executor/cmd_navigation.go b/mdl/executor/cmd_navigation.go
index 380835252..73745ab0e 100644
--- a/mdl/executor/cmd_navigation.go
+++ b/mdl/executor/cmd_navigation.go
@@ -76,6 +76,7 @@ func execAlterNavigation(ctx *ExecContext, s *ast.AlterNavigationStmt) error {
 func convertMenuItemDef(def ast.NavMenuItemDef) types.NavMenuItemSpec {
 	spec := types.NavMenuItemSpec{
 		Caption: def.Caption,
+		Icon:    def.Icon,
 	}
 	if def.Page != nil {
 		spec.Page = def.Page.String()
@@ -347,17 +348,47 @@ func menuItemTarget(item *types.NavMenuItem) string {
 func printMenuMDL(w io.Writer, items []*types.NavMenuItem, depth int) {
 	indent := strings.Repeat("  ", depth)
 	for _, item := range items {
+		icon := menuItemIconMDL(item)
 		if len(item.Items) > 0 {
 			// Sub-menu container
-			fmt.Fprintf(w, "%smenu '%s' (\n", indent, item.Caption)
+			fmt.Fprintf(w, "%smenu '%s'%s (\n", indent, item.Caption, icon)
 			printMenuMDL(w, item.Items, depth+1)
 			fmt.Fprintf(w, "%s);\n", indent)
 		} else if item.Page != "" {
-			fmt.Fprintf(w, "%smenu item '%s' page %s;\n", indent, item.Caption, item.Page)
+			fmt.Fprintf(w, "%smenu item '%s' page %s%s;\n", indent, item.Caption, item.Page, icon)
 		} else if item.Microflow != "" {
-			fmt.Fprintf(w, "%smenu item '%s' microflow %s;\n", indent, item.Caption, item.Microflow)
+			fmt.Fprintf(w, "%smenu item '%s' microflow %s%s;\n", indent, item.Caption, item.Microflow, icon)
 		} else {
-			fmt.Fprintf(w, "%smenu item '%s';\n", indent, item.Caption)
+			fmt.Fprintf(w, "%smenu item '%s'%s;\n", indent, item.Caption, icon)
 		}
+		if note := menuItemIconNote(item); note != "" {
+			fmt.Fprintf(w, "%s%s\n", indent, note)
+		}
+	}
+}
+
+// menuItemIconMDL renders the ICON clause for a menu item, or "" when there is
+// nothing CREATE NAVIGATION can reproduce.
+func menuItemIconMDL(item *types.NavMenuItem) string {
+	if item.Icon == "" || !strings.HasSuffix(item.IconType, "IconCollectionIcon") {
+		return ""
 	}
+	return fmt.Sprintf(" icon '%s'", item.Icon)
+}
+
+// menuItemIconNote flags an icon DESCRIBE cannot round-trip, so re-running the
+// output loses it visibly rather than silently. CREATE NAVIGATION writes only
+// Forms$IconCollectionIcon; a glyph icon (numeric Code) or an image icon
+// (pointing into an image collection, not an icon collection) is a different
+// element and would have to be guessed at.
+func menuItemIconNote(item *types.NavMenuItem) string {
+	if item.IconType == "" || strings.HasSuffix(item.IconType, "IconCollectionIcon") {
+		return ""
+	}
+	target := item.Icon
+	if target == "" {
+		target = "a numeric glyph code"
+	}
+	return fmt.Sprintf("-- icon %s (%s) is not reproducible by CREATE NAVIGATION; set it in Studio Pro",
+		target, item.IconType)
 }
diff --git a/mdl/executor/cmd_navigation_icon_test.go b/mdl/executor/cmd_navigation_icon_test.go
new file mode 100644
index 000000000..db3cc2e27
--- /dev/null
+++ b/mdl/executor/cmd_navigation_icon_test.go
@@ -0,0 +1,82 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package executor
+
+import (
+	"bytes"
+	"strings"
+	"testing"
+
+	"github.com/mendixlabs/mxcli/mdl/types"
+)
+
+// menuMDL renders items through the DESCRIBE emitter.
+func menuMDL(items []*types.NavMenuItem) string {
+	var b bytes.Buffer
+	printMenuMDL(&b, items, 0)
+	return b.String()
+}
+
+// DESCRIBE emits re-executable MDL, so an icon it read must come back out — the
+// alternative is output that silently rewrites the menu when replayed.
+func TestPrintMenuMDL_RoundTripsAnIconCollectionIcon(t *testing.T) {
+	got := menuMDL([]*types.NavMenuItem{{
+		Caption:  "Dashboard",
+		Page:     "M.Dash",
+		Icon:     "Atlas_Core.Atlas.align-center",
+		IconType: "Forms$IconCollectionIcon",
+	}})
+	want := "menu item 'Dashboard' page M.Dash icon 'Atlas_Core.Atlas.align-center';\n"
+	if got != want {
+		t.Errorf("got %q, want %q", got, want)
+	}
+}
+
+// A sub-menu carries its icon before the parenthesised body, matching the
+// grammar's second alternative.
+func TestPrintMenuMDL_RoundTripsASubMenuIcon(t *testing.T) {
+	got := menuMDL([]*types.NavMenuItem{{
+		Caption:  "Reports",
+		Icon:     "Atlas_Core.Atlas.folder",
+		IconType: "Forms$IconCollectionIcon",
+		Items:    []*types.NavMenuItem{{Caption: "Monthly", Page: "M.Monthly"}},
+	}})
+	if !strings.HasPrefix(got, "menu 'Reports' icon 'Atlas_Core.Atlas.folder' (\n") {
+		t.Errorf("sub-menu header lost its icon: %q", got)
+	}
+	if !strings.Contains(got, "menu item 'Monthly' page M.Monthly;") {
+		t.Errorf("sub-items went missing: %q", got)
+	}
+}
+
+// The other two variants are real and appear in Studio Pro-authored projects,
+// but CREATE NAVIGATION cannot write them. Emitting `icon '…'` for an ImageIcon
+// would convert it to an IconCollectionIcon on replay — a silent variant swap.
+// The loss has to be visible instead.
+func TestPrintMenuMDL_FlagsAnIconItCannotReproduce(t *testing.T) {
+	for _, tc := range []struct{ name, iconType, icon, wantIn string }{
+		{"image icon", "Forms$ImageIcon", "System.Images.Close", "System.Images.Close"},
+		{"glyph icon", "Forms$GlyphIcon", "", "a numeric glyph code"},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			got := menuMDL([]*types.NavMenuItem{{
+				Caption: "Close", Page: "M.Close", Icon: tc.icon, IconType: tc.iconType,
+			}})
+			if strings.Contains(got, "icon '") {
+				t.Errorf("emitted an ICON clause for %s, which replay would convert: %q",
+					tc.iconType, got)
+			}
+			if !strings.Contains(got, "-- icon") || !strings.Contains(got, tc.wantIn) {
+				t.Errorf("the unreproducible icon was dropped silently: %q", got)
+			}
+		})
+	}
+}
+
+// No icon means no clause and no note — the common case must stay clean.
+func TestPrintMenuMDL_SilentWhenThereIsNoIcon(t *testing.T) {
+	got := menuMDL([]*types.NavMenuItem{{Caption: "Dashboard", Page: "M.Dash"}})
+	if got != "menu item 'Dashboard' page M.Dash;\n" {
+		t.Errorf("got %q", got)
+	}
+}
diff --git a/mdl/grammar/MDLParser.g4 b/mdl/grammar/MDLParser.g4
index ad7b02d17..44a064cee 100644
--- a/mdl/grammar/MDLParser.g4
+++ b/mdl/grammar/MDLParser.g4
@@ -287,9 +287,11 @@ navigationClause
     | MENU_KW LPAREN navMenuItemDef* RPAREN
     ;
 
+// The icon is a STRING_LITERAL, not a qualifiedName: Atlas icon names carry
+// hyphens (Atlas_Core.Atlas.align-center), which IDENTIFIER cannot lex.
 navMenuItemDef
-    : MENU_KW ITEM STRING_LITERAL ((PAGE qualifiedName) | (MICROFLOW qualifiedName))? SEMICOLON?
-    | MENU_KW STRING_LITERAL LPAREN navMenuItemDef* RPAREN SEMICOLON?
+    : MENU_KW ITEM STRING_LITERAL ((PAGE qualifiedName) | (MICROFLOW qualifiedName))? (ICON STRING_LITERAL)? SEMICOLON?
+    | MENU_KW STRING_LITERAL (ICON STRING_LITERAL)? LPAREN navMenuItemDef* RPAREN SEMICOLON?
     ;
 
 dropStatement
diff --git a/mdl/types/navigation.go b/mdl/types/navigation.go
index b3a14dacf..dc8187a5f 100644
--- a/mdl/types/navigation.go
+++ b/mdl/types/navigation.go
@@ -46,11 +46,17 @@ type NavRoleBasedHome struct {
 
 // NavMenuItem is a recursive navigation menu entry.
 type NavMenuItem struct {
-	Caption    string         `json:"caption"`
-	Page       string         `json:"page,omitempty"`
-	Microflow  string         `json:"microflow,omitempty"`
-	ActionType string         `json:"actionType,omitempty"`
-	Items      []*NavMenuItem `json:"items,omitempty"`
+	Caption    string `json:"caption"`
+	Page       string `json:"page,omitempty"`
+	Microflow  string `json:"microflow,omitempty"`
+	ActionType string `json:"actionType,omitempty"`
+	// Icon is the qualified name an icon-collection or image icon points at.
+	// Empty for no icon and for a glyph icon, which carries a numeric Code
+	// instead. IconType keeps the storage $Type so a reader can tell the three
+	// apart — DESCRIBE only round-trips Forms$IconCollectionIcon.
+	Icon     string         `json:"icon,omitempty"`
+	IconType string         `json:"iconType,omitempty"`
+	Items    []*NavMenuItem `json:"items,omitempty"`
 }
 
 // NavOfflineEntity declares offline sync rules for an entity.
@@ -81,5 +87,8 @@ type NavMenuItemSpec struct {
 	Caption   string
 	Page      string
 	Microflow string
-	Items     []NavMenuItemSpec
+	// Icon is a qualified icon-collection name (Atlas_Core.Atlas.home). Empty
+	// means no icon, which serializes as a null Icon.
+	Icon  string
+	Items []NavMenuItemSpec
 }
diff --git a/mdl/visitor/visitor_navigation.go b/mdl/visitor/visitor_navigation.go
index bcef1c4ef..e263e4640 100644
--- a/mdl/visitor/visitor_navigation.go
+++ b/mdl/visitor/visitor_navigation.go
@@ -86,13 +86,21 @@ func (b *Builder) processNavigationClause(stmt *ast.AlterNavigationStmt, ctx *pa
 func buildNavMenuItemDef(ctx parser.INavMenuItemDefContext) ast.NavMenuItemDef {
 	c := ctx.(*parser.NavMenuItemDefContext)
 
+	// Both alternatives put the caption first and the optional ICON string
+	// second, so positional access is unambiguous.
+	literals := c.AllSTRING_LITERAL()
 	caption := ""
-	if sl := c.STRING_LITERAL(); sl != nil {
-		caption = unquoteString(sl.GetText())
+	if len(literals) > 0 {
+		caption = unquoteString(literals[0].GetText())
+	}
+	icon := ""
+	if c.ICON() != nil && len(literals) > 1 {
+		icon = unquoteString(literals[1].GetText())
 	}
 
 	item := ast.NavMenuItemDef{
 		Caption: caption,
+		Icon:    icon,
 	}
 
 	// The grammar uses a single qualifiedName for either PAGE or MICROFLOW target
diff --git a/mdl/visitor/visitor_navigation_icon_test.go b/mdl/visitor/visitor_navigation_icon_test.go
new file mode 100644
index 000000000..82835a1b0
--- /dev/null
+++ b/mdl/visitor/visitor_navigation_icon_test.go
@@ -0,0 +1,87 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package visitor
+
+import (
+	"testing"
+
+	"github.com/mendixlabs/mxcli/mdl/ast"
+)
+
+// navMenuItems parses a CREATE NAVIGATION with the given menu body and returns
+// its top-level items.
+func navMenuItems(t *testing.T, menuBody string) []ast.NavMenuItemDef {
+	t.Helper()
+	prog, errs := Build("CREATE NAVIGATION Responsive MENU (\n" + menuBody + "\n);")
+	if len(errs) > 0 {
+		t.Fatalf("parsing the menu: %v", errs)
+	}
+	stmt, ok := prog.Statements[0].(*ast.AlterNavigationStmt)
+	if !ok {
+		t.Fatalf("expected AlterNavigationStmt, got %T", prog.Statements[0])
+	}
+	return stmt.MenuItems
+}
+
+// mxcli-formula1 §9: a menu item's icon could not be expressed at all. The name
+// is a STRING_LITERAL because Atlas icon names carry hyphens
+// (Atlas_Core.Atlas.align-center), which IDENTIFIER cannot lex — so a
+// qualifiedName form would not have parsed.
+func TestNavMenuItem_ParsesTheIconOnALeafItem(t *testing.T) {
+	items := navMenuItems(t,
+		"MENU ITEM 'Dashboard' PAGE M.Dash ICON 'Atlas_Core.Atlas.align-center';")
+	if len(items) != 1 {
+		t.Fatalf("expected 1 item, got %d", len(items))
+	}
+	if items[0].Icon != "Atlas_Core.Atlas.align-center" {
+		t.Errorf("Icon = %q, want the hyphenated Atlas name", items[0].Icon)
+	}
+	if items[0].Page == nil || items[0].Page.Name != "Dash" {
+		t.Error("the ICON clause must not displace the PAGE target")
+	}
+}
+
+// The sub-menu alternative takes an icon too, before its parenthesised body.
+func TestNavMenuItem_ParsesTheIconOnASubMenu(t *testing.T) {
+	items := navMenuItems(t,
+		"MENU 'Reports' ICON 'Atlas_Core.Atlas.folder' (\n"+
+			"  MENU ITEM 'Monthly' PAGE M.Monthly;\n"+
+			");")
+	if len(items) != 1 {
+		t.Fatalf("expected 1 item, got %d", len(items))
+	}
+	if items[0].Icon != "Atlas_Core.Atlas.folder" {
+		t.Errorf("sub-menu Icon = %q", items[0].Icon)
+	}
+	if len(items[0].Items) != 1 || items[0].Items[0].Caption != "Monthly" {
+		t.Errorf("the icon swallowed the sub-items: %+v", items[0].Items)
+	}
+}
+
+// The clause is optional, and its absence must not be confused with the caption
+// — both are STRING_LITERALs, so the visitor reads them positionally and has to
+// be pinned against picking up the caption as an icon.
+func TestNavMenuItem_NoIconClauseLeavesIconEmpty(t *testing.T) {
+	items := navMenuItems(t, "MENU ITEM 'Dashboard' PAGE M.Dash;")
+	if len(items) != 1 {
+		t.Fatalf("expected 1 item, got %d", len(items))
+	}
+	if items[0].Icon != "" {
+		t.Errorf("Icon = %q, want empty when no ICON clause is written", items[0].Icon)
+	}
+}
+
+// An icon on an item with no action at all still parses: ICON is independent of
+// the optional PAGE/MICROFLOW target.
+func TestNavMenuItem_IconWithoutATarget(t *testing.T) {
+	items := navMenuItems(t, "MENU ITEM 'Placeholder' ICON 'Atlas_Core.Atlas.home';")
+	if len(items) != 1 {
+		t.Fatalf("expected 1 item, got %d", len(items))
+	}
+	if items[0].Icon != "Atlas_Core.Atlas.home" {
+		t.Errorf("Icon = %q", items[0].Icon)
+	}
+	if items[0].Page != nil || items[0].Microflow != nil {
+		t.Error("no target was written, so none must be built")
+	}
+}
diff --git a/sdk/mpr/parser_misc.go b/sdk/mpr/parser_misc.go
index 4d87ff96f..07f5258f7 100644
--- a/sdk/mpr/parser_misc.go
+++ b/sdk/mpr/parser_misc.go
@@ -563,6 +563,14 @@ func parseNavMenuItem(raw map[string]any) *NavMenuItem {
 		mi.Caption = extractTextFromBson(caption)
 	}
 
+	// Icon is polymorphic: Forms$IconCollectionIcon and Forms$ImageIcon carry a
+	// qualified Image, Forms$GlyphIcon carries a numeric Code and no name at
+	// all. Keep the $Type so callers can tell which one they got.
+	if icon, ok := raw["Icon"].(map[string]any); ok {
+		mi.IconType = extractString(icon["$Type"])
+		mi.Icon = extractString(icon["Image"])
+	}
+
 	// Extract action type and target from Action
 	if action, ok := raw["Action"].(map[string]any); ok {
 		actionType := extractString(action["$Type"])
diff --git a/sdk/mpr/writer_navigation.go b/sdk/mpr/writer_navigation.go
index cd01d9986..41a56a891 100644
--- a/sdk/mpr/writer_navigation.go
+++ b/sdk/mpr/writer_navigation.go
@@ -253,7 +253,7 @@ func buildMenuItemBson(mi NavMenuItemSpec) bson.D {
 		{Key: "Action", Value: buildMenuAction(mi)},
 		{Key: "AlternativeText", Value: nil},
 		{Key: "Caption", Value: buildCaptionBson(mi.Caption)},
-		{Key: "Icon", Value: nil},
+		{Key: "Icon", Value: buildMenuIconBson(mi.Icon)},
 	}
 
 	// Sub-items
@@ -266,6 +266,33 @@ func buildMenuItemBson(mi NavMenuItemSpec) bson.D {
 	return item
 }
 
+// buildMenuIconBson builds a menu item's Icon, or nil when none is set.
+//
+// The metamodel calls this Pages$IconCollectionIcon, but the storage name is
+// Forms$IconCollectionIcon — the same "Form was the original term for Page"
+// rename CLAUDE.md documents for ShowFormAction. Verified against a Studio
+// Pro-authored navigation document (ako/mxcli-ledger), whose menu icons are all
+// Forms$IconCollectionIcon{Image: "Atlas_Core.Atlas.align-center"}, and matching
+// the widget icon path already proven in issue #602.
+//
+// Two sibling variants exist in the same document — Forms$GlyphIcon{Code: int}
+// and Forms$ImageIcon{Image: QN} — and are deliberately NOT emitted here. Both
+// carry a different payload shape, and ImageIcon's qualified name is
+// indistinguishable from an IconCollectionIcon's without resolving which
+// collection document it lands in. Guessing between polymorphic variants is the
+// failure mode that produces a document mxbuild accepts and Studio Pro cannot
+// open.
+func buildMenuIconBson(icon string) interface{} {
+	if icon == "" {
+		return nil
+	}
+	return bson.D{
+		{Key: "$ID", Value: idToBsonBinary(generateUUID())},
+		{Key: "$Type", Value: "Forms$IconCollectionIcon"},
+		{Key: "Image", Value: icon},
+	}
+}
+
 // buildCaptionBson builds a Texts$Text BSON document with a single en_US translation.
 func buildCaptionBson(text string) bson.D {
 	return bson.D{
diff --git a/sdk/mpr/writer_navigation_icon_test.go b/sdk/mpr/writer_navigation_icon_test.go
new file mode 100644
index 000000000..ea4f14f2a
--- /dev/null
+++ b/sdk/mpr/writer_navigation_icon_test.go
@@ -0,0 +1,192 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package mpr
+
+import (
+	"testing"
+
+	"go.mongodb.org/mongo-driver/bson"
+)
+
+// navIconEntry returns the value of a key in a bson.D and whether it was
+// present. Unlike the package's bsonLookup it separates an absent key from a
+// null one — the distinction a null Icon turns on.
+func navIconEntry(d bson.D, key string) (interface{}, bool) {
+	for _, e := range d {
+		if e.Key == key {
+			return e.Value, true
+		}
+	}
+	return nil, false
+}
+
+// The storage name is the whole point of this test.
+//
+// The metamodel calls the element Pages$IconCollectionIcon, but Mendix stores it
+// as Forms$IconCollectionIcon — the "Form was the original term for Page" rename
+// CLAUDE.md documents for ShowFormAction. Getting a polymorphic child's $Type
+// wrong yields a document mxbuild accepts (its deserializer tolerates unknown
+// properties) and Studio Pro cannot open, so the name is pinned against a
+// Studio Pro-authored reference: every menu icon in ako/mxcli-ledger's
+// navigation document is Forms$IconCollectionIcon{Image: "Atlas_Core.Atlas.…"}.
+func TestBuildMenuIconBson_UsesTheFormsStorageName(t *testing.T) {
+	got := buildMenuIconBson("Atlas_Core.Atlas.align-center")
+	d, ok := got.(bson.D)
+	if !ok {
+		t.Fatalf("expected a bson.D, got %T", got)
+	}
+	typ, _ := navIconEntry(d, "$Type")
+	if typ != "Forms$IconCollectionIcon" {
+		t.Errorf("$Type = %v, want Forms$IconCollectionIcon (NOT the metamodel's Pages$…)", typ)
+	}
+	img, present := navIconEntry(d, "Image")
+	if !present {
+		t.Fatal("the icon carries its name in Image; the key is missing")
+	}
+	if img != "Atlas_Core.Atlas.align-center" {
+		t.Errorf("Image = %v", img)
+	}
+	if _, present := navIconEntry(d, "$ID"); !present {
+		t.Error("every stored element needs its own $ID")
+	}
+	// Studio Pro writes exactly these three keys. A fourth would be a property
+	// the type does not declare, which is what makes a document unopenable.
+	if len(d) != 3 {
+		t.Errorf("icon has %d keys, want exactly $ID/$Type/Image: %v", len(d), d)
+	}
+}
+
+// No icon must stay a null, not an empty element: an IconCollectionIcon with a
+// blank Image is a dangling reference, where absent is the modelled default.
+func TestBuildMenuIconBson_EmptyNameStaysNull(t *testing.T) {
+	if got := buildMenuIconBson(""); got != nil {
+		t.Errorf("buildMenuIconBson(\"\") = %v, want nil", got)
+	}
+}
+
+// The regression this fixes: buildMenuItemBson hardcoded Icon to nil, so an icon
+// the author wrote was dropped on the way to the file. Assert on the encoded
+// item, not just the helper, so the wiring is covered too.
+func TestBuildMenuItemBson_CarriesTheIconThrough(t *testing.T) {
+	item := buildMenuItemBson(NavMenuItemSpec{
+		Caption: "Dashboard",
+		Page:    "M.Dash",
+		Icon:    "Atlas_Core.Atlas.align-center",
+	})
+	icon, present := navIconEntry(item, "Icon")
+	if !present {
+		t.Fatal("the Icon key must always be written, even when null")
+	}
+	d, ok := icon.(bson.D)
+	if !ok {
+		t.Fatalf("Icon = %#v; the authored icon was dropped on the way to BSON", icon)
+	}
+	if img, _ := navIconEntry(d, "Image"); img != "Atlas_Core.Atlas.align-center" {
+		t.Errorf("Image = %v", img)
+	}
+}
+
+// A sub-menu is built by the same recursion, so its icon has to survive it.
+func TestBuildMenuItemBson_CarriesTheIconThroughSubItems(t *testing.T) {
+	item := buildMenuItemBson(NavMenuItemSpec{
+		Caption: "Reports",
+		Items: []NavMenuItemSpec{{
+			Caption: "Monthly", Page: "M.Monthly", Icon: "Atlas_Core.Atlas.folder",
+		}},
+	})
+	items, _ := navIconEntry(item, "Items")
+	arr, ok := items.(bson.A)
+	if !ok || len(arr) != 2 { // [list-marker, one child]
+		t.Fatalf("Items = %#v", items)
+	}
+	sub, ok := arr[1].(bson.D)
+	if !ok {
+		t.Fatalf("sub-item = %#v", arr[1])
+	}
+	icon, _ := navIconEntry(sub, "Icon")
+	d, ok := icon.(bson.D)
+	if !ok {
+		t.Fatalf("sub-item Icon = %#v; the recursion dropped it", icon)
+	}
+	if img, _ := navIconEntry(d, "Image"); img != "Atlas_Core.Atlas.folder" {
+		t.Errorf("sub-item Image = %v", img)
+	}
+}
+
+// An item written without an icon keeps the null it had before this change.
+func TestBuildMenuItemBson_NoIconStillWritesNull(t *testing.T) {
+	item := buildMenuItemBson(NavMenuItemSpec{Caption: "Dashboard", Page: "M.Dash"})
+	icon, present := navIconEntry(item, "Icon")
+	if !present {
+		t.Fatal("the Icon key must be written even with no icon")
+	}
+	if icon != nil {
+		t.Errorf("Icon = %#v, want nil", icon)
+	}
+}
+
+// The read side has to recognise all three variants, because a project authored
+// in Studio Pro contains all three. The fixtures are the literal shapes dumped
+// from ako/mxcli-ledger's navigation document.
+func TestParseNavMenuItem_ReadsEachIconVariant(t *testing.T) {
+	for _, tc := range []struct {
+		name           string
+		icon           map[string]any
+		wantType, want string
+	}{
+		{
+			name:     "icon collection",
+			icon:     map[string]any{"$Type": "Forms$IconCollectionIcon", "Image": "Atlas_Core.Atlas.align-center"},
+			wantType: "Forms$IconCollectionIcon", want: "Atlas_Core.Atlas.align-center",
+		},
+		{
+			name:     "image",
+			icon:     map[string]any{"$Type": "Forms$ImageIcon", "Image": "System.Images.Close"},
+			wantType: "Forms$ImageIcon", want: "System.Images.Close",
+		},
+		{
+			// A glyph carries a numeric Code and no name at all. Reporting an
+			// empty Icon here is load-bearing: it is what stops DESCRIBE from
+			// emitting an ICON clause that would convert the variant on replay.
+			name:     "glyph",
+			icon:     map[string]any{"$Type": "Forms$GlyphIcon", "Code": int32(9999)},
+			wantType: "Forms$GlyphIcon", want: "",
+		},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			mi := parseNavMenuItem(map[string]any{
+				"Caption": map[string]any{},
+				"Icon":    tc.icon,
+				"Action": map[string]any{
+					"$Type":        "Forms$FormAction",
+					"FormSettings": map[string]any{"Form": "M.Dash"},
+				},
+			})
+			if mi == nil {
+				t.Fatal("the item did not parse")
+			}
+			if mi.IconType != tc.wantType {
+				t.Errorf("IconType = %q, want %q", mi.IconType, tc.wantType)
+			}
+			if mi.Icon != tc.want {
+				t.Errorf("Icon = %q, want %q", mi.Icon, tc.want)
+			}
+		})
+	}
+}
+
+// A menu item with no icon must read back as no icon, not as an empty-named one.
+func TestParseNavMenuItem_NoIconReadsAsNone(t *testing.T) {
+	mi := parseNavMenuItem(map[string]any{
+		"Caption": map[string]any{},
+		"Action": map[string]any{
+			"$Type": "Forms$FormAction", "FormSettings": map[string]any{"Form": "M.Dash"},
+		},
+	})
+	if mi == nil {
+		t.Fatal("the item did not parse")
+	}
+	if mi.Icon != "" || mi.IconType != "" {
+		t.Errorf("Icon/IconType = (%q, %q), want both empty", mi.Icon, mi.IconType)
+	}
+}

From 9364d43894114cb94ee5399c8de290bdef53927d Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 9 Aug 2026 10:22:55 +0000
Subject: [PATCH 15/29] refactor(navigation): ICON is a qualified name, not a
 string

An icon is a reference into the model, so it should be spelled like every
other reference (ADR-0003), not quoted as a string:

  ICON Atlas_Core.Atlas.home
  ICON Atlas_Core.Atlas."align-center"

No grammar machinery was needed: qualifiedName is already arbitrary-depth and
identifierOrKeyword already accepts QUOTED_IDENTIFIER. Atlas names are
hyphenated and `align-center` lexes as HYPHENATED_ID, so that segment is
double-quoted -- the same escape MDL already uses for a name that collides
with a keyword.

The DESCRIBE emitter now has to decide quoting per segment, and deliberately
does NOT reuse mdlIdent. mdlIdent quotes anything that does not lex as a bare
IDENTIFIER, which is right where the grammar wants an IDENTIFIER -- but a
qualifiedName segment is an identifierOrKeyword, and that rule accepts
keywords unquoted. Most short Atlas names are keyword tokens (home, user,
add, folder), so mdlIdent would have quoted nearly every icon and buried the
reference in punctuation. quoteQualifiedName instead asks the real parser
whether a segment is accepted, so it stays correct as the keyword set moves.

I guessed the quoting rule wrong twice writing this, so the test that matters
is not an expectation about which names get quotes: it feeds the emitted
statement back through the parser and asserts it re-parses to the same icon.
Controls both ways -- stop quoting and the hyphenated case fails to parse;
quote everything and the keyword case regresses.

Verified: mxbuild doctype gate 0 errors on both engines; DESCRIBE against a
real Studio Pro project emits the new form and replays clean.

mxcli-formula1 #9
---
 .claude/skills/fix-issue.md                   |  2 +-
 .claude/skills/mendix/manage-navigation.md    | 20 +++---
 cmd/mxcli/syntax/features_misc.go             | 22 +++---
 docs/01-project/MDL_QUICK_REFERENCE.md        | 13 ++--
 .../doctype-tests/11-navigation-examples.mdl  | 14 ++--
 mdl/executor/cmd_navigation.go                |  3 +-
 mdl/executor/cmd_navigation_icon_test.go      | 64 +++++++++++++++--
 mdl/executor/qualified_name_quoting.go        | 71 +++++++++++++++++++
 mdl/grammar/MDLParser.g4                      | 11 +--
 mdl/visitor/visitor_navigation.go             | 38 +++++-----
 mdl/visitor/visitor_navigation_icon_test.go   | 40 +++++++----
 11 files changed, 224 insertions(+), 74 deletions(-)
 create mode 100644 mdl/executor/qualified_name_quoting.go

diff --git a/.claude/skills/fix-issue.md b/.claude/skills/fix-issue.md
index 4a8467eb4..0a640d910 100644
--- a/.claude/skills/fix-issue.md
+++ b/.claude/skills/fix-issue.md
@@ -438,4 +438,4 @@ extracting `OffsetExpression`/`LimitExpression`.
 | A `--` comment written between two operands of a Mendix expression ends up **inside** the expression; the build fails **CE0117** "Error(s) in expression". `mxcli check` passes and `DESCRIBE` round-trips the comment, so nothing before mxbuild objects | `extractOriginalText` reads the raw input stream between two token positions — which is exactly what preserves an expression's spacing, and also drags in every token the lexer sent to a hidden channel. MDL's `--` and `/* */` are `-> skip`, so they never appear in `ctx.GetText()` but always appear in the source slice | `mdl/visitor/visitor_helpers.go` (`stripMDLComments`, `extractExpressionText`), applied at the six microflow-expression sites in `visitor_microflow_statements.go` / `visitor_microflow_actions.go` | **The ANTLR trap: `ctx.GetText()` excludes hidden tokens, a source-interval slice includes them.** Any code reaching for original text to preserve formatting inherits every comment in that span. **Replace a comment with whitespace, never with nothing** — `1 --c\n+ 2` must not become `1+ 2`, and `'a'--c\n'b'` must not weld into one token. **Respect single-quoted strings**: a Mendix string may legitimately contain `--` or `/*`, and stripping those corrupts the value (tested both, plus the `''` escape that keeps a string open). **Left OQL alone on purpose** — `visitor_entity.go` uses the same helper for view-entity queries, where `--` is legitimate SQL comment syntax; stripping it would change a different language's meaning. **The unit test alone would not have caught a wiring mistake**: it still passed with `extractExpressionText` bypassed, and only the mxbuild run (1 error → 0, same script, same project) proved the call sites were converted. Tests `visitor_strip_comments_test.go`, repro `mdl-examples/bug-tests/comment-in-expression.mdl`. mxcli-formula1 §34 / suggested issue 11 |
 | A published OData entity with no `KEY` fails the build with **CE6585** "Published entity 'X' must have a key defined." — so any advice of the form "drop the KEY" is impossible to follow | Mendix requires every published entity to have a key. MDL-ODATA02's suggestion offered "…or drop the KEY" as the alternative to answering a key lookup, and a doctype example demonstrated that non-existent option | `mdl/executor/validate_odata_read_contract.go` (suggestion text), `mdl-examples/doctype-tests/10-odata-examples.mdl`, `.claude/skills/mendix/odata-data-sharing.md` | **Query options you may decline; the key you may not.** A microflow-backed resource whose rows a client can hold *must* answer the key lookup — there is no opt-out, which makes MDL-ODATA02's real remedy singular rather than a choice. **Verify the remedy a diagnostic recommends, not just the diagnosis** — the rule correctly identified an unanswerable KEY and then proposed something mxbuild rejects, which is worse than saying nothing. This is the second time in one session that a doctype example was validated with `mxcli check` (parse-only) instead of the integration gate; `mxcli check` cannot see CE-codes at all, so **any change to `mdl-examples/doctype-tests/` needs `go test -tags integration -run TestMxCheck_DoctypeScripts/<script>` before it is called done** — the two-minute run that would have caught both. mxcli-formula1 §37 follow-up |
 | A page written by mxcli will not open in Studio Pro, and `mx check` dies during *load* with `ArgumentNullException` at `EntityRefStep.set_AssociationId` — no page error, no CE code, the whole project is down rather than one document | An association DATASOURCE wrote the association name exactly as authored. Both halves of an `EntityRefStep` are BY_NAME and Mendix resolves either one it cannot find to null, but only `DestinationEntity` was guarded (issuetracker #14) — a bare `Order_Line` reached BSON unqualified. The **explicit-destination** form is the live trap: supplying the destination satisfies that guard, so nothing stood between a bare name and the crash — and `Assoc/Module.Entity` is exactly what the guard's error tells the author to write | `mdl/executor/cmd_pages_builder_v3.go` (`buildDataSourceV3`, `case "association"`: qualify via `resolveAssociationPathIn`, then verify an author-supplied destination's association exists via `associationEndpoints`) | **Guard every BY_NAME half of a ref, not the one that was reported.** #854 reported the destination; the association beside it failed identically and was reachable through the fix's own advice. **Diff the two properties in the dump** (`grep -A1 '"Key": "(Association\|DestinationEntity)"'`) rather than reading the exception name — the loader reports whichever it touches first. **Hold the input constant across builds**: the pre-fix binary was first run with bare names and post-fix with qualified ones, which "reproduced" nothing; re-running the *same qualified* script on both is what isolated cross-module (`""`) from same-module (resolved). `mx check` exits 0 on this failure — assert on the `contains: N errors` line, never `$?`. Tests `cmd_pages_builder_assoc_datasource_test.go`, example `mdl-examples/bug-tests/854-assoc-datasource-qualified-name.mdl`. upstream #854 follow-on |
-| A navigation menu item cannot be given an icon at all — the grammar has no `ICON`, and every item mxcli writes gets `Icon: null`, so a menu authored in MDL is flat text next to one authored in Studio Pro | The syntax was never added, and the reason it stayed unadded is instructive: the metamodel names the element `Pages$IconCollectionIcon`, but Mendix **stores** it as `Forms$IconCollectionIcon` — one more instance of the "Form was the original term for Page" rename CLAUDE.md documents for `ShowFormAction`. There was no way to know that from the metamodel alone, and inventing a `$Type` for a polymorphic child is the failure mode where mxbuild builds green and Studio Pro cannot open the document | `mdl/grammar/MDLParser.g4` (`navMenuItemDef`, both alternatives), `mdl/ast/ast_navigation.go`, `mdl/visitor/visitor_navigation.go` (positional `AllSTRING_LITERAL()` — caption and icon are both string literals), `mdl/types/navigation.go`, `mdl/executor/cmd_navigation.go` (`convertMenuItemDef`, `printMenuMDL`), `sdk/mpr/writer_navigation.go` (`buildMenuIconBson`), `mdl/backend/modelsdk/navigation_write.go`, `sdk/mpr/parser_misc.go`, `mdl/backend/mpr/convert.go` (`convertNavMenuItem` is a field-by-field copy and drops anything new) | **Get the reference before writing the BSON.** A Studio Pro-authored project (`ako/mxcli-ledger`) settled in one dump what no amount of metamodel reading could: the storage name, the field (`Image`, a 3-part `Module.Collection.name`), the exact key set (`$ID`/`$Type`/`Image`, nothing more), and that **all three variants coexist** — `Forms$IconCollectionIcon{Image}`, `Forms$ImageIcon{Image}` (indistinguishable by name alone; it points into an *image* collection), `Forms$GlyphIcon{Code: int}`. Only the first is written; DESCRIBE emits a `-- icon … is not reproducible` comment for the other two rather than an `icon` clause that would convert the variant on replay. To dump a v2 unit: `grep -rl 'Menus$MenuItem' mprcontents` then `bson.Unmarshal` into a `bson.D`. **`mx check` reporting 0 errors is not the proof here** — its deserializer tolerates unknown properties; the proof is diffing the written element against the Studio Pro one (done: byte-shape identical, same key order). Icon *names* are also not guessable — `Atlas.list` and `Atlas_Filled.user-check` do not exist while `list-bullets` and `user` do; verify against the collection. **Second trap, in the read path**: `codec.Decode` returns a bare `*element.Base` for an *unregistered* `$Type` but a generated struct (which only *embeds* Base) for a registered one, so `icon.(*element.Base)` silently returns nothing for exactly the variants that exist in real projects — DESCRIBE printed every icon under `legacy` and none under `modelsdk`. Assert on `interface{ Raw() bson.Raw }`, which both shapes satisfy. A unit test passing `nil` did not reach this; **running `describe` against a real Studio Pro project under both `MXCLI_ENGINE` values did**, and that engine-vs-engine diff is the cheapest way to find a read-path divergence. Note `modelsdk/codec` is on bson **v2** while `mdl/backend/modelsdk`'s write path is on v1 — a test touching both needs an alias. Tests `sdk/mpr/writer_navigation_icon_test.go`, `mdl/visitor/visitor_navigation_icon_test.go`, `mdl/executor/cmd_navigation_icon_test.go`, `mdl/backend/modelsdk/navigation_icon_test.go`; example `mdl-examples/doctype-tests/11-navigation-examples.mdl`. mxcli-formula1 #9 |
+| A navigation menu item cannot be given an icon at all — the grammar has no `ICON`, and every item mxcli writes gets `Icon: null`, so a menu authored in MDL is flat text next to one authored in Studio Pro | The syntax was never added, and the reason it stayed unadded is instructive: the metamodel names the element `Pages$IconCollectionIcon`, but Mendix **stores** it as `Forms$IconCollectionIcon` — one more instance of the "Form was the original term for Page" rename CLAUDE.md documents for `ShowFormAction`. There was no way to know that from the metamodel alone, and inventing a `$Type` for a polymorphic child is the failure mode where mxbuild builds green and Studio Pro cannot open the document | `mdl/grammar/MDLParser.g4` (`navMenuItemDef`, both alternatives), `mdl/ast/ast_navigation.go`, `mdl/visitor/visitor_navigation.go` (positional `AllQualifiedName()` — the PAGE/MICROFLOW target and the icon share one indexed list), `mdl/types/navigation.go`, `mdl/executor/cmd_navigation.go` (`convertMenuItemDef`, `printMenuMDL`), `sdk/mpr/writer_navigation.go` (`buildMenuIconBson`), `mdl/backend/modelsdk/navigation_write.go`, `sdk/mpr/parser_misc.go`, `mdl/backend/mpr/convert.go` (`convertNavMenuItem` is a field-by-field copy and drops anything new) | **The icon is a `qualifiedName`, not a string** — it is a reference into the model, so it is spelled like every other reference (ADR-0003). Atlas names are hyphenated, and `align-center` lexes as HYPHENATED_ID, so that *segment* is double-quoted: `ICON Atlas_Core.Atlas."align-center"`. The DESCRIBE emitter (`quoteQualifiedName` in `mdl/executor/qualified_name_quoting.go`) must therefore decide quoting per segment, and **must not reuse `mdlIdent`**: mdlIdent quotes anything not lexing as a bare IDENTIFIER, but a qualifiedName segment is an `identifierOrKeyword`, which accepts keywords — and `home`, `user`, `add`, `folder` are all keyword tokens, so mdlIdent would quote nearly every icon. Decide acceptance by running the real parser on the segment, never a hardcoded keyword list. The invariant worth testing is not "which names get quotes" (I guessed that wrong twice) but **"does the emitted statement re-parse"** — feed DESCRIBE output back through `visitor.Build`. **Get the reference before writing the BSON.** A Studio Pro-authored project (`ako/mxcli-ledger`) settled in one dump what no amount of metamodel reading could: the storage name, the field (`Image`, a 3-part `Module.Collection.name`), the exact key set (`$ID`/`$Type`/`Image`, nothing more), and that **all three variants coexist** — `Forms$IconCollectionIcon{Image}`, `Forms$ImageIcon{Image}` (indistinguishable by name alone; it points into an *image* collection), `Forms$GlyphIcon{Code: int}`. Only the first is written; DESCRIBE emits a `-- icon … is not reproducible` comment for the other two rather than an `icon` clause that would convert the variant on replay. To dump a v2 unit: `grep -rl 'Menus$MenuItem' mprcontents` then `bson.Unmarshal` into a `bson.D`. **`mx check` reporting 0 errors is not the proof here** — its deserializer tolerates unknown properties; the proof is diffing the written element against the Studio Pro one (done: byte-shape identical, same key order). Icon *names* are also not guessable — `Atlas.list` and `Atlas_Filled.user-check` do not exist while `list-bullets` and `user` do; verify against the collection. **Second trap, in the read path**: `codec.Decode` returns a bare `*element.Base` for an *unregistered* `$Type` but a generated struct (which only *embeds* Base) for a registered one, so `icon.(*element.Base)` silently returns nothing for exactly the variants that exist in real projects — DESCRIBE printed every icon under `legacy` and none under `modelsdk`. Assert on `interface{ Raw() bson.Raw }`, which both shapes satisfy. A unit test passing `nil` did not reach this; **running `describe` against a real Studio Pro project under both `MXCLI_ENGINE` values did**, and that engine-vs-engine diff is the cheapest way to find a read-path divergence. Note `modelsdk/codec` is on bson **v2** while `mdl/backend/modelsdk`'s write path is on v1 — a test touching both needs an alias. Tests `sdk/mpr/writer_navigation_icon_test.go`, `mdl/visitor/visitor_navigation_icon_test.go`, `mdl/executor/cmd_navigation_icon_test.go`, `mdl/backend/modelsdk/navigation_icon_test.go`; example `mdl-examples/doctype-tests/11-navigation-examples.mdl`. mxcli-formula1 #9 |
diff --git a/.claude/skills/mendix/manage-navigation.md b/.claude/skills/mendix/manage-navigation.md
index 79f04ea92..8dce073cf 100644
--- a/.claude/skills/mendix/manage-navigation.md
+++ b/.claude/skills/mendix/manage-navigation.md
@@ -86,23 +86,26 @@ create or replace navigation Responsive
 
 ### Menu Icons
 
-Both `menu item` and `menu 'caption' (...)` take an optional `icon`, naming an
-entry in an **icon collection**:
+Both `menu item` and `menu 'caption' (...)` take an optional `icon`. It is a
+**qualified name** into an **icon collection** — a model reference, written like
+every other reference in MDL, not a string:
 
 ```sql
 create or replace navigation Responsive
   home page MyModule.Home_Web
   menu (
-    menu item 'Home' page MyModule.Home_Web icon 'Atlas_Core.Atlas.home';
-    menu 'Orders' icon 'Atlas_Core.Atlas.shopping-cart' (
+    menu item 'Home' page MyModule.Home_Web icon Atlas_Core.Atlas.home;
+    menu 'Orders' icon Atlas_Core.Atlas."shopping-cart" (
       menu item 'All Orders' page Orders.Order_Overview
-        icon 'Atlas_Core.Atlas.list-bullets';
+        icon Atlas_Core.Atlas."list-bullets";
     );
   );
 ```
 
-The name is **quoted** — Atlas icon names contain hyphens (`align-center`,
-`list-bullets`), so they are not bare identifiers. Atlas_Core ships three
+**Hyphenated names are double-quoted** (`Atlas_Core.Atlas."align-center"`) —
+a hyphen does not lex as an identifier, so the segment is quoted exactly as a
+keyword-colliding name would be. Plain names need no quotes, including ones that
+happen to be MDL keywords (`home`, `user`, `add`). Atlas_Core ships three
 collections: `Atlas` (outline), `Atlas_Filled`, and `Atlas_Styling`. List what
 is actually available in your project rather than guessing a name:
 
@@ -248,5 +251,6 @@ create or replace navigation Responsive
 - [ ] Role references in `for` clauses are fully qualified (`Module.Role`)
 - [ ] Every `menu item` and `menu 'caption' (...)` ends with `;`
 - [ ] Sub-menu items are wrapped in `menu 'caption' ( ... );`
-- [ ] `icon` names are quoted and exist — check with `describe icon collection Module.Name`, do not guess
+- [ ] `icon` is a qualified name (not a string); hyphenated segments are double-quoted
+- [ ] The icon exists — check with `describe icon collection Module.Name`, do not guess
 - [ ] Use `describe navigation` to verify changes after applying
diff --git a/cmd/mxcli/syntax/features_misc.go b/cmd/mxcli/syntax/features_misc.go
index cce82c91b..856578409 100644
--- a/cmd/mxcli/syntax/features_misc.go
+++ b/cmd/mxcli/syntax/features_misc.go
@@ -87,23 +87,25 @@ DISCONNECT;`,
   [LOGIN PAGE Module.LoginPage]
   [NOT FOUND PAGE Module.Custom404]
   [MENU (
-    MENU ITEM 'Label' PAGE Module.Page [ICON 'Module.IconCollection.name'];
-    MENU 'Group' [ICON 'Module.IconCollection.name'] ( ... );
+    MENU ITEM 'Label' PAGE Module.Page [ICON Module.IconCollection.Name];
+    MENU 'Group' [ICON Module.IconCollection.Name] ( ... );
   )];
 
--- ICON names an entry in an ICON COLLECTION (Atlas_Core.Atlas,
--- Atlas_Core.Atlas_Filled, Atlas_Core.Atlas_Styling, or your own). It is
--- quoted because Atlas icon names contain hyphens. Browse the available
--- names with:  SHOW ICON COLLECTION  /  DESCRIBE ICON COLLECTION Module.Name`,
+-- ICON is a qualified name into an ICON COLLECTION (Atlas_Core.Atlas,
+-- Atlas_Core.Atlas_Filled, Atlas_Core.Atlas_Styling, or your own) -- a model
+-- reference, not a string. Hyphenated Atlas names are double-quoted:
+--   ICON Atlas_Core.Atlas."align-center"
+-- Browse the available names with:
+--   SHOW ICON COLLECTION  /  DESCRIBE ICON COLLECTION Module.Name`,
 		Example: `CREATE OR REPLACE NAVIGATION Responsive
   HOME PAGE MyModule.Home_Web
   HOME PAGE MyModule.AdminDashboard FOR Administration.Administrator
   LOGIN PAGE Administration.Login
   MENU (
-    MENU ITEM 'Home' PAGE MyModule.Home_Web ICON 'Atlas_Core.Atlas.home';
-    MENU 'Orders' ICON 'Atlas_Core.Atlas.shopping-cart' (
-      MENU ITEM 'All Orders' PAGE Orders.Order_Overview ICON 'Atlas_Core.Atlas.list-bullets';
-      MENU ITEM 'New Order' PAGE Orders.Order_New ICON 'Atlas_Core.Atlas.add';
+    MENU ITEM 'Home' PAGE MyModule.Home_Web ICON Atlas_Core.Atlas.home;
+    MENU 'Orders' ICON Atlas_Core.Atlas."shopping-cart" (
+      MENU ITEM 'All Orders' PAGE Orders.Order_Overview ICON Atlas_Core.Atlas."list-bullets";
+      MENU ITEM 'New Order' PAGE Orders.Order_New ICON Atlas_Core.Atlas.add;
     );
   );`,
 		SeeAlso: []string{"navigation.show"},
diff --git a/docs/01-project/MDL_QUICK_REFERENCE.md b/docs/01-project/MDL_QUICK_REFERENCE.md
index a2d0b61ea..f520cfc77 100644
--- a/docs/01-project/MDL_QUICK_REFERENCE.md
+++ b/docs/01-project/MDL_QUICK_REFERENCE.md
@@ -506,18 +506,19 @@ create or replace navigation Responsive
   login page Administration.Login
   not found page MyModule.Custom404
   menu (
-    menu item 'Home' page MyModule.Home_Web icon 'Atlas_Core.Atlas.home';
-    menu 'Admin' icon 'Atlas_Core.Atlas.user' (
+    menu item 'Home' page MyModule.Home_Web icon Atlas_Core.Atlas.home;
+    menu 'Admin' icon Atlas_Core.Atlas."align-center" (
       menu item 'Users' page Administration.Account_Overview;
     );
   );
 ```
 
-`icon` is optional and names an entry in an **icon collection** —
+`icon` is optional and is a **qualified name** into an **icon collection** —
 `Atlas_Core.Atlas`, `Atlas_Core.Atlas_Filled`, `Atlas_Core.Atlas_Styling`, or one
-of your own. It is quoted because Atlas icon names contain hyphens
-(`align-center`). List the available names with `describe icon collection
-Atlas_Core.Atlas`.
+of your own — written like any other model reference. Hyphenated Atlas names
+(`align-center`) are double-quoted, the same way a keyword-colliding name is:
+`Atlas_Core.Atlas."align-center"`. List the available names with `describe icon
+collection Atlas_Core.Atlas`.
 
 Studio Pro can also set a *glyph* icon (a numeric character code) or an *image*
 icon (pointing into an image collection). Those are different elements; MDL
diff --git a/mdl-examples/doctype-tests/11-navigation-examples.mdl b/mdl-examples/doctype-tests/11-navigation-examples.mdl
index 6d91b7c52..a7e673cd3 100644
--- a/mdl-examples/doctype-tests/11-navigation-examples.mdl
+++ b/mdl-examples/doctype-tests/11-navigation-examples.mdl
@@ -89,20 +89,20 @@ create or replace navigation Responsive
   );
 
 -- ============================================================================
--- ICON — a menu item's icon, named as Module.IconCollection.icon
--- The name is quoted because Atlas icon names contain hyphens. It resolves to
--- an icon collection (Atlas_Core.Atlas, Atlas_Core.Atlas_Filled, …), not an
--- image collection.
+-- ICON — a menu item's icon, as a qualified name into an icon collection
+-- (Atlas_Core.Atlas, Atlas_Core.Atlas_Filled, …), not an image collection.
+-- Written like any other model reference. Hyphenated Atlas names are
+-- double-quoted, the same way a keyword-colliding name is.
 -- ============================================================================
 
 create or replace navigation Responsive
   home page NavTest.NavTest_Home
   login page Administration.login
   menu (
-    menu item 'Home' page NavTest.NavTest_Home icon 'Atlas_Core.Atlas.home';
-    menu 'Admin' icon 'Atlas_Core.Atlas.user' (
+    menu item 'Home' page NavTest.NavTest_Home icon Atlas_Core.Atlas.home;
+    menu 'Admin' icon Atlas_Core.Atlas.user (
       menu item 'Users' page Administration.Account_Overview
-        icon 'Atlas_Core.Atlas_Filled.user';
+        icon Atlas_Core.Atlas."list-bullets";
     );
   );
 
diff --git a/mdl/executor/cmd_navigation.go b/mdl/executor/cmd_navigation.go
index 73745ab0e..26bc6797e 100644
--- a/mdl/executor/cmd_navigation.go
+++ b/mdl/executor/cmd_navigation.go
@@ -373,9 +373,10 @@ func menuItemIconMDL(item *types.NavMenuItem) string {
 	if item.Icon == "" || !strings.HasSuffix(item.IconType, "IconCollectionIcon") {
 		return ""
 	}
-	return fmt.Sprintf(" icon '%s'", item.Icon)
+	return " icon " + quoteQualifiedName(item.Icon)
 }
 
+
 // menuItemIconNote flags an icon DESCRIBE cannot round-trip, so re-running the
 // output loses it visibly rather than silently. CREATE NAVIGATION writes only
 // Forms$IconCollectionIcon; a glyph icon (numeric Code) or an image icon
diff --git a/mdl/executor/cmd_navigation_icon_test.go b/mdl/executor/cmd_navigation_icon_test.go
index db3cc2e27..fbb9986d8 100644
--- a/mdl/executor/cmd_navigation_icon_test.go
+++ b/mdl/executor/cmd_navigation_icon_test.go
@@ -7,7 +7,9 @@ import (
 	"strings"
 	"testing"
 
+	"github.com/mendixlabs/mxcli/mdl/ast"
 	"github.com/mendixlabs/mxcli/mdl/types"
+	"github.com/mendixlabs/mxcli/mdl/visitor"
 )
 
 // menuMDL renders items through the DESCRIBE emitter.
@@ -18,7 +20,9 @@ func menuMDL(items []*types.NavMenuItem) string {
 }
 
 // DESCRIBE emits re-executable MDL, so an icon it read must come back out — the
-// alternative is output that silently rewrites the menu when replayed.
+// alternative is output that silently rewrites the menu when replayed. The
+// hyphenated segment has to be re-quoted: `align-center` lexes as HYPHENATED_ID,
+// not IDENTIFIER, so an unquoted emission would be output the parser rejects.
 func TestPrintMenuMDL_RoundTripsAnIconCollectionIcon(t *testing.T) {
 	got := menuMDL([]*types.NavMenuItem{{
 		Caption:  "Dashboard",
@@ -26,7 +30,24 @@ func TestPrintMenuMDL_RoundTripsAnIconCollectionIcon(t *testing.T) {
 		Icon:     "Atlas_Core.Atlas.align-center",
 		IconType: "Forms$IconCollectionIcon",
 	}})
-	want := "menu item 'Dashboard' page M.Dash icon 'Atlas_Core.Atlas.align-center';\n"
+	want := "menu item 'Dashboard' page M.Dash icon Atlas_Core.Atlas.\"align-center\";\n"
+	if got != want {
+		t.Errorf("got %q, want %q", got, want)
+	}
+}
+
+// A name a qualifiedName segment can hold is emitted bare, and quoting it
+// anyway would be noise. `home` is a KEYWORD token, not an IDENTIFIER — and
+// `identifierOrKeyword` accepts keywords, so it must NOT be quoted. Most short
+// Atlas names are in this bucket (`home`, `user`, `add`, `folder`), which is why
+// the emitter tests parser acceptance rather than reusing mdlIdent's
+// lexes-as-IDENTIFIER rule.
+func TestPrintMenuMDL_LeavesAKeywordIconNameUnquoted(t *testing.T) {
+	got := menuMDL([]*types.NavMenuItem{{
+		Caption: "Home", Page: "M.Home",
+		Icon: "Atlas_Core.Atlas.home", IconType: "Forms$IconCollectionIcon",
+	}})
+	want := "menu item 'Home' page M.Home icon Atlas_Core.Atlas.home;\n"
 	if got != want {
 		t.Errorf("got %q, want %q", got, want)
 	}
@@ -37,11 +58,11 @@ func TestPrintMenuMDL_RoundTripsAnIconCollectionIcon(t *testing.T) {
 func TestPrintMenuMDL_RoundTripsASubMenuIcon(t *testing.T) {
 	got := menuMDL([]*types.NavMenuItem{{
 		Caption:  "Reports",
-		Icon:     "Atlas_Core.Atlas.folder",
+		Icon:     "Atlas_Core.Atlas.list-bullets",
 		IconType: "Forms$IconCollectionIcon",
 		Items:    []*types.NavMenuItem{{Caption: "Monthly", Page: "M.Monthly"}},
 	}})
-	if !strings.HasPrefix(got, "menu 'Reports' icon 'Atlas_Core.Atlas.folder' (\n") {
+	if !strings.HasPrefix(got, "menu 'Reports' icon Atlas_Core.Atlas.\"list-bullets\" (\n") {
 		t.Errorf("sub-menu header lost its icon: %q", got)
 	}
 	if !strings.Contains(got, "menu item 'Monthly' page M.Monthly;") {
@@ -62,7 +83,9 @@ func TestPrintMenuMDL_FlagsAnIconItCannotReproduce(t *testing.T) {
 			got := menuMDL([]*types.NavMenuItem{{
 				Caption: "Close", Page: "M.Close", Icon: tc.icon, IconType: tc.iconType,
 			}})
-			if strings.Contains(got, "icon '") {
+			// Check the statement line only — the note below it also says "icon".
+			stmt := strings.SplitN(got, "\n", 2)[0]
+			if strings.Contains(stmt, " icon ") {
 				t.Errorf("emitted an ICON clause for %s, which replay would convert: %q",
 					tc.iconType, got)
 			}
@@ -80,3 +103,34 @@ func TestPrintMenuMDL_SilentWhenThereIsNoIcon(t *testing.T) {
 		t.Errorf("got %q", got)
 	}
 }
+
+// The point of quoting is that DESCRIBE output re-executes. Assert that
+// directly by feeding the emitted statement back through the parser, rather
+// than trusting a hand-written expectation about which names need quotes —
+// which is exactly the thing that was wrong twice while writing this.
+func TestPrintMenuMDL_EmittedIconsReParse(t *testing.T) {
+	for _, icon := range []string{
+		"Atlas_Core.Atlas.align-center", // HYPHENATED_ID: needs quoting
+		"Atlas_Core.Atlas.home",         // keyword token: accepted bare
+		"Atlas_Core.Atlas.add",          // keyword token
+		"Atlas_Core.Atlas_Filled.user",  // keyword token, non-default collection
+	} {
+		t.Run(icon, func(t *testing.T) {
+			body := menuMDL([]*types.NavMenuItem{{
+				Caption: "X", Page: "M.P", Icon: icon, IconType: "Forms$IconCollectionIcon",
+			}})
+			script := "create or replace navigation Responsive menu (\n" + body + ");"
+			prog, errs := visitor.Build(script)
+			if len(errs) > 0 {
+				t.Fatalf("DESCRIBE emitted output its own parser rejects:\n%s\nerrors: %v", script, errs)
+			}
+			stmt, ok := prog.Statements[0].(*ast.AlterNavigationStmt)
+			if !ok || len(stmt.MenuItems) != 1 {
+				t.Fatalf("re-parsed to %T", prog.Statements[0])
+			}
+			if got := stmt.MenuItems[0].Icon; got != icon {
+				t.Errorf("round trip changed the icon: %q -> %q", icon, got)
+			}
+		})
+	}
+}
diff --git a/mdl/executor/qualified_name_quoting.go b/mdl/executor/qualified_name_quoting.go
new file mode 100644
index 000000000..c6bdef8f3
--- /dev/null
+++ b/mdl/executor/qualified_name_quoting.go
@@ -0,0 +1,71 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package executor
+
+import (
+	"strings"
+
+	antlr "github.com/antlr4-go/antlr/v4"
+	"github.com/mendixlabs/mxcli/mdl/grammar/parser"
+)
+
+// quoteQualifiedName renders a dotted model reference so it re-parses as a
+// qualifiedName, quoting only the segments that actually need it.
+//
+// This is deliberately *not* mdlIdent. mdlIdent quotes anything that does not
+// lex as a bare IDENTIFIER, which is right where the grammar wants an
+// IDENTIFIER — but a qualifiedName segment is an `identifierOrKeyword`, and that
+// rule accepts keywords unquoted. Most short Atlas icon names collide with an
+// MDL keyword (`home`, `user`, `add`, `folder` are all keyword tokens), so
+// mdlIdent would quote nearly every icon and bury the reference in punctuation.
+// What genuinely needs quoting is a shape the rule cannot accept at all —
+// notably the hyphenated Atlas names (`align-center`), which lex as
+// HYPHENATED_ID.
+//
+// Acceptance is decided by running the real parser rather than by a hardcoded
+// keyword list, so it stays correct as the grammar's keyword set moves.
+func quoteQualifiedName(name string) string {
+	parts := strings.Split(name, ".")
+	for i, p := range parts {
+		if !parsesAsIdentifierOrKeyword(p) {
+			// QUOTED_IDENTIFIER is '"' ~["\r\n]* '"' — no escape sequence, and
+			// Mendix names never contain a double quote.
+			parts[i] = `"` + p + `"`
+		}
+	}
+	return strings.Join(parts, ".")
+}
+
+// parsesAsIdentifierOrKeyword reports whether s is accepted whole by the
+// identifierOrKeyword rule — i.e. whether it can be written unquoted inside a
+// qualifiedName.
+func parsesAsIdentifierOrKeyword(s string) bool {
+	if s == "" {
+		return false
+	}
+	lexer := parser.NewMDLLexer(antlr.NewInputStream(s))
+	lexer.RemoveErrorListeners()
+	stream := antlr.NewCommonTokenStream(lexer, antlr.TokenDefaultChannel)
+	p := parser.NewMDLParser(stream)
+	p.RemoveErrorListeners()
+	errs := &countingErrorListener{}
+	p.AddErrorListener(errs)
+	ctx := p.IdentifierOrKeyword()
+	if errs.count > 0 || ctx == nil {
+		return false
+	}
+	// The rule must have consumed the whole string; a trailing remainder means
+	// only a prefix matched.
+	return ctx.GetStop() != nil && ctx.GetStop().GetStop() == len(s)-1
+}
+
+// countingErrorListener counts syntax errors without printing them.
+type countingErrorListener struct {
+	*antlr.DefaultErrorListener
+	count int
+}
+
+func (l *countingErrorListener) SyntaxError(_ antlr.Recognizer, _ interface{},
+	_, _ int, _ string, _ antlr.RecognitionException) {
+	l.count++
+}
diff --git a/mdl/grammar/MDLParser.g4 b/mdl/grammar/MDLParser.g4
index 44a064cee..7b7d9e63f 100644
--- a/mdl/grammar/MDLParser.g4
+++ b/mdl/grammar/MDLParser.g4
@@ -287,11 +287,14 @@ navigationClause
     | MENU_KW LPAREN navMenuItemDef* RPAREN
     ;
 
-// The icon is a STRING_LITERAL, not a qualifiedName: Atlas icon names carry
-// hyphens (Atlas_Core.Atlas.align-center), which IDENTIFIER cannot lex.
+// The icon is a qualifiedName, like every other reference into the model, and
+// not a string. Atlas icon names carry hyphens, which IDENTIFIER cannot lex, so
+// those segments are double-quoted the same way a keyword-colliding name is:
+//   ICON Atlas_Core.Atlas.home
+//   ICON Atlas_Core.Atlas."align-center"
 navMenuItemDef
-    : MENU_KW ITEM STRING_LITERAL ((PAGE qualifiedName) | (MICROFLOW qualifiedName))? (ICON STRING_LITERAL)? SEMICOLON?
-    | MENU_KW STRING_LITERAL (ICON STRING_LITERAL)? LPAREN navMenuItemDef* RPAREN SEMICOLON?
+    : MENU_KW ITEM STRING_LITERAL ((PAGE qualifiedName) | (MICROFLOW qualifiedName))? (ICON qualifiedName)? SEMICOLON?
+    | MENU_KW STRING_LITERAL (ICON qualifiedName)? LPAREN navMenuItemDef* RPAREN SEMICOLON?
     ;
 
 dropStatement
diff --git a/mdl/visitor/visitor_navigation.go b/mdl/visitor/visitor_navigation.go
index e263e4640..10de013c7 100644
--- a/mdl/visitor/visitor_navigation.go
+++ b/mdl/visitor/visitor_navigation.go
@@ -86,32 +86,30 @@ func (b *Builder) processNavigationClause(stmt *ast.AlterNavigationStmt, ctx *pa
 func buildNavMenuItemDef(ctx parser.INavMenuItemDefContext) ast.NavMenuItemDef {
 	c := ctx.(*parser.NavMenuItemDefContext)
 
-	// Both alternatives put the caption first and the optional ICON string
-	// second, so positional access is unambiguous.
-	literals := c.AllSTRING_LITERAL()
 	caption := ""
-	if len(literals) > 0 {
-		caption = unquoteString(literals[0].GetText())
-	}
-	icon := ""
-	if c.ICON() != nil && len(literals) > 1 {
-		icon = unquoteString(literals[1].GetText())
-	}
-
-	item := ast.NavMenuItemDef{
-		Caption: caption,
-		Icon:    icon,
+	if sl := c.STRING_LITERAL(); sl != nil {
+		caption = unquoteString(sl.GetText())
 	}
 
-	// The grammar uses a single qualifiedName for either PAGE or MICROFLOW target
-	qn := c.QualifiedName()
+	item := ast.NavMenuItemDef{Caption: caption}
 
-	if c.PAGE() != nil && qn != nil {
-		built := buildQualifiedName(qn)
+	// Both the PAGE/MICROFLOW target and the ICON are qualifiedNames, so they
+	// arrive in one indexed list. The target always comes first when present;
+	// whatever remains after it is the icon.
+	names := c.AllQualifiedName()
+	next := 0
+	switch {
+	case c.PAGE() != nil && len(names) > next:
+		built := buildQualifiedName(names[next])
 		item.Page = &built
-	} else if c.MICROFLOW() != nil && qn != nil {
-		built := buildQualifiedName(qn)
+		next++
+	case c.MICROFLOW() != nil && len(names) > next:
+		built := buildQualifiedName(names[next])
 		item.Microflow = &built
+		next++
+	}
+	if c.ICON() != nil && len(names) > next {
+		item.Icon = buildQualifiedName(names[next]).String()
 	}
 
 	// Recurse into sub-items (for MENU 'caption' (...))
diff --git a/mdl/visitor/visitor_navigation_icon_test.go b/mdl/visitor/visitor_navigation_icon_test.go
index 82835a1b0..f63430023 100644
--- a/mdl/visitor/visitor_navigation_icon_test.go
+++ b/mdl/visitor/visitor_navigation_icon_test.go
@@ -23,18 +23,34 @@ func navMenuItems(t *testing.T, menuBody string) []ast.NavMenuItemDef {
 	return stmt.MenuItems
 }
 
-// mxcli-formula1 §9: a menu item's icon could not be expressed at all. The name
-// is a STRING_LITERAL because Atlas icon names carry hyphens
-// (Atlas_Core.Atlas.align-center), which IDENTIFIER cannot lex — so a
-// qualifiedName form would not have parsed.
-func TestNavMenuItem_ParsesTheIconOnALeafItem(t *testing.T) {
+// mxcli-formula1 §9: a menu item's icon could not be expressed at all. It is a
+// reference into the model, so it is written as a qualifiedName like every other
+// reference — not as a string. Atlas icon names carry hyphens, which IDENTIFIER
+// cannot lex, so that segment is double-quoted the same way a keyword-colliding
+// name is.
+func TestNavMenuItem_ParsesAQuotedHyphenatedIconSegment(t *testing.T) {
 	items := navMenuItems(t,
-		"MENU ITEM 'Dashboard' PAGE M.Dash ICON 'Atlas_Core.Atlas.align-center';")
+		`MENU ITEM 'Dashboard' PAGE M.Dash ICON Atlas_Core.Atlas."align-center";`)
 	if len(items) != 1 {
 		t.Fatalf("expected 1 item, got %d", len(items))
 	}
 	if items[0].Icon != "Atlas_Core.Atlas.align-center" {
-		t.Errorf("Icon = %q, want the hyphenated Atlas name", items[0].Icon)
+		t.Errorf("Icon = %q, want the quotes stripped from the hyphenated segment", items[0].Icon)
+	}
+	if items[0].Page == nil || items[0].Page.Name != "Dash" {
+		t.Error("the ICON clause must not displace the PAGE target")
+	}
+}
+
+// Most Atlas names are plain identifiers and need no quoting at all — that is
+// the common case and it must read like any other reference.
+func TestNavMenuItem_ParsesABareIconName(t *testing.T) {
+	items := navMenuItems(t, "MENU ITEM 'Dashboard' PAGE M.Dash ICON Atlas_Core.Atlas.home;")
+	if len(items) != 1 {
+		t.Fatalf("expected 1 item, got %d", len(items))
+	}
+	if items[0].Icon != "Atlas_Core.Atlas.home" {
+		t.Errorf("Icon = %q", items[0].Icon)
 	}
 	if items[0].Page == nil || items[0].Page.Name != "Dash" {
 		t.Error("the ICON clause must not displace the PAGE target")
@@ -44,7 +60,7 @@ func TestNavMenuItem_ParsesTheIconOnALeafItem(t *testing.T) {
 // The sub-menu alternative takes an icon too, before its parenthesised body.
 func TestNavMenuItem_ParsesTheIconOnASubMenu(t *testing.T) {
 	items := navMenuItems(t,
-		"MENU 'Reports' ICON 'Atlas_Core.Atlas.folder' (\n"+
+		"MENU 'Reports' ICON Atlas_Core.Atlas.folder (\n"+
 			"  MENU ITEM 'Monthly' PAGE M.Monthly;\n"+
 			");")
 	if len(items) != 1 {
@@ -58,9 +74,9 @@ func TestNavMenuItem_ParsesTheIconOnASubMenu(t *testing.T) {
 	}
 }
 
-// The clause is optional, and its absence must not be confused with the caption
-// — both are STRING_LITERALs, so the visitor reads them positionally and has to
-// be pinned against picking up the caption as an icon.
+// The clause is optional. The target and the icon are both qualifiedNames in one
+// indexed list, so the visitor reads them positionally and has to be pinned
+// against mistaking the PAGE target for an icon.
 func TestNavMenuItem_NoIconClauseLeavesIconEmpty(t *testing.T) {
 	items := navMenuItems(t, "MENU ITEM 'Dashboard' PAGE M.Dash;")
 	if len(items) != 1 {
@@ -74,7 +90,7 @@ func TestNavMenuItem_NoIconClauseLeavesIconEmpty(t *testing.T) {
 // An icon on an item with no action at all still parses: ICON is independent of
 // the optional PAGE/MICROFLOW target.
 func TestNavMenuItem_IconWithoutATarget(t *testing.T) {
-	items := navMenuItems(t, "MENU ITEM 'Placeholder' ICON 'Atlas_Core.Atlas.home';")
+	items := navMenuItems(t, "MENU ITEM 'Placeholder' ICON Atlas_Core.Atlas.home;")
 	if len(items) != 1 {
 		t.Fatalf("expected 1 item, got %d", len(items))
 	}

From dc780ec5c98d73ddebe8ac61cba070d5dae22c57 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 9 Aug 2026 11:25:18 +0000
Subject: [PATCH 16/29] fix(odata): the modelsdk writer never wrote
 AllowedModuleRoles
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The role-grant fix (28ce821) went into sdk/mpr/writer_odata.go. The other
writer had ZERO references to AllowedModuleRoles, so a
`create or modify odata service` on the modelsdk engine kept revoking a
service's access however carefully the mpr writer was fixed:

  mxcli-prefix / legacy:   grant KEPT
  mxcli-prefix / modelsdk: grant LOST      <- the reported defect
  mxcli       / legacy:    grant KEPT
  mxcli       / modelsdk:  grant KEPT

GRANT is a separate statement and cannot be restated in the service body, so
once dropped nothing in the script can put it back.

Two parts: write the field (marker 1, matching the mpr writer), and register
it in MandatoryListMarkers so a service with no grants still emits the empty
marker. ByNameRefList only marks dirty on Append, so without the default an
empty list omits the key entirely -- and omitting is what deletes, because
the document is serialized wholesale.

Answering the follow-up question in the report -- whether the two writers
diverge elsewhere -- the remaining four keys legacy writes and modelsdk does
not name directly (Enumerations, Microflows, MetadataReferences,
ValidatedEntities) are all supplied by TypeDefaults. OData writer parity is
now complete.

Adds TestODataService_EngineWriteParity: run the same script through both
engines, read the stored BSON, and assert modelsdk writes every key legacy
does. That is the general property, so it catches the next dropped field
rather than only this one.

Two measurements changed what this commit does:

- `mx check` CANNOT gate this. A published service with no allowed roles is
  0 errors on Mendix 11.12 -- CE0307 does not fire -- so the doctype gate is
  blind to the symptom. The example added here exercises the path and says
  plainly that it does not gate it; the BSON comparison is the gate.
- The parity test needs the `create or modify` step. GRANT patches the
  stored document, so create+grant alone passes on both engines even with
  the bug present. My first version omitted the modify and the revert
  control passed -- the test proved nothing until that step was added.

mxcli-formula1 §41
---
 .../doctype-tests/10-odata-examples.mdl       |  62 +++++++
 mdl/backend/modelsdk/odata_roles_test.go      | 173 ++++++++++++++++++
 mdl/backend/modelsdk/odata_write.go           |  20 +-
 mdl/executor/odata_engine_parity_test.go      | 154 ++++++++++++++++
 4 files changed, 408 insertions(+), 1 deletion(-)
 create mode 100644 mdl/backend/modelsdk/odata_roles_test.go
 create mode 100644 mdl/executor/odata_engine_parity_test.go

diff --git a/mdl-examples/doctype-tests/10-odata-examples.mdl b/mdl-examples/doctype-tests/10-odata-examples.mdl
index 657bdc134..4a583e82a 100644
--- a/mdl-examples/doctype-tests/10-odata-examples.mdl
+++ b/mdl-examples/doctype-tests/10-odata-examples.mdl
@@ -434,6 +434,68 @@ grant access on odata service OdTest.CustomerAPI to OdTest.Admin, OdTest.user;
 revoke access on odata service OdTest.CustomerAPI from OdTest.user;
 /
 
+/**
+ * Level 8.7c: A modify must NOT revoke the grants made above.
+ *
+ * The service document is serialized wholesale, so a writer that omits
+ * AllowedModuleRoles deletes it. Grants are made by GRANT ACCESS, a separate
+ * statement, and cannot be restated inside the service body — so once dropped
+ * nothing in the script can put them back and the build fails CE0307
+ * "At least one allowed role must be selected".
+ *
+ * NOTE: `mx check` does NOT catch this. A published service with no allowed
+ * roles is 0 errors on Mendix 11.12 (measured), so this example exercises the
+ * path but cannot gate it. The gate is
+ * TestODataService_EngineWriteParity, which reads the stored BSON and compares
+ * the two engines directly (mxcli-formula1 §26, §41).
+ */
+create or modify odata service OdTest.CustomerAPI (
+  path: 'odata/customers/',
+  version: '1.0.1',
+  ODataVersion: OData4,
+  namespace: 'OdTest.Customers',
+  ServiceName: 'Customer Service',
+  Summary: 'API for managing customers (modified, grants not restated)',
+  PublishAssociations: Yes
+)
+authentication basic, session
+{
+  publish entity OdTest.Customer as 'Customers' (
+    ReadMode: source,
+    InsertMode: source,
+    UpdateMode: source,
+    DeleteMode: not_supported,
+    UsePaging: Yes,
+    PageSize: 100
+  )
+  expose (
+    Email as 'customerId' (KEY, Filterable, Sortable),
+    Name (Filterable, Sortable),
+    Phone,
+    IsActive,
+    Order_Customer as 'Orders'
+  );
+
+  publish entity OdTest.Order as 'Orders' (
+    ReadMode: source,
+    InsertMode: not_supported,
+    UpdateMode: not_supported,
+    DeleteMode: not_supported
+  )
+  expose (
+    OrderNumber as 'orderId' (KEY, Filterable, Sortable),
+    OrderDate (Sortable),
+    TotalAmount (Sortable),
+    Status (Filterable),
+    Order_Customer as 'Customer'
+  );
+};
+/
+
+-- The grant made in 8.7a must still be there.
+describe odata service OdTest.CustomerAPI;
+/
+
 -- ############################################################################
 -- LEVEL 9: EXTERNAL ACTION CALLS IN MICROFLOWS
 -- ############################################################################
diff --git a/mdl/backend/modelsdk/odata_roles_test.go b/mdl/backend/modelsdk/odata_roles_test.go
new file mode 100644
index 000000000..f206cfab6
--- /dev/null
+++ b/mdl/backend/modelsdk/odata_roles_test.go
@@ -0,0 +1,173 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package modelsdkbackend
+
+import (
+	"testing"
+
+	"github.com/mendixlabs/mxcli/model"
+	"github.com/mendixlabs/mxcli/modelsdk/codec"
+	"go.mongodb.org/mongo-driver/v2/bson"
+)
+
+// mxcli-formula1 §41: the §26 role-grant fix landed in sdk/mpr/writer_odata.go
+// only. This writer had ZERO references to AllowedModuleRoles, so a
+// `create or modify odata service` through the modelsdk engine still revoked the
+// service's access however carefully the other writer was fixed:
+//
+//	grant, then mx check              → 0 errors
+//	create-or-modify, no grant clause → CE0307 "At least one allowed role must be selected"
+//
+// The document is serialized wholesale, so a field the serializer omits is not
+// left alone — it is deleted.
+func TestPublishedODataServiceToGen_WritesTheRoleGrants(t *testing.T) {
+	g := publishedODataServiceToGen(&model.PublishedODataService{
+		Name:               "ZzApi",
+		AllowedModuleRoles: []string{"MyFirstModule.User", "MyFirstModule.Admin"},
+	})
+	raw, err := (&codec.Encoder{}).Encode(g)
+	if err != nil {
+		t.Fatalf("encode: %v", err)
+	}
+	val, lookupErr := bson.Raw(raw).LookupErr("AllowedModuleRoles")
+	if lookupErr != nil {
+		t.Fatal("AllowedModuleRoles is absent; a modify through this engine revokes the grants (CE0307)")
+	}
+	arr, ok := val.ArrayOK()
+	if !ok {
+		t.Fatalf("AllowedModuleRoles is not an array: %v", val)
+	}
+	vals, err := arr.Values()
+	if err != nil {
+		t.Fatalf("reading the array: %v", err)
+	}
+	// Marker 1, then the qualified names. The marker is not decoration: the
+	// legacy writer documents that a role list without its version prefix is
+	// read as stale access control.
+	if len(vals) != 3 {
+		t.Fatalf("got %d entries, want marker + 2 roles: %v", len(vals), vals)
+	}
+	if m, ok := vals[0].Int32OK(); !ok || m != 1 {
+		t.Errorf("version marker = %v, want int32(1) — the marker AllowedModuleRoles uses", vals[0])
+	}
+	for i, want := range []string{"MyFirstModule.User", "MyFirstModule.Admin"} {
+		if got, ok := vals[i+1].StringValueOK(); !ok || got != want {
+			t.Errorf("role %d = %v, want %q", i, vals[i+1], want)
+		}
+	}
+}
+
+// A service with no grants must still write the key. Omitting it entirely is
+// what deletes the stored grants on the next modify; an explicit empty list is
+// the honest encoding of "none", and matches what the legacy writer emits.
+func TestPublishedODataServiceToGen_WritesAnEmptyRoleListNotNothing(t *testing.T) {
+	g := publishedODataServiceToGen(&model.PublishedODataService{Name: "ZzApi"})
+	raw, err := (&codec.Encoder{}).Encode(g)
+	if err != nil {
+		t.Fatalf("encode: %v", err)
+	}
+	val, lookupErr := bson.Raw(raw).LookupErr("AllowedModuleRoles")
+	if lookupErr != nil {
+		t.Fatal("the key must be written even with no grants")
+	}
+	arr, _ := val.ArrayOK()
+	vals, _ := arr.Values()
+	if len(vals) != 1 {
+		t.Fatalf("got %d entries, want just the marker: %v", len(vals), vals)
+	}
+}
+
+// The engine-parity claim, asserted rather than assumed. The two writers
+// serialize the same document; a field one carries and the other drops means
+// MXCLI_ENGINE silently changes whether a service keeps its access — and
+// nothing in the suite noticed for a whole release.
+func TestPublishedODataServiceToGen_RoleEncodingMatchesTheMprEngine(t *testing.T) {
+	roles := []string{"MyFirstModule.User"}
+	g := publishedODataServiceToGen(&model.PublishedODataService{Name: "ZzApi", AllowedModuleRoles: roles})
+	raw, err := (&codec.Encoder{}).Encode(g)
+	if err != nil {
+		t.Fatalf("encode: %v", err)
+	}
+	got, lookupErr := bson.Raw(raw).LookupErr("AllowedModuleRoles")
+	if lookupErr != nil {
+		t.Fatal("AllowedModuleRoles is absent")
+	}
+	// The legacy writer builds exactly bson.A{int32(1), "MyFirstModule.User"}.
+	wantDoc, err := bson.Marshal(bson.D{{Key: "AllowedModuleRoles",
+		Value: bson.A{int32(1), "MyFirstModule.User"}}})
+	if err != nil {
+		t.Fatalf("marshalling the legacy shape: %v", err)
+	}
+	want := bson.Raw(wantDoc).Lookup("AllowedModuleRoles")
+	if !got.Equal(want) {
+		t.Errorf("modelsdk encodes %v; the mpr engine encodes %v", got, want)
+	}
+}
+
+// The reproduction from the report, through the backend rather than the
+// serializer: grant, then modify without restating the grant. The read path
+// already carried the roles; only the write dropped them, so a unit test on the
+// serializer alone would not have proven the cycle closes.
+func TestPublishedODataService_ModifyKeepsTheGrants(t *testing.T) {
+	proj := copyFixture(t)
+	b := New()
+	if err := b.Connect(proj); err != nil {
+		t.Fatalf("connect: %v", err)
+	}
+	t.Cleanup(func() { _ = b.Disconnect() })
+
+	mod, err := b.GetModuleByName("MyFirstModule")
+	if err != nil || mod == nil {
+		t.Fatalf("GetModuleByName: %v", err)
+	}
+	svc := &model.PublishedODataService{
+		ContainerID: mod.ID, Name: "RolesApi", Path: "odata/roles/",
+		Version: "1.0.0", ODataVersion: "OData4", Namespace: "MyFirstModule.Roles",
+		AllowedModuleRoles: []string{"MyFirstModule.User"},
+	}
+	if err := b.CreatePublishedODataService(svc); err != nil {
+		t.Fatalf("create: %v", err)
+	}
+
+	// Reconnect so the modify reads the stored document rather than reusing the
+	// in-memory one — that read-modify-write is where the grants were lost.
+	b2 := New()
+	if err := b2.Connect(proj); err != nil {
+		t.Fatalf("reconnect: %v", err)
+	}
+	t.Cleanup(func() { _ = b2.Disconnect() })
+
+	stored := findServiceByName(t, b2, "RolesApi")
+	if len(stored.AllowedModuleRoles) != 1 {
+		t.Fatalf("the grant did not survive CREATE: %v", stored.AllowedModuleRoles)
+	}
+	stored.Summary = "modified" // any edit; the grant clause is NOT restated
+	if err := b2.UpdatePublishedODataService(stored); err != nil {
+		t.Fatalf("update: %v", err)
+	}
+
+	b3 := New()
+	if err := b3.Connect(proj); err != nil {
+		t.Fatalf("reconnect: %v", err)
+	}
+	t.Cleanup(func() { _ = b3.Disconnect() })
+	after := findServiceByName(t, b3, "RolesApi")
+	if len(after.AllowedModuleRoles) != 1 || after.AllowedModuleRoles[0] != "MyFirstModule.User" {
+		t.Errorf("modify revoked the grants: %v — the next build fails CE0307", after.AllowedModuleRoles)
+	}
+}
+
+func findServiceByName(t *testing.T, b *Backend, name string) *model.PublishedODataService {
+	t.Helper()
+	svcs, err := b.ListPublishedODataServices()
+	if err != nil {
+		t.Fatalf("ListPublishedODataServices: %v", err)
+	}
+	for _, s := range svcs {
+		if s.Name == name {
+			return s
+		}
+	}
+	t.Fatalf("service %q not found", name)
+	return nil
+}
diff --git a/mdl/backend/modelsdk/odata_write.go b/mdl/backend/modelsdk/odata_write.go
index a02b7d92b..cceeab177 100644
--- a/mdl/backend/modelsdk/odata_write.go
+++ b/mdl/backend/modelsdk/odata_write.go
@@ -29,8 +29,14 @@ func init() {
 	codec.RegisterListMarker("ODataPublish$PublishedAttribute", 3)
 	codec.RegisterListMarker("ODataPublish$PublishedAssociationEnd", 3)
 	codec.RegisterListMarker("ODataPublish$PublishedId", 3)
+	// AllowedModuleRoles empties as marker 1, not 3 — it is a BY_NAME role list,
+	// not a part list. Without the entry, a service with no grants omits the key
+	// entirely, and since the document is serialized wholesale that DELETES the
+	// stored grants on the next modify (CE0307). An empty list is only reached
+	// when the property itself wrote nothing, because ByNameRefList marks dirty
+	// on Append.
 	codec.RegisterTypeDefaults("ODataPublish$PublishedODataService2", codec.TypeDefaults{
-		MandatoryListMarkers: map[string]int32{"AuthenticationTypes": 3, "EntityTypes": 3, "EntitySets": 3, "Enumerations": 3, "Microflows": 3},
+		MandatoryListMarkers: map[string]int32{"AllowedModuleRoles": 1, "AuthenticationTypes": 3, "EntityTypes": 3, "EntitySets": 3, "Enumerations": 3, "Microflows": 3},
 	})
 	codec.RegisterTypeDefaults("ODataPublish$EntityType", codec.TypeDefaults{
 		MandatoryListMarkers: map[string]int32{"ChildMembers": 3},
@@ -231,6 +237,18 @@ func publishedODataServiceToGen(svc *model.PublishedODataService) element.Elemen
 	addBool(g, "PublishAssociations", svc.PublishAssociations)
 	addBool(g, "UseGeneralization", svc.UseGeneralization)
 	addStr(g, "AuthenticationMicroflow", svc.AuthMicroflow)
+	// AllowedModuleRoles is written unconditionally, marker 1, matching
+	// sdk/mpr/writer_odata.go. This document is serialized wholesale, so a key
+	// the serializer omits is not left alone — it is deleted, silently revoking
+	// the service's access on every `create or modify`. Grants are made by a
+	// separate statement (`grant access on odata service …`) and cannot be
+	// restated in the create script, so nothing in the script can put them back;
+	// the next build fails CE0307 "At least one allowed role must be selected".
+	//
+	// The §26 fix went into the mpr writer only, and this one had no reference to
+	// the field at all, so the bug survived here for a full release with a green
+	// suite (mxcli-formula1 §41).
+	addByNameRefList(g, "AllowedModuleRoles", "", svc.AllowedModuleRoles)
 	if len(svc.AuthenticationTypes) > 0 {
 		addByNameRefListV3(g, "AuthenticationTypes", svc.AuthenticationTypes)
 	}
diff --git a/mdl/executor/odata_engine_parity_test.go b/mdl/executor/odata_engine_parity_test.go
new file mode 100644
index 000000000..4346ab47a
--- /dev/null
+++ b/mdl/executor/odata_engine_parity_test.go
@@ -0,0 +1,154 @@
+// SPDX-License-Identifier: Apache-2.0
+
+//go:build integration
+
+package executor
+
+import (
+	"sort"
+	"testing"
+
+	"github.com/mendixlabs/mxcli/mdl/backend"
+	modelsdkbackend "github.com/mendixlabs/mxcli/mdl/backend/modelsdk"
+	mprbackend "github.com/mendixlabs/mxcli/mdl/backend/mpr"
+	"github.com/mendixlabs/mxcli/mdl/visitor"
+	"github.com/mendixlabs/mxcli/model"
+	"go.mongodb.org/mongo-driver/bson"
+)
+
+// parityScript creates a published service and grants it a role. GRANT is a
+// separate statement — it cannot be expressed in the service body — which is
+// exactly why a writer that drops AllowedModuleRoles is unrecoverable from the
+// script.
+const parityScript = `
+create module PTest;
+create entity PTest.Cust (Email: string(200) unique error 'u' required error 'r');
+create module role PTest.Admin;
+create odata service PTest.Api (
+  path: 'odata/p/', version: '1.0.0', ODataVersion: OData4,
+  namespace: 'PTest.Api', ServiceName: 'Api'
+)
+authentication basic
+{
+  publish entity PTest.Cust as 'Custs' (
+    ReadMode: source, InsertMode: not_supported,
+    UpdateMode: not_supported, DeleteMode: not_supported
+  )
+  expose ( Email as 'email' (KEY) );
+};
+grant access on odata service PTest.Api to PTest.Admin;
+
+-- The modify is the load-bearing step. GRANT patches the stored document, so a
+-- create+grant alone looks fine on both engines; it is the wholesale
+-- re-serialization on modify that deletes whatever the writer omits.
+create or modify odata service PTest.Api (
+  path: 'odata/p/', version: '1.0.1', ODataVersion: OData4,
+  namespace: 'PTest.Api', ServiceName: 'Api'
+)
+authentication basic
+{
+  publish entity PTest.Cust as 'Custs' (
+    ReadMode: source, InsertMode: not_supported,
+    UpdateMode: not_supported, DeleteMode: not_supported
+  )
+  expose ( Email as 'email' (KEY) );
+};
+`
+
+// storedODataService runs parityScript on a fresh project through the given
+// engine and returns the service's stored BSON document.
+func storedODataService(t *testing.T, factory func() backend.FullBackend) map[string]any {
+	t.Helper()
+	env := setupTestEnvWithBackend(t, factory)
+	defer env.teardown()
+
+	prog, errs := visitor.Build(parityScript)
+	if len(errs) > 0 {
+		t.Fatalf("parse: %v", errs[0])
+	}
+	if err := env.executor.ExecuteProgram(prog); err != nil {
+		t.Fatalf("execute: %v", err)
+	}
+
+	svcs, err := env.executor.Backend().ListPublishedODataServices()
+	if err != nil {
+		t.Fatalf("list services: %v", err)
+	}
+	var id model.ID
+	for _, s := range svcs {
+		if s.Name == "Api" {
+			id = s.ID
+		}
+	}
+	if id == "" {
+		t.Fatal("the service was not created")
+	}
+	raw, err := env.executor.Backend().GetRawUnit(id)
+	if err != nil {
+		t.Fatalf("read raw unit: %v", err)
+	}
+	return raw
+}
+
+// The two OData writers must serialize the same key set.
+//
+// mxcli-formula1 §41: the §26 role-grant fix went into sdk/mpr/writer_odata.go,
+// and the modelsdk writer had no reference to AllowedModuleRoles at all — so a
+// `create or modify odata service` on that engine kept revoking the grants for a
+// whole release. Nothing noticed, because every existing test exercised one
+// writer or the other, never the two against each other.
+//
+// The doctype gate cannot stand in for this. A published service with no allowed
+// roles is 0 errors under `mx check` on Mendix 11.12 (measured, not assumed), so
+// the build is blind to the symptom; the loss is only visible in the stored
+// document. That is why this asserts on BSON rather than on a check result.
+//
+// Asserted as the general property, not the one field: whatever legacy writes,
+// modelsdk writes too.
+func TestODataService_EngineWriteParity(t *testing.T) {
+	legacy := storedODataService(t, func() backend.FullBackend { return mprbackend.New() })
+	msdk := storedODataService(t, func() backend.FullBackend { return modelsdkbackend.New() })
+
+	var missing []string
+	for k := range legacy {
+		if _, ok := msdk[k]; !ok {
+			missing = append(missing, k)
+		}
+	}
+	sort.Strings(missing)
+	if len(missing) > 0 {
+		t.Errorf("modelsdk drops %d key(s) the mpr engine writes: %v\n"+
+			"The document is serialized wholesale, so a key the serializer omits is "+
+			"not left alone — it is deleted on the next modify.", len(missing), missing)
+	}
+
+	// The reported field, by value rather than presence: an empty marker array
+	// satisfies a key-set check while still having revoked the grant.
+	for name, doc := range map[string]map[string]any{"legacy": legacy, "modelsdk": msdk} {
+		roles, ok := doc["AllowedModuleRoles"]
+		if !ok {
+			t.Errorf("%s: AllowedModuleRoles absent", name)
+			continue
+		}
+		// The two readers hand back the same array under different static
+		// types (bson.A on one path, a plain []any on the other), so accept both
+		// rather than pinning an incidental difference.
+		var arr []any
+		switch v := roles.(type) {
+		case bson.A:
+			arr = v
+		case []any:
+			arr = v
+		default:
+			t.Errorf("%s: AllowedModuleRoles is %T, want an array", name, roles)
+			continue
+		}
+		if len(arr) != 2 {
+			t.Errorf("%s: AllowedModuleRoles = %v, want marker + the granted role", name, arr)
+			continue
+		}
+		if arr[1] != "PTest.Admin" {
+			t.Errorf("%s: granted role = %v, want PTest.Admin", name, arr[1])
+		}
+	}
+}

From 109a55c4516cc82bdfb1a65e0938c8c25055d06e Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 9 Aug 2026 11:47:00 +0000
Subject: [PATCH 17/29] feat(odata): name the custom-authentication microflow
 from MDL
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`authentication microflow Module.Auth` parsed, checked clean and reported
"Created OData service" -- then failed the build with CE0333 "Please select a
microflow to use for authentication", because nothing ever assigned the name.

The plumbing existed at both ends and only the middle was missing: the
grammar already accepted `MICROFLOW qualifiedName?`, both writers already
serialize AuthenticationMicroflow from svc.AuthMicroflow, and both readers
already read it back. parseODataAuthTypes recognised the keyword and threw
the name away, so the field was only ever populated by reading a model Studio
Pro had written.

DESCRIBE emitted it as a comment (`-- Auth Microflow: …`), which is the same
defect class as the page-parameter loss: output that looks complete and
replays into a model the build rejects. It is now part of the clause, and the
round-trip test asserts the emitted text re-parses to the same microflow.

Adds MDL-ODATA04: the name is optional in the grammar, so `authentication
microflow` alone still parses -- and that is exactly what produces CE0333.

This matters beyond syntax completeness. Custom authentication is the only
way to avoid a full password hash on every OData request; basic auth pays it
per call and even pays it on a wrong password, which measured as 60-80% of a
page turn. The consumer needs no change: the microflow can read the
Authorization header itself.

Verified by writing a custom-auth service entirely from MDL into a real
project: DESCRIBE round-trips it, and `mx check` reports 0 errors. A modify
that omits the authentication clause preserves the microflow on both engines.

Deliberately NOT in the doctype gate: those projects run with security off,
and Mendix reports CE6600 "App security is off, but custom authentication is
enabled" for any custom-auth service there, regardless of correctness. The
skill documents both that rule and CE0333.

mxcli-formula1 §40
---
 .claude/skills/fix-issue.md                 |   1 +
 .claude/skills/mendix/odata-data-sharing.md |  72 +++++++++
 cmd/mxcli/cmd_check.go                      |   5 +
 cmd/mxcli/syntax/features_integration.go    |   5 +
 docs/01-project/MDL_QUICK_REFERENCE.md      |   5 +
 mdl/ast/ast_odata.go                        |   9 +-
 mdl/executor/cmd_odata.go                   |  38 ++++-
 mdl/executor/odata_auth_microflow_test.go   | 159 ++++++++++++++++++++
 mdl/executor/validate_odata_auth.go         |  59 ++++++++
 mdl/visitor/visitor_odata.go                |  18 ++-
 10 files changed, 359 insertions(+), 12 deletions(-)
 create mode 100644 mdl/executor/odata_auth_microflow_test.go
 create mode 100644 mdl/executor/validate_odata_auth.go

diff --git a/.claude/skills/fix-issue.md b/.claude/skills/fix-issue.md
index 0a640d910..7de26e997 100644
--- a/.claude/skills/fix-issue.md
+++ b/.claude/skills/fix-issue.md
@@ -439,3 +439,4 @@ extracting `OffsetExpression`/`LimitExpression`.
 | A published OData entity with no `KEY` fails the build with **CE6585** "Published entity 'X' must have a key defined." — so any advice of the form "drop the KEY" is impossible to follow | Mendix requires every published entity to have a key. MDL-ODATA02's suggestion offered "…or drop the KEY" as the alternative to answering a key lookup, and a doctype example demonstrated that non-existent option | `mdl/executor/validate_odata_read_contract.go` (suggestion text), `mdl-examples/doctype-tests/10-odata-examples.mdl`, `.claude/skills/mendix/odata-data-sharing.md` | **Query options you may decline; the key you may not.** A microflow-backed resource whose rows a client can hold *must* answer the key lookup — there is no opt-out, which makes MDL-ODATA02's real remedy singular rather than a choice. **Verify the remedy a diagnostic recommends, not just the diagnosis** — the rule correctly identified an unanswerable KEY and then proposed something mxbuild rejects, which is worse than saying nothing. This is the second time in one session that a doctype example was validated with `mxcli check` (parse-only) instead of the integration gate; `mxcli check` cannot see CE-codes at all, so **any change to `mdl-examples/doctype-tests/` needs `go test -tags integration -run TestMxCheck_DoctypeScripts/<script>` before it is called done** — the two-minute run that would have caught both. mxcli-formula1 §37 follow-up |
 | A page written by mxcli will not open in Studio Pro, and `mx check` dies during *load* with `ArgumentNullException` at `EntityRefStep.set_AssociationId` — no page error, no CE code, the whole project is down rather than one document | An association DATASOURCE wrote the association name exactly as authored. Both halves of an `EntityRefStep` are BY_NAME and Mendix resolves either one it cannot find to null, but only `DestinationEntity` was guarded (issuetracker #14) — a bare `Order_Line` reached BSON unqualified. The **explicit-destination** form is the live trap: supplying the destination satisfies that guard, so nothing stood between a bare name and the crash — and `Assoc/Module.Entity` is exactly what the guard's error tells the author to write | `mdl/executor/cmd_pages_builder_v3.go` (`buildDataSourceV3`, `case "association"`: qualify via `resolveAssociationPathIn`, then verify an author-supplied destination's association exists via `associationEndpoints`) | **Guard every BY_NAME half of a ref, not the one that was reported.** #854 reported the destination; the association beside it failed identically and was reachable through the fix's own advice. **Diff the two properties in the dump** (`grep -A1 '"Key": "(Association\|DestinationEntity)"'`) rather than reading the exception name — the loader reports whichever it touches first. **Hold the input constant across builds**: the pre-fix binary was first run with bare names and post-fix with qualified ones, which "reproduced" nothing; re-running the *same qualified* script on both is what isolated cross-module (`""`) from same-module (resolved). `mx check` exits 0 on this failure — assert on the `contains: N errors` line, never `$?`. Tests `cmd_pages_builder_assoc_datasource_test.go`, example `mdl-examples/bug-tests/854-assoc-datasource-qualified-name.mdl`. upstream #854 follow-on |
 | A navigation menu item cannot be given an icon at all — the grammar has no `ICON`, and every item mxcli writes gets `Icon: null`, so a menu authored in MDL is flat text next to one authored in Studio Pro | The syntax was never added, and the reason it stayed unadded is instructive: the metamodel names the element `Pages$IconCollectionIcon`, but Mendix **stores** it as `Forms$IconCollectionIcon` — one more instance of the "Form was the original term for Page" rename CLAUDE.md documents for `ShowFormAction`. There was no way to know that from the metamodel alone, and inventing a `$Type` for a polymorphic child is the failure mode where mxbuild builds green and Studio Pro cannot open the document | `mdl/grammar/MDLParser.g4` (`navMenuItemDef`, both alternatives), `mdl/ast/ast_navigation.go`, `mdl/visitor/visitor_navigation.go` (positional `AllQualifiedName()` — the PAGE/MICROFLOW target and the icon share one indexed list), `mdl/types/navigation.go`, `mdl/executor/cmd_navigation.go` (`convertMenuItemDef`, `printMenuMDL`), `sdk/mpr/writer_navigation.go` (`buildMenuIconBson`), `mdl/backend/modelsdk/navigation_write.go`, `sdk/mpr/parser_misc.go`, `mdl/backend/mpr/convert.go` (`convertNavMenuItem` is a field-by-field copy and drops anything new) | **The icon is a `qualifiedName`, not a string** — it is a reference into the model, so it is spelled like every other reference (ADR-0003). Atlas names are hyphenated, and `align-center` lexes as HYPHENATED_ID, so that *segment* is double-quoted: `ICON Atlas_Core.Atlas."align-center"`. The DESCRIBE emitter (`quoteQualifiedName` in `mdl/executor/qualified_name_quoting.go`) must therefore decide quoting per segment, and **must not reuse `mdlIdent`**: mdlIdent quotes anything not lexing as a bare IDENTIFIER, but a qualifiedName segment is an `identifierOrKeyword`, which accepts keywords — and `home`, `user`, `add`, `folder` are all keyword tokens, so mdlIdent would quote nearly every icon. Decide acceptance by running the real parser on the segment, never a hardcoded keyword list. The invariant worth testing is not "which names get quotes" (I guessed that wrong twice) but **"does the emitted statement re-parse"** — feed DESCRIBE output back through `visitor.Build`. **Get the reference before writing the BSON.** A Studio Pro-authored project (`ako/mxcli-ledger`) settled in one dump what no amount of metamodel reading could: the storage name, the field (`Image`, a 3-part `Module.Collection.name`), the exact key set (`$ID`/`$Type`/`Image`, nothing more), and that **all three variants coexist** — `Forms$IconCollectionIcon{Image}`, `Forms$ImageIcon{Image}` (indistinguishable by name alone; it points into an *image* collection), `Forms$GlyphIcon{Code: int}`. Only the first is written; DESCRIBE emits a `-- icon … is not reproducible` comment for the other two rather than an `icon` clause that would convert the variant on replay. To dump a v2 unit: `grep -rl 'Menus$MenuItem' mprcontents` then `bson.Unmarshal` into a `bson.D`. **`mx check` reporting 0 errors is not the proof here** — its deserializer tolerates unknown properties; the proof is diffing the written element against the Studio Pro one (done: byte-shape identical, same key order). Icon *names* are also not guessable — `Atlas.list` and `Atlas_Filled.user-check` do not exist while `list-bullets` and `user` do; verify against the collection. **Second trap, in the read path**: `codec.Decode` returns a bare `*element.Base` for an *unregistered* `$Type` but a generated struct (which only *embeds* Base) for a registered one, so `icon.(*element.Base)` silently returns nothing for exactly the variants that exist in real projects — DESCRIBE printed every icon under `legacy` and none under `modelsdk`. Assert on `interface{ Raw() bson.Raw }`, which both shapes satisfy. A unit test passing `nil` did not reach this; **running `describe` against a real Studio Pro project under both `MXCLI_ENGINE` values did**, and that engine-vs-engine diff is the cheapest way to find a read-path divergence. Note `modelsdk/codec` is on bson **v2** while `mdl/backend/modelsdk`'s write path is on v1 — a test touching both needs an alias. Tests `sdk/mpr/writer_navigation_icon_test.go`, `mdl/visitor/visitor_navigation_icon_test.go`, `mdl/executor/cmd_navigation_icon_test.go`, `mdl/backend/modelsdk/navigation_icon_test.go`; example `mdl-examples/doctype-tests/11-navigation-examples.mdl`. mxcli-formula1 #9 |
+| `authentication microflow Module.Auth` on a published OData service parses, checks clean and reports `Created OData service` — then the build fails **CE0333** "Please select a microflow to use for authentication", and `DESCRIBE` shows `authentication Microflow` with no name. Custom authentication is unreachable from MDL, which matters because it is the only way to avoid a full BCrypt hash on every OData request (60–80% of a page turn measured) | The grammar had accepted `MICROFLOW qualifiedName?` all along and both writers already serialized `AuthenticationMicroflow` from `svc.AuthMicroflow` — but nothing ever *assigned* it. `parseODataAuthTypes` recognised the `microflow` keyword and discarded the name, so the field was only ever populated by reading a model Studio Pro wrote. DESCRIBE then emitted it as a comment (`-- Auth Microflow: …`), so a custom-auth service could not round-trip either | `mdl/ast/ast_odata.go` (`AuthMicroflow`), `mdl/visitor/visitor_odata.go` (`parseODataAuthTypes` returns the name), `mdl/executor/cmd_odata.go` (assign on create AND modify; `odataAuthClause` for DESCRIBE), `mdl/executor/validate_odata_auth.go` (MDL-ODATA04) | **When a feature "silently drops" one field, check whether the plumbing already exists at both ends** — here only the middle assignment was missing, so the fix was ~10 lines across four files rather than a new write path. The grammar already parsed the name: `at.QualifiedName()` was simply never read. **DESCRIBE emitting a value as a comment is the same defect class as dropping it** (§39): the output looks complete and replays into a model the build rejects — so the round-trip test asserts the emitted clause re-parses to the same microflow, not that it contains some text. Two Mendix rules bound the feature and are easy to hit while verifying: **CE0333** if no microflow is named (now MDL-ODATA04 at check time), and **CE6600** "App security is off, but custom authentication is enabled" — so a fixture project needs `alter project security level prototype` before it can prove anything. That second one is why this is NOT in the doctype gate: those projects run with security off, so any custom-auth service there fails CE6600 regardless of correctness. Verified instead by writing the service from MDL into a real project and running `mx check` (0 errors). Tests `mdl/executor/odata_auth_microflow_test.go`. mxcli-formula1 §40 |
diff --git a/.claude/skills/mendix/odata-data-sharing.md b/.claude/skills/mendix/odata-data-sharing.md
index 707f38d6f..37e6f58a9 100644
--- a/.claude/skills/mendix/odata-data-sharing.md
+++ b/.claude/skills/mendix/odata-data-sharing.md
@@ -602,6 +602,78 @@ non-filterable"` before the microflow runs. So the microflow only ever sees name
 that exist in the published metadata. That is defence in depth, not a substitute for a
 whitelist — it constrains the *name*, not what you do with it.
 
+## Authentication Methods, and the Cost of Basic Auth
+
+A published service names one or more methods in the `authentication` clause:
+
+```sql
+authentication basic, session
+authentication microflow ProductApi.Authenticate
+```
+
+| Method | How the caller proves itself | Cost per request |
+|---|---|---|
+| `basic` | `Authorization: Basic …` on every request | **a full password hash** |
+| `session` | an existing session + `X-Csrf-Token` | none, but only reachable from same-origin JavaScript in the same app |
+| `guest` | anonymous | none |
+| `microflow` | your microflow decides | whatever the microflow does |
+
+**Basic auth hashes on every call, including failures.** A consumed OData
+service holds no session, so every request is a fresh login. Measured on a real
+app, that was 60–80% of a page turn — and a *wrong* password costs the same,
+because the hash runs either way:
+
+```
+GET /odata/f1/Drivers?$top=20
+  basic auth                 200  ~360 ms
+  wrong password             401  ~346 ms   <- hashes either way
+  session cookie             200   ~19 ms
+  no credentials             401   ~42 ms
+```
+
+Do not read the 19 ms as the fix: `session` is only open to same-origin
+JavaScript, and a Mendix OData *client* sends basic auth and keeps no cookie.
+
+### Custom authentication
+
+A microflow taking `List of System.HttpHeader` and returning a `System.User`.
+Return empty to deny. No password hash anywhere, so the ~42 ms floor.
+
+```sql
+CREATE MICROFLOW ProductApi.Authenticate ($Headers: List of System.HttpHeader)
+  RETURNS System.User AS $User
+BEGIN
+  -- e.g. compare a shared secret from $Headers, then retrieve the service account
+  retrieve $Users from System.User;
+  $User = head($Users);
+  RETURN $User;
+END;
+
+create odata service ProductApi.Api ( ... )
+authentication microflow ProductApi.Authenticate
+{ ... };
+```
+
+**The client needs no change.** The microflow can read the `Authorization:
+Basic …` header itself and compare it against a constant, so the consumer keeps
+its existing username/password configuration and the server simply stops
+calling BCrypt.
+
+Two build rules to know before you reach for it:
+
+- **The microflow is mandatory.** `authentication microflow` with no name parses
+  but fails the build with **CE0333** "Please select a microflow to use for
+  authentication". `mxcli check` flags this as `MDL-ODATA04`.
+- **App security must be on.** With security off, Mendix reports **CE6600**
+  "App security is off, but custom authentication is enabled for this service".
+  Set it with `alter project security level prototype` (or `production`).
+
+If custom authentication is more than you need, `ALTER SETTINGS MODEL
+BcryptCost = 8` shrinks the hash instead of removing it. Each step down halves
+the cost; the default is 12. That is a judgement about the accounts in *that*
+app — appropriate for machine accounts with generated passwords, not for a
+database of human passwords.
+
 ## Step-by-Step: Read-Write API with Microflow Handlers
 
 For write operations (insert, update, delete), the OData service delegates to microflows that map between the view entity and the underlying persistent entities.
diff --git a/cmd/mxcli/cmd_check.go b/cmd/mxcli/cmd_check.go
index 2c83275ab..43b23ce6e 100644
--- a/cmd/mxcli/cmd_check.go
+++ b/cmd/mxcli/cmd_check.go
@@ -189,6 +189,11 @@ Examples:
 		// has to be declared correctly up front, and nothing else checks that.
 		violations = append(violations, executor.ValidateODataReadContract(prog)...)
 
+		// Flag `authentication microflow` with no microflow named. The grammar
+		// makes the name optional, so this parses and executes into a service
+		// Mendix refuses to build (CE0333).
+		violations = append(violations, executor.ValidateODataAuth(prog)...)
+
 		// Flag a page whose widgets point at a page created further down the same
 		// script. `exec` resolves page references in statement order and is not
 		// transactional, so this fails after earlier statements are already
diff --git a/cmd/mxcli/syntax/features_integration.go b/cmd/mxcli/syntax/features_integration.go
index 24e6e34d8..c3e35c435 100644
--- a/cmd/mxcli/syntax/features_integration.go
+++ b/cmd/mxcli/syntax/features_integration.go
@@ -84,6 +84,11 @@ func init() {
 			"  PublishAssociations: Yes           -- optional; default Yes (associations as links)\n" +
 			")\n" +
 			"authentication basic, session\n" +
+			"-- or, for custom authentication (no per-request password hash):\n" +
+			"--   authentication microflow Module.Authenticate\n" +
+			"-- The microflow takes a List of System.HttpHeader and returns a\n" +
+			"-- System.User; returning empty denies the request. Requires app\n" +
+			"-- security to be on (CE6600) and a microflow to be named (CE0333).\n" +
 			"{\n" +
 			"  publish entity Module.Entity as 'EntitySet' (\n" +
 			"    ReadMode: source | microflow Module.Read_X,\n" +
diff --git a/docs/01-project/MDL_QUICK_REFERENCE.md b/docs/01-project/MDL_QUICK_REFERENCE.md
index f520cfc77..fd26361f9 100644
--- a/docs/01-project/MDL_QUICK_REFERENCE.md
+++ b/docs/01-project/MDL_QUICK_REFERENCE.md
@@ -214,6 +214,11 @@ create odata service MyModule.CustomerAPI (
   namespace: 'MyModule.Customers'
 )
 authentication basic, session
+-- or: authentication microflow Module.Authenticate
+--   Custom authentication. The microflow takes a List of System.HttpHeader and
+--   returns a System.User (empty denies). It removes the per-request password
+--   hash that `basic` pays on every call. Requires app security on (CE6600) and
+--   a microflow to be named (CE0333, flagged as MDL-ODATA04).
 {
   publish entity MyModule.Customer as 'Customers' (
     ReadMode: source,
diff --git a/mdl/ast/ast_odata.go b/mdl/ast/ast_odata.go
index 158129ab7..9603332c7 100644
--- a/mdl/ast/ast_odata.go
+++ b/mdl/ast/ast_odata.go
@@ -102,8 +102,13 @@ type CreateODataServiceStmt struct {
 	PublishAssociations    bool
 	PublishAssociationsSet bool
 	AuthenticationTypes    []string
-	Entities               []*PublishedEntityDef
-	CreateOrModify         bool // True if CREATE OR MODIFY was used
+	// AuthMicroflow is the microflow named by `authentication microflow X`.
+	// Custom authentication is the only method that carries a target, and
+	// Mendix rejects the service without one (CE0333 "Please select a microflow
+	// to use for authentication").
+	AuthMicroflow  string
+	Entities       []*PublishedEntityDef
+	CreateOrModify bool // True if CREATE OR MODIFY was used
 
 	// UnknownProperties holds property names the visitor did not recognise, in
 	// source order. The parser accepts any `name: value` pair, so without this
diff --git a/mdl/executor/cmd_odata.go b/mdl/executor/cmd_odata.go
index dd82768bb..a6b2e274f 100644
--- a/mdl/executor/cmd_odata.go
+++ b/mdl/executor/cmd_odata.go
@@ -348,12 +348,15 @@ func outputPublishedODataServiceMDL(ctx *ExecContext, svc *model.PublishedODataS
 
 	fmt.Fprintln(ctx.Output, ")")
 
-	// Authentication types
+	// Authentication types. The custom-authentication microflow is part of the
+	// clause, not a comment beside it: emitted as a comment the output looked
+	// complete but replayed into a service Mendix rejects with CE0333
+	// (mxcli-formula1 §40).
 	if len(svc.AuthenticationTypes) > 0 {
-		fmt.Fprintf(ctx.Output, "authentication %s\n", strings.Join(svc.AuthenticationTypes, ", "))
-	}
-	if svc.AuthMicroflow != "" {
-		fmt.Fprintf(ctx.Output, "-- Auth Microflow: %s\n", svc.AuthMicroflow)
+		fmt.Fprintf(ctx.Output, "authentication %s\n", odataAuthClause(svc))
+	} else if svc.AuthMicroflow != "" {
+		// A microflow with no type recorded still has to survive the round trip.
+		fmt.Fprintf(ctx.Output, "authentication microflow %s\n", svc.AuthMicroflow)
 	}
 
 	// Published entities block
@@ -1372,6 +1375,9 @@ func createODataService(ctx *ExecContext, stmt *ast.CreateODataServiceStmt) erro
 					}
 					if len(stmt.AuthenticationTypes) > 0 {
 						svc.AuthenticationTypes = stmt.AuthenticationTypes
+						// Restated auth replaces the microflow too, including
+						// clearing it when the new clause is not `microflow`.
+						svc.AuthMicroflow = stmt.AuthMicroflow
 					}
 					// Published entities are replaced wholesale when the statement
 					// supplies any. Previously the modify branch ignored them
@@ -1454,6 +1460,7 @@ func createODataService(ctx *ExecContext, stmt *ast.CreateODataServiceStmt) erro
 		Description:         stmt.Description,
 		PublishAssociations: publishAssociationsFor(stmt),
 		AuthenticationTypes: stmt.AuthenticationTypes,
+		AuthMicroflow:       stmt.AuthMicroflow,
 	}
 
 	// Map AST entity definitions to model entity types and entity sets.
@@ -2156,3 +2163,24 @@ func bareMemberName(name string) string {
 	}
 	return name
 }
+
+// odataAuthClause renders a service's authentication methods as MDL, attaching
+// the microflow to the `Microflow` method rather than trailing it as a comment.
+// Custom authentication is the only method that names a target.
+func odataAuthClause(svc *model.PublishedODataService) string {
+	parts := make([]string, 0, len(svc.AuthenticationTypes))
+	named := false
+	for _, t := range svc.AuthenticationTypes {
+		if strings.EqualFold(t, "Microflow") && svc.AuthMicroflow != "" {
+			parts = append(parts, t+" "+svc.AuthMicroflow)
+			named = true
+			continue
+		}
+		parts = append(parts, t)
+	}
+	// A stored microflow with no matching method would otherwise be dropped.
+	if !named && svc.AuthMicroflow != "" {
+		parts = append(parts, "Microflow "+svc.AuthMicroflow)
+	}
+	return strings.Join(parts, ", ")
+}
diff --git a/mdl/executor/odata_auth_microflow_test.go b/mdl/executor/odata_auth_microflow_test.go
new file mode 100644
index 000000000..7b8d829c3
--- /dev/null
+++ b/mdl/executor/odata_auth_microflow_test.go
@@ -0,0 +1,159 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package executor
+
+import (
+	"strings"
+	"testing"
+
+	"github.com/mendixlabs/mxcli/mdl/ast"
+	"github.com/mendixlabs/mxcli/mdl/visitor"
+	"github.com/mendixlabs/mxcli/model"
+)
+
+// authService parses a service with the given authentication clause.
+func authService(t *testing.T, clause string) *ast.CreateODataServiceStmt {
+	t.Helper()
+	script := `create odata service T.Api (
+  path: 'odata/t/', version: '1.0.0', ODataVersion: OData4,
+  namespace: 'T.Api', ServiceName: 'Api'
+)
+` + clause + `
+{
+  publish entity T.Row as 'Rows' (
+    ReadMode: source, InsertMode: not_supported,
+    UpdateMode: not_supported, DeleteMode: not_supported
+  )
+  expose ( K as 'k' (KEY) );
+};`
+	prog, errs := visitor.Build(script)
+	if len(errs) > 0 {
+		t.Fatalf("parse: %v", errs)
+	}
+	svc, ok := prog.Statements[0].(*ast.CreateODataServiceStmt)
+	if !ok {
+		t.Fatalf("expected CreateODataServiceStmt, got %T", prog.Statements[0])
+	}
+	return svc
+}
+
+// mxcli-formula1 §40: the grammar always accepted the qualified name; the
+// visitor discarded it. So `authentication microflow M.Auth` parsed, checked and
+// executed while the model got a Microflow method with no microflow — and
+// Mendix refused to build it (CE0333). Custom authentication is the fix for the
+// per-request BCrypt cost, so this gap kept a real optimisation out of reach of
+// a project whose model is written as MDL.
+func TestODataAuth_CapturesTheMicroflowName(t *testing.T) {
+	svc := authService(t, "authentication microflow T.Authenticate")
+	if svc.AuthMicroflow != "T.Authenticate" {
+		t.Errorf("AuthMicroflow = %q, want T.Authenticate — the name was discarded", svc.AuthMicroflow)
+	}
+	if len(svc.AuthenticationTypes) != 1 || svc.AuthenticationTypes[0] != "Microflow" {
+		t.Errorf("AuthenticationTypes = %v, want [Microflow]", svc.AuthenticationTypes)
+	}
+}
+
+// The method list is comma-separated, so the microflow must attach to its own
+// entry and not swallow the neighbours.
+func TestODataAuth_MicroflowAlongsideOtherMethods(t *testing.T) {
+	svc := authService(t, "authentication basic, microflow T.Authenticate, guest")
+	if svc.AuthMicroflow != "T.Authenticate" {
+		t.Errorf("AuthMicroflow = %q", svc.AuthMicroflow)
+	}
+	want := []string{"Basic", "Microflow", "Guest"}
+	if strings.Join(svc.AuthenticationTypes, ",") != strings.Join(want, ",") {
+		t.Errorf("AuthenticationTypes = %v, want %v", svc.AuthenticationTypes, want)
+	}
+}
+
+// Methods that carry no target must stay unaffected.
+func TestODataAuth_NoMicroflowForOtherMethods(t *testing.T) {
+	svc := authService(t, "authentication basic, session")
+	if svc.AuthMicroflow != "" {
+		t.Errorf("AuthMicroflow = %q, want empty", svc.AuthMicroflow)
+	}
+}
+
+// The name is optional in the grammar, so the incomplete form still parses —
+// and is exactly what produced CE0333. Check has to catch it.
+func TestODataAuth_FlagsMicroflowWithNoName(t *testing.T) {
+	svc := authService(t, "authentication microflow")
+	if svc.AuthMicroflow != "" {
+		t.Fatalf("AuthMicroflow = %q, want empty for this fixture", svc.AuthMicroflow)
+	}
+	prog := &ast.Program{Statements: []ast.Statement{svc}}
+	vs := ValidateODataAuth(prog)
+	if len(vs) != 1 || vs[0].RuleID != "MDL-ODATA04" {
+		t.Fatalf("expected one MDL-ODATA04, got %+v", vs)
+	}
+	if !strings.Contains(vs[0].Suggestion, "CE0333") {
+		t.Errorf("the suggestion should name the build error it prevents: %q", vs[0].Suggestion)
+	}
+}
+
+// A named microflow must not be flagged — otherwise the rule punishes the fix
+// it recommends.
+func TestODataAuth_SilentWhenTheMicroflowIsNamed(t *testing.T) {
+	svc := authService(t, "authentication microflow T.Authenticate")
+	if vs := ValidateODataAuth(&ast.Program{Statements: []ast.Statement{svc}}); len(vs) != 0 {
+		t.Errorf("a named microflow must not be flagged: %+v", vs)
+	}
+}
+
+// Nor must a service that never asked for custom authentication.
+func TestODataAuth_SilentForOtherMethods(t *testing.T) {
+	svc := authService(t, "authentication basic, session")
+	if vs := ValidateODataAuth(&ast.Program{Statements: []ast.Statement{svc}}); len(vs) != 0 {
+		t.Errorf("basic/session must not be flagged: %+v", vs)
+	}
+}
+
+// DESCRIBE emits re-executable MDL. Emitting the microflow as a comment
+// (`-- Auth Microflow: …`) made the output look complete while replaying into a
+// service Mendix rejects — the same shape as §39.
+func TestDescribeODataService_RoundTripsTheAuthMicroflow(t *testing.T) {
+	got := odataAuthClause(&model.PublishedODataService{
+		AuthenticationTypes: []string{"Microflow"},
+		AuthMicroflow:       "T.Authenticate",
+	})
+	if got != "Microflow T.Authenticate" {
+		t.Errorf("got %q, want %q", got, "Microflow T.Authenticate")
+	}
+}
+
+func TestDescribeODataService_AuthClauseKeepsOtherMethods(t *testing.T) {
+	got := odataAuthClause(&model.PublishedODataService{
+		AuthenticationTypes: []string{"Basic", "Microflow"},
+		AuthMicroflow:       "T.Authenticate",
+	})
+	if got != "Basic, Microflow T.Authenticate" {
+		t.Errorf("got %q", got)
+	}
+}
+
+// A stored microflow with no matching method would otherwise vanish from the
+// output; append it rather than lose it.
+func TestDescribeODataService_AuthMicroflowWithoutAMethodIsStillEmitted(t *testing.T) {
+	got := odataAuthClause(&model.PublishedODataService{
+		AuthenticationTypes: []string{"Basic"},
+		AuthMicroflow:       "T.Authenticate",
+	})
+	if got != "Basic, Microflow T.Authenticate" {
+		t.Errorf("got %q", got)
+	}
+}
+
+// The whole point: what DESCRIBE prints must parse back to the same service.
+func TestDescribeODataService_AuthClauseReParses(t *testing.T) {
+	clause := odataAuthClause(&model.PublishedODataService{
+		AuthenticationTypes: []string{"Basic", "Microflow"},
+		AuthMicroflow:       "T.Authenticate",
+	})
+	svc := authService(t, "authentication "+clause)
+	if svc.AuthMicroflow != "T.Authenticate" {
+		t.Errorf("round trip lost the microflow: %q", svc.AuthMicroflow)
+	}
+	if strings.Join(svc.AuthenticationTypes, ",") != "Basic,Microflow" {
+		t.Errorf("round trip changed the methods: %v", svc.AuthenticationTypes)
+	}
+}
diff --git a/mdl/executor/validate_odata_auth.go b/mdl/executor/validate_odata_auth.go
new file mode 100644
index 000000000..3c52f1f51
--- /dev/null
+++ b/mdl/executor/validate_odata_auth.go
@@ -0,0 +1,59 @@
+// SPDX-License-Identifier: Apache-2.0
+
+// Check-time validation of a published OData service's authentication clause.
+//
+// Custom authentication is the only method that names a target: a microflow
+// taking the request's HttpHeader list and returning a User. Mendix rejects the
+// service without one — CE0333 "Please select a microflow to use for
+// authentication" — and the grammar makes the name optional, so `authentication
+// microflow` alone parses and executes into a model that cannot build.
+//
+// mxcli-formula1 §40.
+package executor
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/mendixlabs/mxcli/mdl/ast"
+	"github.com/mendixlabs/mxcli/mdl/linter"
+)
+
+// ValidateODataAuth flags a Microflow authentication method with no microflow.
+func ValidateODataAuth(prog *ast.Program) []linter.Violation {
+	if prog == nil {
+		return nil
+	}
+	var out []linter.Violation
+	for _, stmt := range prog.Statements {
+		svc, ok := stmt.(*ast.CreateODataServiceStmt)
+		if !ok {
+			continue
+		}
+		if !namesMicroflowAuth(svc.AuthenticationTypes) || svc.AuthMicroflow != "" {
+			continue
+		}
+		out = append(out, linter.Violation{
+			RuleID:   "MDL-ODATA04",
+			Severity: linter.SeverityError,
+			Message: fmt.Sprintf("odata service %s: `authentication microflow` names no microflow",
+				svc.Name.String()),
+			Suggestion: "Custom authentication is the only method that carries a target — write " +
+				"`authentication microflow Module.Authenticate`. Mendix refuses to build the " +
+				"service otherwise (CE0333 \"Please select a microflow to use for authentication\"). " +
+				"The microflow takes the request's System.HttpHeader list and returns a " +
+				"System.User; returning empty denies the request.",
+		})
+	}
+	return out
+}
+
+// namesMicroflowAuth reports whether the clause selected custom authentication.
+func namesMicroflowAuth(types []string) bool {
+	for _, t := range types {
+		if strings.EqualFold(t, "Microflow") {
+			return true
+		}
+	}
+	return false
+}
diff --git a/mdl/visitor/visitor_odata.go b/mdl/visitor/visitor_odata.go
index 519dac706..7f1fc3c66 100644
--- a/mdl/visitor/visitor_odata.go
+++ b/mdl/visitor/visitor_odata.go
@@ -133,7 +133,7 @@ func (b *Builder) ExitCreateODataServiceStatement(ctx *parser.CreateODataService
 
 	// Parse authentication clause
 	if authCtx := ctx.OdataAuthenticationClause(); authCtx != nil {
-		stmt.AuthenticationTypes = parseODataAuthTypes(authCtx)
+		stmt.AuthenticationTypes, stmt.AuthMicroflow = parseODataAuthTypes(authCtx)
 	}
 
 	// Parse PUBLISH ENTITY blocks
@@ -319,10 +319,15 @@ func odataAssignmentValueText(prop *parser.OdataPropertyAssignmentContext) strin
 	return odataValueText(valCtx.(*parser.OdataPropertyValueContext))
 }
 
-// parseODataAuthTypes extracts authentication types from the clause.
-func parseODataAuthTypes(authCtx parser.IOdataAuthenticationClauseContext) []string {
+// parseODataAuthTypes extracts authentication types from the clause, and the
+// microflow named by `authentication microflow X`.
+//
+// The grammar has always accepted the qualified name; only the name was
+// discarded, so `authentication microflow M.Auth` parsed, checked and executed
+// while the model got a Microflow auth type with no microflow — a service that
+// then failed to build with CE0333 (mxcli-formula1 §40).
+func parseODataAuthTypes(authCtx parser.IOdataAuthenticationClauseContext) (types []string, microflow string) {
 	clause := authCtx.(*parser.OdataAuthenticationClauseContext)
-	var types []string
 
 	for _, atCtx := range clause.AllOdataAuthType() {
 		at := atCtx.(*parser.OdataAuthTypeContext)
@@ -334,12 +339,15 @@ func parseODataAuthTypes(authCtx parser.IOdataAuthenticationClauseContext) []str
 			types = append(types, "Guest")
 		} else if at.MICROFLOW() != nil {
 			types = append(types, "Microflow")
+			if qn := at.QualifiedName(); qn != nil {
+				microflow = buildQualifiedName(qn).String()
+			}
 		} else if at.IDENTIFIER() != nil {
 			types = append(types, at.IDENTIFIER().GetText())
 		}
 	}
 
-	return types
+	return types, microflow
 }
 
 // parsePublishEntityBlock converts a PUBLISH ENTITY parse context into an AST node.

From ededab1ca41e3d6cde6d9d4da2942adaf48d030b Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 9 Aug 2026 14:06:53 +0000
Subject: [PATCH 18/29] feat(odata): publish a microflow as an OData action
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

MDL could not declare an OData action at all.
`createODataServiceStatement` admitted `publishEntityBlock*` and nothing else,
so every variant of `publish microflow …` was a parse error at
`missing ENTITY` -- and the published $metadata had an EntityContainer with
EntitySets and no ActionImport.

    publish microflow AcTest.RecordPrediction as 'RecordPrediction'
      expose ( DriverId as 'driverId', Points as 'points' );

Parameter data types and the return type are NOT restated in MDL. They are
read off the microflow, which already declares them -- the same thing Studio
Pro does, and the only way the two cannot drift. An omitted expose clause
publishes every parameter under its own name.

Unlike the custom-auth gap, the write path did not exist either: neither
sdk/mpr/writer_odata.go nor mdl/backend/modelsdk/odata_write.go had a single
reference to PublishedMicroflow. Both now serialize it.

Nothing here was guessed. Every shape came from something already proven:

- property names and kinds from the generated metamodel
  (modelsdk/gen/odatapublish: ExposedName, AlternativeExposedName, a BY_NAME
  Microflow ref, a Parameters part list, a ReturnType part, Summary,
  Description);
- the Module.Microflow.Param form of the MicroflowParameter ref from the
  published-REST writer, which already ships it;
- the DataTypes$ObjectType/ListType `Entity` key and
  DataTypes$EnumerationType `Enumeration` key from serializeMicroflowDataType,
  which writes the same family for a microflow's own return type.

The semantic model keeps the data type as a kind plus a ref rather than one
string, because "Module.X" alone cannot say whether X is an entity or an
enumeration -- the ambiguity CLAUDE.md documents for the MDL visitor.

Verified beyond `mx check` reporting 0 errors, which for a new element type
proves only that mxbuild tolerated it. Dropping the target microflow makes
mxbuild name the elements back:

  CE1613 "The selected microflow 'AcTest.RecordPrediction' no longer exists."
         at Published microflow 'RecordPrediction'
  CE1613 "The selected parameter 'AcTest.RecordPrediction.DriverId' no longer
         exists." at Published microflow parameter DriverId from published
         microflow RecordPrediction

So mxbuild resolved the exposed name, the microflow reference and both
parameter references -- the element is understood, not merely accepted. Clean
on both engines before the drop; the cross-engine parity gate now publishes an
action too.

Still owed, and not claimed here: DESCRIBE does not yet emit the block, so a
service with an action does not round-trip; no doctype example; docs pending.

mxcli-formula1 §47.1
---
 mdl/ast/ast_odata.go                     |  29 ++++-
 mdl/backend/modelsdk/odata_write.go      |  82 ++++++++++++-
 mdl/executor/cmd_odata.go                |  15 +++
 mdl/executor/cmd_odata_actions.go        | 147 +++++++++++++++++++++++
 mdl/executor/odata_engine_parity_test.go |  14 +++
 mdl/grammar/domains/MDLService.g4        |  15 ++-
 mdl/visitor/visitor_odata.go             |  53 ++++++++
 mdl/visitor/visitor_odata_action_test.go | 106 ++++++++++++++++
 model/types.go                           |  36 +++++-
 sdk/mpr/writer_odata.go                  |  70 ++++++++++-
 10 files changed, 560 insertions(+), 7 deletions(-)
 create mode 100644 mdl/executor/cmd_odata_actions.go
 create mode 100644 mdl/visitor/visitor_odata_action_test.go

diff --git a/mdl/ast/ast_odata.go b/mdl/ast/ast_odata.go
index 9603332c7..a7c9aa524 100644
--- a/mdl/ast/ast_odata.go
+++ b/mdl/ast/ast_odata.go
@@ -106,8 +106,11 @@ type CreateODataServiceStmt struct {
 	// Custom authentication is the only method that carries a target, and
 	// Mendix rejects the service without one (CE0333 "Please select a microflow
 	// to use for authentication").
-	AuthMicroflow  string
-	Entities       []*PublishedEntityDef
+	AuthMicroflow string
+	Entities      []*PublishedEntityDef
+	// Microflows are OData actions — `publish microflow Module.MF`. Mendix
+	// exposes each as an ActionImport in $metadata.
+	Microflows     []*PublishedMicroflowDef
 	CreateOrModify bool // True if CREATE OR MODIFY was used
 
 	// UnknownProperties holds property names the visitor did not recognise, in
@@ -143,6 +146,28 @@ type PublishedEntityDef struct {
 	UnknownProperties []string
 }
 
+// PublishedMicroflowDef represents a PUBLISH MICROFLOW block — an OData action.
+//
+// Parameter data types and the return type are read off the microflow rather
+// than restated here, so the two cannot drift.
+type PublishedMicroflowDef struct {
+	Microflow   QualifiedName
+	ExposedName string
+	// Parameters selects and optionally renames the microflow's parameters.
+	// Empty means expose them all under their own names.
+	Parameters []*PublishedParamDef
+	// ExposeAll records an explicit `expose (*)`, which is the same as omitting
+	// the clause but says so.
+	ExposeAll bool
+}
+
+// PublishedParamDef is one exposed microflow parameter.
+type PublishedParamDef struct {
+	Name        string
+	ExposedName string
+	CanBeEmpty  bool
+}
+
 // PublishedMemberDef represents an EXPOSE member within a PUBLISH ENTITY block.
 type PublishedMemberDef struct {
 	Name        string
diff --git a/mdl/backend/modelsdk/odata_write.go b/mdl/backend/modelsdk/odata_write.go
index cceeab177..7f803c856 100644
--- a/mdl/backend/modelsdk/odata_write.go
+++ b/mdl/backend/modelsdk/odata_write.go
@@ -29,6 +29,10 @@ func init() {
 	codec.RegisterListMarker("ODataPublish$PublishedAttribute", 3)
 	codec.RegisterListMarker("ODataPublish$PublishedAssociationEnd", 3)
 	codec.RegisterListMarker("ODataPublish$PublishedId", 3)
+	// Published microflows (OData actions) and their parameters. Marker 3 like
+	// every other part list in this document.
+	codec.RegisterListMarker("ODataPublish$PublishedMicroflow", 3)
+	codec.RegisterListMarker("ODataPublish$PublishedMicroflowParameter", 3)
 	// AllowedModuleRoles empties as marker 1, not 3 — it is a BY_NAME role list,
 	// not a part list. Without the entry, a service with no grants omits the key
 	// entirely, and since the document is serialized wholesale that DELETES the
@@ -275,14 +279,90 @@ func publishedODataServiceToGen(svc *model.PublishedODataService) element.Elemen
 		addPartList(g, "EntitySets", esElems)
 	}
 
+	if len(svc.Microflows) > 0 {
+		mfElems := make([]element.Element, 0, len(svc.Microflows))
+		for _, pm := range svc.Microflows {
+			mfElems = append(mfElems, publishedMicroflowToGen(pm))
+		}
+		addPartList(g, "Microflows", mfElems)
+	}
+
 	addBool(g, "Excluded", svc.Excluded)
-	// Enumerations / Microflows: empty marker-3 (via TypeDefaults).
+	// Enumerations: empty marker-3 (via TypeDefaults). Microflows too when the
+	// service publishes no actions.
 	addBool(g, "IncludeMetadataByDefault", true)
 	addBool(g, "ReplaceIllegalChars", false)
 	addBool(g, "SupportsGraphQL", false)
 	return g
 }
 
+// publishedMicroflowToGen builds an ODataPublish$PublishedMicroflow — the
+// element Mendix turns into an ActionImport.
+//
+// Property names and kinds come from the generated metamodel
+// (modelsdk/gen/odatapublish): ExposedName, AlternativeExposedName, a BY_NAME
+// Microflow ref, a Parameters part list, a ReturnType part, Summary and
+// Description. The MicroflowParameter ref is Module.Microflow.Param — the shape
+// the published-REST writer already ships.
+func publishedMicroflowToGen(pm *model.PublishedMicroflow) element.Element {
+	g := newElem("ODataPublish$PublishedMicroflow", string(pm.ID))
+	addStr(g, "ExposedName", pm.ExposedName)
+	addStr(g, "AlternativeExposedName", "")
+	addStr(g, "Microflow", pm.Microflow)
+	if len(pm.Parameters) > 0 {
+		params := make([]element.Element, 0, len(pm.Parameters))
+		for _, p := range pm.Parameters {
+			params = append(params, publishedMicroflowParameterToGen(p))
+		}
+		addPartList(g, "Parameters", params)
+	}
+	if rt := dataTypeElement(pm.ReturnTypeKind, pm.ReturnTypeRef); rt != nil {
+		addPart(g, "ReturnType", rt)
+	}
+	addStr(g, "Summary", pm.Summary)
+	addStr(g, "Description", pm.Description)
+	return g
+}
+
+func publishedMicroflowParameterToGen(p *model.PublishedMicroflowParameter) element.Element {
+	g := newElem("ODataPublish$PublishedMicroflowParameter", string(p.ID))
+	addStr(g, "ExposedName", p.ExposedName)
+	addStr(g, "MicroflowParameter", p.MicroflowParameter)
+	if dt := dataTypeElement(p.DataTypeKind, p.DataTypeRef); dt != nil {
+		addPart(g, "DataType", dt)
+	}
+	addBool(g, "CanBeEmpty", p.CanBeEmpty)
+	addStr(g, "Summary", p.Summary)
+	addStr(g, "Description", p.Description)
+	return g
+}
+
+// dataTypeElement builds a DataTypes$* element from a kind and, where the kind
+// names something, its qualified name. The kind strings are the ones
+// microflows.DataType.GetTypeName() produces, so the two stay in step.
+func dataTypeElement(kind, ref string) element.Element {
+	if kind == "" {
+		return nil
+	}
+	switch kind {
+	case "Object":
+		e := newElem("DataTypes$ObjectType", "")
+		addStr(e, "Entity", ref)
+		return e
+	case "List":
+		e := newElem("DataTypes$ListType", "")
+		addStr(e, "Entity", ref)
+		return e
+	case "Enumeration":
+		e := newElem("DataTypes$EnumerationType", "")
+		addStr(e, "Enumeration", ref)
+		return e
+	default:
+		// Boolean, String, Integer, Long, Decimal, DateTime, Binary, Void …
+		return newElem("DataTypes$"+kind+"Type", "")
+	}
+}
+
 func publishedEntityTypeToGen(et *model.PublishedEntityType) element.Element {
 	g := newElem("ODataPublish$EntityType", string(et.ID))
 	addStr(g, "Entity", et.Entity)
diff --git a/mdl/executor/cmd_odata.go b/mdl/executor/cmd_odata.go
index a6b2e274f..d66215361 100644
--- a/mdl/executor/cmd_odata.go
+++ b/mdl/executor/cmd_odata.go
@@ -1373,6 +1373,13 @@ func createODataService(ctx *ExecContext, stmt *ast.CreateODataServiceStmt) erro
 					if stmt.PublishAssociationsSet {
 						svc.PublishAssociations = stmt.PublishAssociations
 					}
+					if len(stmt.Microflows) > 0 {
+						published, mfErr := astMicroflowDefsToModel(ctx, stmt.Microflows)
+						if mfErr != nil {
+							return mfErr
+						}
+						svc.Microflows = published
+					}
 					if len(stmt.AuthenticationTypes) > 0 {
 						svc.AuthenticationTypes = stmt.AuthenticationTypes
 						// Restated auth replaces the microflow too, including
@@ -1463,6 +1470,14 @@ func createODataService(ctx *ExecContext, stmt *ast.CreateODataServiceStmt) erro
 		AuthMicroflow:       stmt.AuthMicroflow,
 	}
 
+	// OData actions. Resolved against the project's microflows so the parameter
+	// types and return type come off the microflow rather than being restated.
+	publishedMFs, mfErr := astMicroflowDefsToModel(ctx, stmt.Microflows)
+	if mfErr != nil {
+		return mfErr
+	}
+	newSvc.Microflows = publishedMFs
+
 	// Map AST entity definitions to model entity types and entity sets.
 	// Pass ctx so the executor can resolve exposed members against the
 	// entity's actual attributes and (for navigation properties) the
diff --git a/mdl/executor/cmd_odata_actions.go b/mdl/executor/cmd_odata_actions.go
new file mode 100644
index 000000000..f6447ad91
--- /dev/null
+++ b/mdl/executor/cmd_odata_actions.go
@@ -0,0 +1,147 @@
+// SPDX-License-Identifier: Apache-2.0
+
+// PUBLISH MICROFLOW — an OData action.
+//
+// Mendix exposes a published microflow in $metadata as an ActionImport, so a
+// client can POST arguments to it. Without it, a parameterised resource has to
+// be modelled as an entity set that carries its own arguments as attributes and
+// echoes them back on every row, because Mendix validates $filter against the
+// published metadata before the read microflow ever runs (mxcli-formula1 §47).
+//
+// Parameter data types and the return type are read off the microflow rather
+// than authored, so the two cannot drift — the same thing Studio Pro does.
+package executor
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/mendixlabs/mxcli/mdl/ast"
+	mdlerrors "github.com/mendixlabs/mxcli/mdl/errors"
+	"github.com/mendixlabs/mxcli/model"
+	"github.com/mendixlabs/mxcli/sdk/microflows"
+)
+
+// astMicroflowDefsToModel resolves each PUBLISH MICROFLOW block against the
+// project's microflows and converts it to the semantic model.
+func astMicroflowDefsToModel(ctx *ExecContext, defs []*ast.PublishedMicroflowDef) ([]*model.PublishedMicroflow, error) {
+	if len(defs) == 0 {
+		return nil, nil
+	}
+	byName, err := microflowsByQualifiedName(ctx)
+	if err != nil {
+		return nil, err
+	}
+	out := make([]*model.PublishedMicroflow, 0, len(defs))
+	for _, def := range defs {
+		qn := def.Microflow.String()
+		mf, ok := byName[strings.ToLower(qn)]
+		if !ok {
+			return nil, mdlerrors.NewNotFoundMsg("microflow", qn,
+				fmt.Sprintf("cannot publish %s as an OData action: microflow not found", qn))
+		}
+		pm, err := publishedMicroflowFor(def, mf, qn)
+		if err != nil {
+			return nil, err
+		}
+		out = append(out, pm)
+	}
+	return out, nil
+}
+
+// publishedMicroflowFor builds one published microflow from its definition and
+// the microflow it names.
+func publishedMicroflowFor(def *ast.PublishedMicroflowDef, mf *microflows.Microflow, qn string) (*model.PublishedMicroflow, error) {
+	exposed := def.ExposedName
+	if exposed == "" {
+		exposed = mf.Name
+	}
+	pm := &model.PublishedMicroflow{Microflow: qn, ExposedName: exposed}
+	pm.ReturnTypeKind, pm.ReturnTypeRef = dataTypeKindRef(mf.ReturnType)
+
+	// Index the microflow's own parameters so an authored name can be checked
+	// against them — a typo would otherwise publish a parameter Mendix cannot
+	// bind, and the failure would surface as a build error far from the cause.
+	params := map[string]*microflows.MicroflowParameter{}
+	for _, p := range mf.Parameters {
+		params[strings.ToLower(p.Name)] = p
+	}
+
+	selected := def.Parameters
+	if len(selected) == 0 {
+		// No selection: publish every parameter under its own name, in the
+		// microflow's declared order.
+		for _, p := range mf.Parameters {
+			selected = append(selected, &ast.PublishedParamDef{Name: p.Name})
+		}
+	}
+	for _, sel := range selected {
+		p, ok := params[strings.ToLower(sel.Name)]
+		if !ok {
+			return nil, mdlerrors.NewNotFoundMsg("microflow parameter", sel.Name,
+				fmt.Sprintf("%s has no parameter %q (it has: %s)",
+					qn, sel.Name, microflowParamNames(mf)))
+		}
+		exposedParam := sel.ExposedName
+		if exposedParam == "" {
+			exposedParam = p.Name
+		}
+		mp := &model.PublishedMicroflowParameter{
+			// Module.Microflow.Param — the same by-name shape the published-REST
+			// writer uses for this reference.
+			MicroflowParameter: qn + "." + p.Name,
+			ExposedName:        exposedParam,
+			CanBeEmpty:         sel.CanBeEmpty,
+		}
+		mp.DataTypeKind, mp.DataTypeRef = dataTypeKindRef(p.Type)
+		pm.Parameters = append(pm.Parameters, mp)
+	}
+	return pm, nil
+}
+
+// dataTypeKindRef splits a microflow data type into a kind and, for the three
+// kinds that name something, its qualified name. Kept apart because
+// "Module.X" alone cannot say whether X is an entity or an enumeration.
+func dataTypeKindRef(dt microflows.DataType) (kind, ref string) {
+	switch t := dt.(type) {
+	case nil:
+		return "", ""
+	case *microflows.ObjectType:
+		return "Object", t.EntityQualifiedName
+	case *microflows.ListType:
+		return "List", t.EntityQualifiedName
+	case *microflows.EnumerationType:
+		return "Enumeration", t.EnumerationQualifiedName
+	default:
+		return dt.GetTypeName(), ""
+	}
+}
+
+// microflowParamNames lists a microflow's parameter names for an error message.
+func microflowParamNames(mf *microflows.Microflow) string {
+	if len(mf.Parameters) == 0 {
+		return "none"
+	}
+	names := make([]string, 0, len(mf.Parameters))
+	for _, p := range mf.Parameters {
+		names = append(names, p.Name)
+	}
+	return strings.Join(names, ", ")
+}
+
+// microflowsByQualifiedName indexes the project's microflows, lower-cased.
+func microflowsByQualifiedName(ctx *ExecContext) (map[string]*microflows.Microflow, error) {
+	h, err := getHierarchy(ctx)
+	if err != nil {
+		return nil, mdlerrors.NewBackend("resolve module hierarchy", err)
+	}
+	mfs, err := ctx.Backend.ListMicroflows()
+	if err != nil {
+		return nil, mdlerrors.NewBackend("list microflows", err)
+	}
+	out := make(map[string]*microflows.Microflow, len(mfs))
+	for _, mf := range mfs {
+		out[strings.ToLower(h.GetQualifiedName(mf.ContainerID, mf.Name))] = mf
+	}
+	return out, nil
+}
diff --git a/mdl/executor/odata_engine_parity_test.go b/mdl/executor/odata_engine_parity_test.go
index 4346ab47a..e9644125c 100644
--- a/mdl/executor/odata_engine_parity_test.go
+++ b/mdl/executor/odata_engine_parity_test.go
@@ -24,6 +24,14 @@ const parityScript = `
 create module PTest;
 create entity PTest.Cust (Email: string(200) unique error 'u' required error 'r');
 create module role PTest.Admin;
+
+CREATE MICROFLOW PTest.DoThing ($Note: string)
+  RETURNS Boolean AS $Ok
+BEGIN
+  declare $Ok Boolean = true;
+  RETURN $Ok;
+END;
+
 create odata service PTest.Api (
   path: 'odata/p/', version: '1.0.0', ODataVersion: OData4,
   namespace: 'PTest.Api', ServiceName: 'Api'
@@ -35,6 +43,10 @@ authentication basic
     UpdateMode: not_supported, DeleteMode: not_supported
   )
   expose ( Email as 'email' (KEY) );
+
+  -- An OData action. Both writers must serialize the Microflows part list;
+  -- neither referenced PublishedMicroflow before mxcli-formula1 §47.
+  publish microflow PTest.DoThing as 'DoThing' expose ( Note as 'note' );
 };
 grant access on odata service PTest.Api to PTest.Admin;
 
@@ -52,6 +64,8 @@ authentication basic
     UpdateMode: not_supported, DeleteMode: not_supported
   )
   expose ( Email as 'email' (KEY) );
+
+  publish microflow PTest.DoThing as 'DoThing' expose ( Note as 'note' );
 };
 `
 
diff --git a/mdl/grammar/domains/MDLService.g4 b/mdl/grammar/domains/MDLService.g4
index e9c3471f6..ed388b5cc 100644
--- a/mdl/grammar/domains/MDLService.g4
+++ b/mdl/grammar/domains/MDLService.g4
@@ -145,7 +145,7 @@ createODataServiceStatement
     : ODATA SERVICE qualifiedName
       LPAREN odataPropertyAssignment (COMMA odataPropertyAssignment)* RPAREN
       odataAuthenticationClause?
-      (LBRACE publishEntityBlock* RBRACE)?
+      (LBRACE (publishEntityBlock | publishMicroflowBlock)* RBRACE)?
     ;
 
 odataPropertyValue
@@ -185,6 +185,19 @@ publishEntityBlock
       SEMICOLON?
     ;
 
+// An OData action/function: a published microflow. Mendix exposes it in
+// $metadata as an ActionImport, so a client can POST arguments to it rather
+// than reading them back as echoed columns of an entity set.
+//
+// Parameter DataTypes and the return type are NOT restated here — they are read
+// off the microflow, which already declares them. Restating would let the two
+// drift, and Studio Pro derives them the same way.
+publishMicroflowBlock
+    : PUBLISH MICROFLOW qualifiedName (AS STRING_LITERAL)?
+      exposeClause?
+      SEMICOLON?
+    ;
+
 exposeClause
     : EXPOSE LPAREN (STAR | exposeMember (COMMA exposeMember)*) RPAREN
     ;
diff --git a/mdl/visitor/visitor_odata.go b/mdl/visitor/visitor_odata.go
index 7f1fc3c66..e13a88eb6 100644
--- a/mdl/visitor/visitor_odata.go
+++ b/mdl/visitor/visitor_odata.go
@@ -136,6 +136,13 @@ func (b *Builder) ExitCreateODataServiceStatement(ctx *parser.CreateODataService
 		stmt.AuthenticationTypes, stmt.AuthMicroflow = parseODataAuthTypes(authCtx)
 	}
 
+	// Parse PUBLISH MICROFLOW blocks (OData actions)
+	for _, blockCtx := range ctx.AllPublishMicroflowBlock() {
+		if mf := parsePublishMicroflowBlock(blockCtx); mf != nil {
+			stmt.Microflows = append(stmt.Microflows, mf)
+		}
+	}
+
 	// Parse PUBLISH ENTITY blocks
 	for _, blockCtx := range ctx.AllPublishEntityBlock() {
 		entity := parsePublishEntityBlock(blockCtx)
@@ -424,6 +431,52 @@ func parseODataHeaders(ctx parser.IOdataHeadersClauseContext) []ast.HeaderDef {
 	return headers
 }
 
+// parsePublishMicroflowBlock converts a PUBLISH MICROFLOW block (an OData
+// action) into an AST node. Parameter types and the return type are not read
+// here: they come off the microflow at execution time, so the two cannot drift.
+func parsePublishMicroflowBlock(ctx parser.IPublishMicroflowBlockContext) *ast.PublishedMicroflowDef {
+	block := ctx.(*parser.PublishMicroflowBlockContext)
+	if block.QualifiedName() == nil {
+		return nil
+	}
+	def := &ast.PublishedMicroflowDef{
+		Microflow: buildQualifiedName(block.QualifiedName()),
+	}
+	if sl := block.STRING_LITERAL(); sl != nil {
+		def.ExposedName = unquoteString(sl.GetText())
+	}
+	if exposeCtx := block.ExposeClause(); exposeCtx != nil {
+		expose := exposeCtx.(*parser.ExposeClauseContext)
+		if expose.STAR() != nil {
+			def.ExposeAll = true
+		}
+		for _, memberCtx := range expose.AllExposeMember() {
+			member := memberCtx.(*parser.ExposeMemberContext)
+			if member.IdentifierOrKeyword() == nil {
+				continue
+			}
+			p := &ast.PublishedParamDef{Name: member.IdentifierOrKeyword().GetText()}
+			if sl := member.STRING_LITERAL(); sl != nil {
+				p.ExposedName = unquoteString(sl.GetText())
+			}
+			if opts := member.ExposeMemberOptions(); opts != nil {
+				optsCtx := opts.(*parser.ExposeMemberOptionsContext)
+				for _, id := range optsCtx.AllIdentifierOrKeyword() {
+					if strings.EqualFold(id.GetText(), "canbeempty") ||
+						strings.EqualFold(id.GetText(), "optional") {
+						p.CanBeEmpty = true
+					}
+				}
+			}
+			def.Parameters = append(def.Parameters, p)
+		}
+	} else {
+		// No clause at all means every parameter, under its own name.
+		def.ExposeAll = true
+	}
+	return def
+}
+
 // parseExposeMembers converts an EXPOSE clause into AST member definitions.
 func parseExposeMembers(ctx parser.IExposeClauseContext) []*ast.PublishedMemberDef {
 	expose := ctx.(*parser.ExposeClauseContext)
diff --git a/mdl/visitor/visitor_odata_action_test.go b/mdl/visitor/visitor_odata_action_test.go
new file mode 100644
index 000000000..2cd0bf5df
--- /dev/null
+++ b/mdl/visitor/visitor_odata_action_test.go
@@ -0,0 +1,106 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package visitor
+
+import (
+	"testing"
+
+	"github.com/mendixlabs/mxcli/mdl/ast"
+)
+
+// odataActionService parses a service whose body is the given block.
+func odataActionService(t *testing.T, body string) *ast.CreateODataServiceStmt {
+	t.Helper()
+	prog, errs := Build(`create odata service T.Api (
+  path: 'odata/t/', version: '1.0.0', ODataVersion: OData4,
+  namespace: 'T.Api', ServiceName: 'Api'
+)
+{
+` + body + `
+};`)
+	if len(errs) > 0 {
+		t.Fatalf("parse: %v", errs)
+	}
+	svc, ok := prog.Statements[0].(*ast.CreateODataServiceStmt)
+	if !ok {
+		t.Fatalf("expected CreateODataServiceStmt, got %T", prog.Statements[0])
+	}
+	return svc
+}
+
+// mxcli-formula1 §47.1: MDL could not declare an OData action at all.
+// `createODataServiceStatement` admitted publishEntityBlock* and nothing else,
+// so every variant of `publish microflow …` was a parse error at
+// `missing ENTITY` — and the published $metadata had no ActionImport.
+func TestPublishMicroflow_Parses(t *testing.T) {
+	svc := odataActionService(t,
+		"  publish microflow T.RecordPrediction as 'RecordPrediction'\n"+
+			"    expose ( DriverId as 'driverId', Points as 'points' );")
+	if len(svc.Microflows) != 1 {
+		t.Fatalf("expected 1 published microflow, got %d", len(svc.Microflows))
+	}
+	mf := svc.Microflows[0]
+	if mf.Microflow.String() != "T.RecordPrediction" {
+		t.Errorf("Microflow = %q", mf.Microflow.String())
+	}
+	if mf.ExposedName != "RecordPrediction" {
+		t.Errorf("ExposedName = %q", mf.ExposedName)
+	}
+	if len(mf.Parameters) != 2 {
+		t.Fatalf("expected 2 parameters, got %d", len(mf.Parameters))
+	}
+	if mf.Parameters[0].Name != "DriverId" || mf.Parameters[0].ExposedName != "driverId" {
+		t.Errorf("param 0 = %+v", mf.Parameters[0])
+	}
+	if mf.Parameters[1].Name != "Points" || mf.Parameters[1].ExposedName != "points" {
+		t.Errorf("param 1 = %+v", mf.Parameters[1])
+	}
+}
+
+// No expose clause means every parameter under its own name — resolved against
+// the microflow at execution time, so nothing is restated here.
+func TestPublishMicroflow_NoExposeClauseMeansAllParameters(t *testing.T) {
+	svc := odataActionService(t, "  publish microflow T.DoThing;")
+	if len(svc.Microflows) != 1 {
+		t.Fatalf("expected 1 published microflow, got %d", len(svc.Microflows))
+	}
+	mf := svc.Microflows[0]
+	if !mf.ExposeAll {
+		t.Error("an omitted expose clause must mean all parameters")
+	}
+	if len(mf.Parameters) != 0 {
+		t.Errorf("no parameters should be selected explicitly: %+v", mf.Parameters)
+	}
+	if mf.ExposedName != "" {
+		t.Errorf("ExposedName = %q, want empty so the executor can default it to the microflow name", mf.ExposedName)
+	}
+}
+
+// A parameter can be marked optional; Mendix stores that as CanBeEmpty.
+func TestPublishMicroflow_CanBeEmptyOption(t *testing.T) {
+	svc := odataActionService(t,
+		"  publish microflow T.DoThing expose ( Note (CanBeEmpty) );")
+	mf := svc.Microflows[0]
+	if len(mf.Parameters) != 1 || !mf.Parameters[0].CanBeEmpty {
+		t.Errorf("CanBeEmpty was not captured: %+v", mf.Parameters)
+	}
+}
+
+// Actions and entity sets coexist in one service, which is the normal case:
+// the entity sets are the reads and the actions are the writes.
+func TestPublishMicroflow_AlongsideEntities(t *testing.T) {
+	svc := odataActionService(t,
+		"  publish entity T.Row as 'Rows' (\n"+
+			"    ReadMode: source, InsertMode: not_supported,\n"+
+			"    UpdateMode: not_supported, DeleteMode: not_supported\n"+
+			"  )\n"+
+			"  expose ( K as 'k' (KEY) );\n"+
+			"\n"+
+			"  publish microflow T.DoThing as 'DoThing';")
+	if len(svc.Entities) != 1 {
+		t.Errorf("expected 1 published entity, got %d", len(svc.Entities))
+	}
+	if len(svc.Microflows) != 1 {
+		t.Errorf("expected 1 published microflow, got %d", len(svc.Microflows))
+	}
+}
diff --git a/model/types.go b/model/types.go
index 6435c5127..bdfde6ad1 100644
--- a/model/types.go
+++ b/model/types.go
@@ -438,8 +438,40 @@ type PublishedODataService struct {
 	AuthMicroflow       string                 `json:"authMicroflow,omitempty"`
 	EntityTypes         []*PublishedEntityType `json:"entityTypes,omitempty"`
 	EntitySets          []*PublishedEntitySet  `json:"entitySets,omitempty"`
-	AllowedModuleRoles  []string               `json:"allowedModuleRoles,omitempty"`
-	Excluded            bool                   `json:"excluded,omitempty"`
+	// Microflows are published as OData actions (ActionImport in $metadata).
+	Microflows         []*PublishedMicroflow `json:"microflows,omitempty"`
+	AllowedModuleRoles []string              `json:"allowedModuleRoles,omitempty"`
+	Excluded           bool                  `json:"excluded,omitempty"`
+}
+
+// PublishedMicroflow is a microflow exposed as an OData action.
+type PublishedMicroflow struct {
+	BaseElement
+	Microflow   string `json:"microflow,omitempty"`   // BY_NAME ref, Module.Microflow
+	ExposedName string `json:"exposedName,omitempty"` // the ActionImport name
+	Summary     string `json:"summary,omitempty"`
+	Description string `json:"description,omitempty"`
+	// The microflow's own return type, read off the microflow rather than
+	// authored so the two cannot drift. Kind and Ref are kept apart on purpose:
+	// "Module.X" alone cannot say whether X is an entity or an enumeration —
+	// the ambiguity CLAUDE.md documents for the MDL visitor.
+	ReturnTypeKind string                         `json:"returnTypeKind,omitempty"` // Boolean|String|…|Object|List|Enumeration
+	ReturnTypeRef  string                         `json:"returnTypeRef,omitempty"`  // qualified name for Object/List/Enumeration
+	Parameters     []*PublishedMicroflowParameter `json:"parameters,omitempty"`
+}
+
+// PublishedMicroflowParameter is one argument of a published microflow.
+type PublishedMicroflowParameter struct {
+	BaseElement
+	// MicroflowParameter is a BY_NAME ref of the form Module.Microflow.Param,
+	// the same shape the published-REST writer uses.
+	MicroflowParameter string `json:"microflowParameter,omitempty"`
+	ExposedName        string `json:"exposedName,omitempty"`
+	DataTypeKind       string `json:"dataTypeKind,omitempty"`
+	DataTypeRef        string `json:"dataTypeRef,omitempty"`
+	CanBeEmpty         bool   `json:"canBeEmpty,omitempty"`
+	Summary            string `json:"summary,omitempty"`
+	Description        string `json:"description,omitempty"`
 }
 
 // GetName returns the service's name.
diff --git a/sdk/mpr/writer_odata.go b/sdk/mpr/writer_odata.go
index 6e2e4f5f1..6ee9e5e8e 100644
--- a/sdk/mpr/writer_odata.go
+++ b/sdk/mpr/writer_odata.go
@@ -249,6 +249,15 @@ func (w *Writer) serializePublishedODataService(svc *model.PublishedODataService
 	// statement (`grant access on odata service …`) and cannot be re-stated in
 	// the create script, so nothing in the script could put them back
 	// (mxcli-formula1 §26).
+	// Published microflows — OData actions. Mendix turns each into an
+	// ActionImport in $metadata; without them a parameterised resource has to be
+	// modelled as an entity set echoing its own arguments back as columns
+	// (mxcli-formula1 §47).
+	publishedMicroflows := bson.A{int32(3)}
+	for _, pm := range svc.Microflows {
+		publishedMicroflows = append(publishedMicroflows, serializePublishedMicroflow(pm))
+	}
+
 	allowedRoles := bson.A{int32(1)}
 	for _, name := range svc.AllowedModuleRoles {
 		allowedRoles = append(allowedRoles, name)
@@ -315,7 +324,7 @@ func (w *Writer) serializePublishedODataService(svc *model.PublishedODataService
 		// to resolve the second's (CE6585) — observed when comparing a
 		// Studio Pro-authored multi-entity service against ours.
 		{Key: "Enumerations", Value: bson.A{int32(3)}},
-		{Key: "Microflows", Value: bson.A{int32(3)}},
+		{Key: "Microflows", Value: publishedMicroflows},
 		{Key: "IncludeMetadataByDefault", Value: true},
 		{Key: "ReplaceIllegalChars", Value: false},
 		{Key: "SupportsGraphQL", Value: false},
@@ -565,3 +574,62 @@ func serializeChangeMode(mode string) bson.D {
 		}
 	}
 }
+
+// serializePublishedMicroflow serializes an ODataPublish$PublishedMicroflow.
+//
+// Property names come from the generated metamodel; the MicroflowParameter ref
+// is Module.Microflow.Param, the shape the published-REST writer already ships.
+// DataTypes$* elements are built by the same rules serializeMicroflowDataType
+// uses for a microflow's own return type.
+func serializePublishedMicroflow(pm *model.PublishedMicroflow) bson.D {
+	params := bson.A{int32(3)}
+	for _, p := range pm.Parameters {
+		params = append(params, serializePublishedMicroflowParameter(p))
+	}
+	return bson.D{
+		{Key: "$ID", Value: idToBsonBinary(generateUUID())},
+		{Key: "$Type", Value: "ODataPublish$PublishedMicroflow"},
+		{Key: "ExposedName", Value: pm.ExposedName},
+		{Key: "AlternativeExposedName", Value: ""},
+		{Key: "Microflow", Value: pm.Microflow},
+		{Key: "Parameters", Value: params},
+		{Key: "ReturnType", Value: serializeODataDataType(pm.ReturnTypeKind, pm.ReturnTypeRef)},
+		{Key: "Summary", Value: pm.Summary},
+		{Key: "Description", Value: pm.Description},
+	}
+}
+
+func serializePublishedMicroflowParameter(p *model.PublishedMicroflowParameter) bson.D {
+	return bson.D{
+		{Key: "$ID", Value: idToBsonBinary(generateUUID())},
+		{Key: "$Type", Value: "ODataPublish$PublishedMicroflowParameter"},
+		{Key: "ExposedName", Value: p.ExposedName},
+		{Key: "MicroflowParameter", Value: p.MicroflowParameter},
+		{Key: "DataType", Value: serializeODataDataType(p.DataTypeKind, p.DataTypeRef)},
+		{Key: "CanBeEmpty", Value: p.CanBeEmpty},
+		{Key: "Summary", Value: p.Summary},
+		{Key: "Description", Value: p.Description},
+	}
+}
+
+// serializeODataDataType builds a DataTypes$* element from a kind and, for the
+// three kinds that name something, its qualified name. Object/List carry
+// `Entity`, Enumeration carries `Enumeration` — verified against
+// serializeMicroflowDataType, which writes the same family for microflow return
+// types and is already proven in the build.
+func serializeODataDataType(kind, ref string) interface{} {
+	if kind == "" {
+		return nil
+	}
+	doc := bson.D{
+		{Key: "$ID", Value: idToBsonBinary(generateUUID())},
+		{Key: "$Type", Value: "DataTypes$" + kind + "Type"},
+	}
+	switch kind {
+	case "Object", "List":
+		return append(doc, bson.E{Key: "Entity", Value: ref})
+	case "Enumeration":
+		return append(doc, bson.E{Key: "Enumeration", Value: ref})
+	}
+	return doc
+}

From 3509f2aedfda4d51e521f191675a6dea541fcab1 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 9 Aug 2026 16:15:17 +0000
Subject: [PATCH 19/29] feat(odata): DESCRIBE round-trips a published microflow
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Completes the OData action support. DESCRIBE now emits the `publish
microflow` block as part of the service body, so its output is a full
description of the service rather than one missing its actions.

Read paths added on both engines -- sdk/mpr/parser_odata.go and
mdl/backend/modelsdk/odata_read_detail.go -- including a DataTypes$* reader
that mirrors the writers: Object/List name an Entity, Enumeration names an
Enumeration, everything else is a bare primitive.

The block guard also had to widen: it keyed off entity types and entity sets,
so a service whose only published thing is an action emitted no body at all.

Two things the controls corrected:

- **A test that calls the emitter helper directly does not prove the emitter
  is wired.** Reverting the loop in outputPublishedODataServiceMDL left every
  printPublishedMicroflowMDL test green. The DESCRIBE tests now go through the
  real entry point, and both the loop and the widened block guard have a
  revert control that fails.
- **The severity claim in the previous commit was too strong.** Replaying
  DESCRIBE output does NOT drop the action even with the emitter reverted,
  because `create or replace` preserves microflows when the statement supplies
  none (the same rule entities follow). The defect was an incomplete
  description -- you could not see the action, or use the output to recreate
  the service elsewhere -- not in-place loss.

Verified end to end on both engines: write from MDL, DESCRIBE, replay the
output, action still present, `mx check` 0 errors. The doctype example now
publishes an action (including an action-only service), so the mxbuild gate
covers it on both engines.

Docs: odata-data-sharing.md gains an OData Actions section explaining why this
matters -- Mendix validates $filter against published metadata before the read
microflow runs, so a parameterised entity set cannot take its arguments as
filters -- plus the two Mendix behaviours that bite around it (a returning
stored procedure needs a SELECT-able wrapper; the JDBC driver must be declared
and included even for PostgreSQL). Syntax help and the quick reference updated.

mxcli-formula1 §47.1
---
 .claude/skills/fix-issue.md                   |   1 +
 .claude/skills/mendix/odata-data-sharing.md   |  50 ++++++
 cmd/mxcli/syntax/features_integration.go      |   6 +
 docs/01-project/MDL_QUICK_REFERENCE.md        |   5 +
 .../doctype-tests/10-odata-examples.mdl       |  41 +++++
 mdl/backend/modelsdk/integration_read.go      |   1 +
 mdl/backend/modelsdk/odata_read_detail.go     |  61 +++++++
 mdl/executor/cmd_odata.go                     |  43 ++++-
 mdl/executor/odata_auth_microflow_test.go     | 154 ++++++++++++++++++
 sdk/mpr/parser_odata.go                       |  64 ++++++++
 10 files changed, 425 insertions(+), 1 deletion(-)

diff --git a/.claude/skills/fix-issue.md b/.claude/skills/fix-issue.md
index 7de26e997..9a8ddb511 100644
--- a/.claude/skills/fix-issue.md
+++ b/.claude/skills/fix-issue.md
@@ -440,3 +440,4 @@ extracting `OffsetExpression`/`LimitExpression`.
 | A page written by mxcli will not open in Studio Pro, and `mx check` dies during *load* with `ArgumentNullException` at `EntityRefStep.set_AssociationId` — no page error, no CE code, the whole project is down rather than one document | An association DATASOURCE wrote the association name exactly as authored. Both halves of an `EntityRefStep` are BY_NAME and Mendix resolves either one it cannot find to null, but only `DestinationEntity` was guarded (issuetracker #14) — a bare `Order_Line` reached BSON unqualified. The **explicit-destination** form is the live trap: supplying the destination satisfies that guard, so nothing stood between a bare name and the crash — and `Assoc/Module.Entity` is exactly what the guard's error tells the author to write | `mdl/executor/cmd_pages_builder_v3.go` (`buildDataSourceV3`, `case "association"`: qualify via `resolveAssociationPathIn`, then verify an author-supplied destination's association exists via `associationEndpoints`) | **Guard every BY_NAME half of a ref, not the one that was reported.** #854 reported the destination; the association beside it failed identically and was reachable through the fix's own advice. **Diff the two properties in the dump** (`grep -A1 '"Key": "(Association\|DestinationEntity)"'`) rather than reading the exception name — the loader reports whichever it touches first. **Hold the input constant across builds**: the pre-fix binary was first run with bare names and post-fix with qualified ones, which "reproduced" nothing; re-running the *same qualified* script on both is what isolated cross-module (`""`) from same-module (resolved). `mx check` exits 0 on this failure — assert on the `contains: N errors` line, never `$?`. Tests `cmd_pages_builder_assoc_datasource_test.go`, example `mdl-examples/bug-tests/854-assoc-datasource-qualified-name.mdl`. upstream #854 follow-on |
 | A navigation menu item cannot be given an icon at all — the grammar has no `ICON`, and every item mxcli writes gets `Icon: null`, so a menu authored in MDL is flat text next to one authored in Studio Pro | The syntax was never added, and the reason it stayed unadded is instructive: the metamodel names the element `Pages$IconCollectionIcon`, but Mendix **stores** it as `Forms$IconCollectionIcon` — one more instance of the "Form was the original term for Page" rename CLAUDE.md documents for `ShowFormAction`. There was no way to know that from the metamodel alone, and inventing a `$Type` for a polymorphic child is the failure mode where mxbuild builds green and Studio Pro cannot open the document | `mdl/grammar/MDLParser.g4` (`navMenuItemDef`, both alternatives), `mdl/ast/ast_navigation.go`, `mdl/visitor/visitor_navigation.go` (positional `AllQualifiedName()` — the PAGE/MICROFLOW target and the icon share one indexed list), `mdl/types/navigation.go`, `mdl/executor/cmd_navigation.go` (`convertMenuItemDef`, `printMenuMDL`), `sdk/mpr/writer_navigation.go` (`buildMenuIconBson`), `mdl/backend/modelsdk/navigation_write.go`, `sdk/mpr/parser_misc.go`, `mdl/backend/mpr/convert.go` (`convertNavMenuItem` is a field-by-field copy and drops anything new) | **The icon is a `qualifiedName`, not a string** — it is a reference into the model, so it is spelled like every other reference (ADR-0003). Atlas names are hyphenated, and `align-center` lexes as HYPHENATED_ID, so that *segment* is double-quoted: `ICON Atlas_Core.Atlas."align-center"`. The DESCRIBE emitter (`quoteQualifiedName` in `mdl/executor/qualified_name_quoting.go`) must therefore decide quoting per segment, and **must not reuse `mdlIdent`**: mdlIdent quotes anything not lexing as a bare IDENTIFIER, but a qualifiedName segment is an `identifierOrKeyword`, which accepts keywords — and `home`, `user`, `add`, `folder` are all keyword tokens, so mdlIdent would quote nearly every icon. Decide acceptance by running the real parser on the segment, never a hardcoded keyword list. The invariant worth testing is not "which names get quotes" (I guessed that wrong twice) but **"does the emitted statement re-parse"** — feed DESCRIBE output back through `visitor.Build`. **Get the reference before writing the BSON.** A Studio Pro-authored project (`ako/mxcli-ledger`) settled in one dump what no amount of metamodel reading could: the storage name, the field (`Image`, a 3-part `Module.Collection.name`), the exact key set (`$ID`/`$Type`/`Image`, nothing more), and that **all three variants coexist** — `Forms$IconCollectionIcon{Image}`, `Forms$ImageIcon{Image}` (indistinguishable by name alone; it points into an *image* collection), `Forms$GlyphIcon{Code: int}`. Only the first is written; DESCRIBE emits a `-- icon … is not reproducible` comment for the other two rather than an `icon` clause that would convert the variant on replay. To dump a v2 unit: `grep -rl 'Menus$MenuItem' mprcontents` then `bson.Unmarshal` into a `bson.D`. **`mx check` reporting 0 errors is not the proof here** — its deserializer tolerates unknown properties; the proof is diffing the written element against the Studio Pro one (done: byte-shape identical, same key order). Icon *names* are also not guessable — `Atlas.list` and `Atlas_Filled.user-check` do not exist while `list-bullets` and `user` do; verify against the collection. **Second trap, in the read path**: `codec.Decode` returns a bare `*element.Base` for an *unregistered* `$Type` but a generated struct (which only *embeds* Base) for a registered one, so `icon.(*element.Base)` silently returns nothing for exactly the variants that exist in real projects — DESCRIBE printed every icon under `legacy` and none under `modelsdk`. Assert on `interface{ Raw() bson.Raw }`, which both shapes satisfy. A unit test passing `nil` did not reach this; **running `describe` against a real Studio Pro project under both `MXCLI_ENGINE` values did**, and that engine-vs-engine diff is the cheapest way to find a read-path divergence. Note `modelsdk/codec` is on bson **v2** while `mdl/backend/modelsdk`'s write path is on v1 — a test touching both needs an alias. Tests `sdk/mpr/writer_navigation_icon_test.go`, `mdl/visitor/visitor_navigation_icon_test.go`, `mdl/executor/cmd_navigation_icon_test.go`, `mdl/backend/modelsdk/navigation_icon_test.go`; example `mdl-examples/doctype-tests/11-navigation-examples.mdl`. mxcli-formula1 #9 |
 | `authentication microflow Module.Auth` on a published OData service parses, checks clean and reports `Created OData service` — then the build fails **CE0333** "Please select a microflow to use for authentication", and `DESCRIBE` shows `authentication Microflow` with no name. Custom authentication is unreachable from MDL, which matters because it is the only way to avoid a full BCrypt hash on every OData request (60–80% of a page turn measured) | The grammar had accepted `MICROFLOW qualifiedName?` all along and both writers already serialized `AuthenticationMicroflow` from `svc.AuthMicroflow` — but nothing ever *assigned* it. `parseODataAuthTypes` recognised the `microflow` keyword and discarded the name, so the field was only ever populated by reading a model Studio Pro wrote. DESCRIBE then emitted it as a comment (`-- Auth Microflow: …`), so a custom-auth service could not round-trip either | `mdl/ast/ast_odata.go` (`AuthMicroflow`), `mdl/visitor/visitor_odata.go` (`parseODataAuthTypes` returns the name), `mdl/executor/cmd_odata.go` (assign on create AND modify; `odataAuthClause` for DESCRIBE), `mdl/executor/validate_odata_auth.go` (MDL-ODATA04) | **When a feature "silently drops" one field, check whether the plumbing already exists at both ends** — here only the middle assignment was missing, so the fix was ~10 lines across four files rather than a new write path. The grammar already parsed the name: `at.QualifiedName()` was simply never read. **DESCRIBE emitting a value as a comment is the same defect class as dropping it** (§39): the output looks complete and replays into a model the build rejects — so the round-trip test asserts the emitted clause re-parses to the same microflow, not that it contains some text. Two Mendix rules bound the feature and are easy to hit while verifying: **CE0333** if no microflow is named (now MDL-ODATA04 at check time), and **CE6600** "App security is off, but custom authentication is enabled" — so a fixture project needs `alter project security level prototype` before it can prove anything. That second one is why this is NOT in the doctype gate: those projects run with security off, so any custom-auth service there fails CE6600 regardless of correctness. Verified instead by writing the service from MDL into a real project and running `mx check` (0 errors). Tests `mdl/executor/odata_auth_microflow_test.go`. mxcli-formula1 §40 |
+| MDL cannot declare an OData action. `publish microflow …`, `publish action …` and every variant is a parse error at `missing ENTITY`, so a service's `$metadata` has an `EntityContainer` with `EntitySet` elements and no `ActionImport` — and every parameterised resource has to be modelled as an entity set that echoes its own arguments back as columns | `createODataServiceStatement` admitted `publishEntityBlock*` and nothing else. Unlike the custom-auth gap the write path was missing too: neither `sdk/mpr/writer_odata.go` nor `mdl/backend/modelsdk/odata_write.go` had a single reference to `PublishedMicroflow`, though `modelsdk/gen/odatapublish` has `NewPublishedMicroflow()`/`NewPublishedMicroflowParameter()` with every setter wired | `mdl/grammar/domains/MDLService.g4` (`publishMicroflowBlock`, reusing `exposeClause`), `mdl/ast/ast_odata.go`, `mdl/visitor/visitor_odata.go`, `model/types.go` (`PublishedMicroflow`/`…Parameter`), `mdl/executor/cmd_odata_actions.go` (resolve the microflow, derive types), `sdk/mpr/writer_odata.go` + `parser_odata.go`, `mdl/backend/modelsdk/odata_write.go` + `odata_read_detail.go` + `integration_read.go`, `mdl/executor/cmd_odata.go` (`printPublishedMicroflowMDL`) | **With no Studio Pro reference available, derive every shape from something already proven rather than stopping.** Property names/kinds came from the generated metamodel; the `Module.Microflow.Param` form of the `MicroflowParameter` by-name ref from `published_rest_write.go`, which already ships it; the `DataTypes$ObjectType`/`ListType` `Entity` key and `EnumerationType` `Enumeration` key from `serializeMicroflowDataType`. **Do not restate what the model already declares** — parameter types and the return type are read off the microflow, so they cannot drift. Store a data type as **kind + ref, never one string**: `Module.X` cannot say whether X is an entity or an enumeration. **`mx check` reporting 0 errors is near-worthless for a NEW element type** (mxbuild ignores unknown properties); the test that settles it is to delete the referent — dropping the microflow makes mxbuild answer `CE1613 … at Published microflow parameter DriverId from published microflow RecordPrediction`, naming the elements back in its own vocabulary. **A test that calls the emitter helper directly does not prove the emitter is wired**: reverting the loop in `outputPublishedODataServiceMDL` left every `printPublishedMicroflowMDL` test green, so the DESCRIBE test goes through the real entry point. Also note the replay control does NOT reproduce a missing emitter, because `create or replace` preserves microflows when the statement supplies none — the defect is an incomplete description, not in-place loss. Tests `mdl/visitor/visitor_odata_action_test.go`, `mdl/executor/odata_auth_microflow_test.go`; example `mdl-examples/doctype-tests/10-odata-examples.mdl`. mxcli-formula1 §47.1 |
diff --git a/.claude/skills/mendix/odata-data-sharing.md b/.claude/skills/mendix/odata-data-sharing.md
index 37e6f58a9..0ea149d79 100644
--- a/.claude/skills/mendix/odata-data-sharing.md
+++ b/.claude/skills/mendix/odata-data-sharing.md
@@ -602,6 +602,56 @@ non-filterable"` before the microflow runs. So the microflow only ever sees name
 that exist in the published metadata. That is defence in depth, not a substitute for a
 whitelist — it constrains the *name*, not what you do with it.
 
+## OData Actions: Publishing a Microflow
+
+An entity set is a *read* surface. To let a client **invoke** something —
+`POST /odata/x/RecordNote` with arguments in the body — publish a microflow.
+Mendix exposes it in `$metadata` as an `ActionImport`.
+
+```sql
+create odata service ProductApi.Actions ( ... )
+authentication basic
+{
+  publish microflow ProductApi.RecordNote as 'RecordNote'
+    expose ( Note as 'note', Amount as 'amount' (CanBeEmpty) );
+};
+```
+
+**Parameter data types and the return type are not written in MDL.** They are
+read off the microflow, which already declares them — the same thing Studio Pro
+does, and the only arrangement in which the two cannot drift. Omitting the
+`expose` clause publishes every parameter under its own name.
+
+### Why this matters more than it looks
+
+Mendix validates `$filter` against the published metadata **before** the read
+microflow runs. So a parameterised *entity set* cannot take its arguments as
+filters: `?$filter=driverId eq 'x'` against a resource whose entity has no
+`driverId` attribute is answered
+
+```
+400  Could not map 'driverId' to attribute or association.
+```
+
+and the microflow never sees it. The workaround is to carry every parameter as
+an attribute and echo it back on each row — `SELECT f.*, {driverId} AS driver_id
+…`. An action takes them as parameters and needs none of that.
+
+### Two things Mendix will not do for you
+
+- **A returning stored procedure cannot be called directly.** The External
+  Database Connector dispatches a `CALL` as an update, and PgJDBC refuses
+  because a `CALL` with INOUT parameters answers with a row: *"A result was
+  returned when none was expected"*. There is no `execute database statement`
+  activity — only `execute database query`, which wants a `SELECT`. Wrap the
+  procedure in a one-line function that `CALL`s it and returns its row.
+- **The JDBC driver must be declared and shipped even for PostgreSQL**, the
+  database Mendix itself runs on. Without a module jar dependency the build
+  fails CE5278; declared but `included = false`, the build is green and the
+  first request dies with *"No JDBC driver found in app for URL"* — the
+  Connector resolves drivers from the app's classpath, not the runtime's. Use
+  `included = true` and `mxcli sync-java-deps`.
+
 ## Authentication Methods, and the Cost of Basic Auth
 
 A published service names one or more methods in the `authentication` clause:
diff --git a/cmd/mxcli/syntax/features_integration.go b/cmd/mxcli/syntax/features_integration.go
index c3e35c435..54832775a 100644
--- a/cmd/mxcli/syntax/features_integration.go
+++ b/cmd/mxcli/syntax/features_integration.go
@@ -106,6 +106,12 @@ func init() {
 			"    OtherAttr (Filterable),\n" +
 			"    AssocName as 'NavProp'   -- bare association name -> PublishedAssociationEnd\n" +
 			"  );\n" +
+			"\n" +
+			"  -- An OData action (an ActionImport in $metadata). Parameter types and\n" +
+			"  -- the return type come off the microflow, which already declares them;\n" +
+			"  -- omitting the expose clause publishes every parameter by its own name.\n" +
+			"  publish microflow Module.DoThing as 'DoThing'\n" +
+			"    expose ( Note as 'note', Amount as 'amount' (CanBeEmpty) );\n" +
 			"};\n" +
 			"\n" +
 			"GRANT ACCESS ON ODATA SERVICE Module.Name TO Module.Role;\n" +
diff --git a/docs/01-project/MDL_QUICK_REFERENCE.md b/docs/01-project/MDL_QUICK_REFERENCE.md
index fd26361f9..d434252df 100644
--- a/docs/01-project/MDL_QUICK_REFERENCE.md
+++ b/docs/01-project/MDL_QUICK_REFERENCE.md
@@ -214,6 +214,11 @@ create odata service MyModule.CustomerAPI (
   namespace: 'MyModule.Customers'
 )
 authentication basic, session
+-- Inside the { } body, alongside `publish entity`, a microflow can be published
+-- as an OData action (an ActionImport in $metadata):
+--   publish microflow Module.DoThing as 'DoThing'
+--     expose ( Note as 'note', Amount as 'amount' (CanBeEmpty) );
+-- Parameter types and the return type are read off the microflow, not restated.
 -- or: authentication microflow Module.Authenticate
 --   Custom authentication. The microflow takes a List of System.HttpHeader and
 --   returns a System.User (empty denies). It removes the per-request password
diff --git a/mdl-examples/doctype-tests/10-odata-examples.mdl b/mdl-examples/doctype-tests/10-odata-examples.mdl
index 4a583e82a..36029d76b 100644
--- a/mdl-examples/doctype-tests/10-odata-examples.mdl
+++ b/mdl-examples/doctype-tests/10-odata-examples.mdl
@@ -434,6 +434,47 @@ grant access on odata service OdTest.CustomerAPI to OdTest.Admin, OdTest.user;
 revoke access on odata service OdTest.CustomerAPI from OdTest.user;
 /
 
+/**
+ * Level 8.6b: OData action — publish a microflow
+ *
+ * Mendix exposes a published microflow in $metadata as an ActionImport, so a
+ * client can POST arguments to it. Without one, a parameterised resource has to
+ * be modelled as an entity set that carries its own arguments as attributes and
+ * echoes them back on every row: Mendix validates $filter against the published
+ * metadata before the read microflow runs, so an argument that is not an
+ * attribute is answered 400 and never reaches the microflow.
+ *
+ * Parameter data types and the return type are NOT written here. They are read
+ * off the microflow, which already declares them — the same thing Studio Pro
+ * does, and the only arrangement in which the two cannot drift.
+ */
+CREATE MICROFLOW OdTest.RecordNote ($Note: string, $Amount: integer)
+  RETURNS Boolean AS $Ok
+BEGIN
+  declare $Ok Boolean = true;
+  RETURN $Ok;
+END;
+/
+
+create or modify odata service OdTest.ActionApi (
+  path: 'odata/actions/',
+  version: '1.0.0',
+  ODataVersion: OData4,
+  namespace: 'OdTest.Actions',
+  ServiceName: 'Action Service'
+)
+authentication basic
+{
+  -- An action alongside no entity sets at all is legitimate.
+  publish microflow OdTest.RecordNote as 'RecordNote'
+    expose ( Note as 'note', Amount as 'amount' (CanBeEmpty) );
+};
+/
+
+-- DESCRIBE round-trips the block, so this output is re-executable.
+describe odata service OdTest.ActionApi;
+/
+
 /**
  * Level 8.7c: A modify must NOT revoke the grants made above.
  *
diff --git a/mdl/backend/modelsdk/integration_read.go b/mdl/backend/modelsdk/integration_read.go
index 7f05d1e13..49bdcd3b7 100644
--- a/mdl/backend/modelsdk/integration_read.go
+++ b/mdl/backend/modelsdk/integration_read.go
@@ -124,6 +124,7 @@ func (b *Backend) ListPublishedODataServices() ([]*model.PublishedODataService,
 		// Pro on load (NullReferenceException).
 		if raw, rerr := b.GetRawUnit(svc.ID); rerr == nil {
 			svc.EntityTypes, svc.EntitySets = publishedEntityTreeFromRaw(raw)
+			svc.Microflows = publishedMicroflowsFromRaw(raw)
 		}
 		out = append(out, svc)
 	}
diff --git a/mdl/backend/modelsdk/odata_read_detail.go b/mdl/backend/modelsdk/odata_read_detail.go
index 95a5c4894..2136ede82 100644
--- a/mdl/backend/modelsdk/odata_read_detail.go
+++ b/mdl/backend/modelsdk/odata_read_detail.go
@@ -3,6 +3,8 @@
 package modelsdkbackend
 
 import (
+	"strings"
+
 	"github.com/mendixlabs/mxcli/model"
 )
 
@@ -70,6 +72,65 @@ func publishedEntityTreeFromRaw(raw map[string]any) ([]*model.PublishedEntityTyp
 	return ets, sets
 }
 
+// publishedMicroflowsFromRaw parses the Microflows part list — the service's
+// OData actions. Without it DESCRIBE would emit a service missing its actions,
+// and replaying that output would silently drop them.
+func publishedMicroflowsFromRaw(raw map[string]any) []*model.PublishedMicroflow {
+	var out []*model.PublishedMicroflow
+	for _, e := range jsAsSlice(raw["Microflows"]) {
+		m := jsToMap(e)
+		if m == nil {
+			continue
+		}
+		pm := &model.PublishedMicroflow{
+			Microflow:   jsExtractString(m["Microflow"]),
+			ExposedName: jsExtractString(m["ExposedName"]),
+			Summary:     jsExtractString(m["Summary"]),
+			Description: jsExtractString(m["Description"]),
+		}
+		pm.TypeName = "ODataPublish$PublishedMicroflow"
+		pm.ReturnTypeKind, pm.ReturnTypeRef = odataDataTypeFromRaw(m["ReturnType"])
+		for _, p := range jsAsSlice(m["Parameters"]) {
+			pmap := jsToMap(p)
+			if pmap == nil {
+				continue
+			}
+			mp := &model.PublishedMicroflowParameter{
+				MicroflowParameter: jsExtractString(pmap["MicroflowParameter"]),
+				ExposedName:        jsExtractString(pmap["ExposedName"]),
+				CanBeEmpty:         jsExtractBool(pmap["CanBeEmpty"]),
+				Summary:            jsExtractString(pmap["Summary"]),
+				Description:        jsExtractString(pmap["Description"]),
+			}
+			mp.TypeName = "ODataPublish$PublishedMicroflowParameter"
+			mp.DataTypeKind, mp.DataTypeRef = odataDataTypeFromRaw(pmap["DataType"])
+			pm.Parameters = append(pm.Parameters, mp)
+		}
+		out = append(out, pm)
+	}
+	return out
+}
+
+// odataDataTypeFromRaw reads a DataTypes$* element into the kind + ref pair the
+// semantic model carries. Mirrors sdk/mpr.parseODataDataType.
+func odataDataTypeFromRaw(v any) (kind, ref string) {
+	m := jsToMap(v)
+	if m == nil {
+		return "", ""
+	}
+	t := jsExtractString(m["$Type"])
+	t = strings.TrimSuffix(strings.TrimPrefix(t, "DataTypes$"), "Type")
+	switch t {
+	case "":
+		return "", ""
+	case "Object", "List":
+		return t, jsExtractString(m["Entity"])
+	case "Enumeration":
+		return t, jsExtractString(m["Enumeration"])
+	}
+	return t, ""
+}
+
 func publishedEntityTypeFromRaw(raw map[string]any) *model.PublishedEntityType {
 	et := &model.PublishedEntityType{
 		BaseElement: model.BaseElement{ID: model.ID(jsExtractBsonID(raw["$ID"])), TypeName: jsExtractString(raw["$Type"])},
diff --git a/mdl/executor/cmd_odata.go b/mdl/executor/cmd_odata.go
index d66215361..c30f05068 100644
--- a/mdl/executor/cmd_odata.go
+++ b/mdl/executor/cmd_odata.go
@@ -360,7 +360,7 @@ func outputPublishedODataServiceMDL(ctx *ExecContext, svc *model.PublishedODataS
 	}
 
 	// Published entities block
-	if len(svc.EntityTypes) > 0 || len(svc.EntitySets) > 0 {
+	if len(svc.EntityTypes) > 0 || len(svc.EntitySets) > 0 || len(svc.Microflows) > 0 {
 		fmt.Fprintln(ctx.Output, "{")
 
 		// Build entity set lookup by exposed name and entity type name for merging
@@ -478,6 +478,13 @@ func outputPublishedODataServiceMDL(ctx *ExecContext, svc *model.PublishedODataS
 			fmt.Fprintln(ctx.Output)
 		}
 
+		// OData actions. Emitted as part of the block, not as a comment beside
+		// it: a comment reads as complete and replays into a service without the
+		// action (mxcli-formula1 §47.1).
+		for _, pm := range svc.Microflows {
+			printPublishedMicroflowMDL(ctx.Output, pm)
+		}
+
 		fmt.Fprintln(ctx.Output, "}")
 	}
 
@@ -2199,3 +2206,37 @@ func odataAuthClause(svc *model.PublishedODataService) string {
 	}
 	return strings.Join(parts, ", ")
 }
+
+// printPublishedMicroflowMDL writes a `publish microflow` block. Parameter data
+// types and the return type are deliberately absent: they are read off the
+// microflow at execution time, so restating them here would let the emitted
+// script and the microflow drift apart.
+func printPublishedMicroflowMDL(w io.Writer, pm *model.PublishedMicroflow) {
+	head := "  publish microflow " + pm.Microflow
+	if pm.ExposedName != "" {
+		head += fmt.Sprintf(" as '%s'", pm.ExposedName)
+	}
+	if len(pm.Parameters) == 0 {
+		fmt.Fprintln(w, head+";")
+		return
+	}
+	fmt.Fprintln(w, head)
+	parts := make([]string, 0, len(pm.Parameters))
+	for _, p := range pm.Parameters {
+		// The stored ref is Module.Microflow.Param; MDL names the parameter
+		// alone, so take the last segment.
+		name := p.MicroflowParameter
+		if i := strings.LastIndex(name, "."); i >= 0 {
+			name = name[i+1:]
+		}
+		part := name
+		if p.ExposedName != "" && p.ExposedName != name {
+			part += fmt.Sprintf(" as '%s'", p.ExposedName)
+		}
+		if p.CanBeEmpty {
+			part += " (CanBeEmpty)"
+		}
+		parts = append(parts, part)
+	}
+	fmt.Fprintf(w, "    expose ( %s );\n", strings.Join(parts, ", "))
+}
diff --git a/mdl/executor/odata_auth_microflow_test.go b/mdl/executor/odata_auth_microflow_test.go
index 7b8d829c3..e0c2ca315 100644
--- a/mdl/executor/odata_auth_microflow_test.go
+++ b/mdl/executor/odata_auth_microflow_test.go
@@ -3,6 +3,7 @@
 package executor
 
 import (
+	"bytes"
 	"strings"
 	"testing"
 
@@ -157,3 +158,156 @@ func TestDescribeODataService_AuthClauseReParses(t *testing.T) {
 		t.Errorf("round trip changed the methods: %v", svc.AuthenticationTypes)
 	}
 }
+
+// describeAction renders one published microflow through the DESCRIBE emitter.
+func describeAction(pm *model.PublishedMicroflow) string {
+	var b bytes.Buffer
+	printPublishedMicroflowMDL(&b, pm)
+	return b.String()
+}
+
+// mxcli-formula1 §47.1: DESCRIBE emits re-executable MDL, so an OData action it
+// read must come back out. Leaving it off — or emitting it as a comment — is the
+// same defect class as §39 and §40: output that looks complete and replays into
+// a lesser model.
+func TestDescribeODataService_EmitsAnAction(t *testing.T) {
+	got := describeAction(&model.PublishedMicroflow{
+		Microflow: "T.RecordPrediction", ExposedName: "RecordPrediction",
+		Parameters: []*model.PublishedMicroflowParameter{
+			{MicroflowParameter: "T.RecordPrediction.DriverId", ExposedName: "driverId"},
+			{MicroflowParameter: "T.RecordPrediction.Points", ExposedName: "points"},
+		},
+	})
+	want := "  publish microflow T.RecordPrediction as 'RecordPrediction'\n" +
+		"    expose ( DriverId as 'driverId', Points as 'points' );\n"
+	if got != want {
+		t.Errorf("got %q, want %q", got, want)
+	}
+}
+
+// A parameter whose exposed name equals its own name needs no alias — emitting
+// one would be noise that the round trip has to carry forever.
+func TestDescribeODataService_ActionOmitsARedundantAlias(t *testing.T) {
+	got := describeAction(&model.PublishedMicroflow{
+		Microflow: "T.DoThing", ExposedName: "DoThing",
+		Parameters: []*model.PublishedMicroflowParameter{
+			{MicroflowParameter: "T.DoThing.Note", ExposedName: "Note", CanBeEmpty: true},
+		},
+	})
+	want := "  publish microflow T.DoThing as 'DoThing'\n    expose ( Note (CanBeEmpty) );\n"
+	if got != want {
+		t.Errorf("got %q, want %q", got, want)
+	}
+}
+
+// An action with no parameters is a one-liner.
+func TestDescribeODataService_ActionWithNoParameters(t *testing.T) {
+	got := describeAction(&model.PublishedMicroflow{
+		Microflow: "T.Ping", ExposedName: "Ping",
+	})
+	if got != "  publish microflow T.Ping as 'Ping';\n" {
+		t.Errorf("got %q", got)
+	}
+}
+
+// The invariant that matters: what DESCRIBE prints must parse back to the same
+// action. Asserted against the parser rather than against a hand-written
+// expectation about the text.
+func TestDescribeODataService_ActionReParses(t *testing.T) {
+	for _, pm := range []*model.PublishedMicroflow{
+		{Microflow: "T.RecordPrediction", ExposedName: "RecordPrediction",
+			Parameters: []*model.PublishedMicroflowParameter{
+				{MicroflowParameter: "T.RecordPrediction.DriverId", ExposedName: "driverId"},
+				{MicroflowParameter: "T.RecordPrediction.Points", ExposedName: "points"},
+			}},
+		{Microflow: "T.DoThing", ExposedName: "DoThing",
+			Parameters: []*model.PublishedMicroflowParameter{
+				{MicroflowParameter: "T.DoThing.Note", ExposedName: "Note", CanBeEmpty: true},
+			}},
+		{Microflow: "T.Ping", ExposedName: "Ping"},
+	} {
+		t.Run(pm.Microflow, func(t *testing.T) {
+			script := `create odata service T.Api (
+  path: 'odata/t/', version: '1.0.0', ODataVersion: OData4,
+  namespace: 'T.Api', ServiceName: 'Api'
+)
+{
+` + describeAction(pm) + `};`
+			prog, errs := visitor.Build(script)
+			if len(errs) > 0 {
+				t.Fatalf("DESCRIBE emitted output its own parser rejects:\n%s\nerrors: %v", script, errs)
+			}
+			svc := prog.Statements[0].(*ast.CreateODataServiceStmt)
+			if len(svc.Microflows) != 1 {
+				t.Fatalf("re-parsed to %d actions", len(svc.Microflows))
+			}
+			got := svc.Microflows[0]
+			if got.Microflow.String() != pm.Microflow || got.ExposedName != pm.ExposedName {
+				t.Errorf("round trip changed the action: %+v", got)
+			}
+			if len(got.Parameters) != len(pm.Parameters) {
+				t.Fatalf("round trip changed the parameter count: %d -> %d",
+					len(pm.Parameters), len(got.Parameters))
+			}
+			for i, want := range pm.Parameters {
+				gotName := got.Parameters[i].ExposedName
+				if gotName == "" {
+					gotName = got.Parameters[i].Name
+				}
+				if gotName != want.ExposedName {
+					t.Errorf("param %d exposed name %q -> %q", i, want.ExposedName, gotName)
+				}
+				if got.Parameters[i].CanBeEmpty != want.CanBeEmpty {
+					t.Errorf("param %d CanBeEmpty %v -> %v", i, want.CanBeEmpty, got.Parameters[i].CanBeEmpty)
+				}
+			}
+		})
+	}
+}
+
+// The tests above call printPublishedMicroflowMDL directly, which does not
+// prove the emitter is WIRED into DESCRIBE. It was not caught by them: reverting
+// the loop in outputPublishedODataServiceMDL left every one of them green. This
+// goes through the real entry point.
+func TestOutputPublishedODataServiceMDL_IncludesActions(t *testing.T) {
+	var buf bytes.Buffer
+	ctx := &ExecContext{Output: &buf}
+	svc := &model.PublishedODataService{
+		Name: "Api", Path: "odata/t/", Version: "1.0.0",
+		ODataVersion: "OData4", Namespace: "T.Api", ServiceName: "Api",
+		Microflows: []*model.PublishedMicroflow{{
+			Microflow: "T.RecordPrediction", ExposedName: "RecordPrediction",
+			Parameters: []*model.PublishedMicroflowParameter{
+				{MicroflowParameter: "T.RecordPrediction.DriverId", ExposedName: "driverId"},
+			},
+		}},
+	}
+	if err := outputPublishedODataServiceMDL(ctx, svc, "T", ""); err != nil {
+		t.Fatalf("output: %v", err)
+	}
+	got := buf.String()
+	if !strings.Contains(got, "publish microflow T.RecordPrediction as 'RecordPrediction'") {
+		t.Errorf("DESCRIBE dropped the action:\n%s", got)
+	}
+	if !strings.Contains(got, "expose ( DriverId as 'driverId' );") {
+		t.Errorf("DESCRIBE dropped the action's parameters:\n%s", got)
+	}
+}
+
+// A service whose ONLY published thing is an action must still emit a body —
+// the block guard used to key off entity types and entity sets alone.
+func TestOutputPublishedODataServiceMDL_ActionOnlyServiceStillEmitsABody(t *testing.T) {
+	var buf bytes.Buffer
+	ctx := &ExecContext{Output: &buf}
+	svc := &model.PublishedODataService{
+		Name: "Api", Path: "odata/t/", Version: "1.0.0",
+		ODataVersion: "OData4", Namespace: "T.Api", ServiceName: "Api",
+		Microflows: []*model.PublishedMicroflow{{Microflow: "T.Ping", ExposedName: "Ping"}},
+	}
+	if err := outputPublishedODataServiceMDL(ctx, svc, "T", ""); err != nil {
+		t.Fatalf("output: %v", err)
+	}
+	if got := buf.String(); !strings.Contains(got, "publish microflow T.Ping") {
+		t.Errorf("an action-only service emitted no body:\n%s", got)
+	}
+}
diff --git a/sdk/mpr/parser_odata.go b/sdk/mpr/parser_odata.go
index 706f15871..0697007fd 100644
--- a/sdk/mpr/parser_odata.go
+++ b/sdk/mpr/parser_odata.go
@@ -4,6 +4,7 @@ package mpr
 
 import (
 	"fmt"
+	"strings"
 
 	"github.com/mendixlabs/mxcli/model"
 
@@ -176,9 +177,72 @@ func (r *Reader) parsePublishedODataService(unitID, containerID string, contents
 		}
 	}
 
+	// Parse published microflows (OData actions)
+	for _, pm := range extractBsonArray(raw["Microflows"]) {
+		if pmMap, ok := pm.(map[string]any); ok {
+			svc.Microflows = append(svc.Microflows, parsePublishedMicroflow(pmMap))
+		}
+	}
+
 	return svc, nil
 }
 
+// parsePublishedMicroflow parses an ODataPublish$PublishedMicroflow — an OData
+// action — from a BSON map.
+func parsePublishedMicroflow(raw map[string]any) *model.PublishedMicroflow {
+	pm := &model.PublishedMicroflow{
+		Microflow:   extractString(raw["Microflow"]),
+		ExposedName: extractString(raw["ExposedName"]),
+		Summary:     extractString(raw["Summary"]),
+		Description: extractString(raw["Description"]),
+	}
+	pm.ID = model.ID(extractID(raw["$ID"]))
+	pm.TypeName = "ODataPublish$PublishedMicroflow"
+	pm.ReturnTypeKind, pm.ReturnTypeRef = parseODataDataType(raw["ReturnType"])
+
+	for _, p := range extractBsonArray(raw["Parameters"]) {
+		pMap, ok := p.(map[string]any)
+		if !ok {
+			continue
+		}
+		mp := &model.PublishedMicroflowParameter{
+			MicroflowParameter: extractString(pMap["MicroflowParameter"]),
+			ExposedName:        extractString(pMap["ExposedName"]),
+			CanBeEmpty:         extractBool(pMap["CanBeEmpty"], false),
+			Summary:            extractString(pMap["Summary"]),
+			Description:        extractString(pMap["Description"]),
+		}
+		mp.ID = model.ID(extractID(pMap["$ID"]))
+		mp.TypeName = "ODataPublish$PublishedMicroflowParameter"
+		mp.DataTypeKind, mp.DataTypeRef = parseODataDataType(pMap["DataType"])
+		pm.Parameters = append(pm.Parameters, mp)
+	}
+	return pm
+}
+
+// parseODataDataType reads a DataTypes$* element back into the kind + ref pair
+// the semantic model carries. Object/List name an Entity, Enumeration names an
+// Enumeration; everything else is a bare primitive whose kind is the $Type with
+// the "DataTypes$" prefix and "Type" suffix removed.
+func parseODataDataType(v any) (kind, ref string) {
+	m, ok := v.(map[string]any)
+	if !ok {
+		return "", ""
+	}
+	t := extractString(m["$Type"])
+	t = strings.TrimPrefix(t, "DataTypes$")
+	t = strings.TrimSuffix(t, "Type")
+	switch t {
+	case "":
+		return "", ""
+	case "Object", "List":
+		return t, extractString(m["Entity"])
+	case "Enumeration":
+		return t, extractString(m["Enumeration"])
+	}
+	return t, ""
+}
+
 // parsePublishedEntityType parses a published entity type from a BSON map.
 func parsePublishedEntityType(raw map[string]any) *model.PublishedEntityType {
 	et := &model.PublishedEntityType{}

From 27ea1dacdf0fae525457b08e1b4e88d15b58f527 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 9 Aug 2026 17:56:47 +0000
Subject: [PATCH 20/29] fix(odata): generated external entities follow the
 contract's $top/$skip
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A service that declares `TopSupported: No` could not be consumed. The
contract carried it correctly, but the generator stamped
`SkipSupported = true; TopSupported = true` on every external entity, so
the consuming app failed to build:

    CE6630 'Seasons' is marked supports $top=False in the OData service,
           but True in the app.

Two layers were involved. `applyCapabilityAnnotations` opened with
`if ann.Record == nil { continue }`, but TopSupported/SkipSupported are
standalone boolean terms carrying `Bool` on the annotation element, not
the record shape InsertRestrictions uses — so the parser discarded them
and EdmEntitySet had nowhere to put them. `applyExternalEntityFields`
then hardcoded both true, beside a Countable that was derived and under
a comment explaining the very CE6630 mechanism the hardcode triggered.

Absent stays true: OData's default is supported, so defaulting to false
would invert CE6630 for every unannotated service.

This is the prerequisite for MDL-ODATA03's advice being followable — the
rule tells authors to declare `TopSupported: No` on a read-microflow
resource, which until now broke their consumers.

mxcli-formula1 §42
---
 .claude/skills/fix-issue.md                   |  1 +
 mdl/executor/cmd_contract.go                  | 11 ++-
 .../cmd_contract_capabilities_test.go         | 78 +++++++++++++++
 mdl/executor/cmd_navigation.go                |  1 -
 mdl/types/edmx.go                             | 25 ++++-
 mdl/types/edmx_test.go                        | 97 +++++++++++++++++++
 6 files changed, 209 insertions(+), 4 deletions(-)
 create mode 100644 mdl/executor/cmd_contract_capabilities_test.go

diff --git a/.claude/skills/fix-issue.md b/.claude/skills/fix-issue.md
index 9a8ddb511..ace58e578 100644
--- a/.claude/skills/fix-issue.md
+++ b/.claude/skills/fix-issue.md
@@ -441,3 +441,4 @@ extracting `OffsetExpression`/`LimitExpression`.
 | A navigation menu item cannot be given an icon at all — the grammar has no `ICON`, and every item mxcli writes gets `Icon: null`, so a menu authored in MDL is flat text next to one authored in Studio Pro | The syntax was never added, and the reason it stayed unadded is instructive: the metamodel names the element `Pages$IconCollectionIcon`, but Mendix **stores** it as `Forms$IconCollectionIcon` — one more instance of the "Form was the original term for Page" rename CLAUDE.md documents for `ShowFormAction`. There was no way to know that from the metamodel alone, and inventing a `$Type` for a polymorphic child is the failure mode where mxbuild builds green and Studio Pro cannot open the document | `mdl/grammar/MDLParser.g4` (`navMenuItemDef`, both alternatives), `mdl/ast/ast_navigation.go`, `mdl/visitor/visitor_navigation.go` (positional `AllQualifiedName()` — the PAGE/MICROFLOW target and the icon share one indexed list), `mdl/types/navigation.go`, `mdl/executor/cmd_navigation.go` (`convertMenuItemDef`, `printMenuMDL`), `sdk/mpr/writer_navigation.go` (`buildMenuIconBson`), `mdl/backend/modelsdk/navigation_write.go`, `sdk/mpr/parser_misc.go`, `mdl/backend/mpr/convert.go` (`convertNavMenuItem` is a field-by-field copy and drops anything new) | **The icon is a `qualifiedName`, not a string** — it is a reference into the model, so it is spelled like every other reference (ADR-0003). Atlas names are hyphenated, and `align-center` lexes as HYPHENATED_ID, so that *segment* is double-quoted: `ICON Atlas_Core.Atlas."align-center"`. The DESCRIBE emitter (`quoteQualifiedName` in `mdl/executor/qualified_name_quoting.go`) must therefore decide quoting per segment, and **must not reuse `mdlIdent`**: mdlIdent quotes anything not lexing as a bare IDENTIFIER, but a qualifiedName segment is an `identifierOrKeyword`, which accepts keywords — and `home`, `user`, `add`, `folder` are all keyword tokens, so mdlIdent would quote nearly every icon. Decide acceptance by running the real parser on the segment, never a hardcoded keyword list. The invariant worth testing is not "which names get quotes" (I guessed that wrong twice) but **"does the emitted statement re-parse"** — feed DESCRIBE output back through `visitor.Build`. **Get the reference before writing the BSON.** A Studio Pro-authored project (`ako/mxcli-ledger`) settled in one dump what no amount of metamodel reading could: the storage name, the field (`Image`, a 3-part `Module.Collection.name`), the exact key set (`$ID`/`$Type`/`Image`, nothing more), and that **all three variants coexist** — `Forms$IconCollectionIcon{Image}`, `Forms$ImageIcon{Image}` (indistinguishable by name alone; it points into an *image* collection), `Forms$GlyphIcon{Code: int}`. Only the first is written; DESCRIBE emits a `-- icon … is not reproducible` comment for the other two rather than an `icon` clause that would convert the variant on replay. To dump a v2 unit: `grep -rl 'Menus$MenuItem' mprcontents` then `bson.Unmarshal` into a `bson.D`. **`mx check` reporting 0 errors is not the proof here** — its deserializer tolerates unknown properties; the proof is diffing the written element against the Studio Pro one (done: byte-shape identical, same key order). Icon *names* are also not guessable — `Atlas.list` and `Atlas_Filled.user-check` do not exist while `list-bullets` and `user` do; verify against the collection. **Second trap, in the read path**: `codec.Decode` returns a bare `*element.Base` for an *unregistered* `$Type` but a generated struct (which only *embeds* Base) for a registered one, so `icon.(*element.Base)` silently returns nothing for exactly the variants that exist in real projects — DESCRIBE printed every icon under `legacy` and none under `modelsdk`. Assert on `interface{ Raw() bson.Raw }`, which both shapes satisfy. A unit test passing `nil` did not reach this; **running `describe` against a real Studio Pro project under both `MXCLI_ENGINE` values did**, and that engine-vs-engine diff is the cheapest way to find a read-path divergence. Note `modelsdk/codec` is on bson **v2** while `mdl/backend/modelsdk`'s write path is on v1 — a test touching both needs an alias. Tests `sdk/mpr/writer_navigation_icon_test.go`, `mdl/visitor/visitor_navigation_icon_test.go`, `mdl/executor/cmd_navigation_icon_test.go`, `mdl/backend/modelsdk/navigation_icon_test.go`; example `mdl-examples/doctype-tests/11-navigation-examples.mdl`. mxcli-formula1 #9 |
 | `authentication microflow Module.Auth` on a published OData service parses, checks clean and reports `Created OData service` — then the build fails **CE0333** "Please select a microflow to use for authentication", and `DESCRIBE` shows `authentication Microflow` with no name. Custom authentication is unreachable from MDL, which matters because it is the only way to avoid a full BCrypt hash on every OData request (60–80% of a page turn measured) | The grammar had accepted `MICROFLOW qualifiedName?` all along and both writers already serialized `AuthenticationMicroflow` from `svc.AuthMicroflow` — but nothing ever *assigned* it. `parseODataAuthTypes` recognised the `microflow` keyword and discarded the name, so the field was only ever populated by reading a model Studio Pro wrote. DESCRIBE then emitted it as a comment (`-- Auth Microflow: …`), so a custom-auth service could not round-trip either | `mdl/ast/ast_odata.go` (`AuthMicroflow`), `mdl/visitor/visitor_odata.go` (`parseODataAuthTypes` returns the name), `mdl/executor/cmd_odata.go` (assign on create AND modify; `odataAuthClause` for DESCRIBE), `mdl/executor/validate_odata_auth.go` (MDL-ODATA04) | **When a feature "silently drops" one field, check whether the plumbing already exists at both ends** — here only the middle assignment was missing, so the fix was ~10 lines across four files rather than a new write path. The grammar already parsed the name: `at.QualifiedName()` was simply never read. **DESCRIBE emitting a value as a comment is the same defect class as dropping it** (§39): the output looks complete and replays into a model the build rejects — so the round-trip test asserts the emitted clause re-parses to the same microflow, not that it contains some text. Two Mendix rules bound the feature and are easy to hit while verifying: **CE0333** if no microflow is named (now MDL-ODATA04 at check time), and **CE6600** "App security is off, but custom authentication is enabled" — so a fixture project needs `alter project security level prototype` before it can prove anything. That second one is why this is NOT in the doctype gate: those projects run with security off, so any custom-auth service there fails CE6600 regardless of correctness. Verified instead by writing the service from MDL into a real project and running `mx check` (0 errors). Tests `mdl/executor/odata_auth_microflow_test.go`. mxcli-formula1 §40 |
 | MDL cannot declare an OData action. `publish microflow …`, `publish action …` and every variant is a parse error at `missing ENTITY`, so a service's `$metadata` has an `EntityContainer` with `EntitySet` elements and no `ActionImport` — and every parameterised resource has to be modelled as an entity set that echoes its own arguments back as columns | `createODataServiceStatement` admitted `publishEntityBlock*` and nothing else. Unlike the custom-auth gap the write path was missing too: neither `sdk/mpr/writer_odata.go` nor `mdl/backend/modelsdk/odata_write.go` had a single reference to `PublishedMicroflow`, though `modelsdk/gen/odatapublish` has `NewPublishedMicroflow()`/`NewPublishedMicroflowParameter()` with every setter wired | `mdl/grammar/domains/MDLService.g4` (`publishMicroflowBlock`, reusing `exposeClause`), `mdl/ast/ast_odata.go`, `mdl/visitor/visitor_odata.go`, `model/types.go` (`PublishedMicroflow`/`…Parameter`), `mdl/executor/cmd_odata_actions.go` (resolve the microflow, derive types), `sdk/mpr/writer_odata.go` + `parser_odata.go`, `mdl/backend/modelsdk/odata_write.go` + `odata_read_detail.go` + `integration_read.go`, `mdl/executor/cmd_odata.go` (`printPublishedMicroflowMDL`) | **With no Studio Pro reference available, derive every shape from something already proven rather than stopping.** Property names/kinds came from the generated metamodel; the `Module.Microflow.Param` form of the `MicroflowParameter` by-name ref from `published_rest_write.go`, which already ships it; the `DataTypes$ObjectType`/`ListType` `Entity` key and `EnumerationType` `Enumeration` key from `serializeMicroflowDataType`. **Do not restate what the model already declares** — parameter types and the return type are read off the microflow, so they cannot drift. Store a data type as **kind + ref, never one string**: `Module.X` cannot say whether X is an entity or an enumeration. **`mx check` reporting 0 errors is near-worthless for a NEW element type** (mxbuild ignores unknown properties); the test that settles it is to delete the referent — dropping the microflow makes mxbuild answer `CE1613 … at Published microflow parameter DriverId from published microflow RecordPrediction`, naming the elements back in its own vocabulary. **A test that calls the emitter helper directly does not prove the emitter is wired**: reverting the loop in `outputPublishedODataServiceMDL` left every `printPublishedMicroflowMDL` test green, so the DESCRIBE test goes through the real entry point. Also note the replay control does NOT reproduce a missing emitter, because `create or replace` preserves microflows when the statement supplies none — the defect is an incomplete description, not in-place loss. Tests `mdl/visitor/visitor_odata_action_test.go`, `mdl/executor/odata_auth_microflow_test.go`; example `mdl-examples/doctype-tests/10-odata-examples.mdl`. mxcli-formula1 §47.1 |
+| A service that correctly declares `TopSupported: No` cannot be consumed: `sql <alias> generate connector` / contract import produces an app whose external entity says `Supports $top = True`, and the **consumer** build fails **CE6630** "'Seasons' is marked supports $top=False in the OData service, but True in the app". The publisher is right, the contract is right, and only the generated consumer is wrong | Two layers, and the first hid the second. `applyCapabilityAnnotations` began with `if ann.Record == nil { continue }` — but `TopSupported`/`SkipSupported` are **standalone boolean terms** (`<Annotation Bool="false" Term="Org.OData.Capabilities.V1.TopSupported"/>`), not the record shape that `InsertRestrictions` and friends use, so the parser discarded them and `EdmEntitySet` had no field to hold them. `applyExternalEntityFields` then hardcoded `ent.SkipSupported = true; ent.TopSupported = true` — directly beside `Countable`, which *was* derived, and under a comment explaining the CE6630 mechanism the hardcode went on to trigger | `mdl/types/edmx.go` (`EdmEntitySet.TopSupported`/`SkipSupported`, `xmlCapabilitiesAnnotation.Bool`, standalone branch in `applyCapabilityAnnotations`), `mdl/executor/cmd_contract.go` (`applyExternalEntityFields`) | **The OData capabilities vocabulary has two annotation shapes, and a parser written against one silently drops the other.** Record terms (`InsertRestrictions`, `CountRestrictions`) wrap a `<Record>`; scalar terms (`TopSupported`, `SkipSupported`) carry `Bool` on the annotation element itself. The `Record == nil` guard read as "malformed, skip" when it actually meant "different, valid shape" — grep any capability parser for that guard before adding a term. **Absent must stay `true`, not `false`**: OData's own default is supported, so a tri-state `*bool` resolved as `p == nil || *p` is load-bearing — defaulting to false would invert CE6630 for every unannotated service, i.e. every service that worked before the fix. **This is the prerequisite for MDL-ODATA03's advice being followable**: the rule tells an author to declare `TopSupported: No` on a read-microflow resource, which was previously a trap that broke consumers. A fixture for this is worth capturing from a live `$metadata` rather than hand-written — the standalone shape is what made the bug, so a hand-built record-shaped fixture would have tested the wrong thing. Tests `mdl/types/edmx_test.go` (`TestParseEdmx_StandaloneTopAndSkipSupported`, plus a control proving record terms still parse), `mdl/executor/cmd_contract_capabilities_test.go`. mxcli-formula1 §42 |
diff --git a/mdl/executor/cmd_contract.go b/mdl/executor/cmd_contract.go
index 9fb38eec5..5df71619c 100644
--- a/mdl/executor/cmd_contract.go
+++ b/mdl/executor/cmd_contract.go
@@ -1211,8 +1211,15 @@ func applyExternalEntityFields(
 		ent.Creatable = entitySet.Insertable != nil && *entitySet.Insertable
 		ent.Deletable = entitySet.Deletable != nil && *entitySet.Deletable
 		ent.Updatable = false
-		ent.SkipSupported = true
-		ent.TopSupported = true
+		// Skip/Top follow the contract for the same reason Countable does. They
+		// were stamped true regardless, which made `TopSupported: No` on the
+		// PUBLISHING side unusable: the contract correctly said Bool="false", the
+		// consuming app said true, and the consumer failed to build with CE6630
+		// "'Seasons' is marked supports $top=False in the OData service, but True
+		// in the app". OData's own default is supported, so an unannotated set
+		// stays true (mxcli-formula1 §42).
+		ent.SkipSupported = entitySet.SkipSupported == nil || *entitySet.SkipSupported
+		ent.TopSupported = entitySet.TopSupported == nil || *entitySet.TopSupported
 		// CreateChangeLocally is deliberately NOT set. Unlike the capability flags
 		// above it cannot be derived from the service contract — it is a local
 		// modelling choice ("Allow creating and changing objects locally"), so
diff --git a/mdl/executor/cmd_contract_capabilities_test.go b/mdl/executor/cmd_contract_capabilities_test.go
new file mode 100644
index 000000000..02379967c
--- /dev/null
+++ b/mdl/executor/cmd_contract_capabilities_test.go
@@ -0,0 +1,78 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package executor
+
+import (
+	"testing"
+
+	"github.com/mendixlabs/mxcli/mdl/types"
+	"github.com/mendixlabs/mxcli/sdk/domainmodel"
+)
+
+// generatedEntity runs the external-entity generator over one entity set.
+func generatedEntity(es *types.EdmEntitySet) *domainmodel.Entity {
+	ent := &domainmodel.Entity{}
+	applyExternalEntityFields(ent, &types.EdmEntityType{Name: "Season"}, true,
+		"M.Client", es, nil, nil)
+	return ent
+}
+
+// mxcli-formula1 §42: the generator stamped SkipSupported/TopSupported true
+// whatever the contract said. So the honest remedy MDL-ODATA03 recommends —
+// declare `TopSupported: No` on the publishing side — could not be used: the
+// contract correctly carried Bool="false", the consuming app still said true,
+// and the consumer failed to build:
+//
+//	CE6630 "'Seasons' is marked supports $top=False in the OData service,
+//	        but True in the app."
+//
+// Countable next to them was already derived from the contract, and the comment
+// above the two lines even explained the CE6630 mechanism — the hardcode
+// contradicted its own stated rationale.
+func TestExternalEntity_SkipTopFollowTheContract(t *testing.T) {
+	ent := generatedEntity(&types.EdmEntitySet{
+		Name:          "Seasons",
+		TopSupported:  boolPtr(false),
+		SkipSupported: boolPtr(false),
+	})
+	if ent.TopSupported {
+		t.Error("TopSupported stayed true against a contract that says false — CE6630")
+	}
+	if ent.SkipSupported {
+		t.Error("SkipSupported stayed true against a contract that says false — CE6630")
+	}
+}
+
+// OData's own default is supported, so a service that annotates nothing must
+// still generate an app that says true. Defaulting to false would invert CE6630
+// for every unannotated service — including every one that worked before.
+func TestExternalEntity_UnannotatedSkipTopStayTrue(t *testing.T) {
+	ent := generatedEntity(&types.EdmEntitySet{Name: "Seasons"})
+	if !ent.TopSupported || !ent.SkipSupported {
+		t.Errorf("unannotated set generated Top=%v Skip=%v, want both true",
+			ent.TopSupported, ent.SkipSupported)
+	}
+}
+
+// An explicit true is honoured as an explicit true, not merely as the default.
+func TestExternalEntity_ExplicitlySupportedStaysTrue(t *testing.T) {
+	ent := generatedEntity(&types.EdmEntitySet{
+		Name: "Seasons", TopSupported: boolPtr(true), SkipSupported: boolPtr(true),
+	})
+	if !ent.TopSupported || !ent.SkipSupported {
+		t.Errorf("Top=%v Skip=%v, want both true", ent.TopSupported, ent.SkipSupported)
+	}
+}
+
+// The two can differ — a service may page with $top but not $skip.
+func TestExternalEntity_SkipAndTopAreIndependent(t *testing.T) {
+	ent := generatedEntity(&types.EdmEntitySet{
+		Name: "Seasons", TopSupported: boolPtr(true), SkipSupported: boolPtr(false),
+	})
+	if !ent.TopSupported {
+		t.Error("TopSupported should be true")
+	}
+	if ent.SkipSupported {
+		t.Error("SkipSupported should be false")
+	}
+}
diff --git a/mdl/executor/cmd_navigation.go b/mdl/executor/cmd_navigation.go
index 26bc6797e..c01caccb1 100644
--- a/mdl/executor/cmd_navigation.go
+++ b/mdl/executor/cmd_navigation.go
@@ -376,7 +376,6 @@ func menuItemIconMDL(item *types.NavMenuItem) string {
 	return " icon " + quoteQualifiedName(item.Icon)
 }
 
-
 // menuItemIconNote flags an icon DESCRIBE cannot round-trip, so re-running the
 // output loses it visibly rather than silently. CREATE NAVIGATION writes only
 // Forms$IconCollectionIcon; a glyph icon (numeric Code) or an image icon
diff --git a/mdl/types/edmx.go b/mdl/types/edmx.go
index c04ed35e6..2c21d236b 100644
--- a/mdl/types/edmx.go
+++ b/mdl/types/edmx.go
@@ -78,6 +78,14 @@ type EdmEntitySet struct {
 	Updatable  *bool // UpdateRestrictions/Updatable
 	Deletable  *bool // DeleteRestrictions/Deletable
 	Countable  *bool // CountRestrictions/Countable
+	// TopSupported / SkipSupported are STANDALONE boolean annotations in the
+	// OData capabilities vocabulary, not records:
+	//   <Annotation Bool="false" Term="Org.OData.Capabilities.V1.TopSupported"/>
+	// Mendix compares them against the app's per-entity flags and reports
+	// CE6630 on a mismatch, so a generator that stamps them true regardless
+	// makes `TopSupported: No` on the publishing side unusable.
+	TopSupported  *bool
+	SkipSupported *bool
 
 	// Property names the service says cannot be filtered or sorted on, from
 	// FilterRestrictions/NonFilterableProperties and
@@ -369,7 +377,19 @@ func parseXmlEntityType(et *xmlEntityType) *EdmEntityType {
 // flags on the EdmEntitySet.
 func applyCapabilityAnnotations(es *EdmEntitySet, annotations []xmlCapabilitiesAnnotation) {
 	for _, ann := range annotations {
+		// Standalone boolean terms carry their value on the annotation itself.
+		// Handled before the record guard, which skipped them entirely.
 		if ann.Record == nil {
+			if ann.Bool == "" {
+				continue
+			}
+			v := ann.Bool == "true"
+			switch ann.Term {
+			case "Org.OData.Capabilities.V1.TopSupported":
+				es.TopSupported = &v
+			case "Org.OData.Capabilities.V1.SkipSupported":
+				es.SkipSupported = &v
+			}
 			continue
 		}
 		switch ann.Term {
@@ -554,7 +574,10 @@ type xmlEntitySet struct {
 // <PropertyValue Property="NonInsertableNavigationProperties"><Collection>
 // <NavigationPropertyPath>Trips</NavigationPropertyPath></Collection></PropertyValue>.
 type xmlCapabilitiesAnnotation struct {
-	Term   string                 `xml:"Term,attr"`
+	Term string `xml:"Term,attr"`
+	// Bool carries a standalone boolean term (TopSupported, SkipSupported).
+	// Empty when the annotation is record-shaped.
+	Bool   string                 `xml:"Bool,attr"`
 	Record *xmlCapabilitiesRecord `xml:"Record"`
 }
 
diff --git a/mdl/types/edmx_test.go b/mdl/types/edmx_test.go
index a0e63178b..3a13b4b01 100644
--- a/mdl/types/edmx_test.go
+++ b/mdl/types/edmx_test.go
@@ -493,3 +493,100 @@ func TestParseEdmx_NoRestrictionsLeavesCapabilitiesUnset(t *testing.T) {
 			es.NonFilterableProperties, es.NonSortableProperties)
 	}
 }
+
+// mxcli-formula1 §42: `TopSupported: No` on a published resource is correctly
+// written and correctly appears in the contract as Bool="false" — and the
+// frontend then cannot build, because the external-entity generator stamps
+// SkipSupported/TopSupported true regardless:
+//
+//	CE6630 "'Seasons' is marked supports $top=False in the OData service,
+//	        but True in the app."
+//
+// The parser is the first half: these two are STANDALONE boolean annotations,
+// not records, and applyCapabilityAnnotations skipped every annotation with no
+// Record at all. The shape below is copied from the $metadata a Mendix 11.12
+// runtime actually served.
+func TestParseEdmx_StandaloneTopAndSkipSupported(t *testing.T) {
+	const md = `<?xml version="1.0" encoding="utf-8"?>
+<edmx:Edmx Version="4.0" xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx">
+  <edmx:DataServices>
+    <Schema Namespace="P" xmlns="http://docs.oasis-open.org/odata/ns/edm">
+      <EntityType Name="Season">
+        <Key><PropertyRef Name="year"/></Key>
+        <Property Name="year" Type="Edm.String" MaxLength="10"/>
+      </EntityType>
+      <EntityContainer Name="C">
+        <EntitySet Name="Seasons" EntityType="P.Season">
+          <Annotation Bool="false" Term="Org.OData.Capabilities.V1.TopSupported"/>
+          <Annotation Bool="false" Term="Org.OData.Capabilities.V1.SkipSupported"/>
+        </EntitySet>
+        <EntitySet Name="Defaults" EntityType="P.Season"/>
+      </EntityContainer>
+    </Schema>
+  </edmx:DataServices>
+</edmx:Edmx>`
+	svc, err := ParseEdmx(md)
+	if err != nil {
+		t.Fatalf("ParseEdmx: %v", err)
+	}
+	var seasons, defaults *EdmEntitySet
+	for i := range svc.EntitySets {
+		switch svc.EntitySets[i].Name {
+		case "Seasons":
+			seasons = svc.EntitySets[i]
+		case "Defaults":
+			defaults = svc.EntitySets[i]
+		}
+	}
+	if seasons == nil || defaults == nil {
+		t.Fatalf("entity sets not parsed: %+v", svc.EntitySets)
+	}
+	if seasons.TopSupported == nil || *seasons.TopSupported {
+		t.Errorf("TopSupported = %v, want an explicit false", seasons.TopSupported)
+	}
+	if seasons.SkipSupported == nil || *seasons.SkipSupported {
+		t.Errorf("SkipSupported = %v, want an explicit false", seasons.SkipSupported)
+	}
+	// Unannotated stays nil, which the caller reads as OData's own default of
+	// true. Defaulting to false here would invert CE6630 for every service that
+	// says nothing.
+	if defaults.TopSupported != nil || defaults.SkipSupported != nil {
+		t.Errorf("unannotated set should be nil/nil, got %v/%v",
+			defaults.TopSupported, defaults.SkipSupported)
+	}
+}
+
+// A record-shaped annotation must still parse — the standalone handling is
+// added alongside, not instead.
+func TestParseEdmx_StandaloneHandlingKeepsRecordAnnotations(t *testing.T) {
+	const md = `<?xml version="1.0" encoding="utf-8"?>
+<edmx:Edmx Version="4.0" xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx">
+  <edmx:DataServices>
+    <Schema Namespace="P" xmlns="http://docs.oasis-open.org/odata/ns/edm">
+      <EntityType Name="Season">
+        <Key><PropertyRef Name="year"/></Key>
+        <Property Name="year" Type="Edm.String" MaxLength="10"/>
+      </EntityType>
+      <EntityContainer Name="C">
+        <EntitySet Name="Seasons" EntityType="P.Season">
+          <Annotation Bool="false" Term="Org.OData.Capabilities.V1.TopSupported"/>
+          <Annotation Term="Org.OData.Capabilities.V1.CountRestrictions">
+            <Record><PropertyValue Bool="false" Property="Countable"/></Record>
+          </Annotation>
+        </EntitySet>
+      </EntityContainer>
+    </Schema>
+  </edmx:DataServices>
+</edmx:Edmx>`
+	svc, err := ParseEdmx(md)
+	if err != nil {
+		t.Fatalf("ParseEdmx: %v", err)
+	}
+	es := svc.EntitySets[0]
+	if es.TopSupported == nil || *es.TopSupported {
+		t.Errorf("TopSupported = %v", es.TopSupported)
+	}
+	if es.Countable == nil || *es.Countable {
+		t.Errorf("Countable = %v — the record arm regressed", es.Countable)
+	}
+}

From 70a169b5756dd5b39e880484fcdf8f5cc6be985c Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 9 Aug 2026 18:08:00 +0000
Subject: [PATCH 21/29] fix(odata): MDL-ODATA03 checks that paging is used, not
 that it could be
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

MDL-ODATA02 (the KEY promise) and MDL-ODATA03 (paging) both fired on one
condition: the read microflow has no System.HttpRequest parameter. But
the two concerns share that parameter, so adding it to answer the KEY
also silenced the paging rule while nothing about the paging changed —
a false negative on exactly the half-fixed resource still shipping
unpaged 200s.

MDL-ODATA03 now asks whether the option is used. An OData query option
is spelled `$top` / `$skip` on the wire, so a microflow implementing one
must name it; the rule reflect-walks the reachable body (following calls
into microflows the script defines) and reports only the options nothing
names. Prose is excluded — an `@annotation` documenting the limitation
is not an implementation of it.

Silence remains the answer whenever the body stops being readable: a
Java action, a JavaScript action, a nanoflow, or a microflow defined
outside the script ends the analysis, the same stance the rule already
took toward out-of-script read microflows.

The doctype example's request-aware variant was written to the old
rationale and started warning; it now locates the options it advertises.
mx check passes on both engines, 0 errors.

mxcli-formula1 §42
---
 .claude/skills/fix-issue.md                   |   1 +
 .claude/skills/mendix/odata-data-sharing.md   |  15 +-
 .../doctype-tests/10-odata-examples.mdl       |  17 +-
 mdl/executor/validate_odata_read_contract.go  | 212 ++++++++++++++++--
 .../validate_odata_read_contract_test.go      | 115 +++++++++-
 5 files changed, 332 insertions(+), 28 deletions(-)

diff --git a/.claude/skills/fix-issue.md b/.claude/skills/fix-issue.md
index ace58e578..0e44661ed 100644
--- a/.claude/skills/fix-issue.md
+++ b/.claude/skills/fix-issue.md
@@ -442,3 +442,4 @@ extracting `OffsetExpression`/`LimitExpression`.
 | `authentication microflow Module.Auth` on a published OData service parses, checks clean and reports `Created OData service` — then the build fails **CE0333** "Please select a microflow to use for authentication", and `DESCRIBE` shows `authentication Microflow` with no name. Custom authentication is unreachable from MDL, which matters because it is the only way to avoid a full BCrypt hash on every OData request (60–80% of a page turn measured) | The grammar had accepted `MICROFLOW qualifiedName?` all along and both writers already serialized `AuthenticationMicroflow` from `svc.AuthMicroflow` — but nothing ever *assigned* it. `parseODataAuthTypes` recognised the `microflow` keyword and discarded the name, so the field was only ever populated by reading a model Studio Pro wrote. DESCRIBE then emitted it as a comment (`-- Auth Microflow: …`), so a custom-auth service could not round-trip either | `mdl/ast/ast_odata.go` (`AuthMicroflow`), `mdl/visitor/visitor_odata.go` (`parseODataAuthTypes` returns the name), `mdl/executor/cmd_odata.go` (assign on create AND modify; `odataAuthClause` for DESCRIBE), `mdl/executor/validate_odata_auth.go` (MDL-ODATA04) | **When a feature "silently drops" one field, check whether the plumbing already exists at both ends** — here only the middle assignment was missing, so the fix was ~10 lines across four files rather than a new write path. The grammar already parsed the name: `at.QualifiedName()` was simply never read. **DESCRIBE emitting a value as a comment is the same defect class as dropping it** (§39): the output looks complete and replays into a model the build rejects — so the round-trip test asserts the emitted clause re-parses to the same microflow, not that it contains some text. Two Mendix rules bound the feature and are easy to hit while verifying: **CE0333** if no microflow is named (now MDL-ODATA04 at check time), and **CE6600** "App security is off, but custom authentication is enabled" — so a fixture project needs `alter project security level prototype` before it can prove anything. That second one is why this is NOT in the doctype gate: those projects run with security off, so any custom-auth service there fails CE6600 regardless of correctness. Verified instead by writing the service from MDL into a real project and running `mx check` (0 errors). Tests `mdl/executor/odata_auth_microflow_test.go`. mxcli-formula1 §40 |
 | MDL cannot declare an OData action. `publish microflow …`, `publish action …` and every variant is a parse error at `missing ENTITY`, so a service's `$metadata` has an `EntityContainer` with `EntitySet` elements and no `ActionImport` — and every parameterised resource has to be modelled as an entity set that echoes its own arguments back as columns | `createODataServiceStatement` admitted `publishEntityBlock*` and nothing else. Unlike the custom-auth gap the write path was missing too: neither `sdk/mpr/writer_odata.go` nor `mdl/backend/modelsdk/odata_write.go` had a single reference to `PublishedMicroflow`, though `modelsdk/gen/odatapublish` has `NewPublishedMicroflow()`/`NewPublishedMicroflowParameter()` with every setter wired | `mdl/grammar/domains/MDLService.g4` (`publishMicroflowBlock`, reusing `exposeClause`), `mdl/ast/ast_odata.go`, `mdl/visitor/visitor_odata.go`, `model/types.go` (`PublishedMicroflow`/`…Parameter`), `mdl/executor/cmd_odata_actions.go` (resolve the microflow, derive types), `sdk/mpr/writer_odata.go` + `parser_odata.go`, `mdl/backend/modelsdk/odata_write.go` + `odata_read_detail.go` + `integration_read.go`, `mdl/executor/cmd_odata.go` (`printPublishedMicroflowMDL`) | **With no Studio Pro reference available, derive every shape from something already proven rather than stopping.** Property names/kinds came from the generated metamodel; the `Module.Microflow.Param` form of the `MicroflowParameter` by-name ref from `published_rest_write.go`, which already ships it; the `DataTypes$ObjectType`/`ListType` `Entity` key and `EnumerationType` `Enumeration` key from `serializeMicroflowDataType`. **Do not restate what the model already declares** — parameter types and the return type are read off the microflow, so they cannot drift. Store a data type as **kind + ref, never one string**: `Module.X` cannot say whether X is an entity or an enumeration. **`mx check` reporting 0 errors is near-worthless for a NEW element type** (mxbuild ignores unknown properties); the test that settles it is to delete the referent — dropping the microflow makes mxbuild answer `CE1613 … at Published microflow parameter DriverId from published microflow RecordPrediction`, naming the elements back in its own vocabulary. **A test that calls the emitter helper directly does not prove the emitter is wired**: reverting the loop in `outputPublishedODataServiceMDL` left every `printPublishedMicroflowMDL` test green, so the DESCRIBE test goes through the real entry point. Also note the replay control does NOT reproduce a missing emitter, because `create or replace` preserves microflows when the statement supplies none — the defect is an incomplete description, not in-place loss. Tests `mdl/visitor/visitor_odata_action_test.go`, `mdl/executor/odata_auth_microflow_test.go`; example `mdl-examples/doctype-tests/10-odata-examples.mdl`. mxcli-formula1 §47.1 |
 | A service that correctly declares `TopSupported: No` cannot be consumed: `sql <alias> generate connector` / contract import produces an app whose external entity says `Supports $top = True`, and the **consumer** build fails **CE6630** "'Seasons' is marked supports $top=False in the OData service, but True in the app". The publisher is right, the contract is right, and only the generated consumer is wrong | Two layers, and the first hid the second. `applyCapabilityAnnotations` began with `if ann.Record == nil { continue }` — but `TopSupported`/`SkipSupported` are **standalone boolean terms** (`<Annotation Bool="false" Term="Org.OData.Capabilities.V1.TopSupported"/>`), not the record shape that `InsertRestrictions` and friends use, so the parser discarded them and `EdmEntitySet` had no field to hold them. `applyExternalEntityFields` then hardcoded `ent.SkipSupported = true; ent.TopSupported = true` — directly beside `Countable`, which *was* derived, and under a comment explaining the CE6630 mechanism the hardcode went on to trigger | `mdl/types/edmx.go` (`EdmEntitySet.TopSupported`/`SkipSupported`, `xmlCapabilitiesAnnotation.Bool`, standalone branch in `applyCapabilityAnnotations`), `mdl/executor/cmd_contract.go` (`applyExternalEntityFields`) | **The OData capabilities vocabulary has two annotation shapes, and a parser written against one silently drops the other.** Record terms (`InsertRestrictions`, `CountRestrictions`) wrap a `<Record>`; scalar terms (`TopSupported`, `SkipSupported`) carry `Bool` on the annotation element itself. The `Record == nil` guard read as "malformed, skip" when it actually meant "different, valid shape" — grep any capability parser for that guard before adding a term. **Absent must stay `true`, not `false`**: OData's own default is supported, so a tri-state `*bool` resolved as `p == nil || *p` is load-bearing — defaulting to false would invert CE6630 for every unannotated service, i.e. every service that worked before the fix. **This is the prerequisite for MDL-ODATA03's advice being followable**: the rule tells an author to declare `TopSupported: No` on a read-microflow resource, which was previously a trap that broke consumers. A fixture for this is worth capturing from a live `$metadata` rather than hand-written — the standalone shape is what made the bug, so a hand-built record-shaped fixture would have tested the wrong thing. Tests `mdl/types/edmx_test.go` (`TestParseEdmx_StandaloneTopAndSkipSupported`, plus a control proving record terms still parse), `mdl/executor/cmd_contract_capabilities_test.go`. mxcli-formula1 §42 |
+| `MDL-ODATA03` ("advertises TopSupported … so no paging is applied") is silenced by giving the read microflow a `System.HttpRequest` parameter — even when the parameter was added for the **KEY** and no paging was implemented. The half-fixed resource, which is the one still shipping unpaged 200s, is exactly the one the rule stops warning about | MDL-ODATA02 (KEY) and MDL-ODATA03 (paging) shared a single test — `takesHTTPRequest(decl)` — and answering either concern satisfied both. The rule could see whether the microflow *could* read the request, not whether it *did* | `mdl/executor/validate_odata_read_contract.go` (`capabilityViolations` now takes the declaration; `pagingEvidence`/`walkForPaging` reflect-walk the reachable body), `mdl-examples/doctype-tests/10-odata-examples.mdl` | **When one input satisfies two rules, the rules will silence each other.** The tell is a shared precondition that means something different to each check — grep for other validators keyed on the same `takesX()` helper before adding one. **The wire spelling is the evidence.** An OData query option is literally named `$top`, so a microflow implementing it must contain that text; presence of the text is weak evidence of handling, absence is strong evidence against — which is the only direction a rule that reports absences needs. **Reflect-walk, do not type-switch per statement**: MDL gains activity types regularly and a walker that misses one converts a false negative into a false *positive* ("nothing reads $top" about a body it never looked at). Reflection also picks up new nesting — loop bodies, if-branches, error handlers — for free. **Exclude `Annotations`/`Documentation`/`Comment` fields from the walk**: an `@annotation '$top is not applied here'` is prose admitting the defect, and counting it as implementation silences the rule on the one resource that documents the bug. **Keep an escape hatch and make it outrank the evidence**: a call into a Java action, a JavaScript action, a nanoflow, or a microflow the script does not define ends the analysis with silence — same stance the rule already took toward out-of-script read microflows. Follow calls into helpers the script *does* define, since real code factors paging out. **Report per option, not per resource** — flagging `SkipSupported` while `$top` is genuinely handled avoids advising an author to withdraw working support. **Shipped examples are part of the blast radius**: the doctype example's variant (a) was written to the old rationale ("taking `$Request` is enough to earn its silence") and started warning the moment the rule tightened — a changed rule needs `mxcli check` over `mdl-examples/` and then the integration gate, not just its own unit tests. Each guard has its own revert control (restore benefit-of-the-doubt / drop the annotation skip / drop `opaque` / stop following helpers), and all four reproduce. Tests `mdl/executor/validate_odata_read_contract_test.go`. mxcli-formula1 §42 |
diff --git a/.claude/skills/mendix/odata-data-sharing.md b/.claude/skills/mendix/odata-data-sharing.md
index 0ea149d79..3b605b6f8 100644
--- a/.claude/skills/mendix/odata-data-sharing.md
+++ b/.claude/skills/mendix/odata-data-sharing.md
@@ -541,7 +541,20 @@ publish entity Api.Row as 'Rows' (
 )
 ```
 
-Declaring `No` is the read path's substitute for the `400` it cannot send.
+Declaring `No` is the read path's substitute for the `400` it cannot send. It is
+also safe to declare: the contract carries `TopSupported`/`SkipSupported` as
+standalone boolean annotations, and `sql <alias> generate connector` reads them,
+so a consuming app generated from this service says `No` too. (Until mxcli
+learned to read them it always generated `Yes`, and the consumer failed to build
+with **CE6630** "'Rows' is marked supports $top=False in the OData service, but
+True in the app" — if you hit that against an older mxcli, that is the cause.)
+
+`mxcli check` enforces this as **MDL-ODATA03**, and it looks for the option
+*names* in the microflow body, not just for a `System.HttpRequest` parameter —
+adding the parameter to answer the KEY (below) does not silence the paging
+warning. A microflow that hands the request to a Java action, a JavaScript
+action, or a microflow outside the script is left alone, since mxcli cannot read
+what those do.
 
 **2. Answer a lookup by your own KEY.** A client holding a row re-reads it by
 key, unprompted, and Mendix's own OData client sends the `$filter` spelling:
diff --git a/mdl-examples/doctype-tests/10-odata-examples.mdl b/mdl-examples/doctype-tests/10-odata-examples.mdl
index 36029d76b..528d5f5ff 100644
--- a/mdl-examples/doctype-tests/10-odata-examples.mdl
+++ b/mdl-examples/doctype-tests/10-odata-examples.mdl
@@ -656,9 +656,12 @@ end;
 
 create non-persistent entity OdTest.LiveRow ( RowKey: string(60), Label: string(200) );
 
--- (a) Take the request and honour it. mxcli cannot tell WHICH options a
---     microflow parses, so taking $Request is enough to earn its silence — the
---     branch key -> filter -> default is the author's job.
+-- (a) Take the request and honour it. Taking $Request answers the KEY concern
+--     (MDL-ODATA02) — but it does NOT answer the paging one, because the two
+--     share a parameter: adding it for the key would otherwise silence
+--     MDL-ODATA03 while nothing about the paging changed. So the paging rule
+--     looks for the option NAMES in the body, on the reasoning that a query
+--     option spelled `$top` on the wire has to be spelled `$top` to be read.
 create microflow OdTest.Read_LiveRows (
   $Request:  System.HttpRequest,
   $Response: System.ODataResponse
@@ -668,6 +671,14 @@ begin
   -- $Request/Uri carries the whole query string, URL-encoded:
   --   ?$filter=rowKey eq '1036-c'   <- a client re-reading a row it holds
   --   ?$top=20&$skip=40             <- paging the client believes works
+  --
+  -- Branching key -> filter -> page is the author's job; the lines below only
+  -- locate the options. Note they are inside the expression, not a comment:
+  -- prose naming `$top` is documentation, and the rule does not read it as
+  -- implementation.
+  declare $Uri string = $Request/Uri;
+  declare $TopAt integer = find($Uri, '$top=');
+  declare $SkipAt integer = find($Uri, '$skip=');
   $Rows = create list of OdTest.LiveRow;
   return $Rows;
 end;
diff --git a/mdl/executor/validate_odata_read_contract.go b/mdl/executor/validate_odata_read_contract.go
index bc206bfab..4d30ea487 100644
--- a/mdl/executor/validate_odata_read_contract.go
+++ b/mdl/executor/validate_odata_read_contract.go
@@ -12,18 +12,28 @@
 // request time has to be stated up front, in the published metadata. These rules
 // check the statement against the microflow it names.
 //
-// Both fire on one provable condition — the microflow does not take a
-// System.HttpRequest parameter — because without the request it cannot see a
-// key, a $filter, a $top or a $skip at all. A microflow that does take the
-// request gets the benefit of the doubt: proving *which* options it parses would
-// need real analysis, and a rule that guesses is a rule people switch off.
+// MDL-ODATA02 (the KEY promise) fires on one provable condition — the microflow
+// does not take a System.HttpRequest parameter — because without the request it
+// cannot see a key at all.
 //
-// mxcli-formula1 §37 (the KEY promise) and §20 (capabilities Mendix does not
-// apply itself).
+// MDL-ODATA03 (paging) needs more than that, because the two concerns share one
+// parameter. Adding $Request to answer the KEY also silenced the paging rule
+// while nothing about the paging changed, which is a false negative exactly on a
+// half-fixed resource (mxcli-formula1 §42). So it asks whether the option is
+// *used*, not whether it could be: an OData query option is named `$top` /
+// `$skip` on the wire, so a microflow that implements one must spell it
+// somewhere. Silence is only reported when the whole reachable body is
+// readable — a call into a Java action, a JavaScript action, or a microflow this
+// script does not define makes the rule say nothing, since a rule that guesses
+// is a rule people switch off.
+//
+// mxcli-formula1 §37 (the KEY promise), §20 (capabilities Mendix does not apply
+// itself) and §42 (the shared-parameter false negative).
 package executor
 
 import (
 	"fmt"
+	"reflect"
 	"strings"
 
 	"github.com/mendixlabs/mxcli/mdl/ast"
@@ -63,13 +73,15 @@ func ValidateODataReadContract(prog *ast.Program) []linter.Violation {
 			// reference to one that already exists in the project is not
 			// evidence of anything, so say nothing.
 			decl, found := flows[strings.ToLower(mf)]
-			if !found || takesHTTPRequest(decl) {
+			if !found {
 				continue
 			}
 			where := fmt.Sprintf("publish entity %s as %q in %s",
 				e.Entity.String(), e.ExposedName, svc.Name.String())
-			out = append(out, keyPromiseViolations(where, e, mf)...)
-			out = append(out, capabilityViolations(where, e, mf)...)
+			if !takesHTTPRequest(decl) {
+				out = append(out, keyPromiseViolations(where, e, mf)...)
+			}
+			out = append(out, capabilityViolations(where, e, mf, decl, flows)...)
 		}
 	}
 	return out
@@ -110,34 +122,198 @@ func keyPromiseViolations(where string, e *ast.PublishedEntityDef, mf string) []
 }
 
 // capabilityViolations flags query options advertised to clients that the read
-// microflow cannot implement (MDL-ODATA03).
-func capabilityViolations(where string, e *ast.PublishedEntityDef, mf string) []linter.Violation {
+// microflow does not implement (MDL-ODATA03).
+//
+// An option is unimplemented when either the microflow cannot see the request at
+// all, or it can and never spells the option's name. The two cases share a rule
+// because they are the same defect to a client — a 200 carrying an unpaged
+// collection — but they read differently to an author, so they are worded apart.
+func capabilityViolations(where string, e *ast.PublishedEntityDef, mf string,
+	decl *ast.CreateMicroflowStmt, flows map[string]*ast.CreateMicroflowStmt) []linter.Violation {
+
 	// nil means "not specified", which publishes Mendix's default of true — so
 	// silence is a claim, and that is exactly what makes this worth flagging.
+	sees := takesHTTPRequest(decl)
+	ev := pagingEvidence(decl, flows)
+	if sees && ev.opaque {
+		// The microflow hands the request off to something this script cannot
+		// read. Say nothing rather than guess.
+		return nil
+	}
+
 	var claimed []string
-	if boolOrTrueAST(e.TopSupported) {
+	if boolOrTrueAST(e.TopSupported) && !(sees && ev.top) {
 		claimed = append(claimed, "TopSupported")
 	}
-	if boolOrTrueAST(e.SkipSupported) {
+	if boolOrTrueAST(e.SkipSupported) && !(sees && ev.skip) {
 		claimed = append(claimed, "SkipSupported")
 	}
 	if len(claimed) == 0 {
 		return nil
 	}
+
+	// The two readings differ in what the author has to look at: one is a missing
+	// parameter, the other a parameter that is there for a different purpose.
+	reason := fmt.Sprintf("%s never sees the request (no %s parameter)", mf, httpRequestType)
+	remedy := fmt.Sprintf("Either parse them from `$Request/Uri` — %s needs a `$Request: %s` parameter first — or declare",
+		mf, httpRequestType)
+	if sees {
+		reason = fmt.Sprintf("nothing in %s reads %s from `$Request/Uri`",
+			mf, strings.Join(quotedOptions(claimed), " or "))
+		remedy = "Either parse them from `$Request/Uri`, or declare"
+	}
+
 	return []linter.Violation{{
 		RuleID:   "MDL-ODATA03",
 		Severity: linter.SeverityWarning,
-		Message: fmt.Sprintf("%s: advertises %s, but %s never sees the request (no %s parameter), so no paging is applied",
-			where, strings.Join(claimed, " and "), mf, httpRequestType),
+		Message: fmt.Sprintf("%s: advertises %s, but %s, so no paging is applied",
+			where, strings.Join(claimed, " and "), reason),
 		Suggestion: fmt.Sprintf(
 			"Mendix applies no query options to a read-microflow resource — it returns exactly what the microflow returns — so these annotations describe %s, not the platform. "+
 				"A client asking for $top=5 gets the whole collection with a 200 and believes it received a page. "+
-				"Either parse them from `$Request/Uri`, or declare `TopSupported: No, SkipSupported: No`. "+
+				"%s `%s`. "+
 				"Declaring No is the read path's substitute for the 400 it cannot send: the read capability has no System.HttpResponse parameter (%s).",
-			mf, odataDocsCustomResponse),
+			mf, remedy, declineClause(claimed), odataDocsCustomResponse),
 	}}
 }
 
+// quotedOptions renders TopSupported/SkipSupported as the query options a client
+// actually sends, which is what the author has to grep the microflow for.
+func quotedOptions(claimed []string) []string {
+	out := make([]string, 0, len(claimed))
+	for _, c := range claimed {
+		out = append(out, "$"+strings.ToLower(strings.TrimSuffix(c, "Supported")))
+	}
+	return out
+}
+
+// declineClause renders the properties to set to No — only the ones flagged, so
+// a half-implemented resource is not told to withdraw the half that works.
+func declineClause(claimed []string) string {
+	parts := make([]string, 0, len(claimed))
+	for _, c := range claimed {
+		parts = append(parts, c+": No")
+	}
+	return strings.Join(parts, ", ")
+}
+
+// paging records what a read microflow was shown to do with the request.
+//
+// opaque is the escape hatch, and it outranks the other two: it means the
+// reachable body leaves what this script can read, so absence of evidence is not
+// evidence of absence.
+type paging struct {
+	top    bool
+	skip   bool
+	opaque bool
+}
+
+// pagingEvidence walks a microflow body — and, transitively, every microflow in
+// the same script that it calls — looking for the literal query option names.
+//
+// A microflow cannot implement `$top` without naming it: the option is spelled
+// that way on the wire, so extracting it means a `find`/`substring` against the
+// literal. That makes the presence of the text weak evidence of handling and its
+// absence strong evidence of the opposite — which is the direction this rule
+// needs, since it only ever reports the absence.
+func pagingEvidence(mf *ast.CreateMicroflowStmt, flows map[string]*ast.CreateMicroflowStmt) paging {
+	var ev paging
+	seen := map[string]bool{}
+	var visit func(*ast.CreateMicroflowStmt)
+	visit = func(m *ast.CreateMicroflowStmt) {
+		if m == nil {
+			return
+		}
+		key := strings.ToLower(m.Name.String())
+		if seen[key] {
+			return
+		}
+		seen[key] = true
+
+		var callees []string
+		walkForPaging(reflect.ValueOf(m.Body), &ev, &callees)
+		for _, callee := range callees {
+			next, found := flows[strings.ToLower(callee)]
+			if !found {
+				// Defined elsewhere in the project (or not at all). Unreadable.
+				ev.opaque = true
+				continue
+			}
+			visit(next)
+		}
+	}
+	visit(mf)
+	return ev
+}
+
+// walkForPaging reflects over microflow statements collecting the option names
+// any string mentions, the calls that leave this script's view, and the calls
+// worth following.
+//
+// Reflection rather than a type switch per statement: MDL gains activity types
+// regularly, and a hand-written walker that misses one turns a false negative
+// into a false positive — the rule would report "nothing reads $top" about a body
+// it simply did not look at. Reflection covers new statement types, and new
+// nesting (loops, if-branches, error handlers), on the day they are added.
+func walkForPaging(v reflect.Value, ev *paging, callees *[]string) {
+	switch v.Kind() {
+	case reflect.Interface:
+		if v.IsNil() {
+			return
+		}
+		// Unwrap to the concrete value; the Ptr case below classifies it. Doing
+		// the type switch here too would count every statement twice.
+		walkForPaging(v.Elem(), ev, callees)
+	case reflect.Ptr:
+		if v.IsNil() {
+			return
+		}
+		switch s := v.Interface().(type) {
+		// Opaque code: a Java or JavaScript action could parse the URI in a
+		// language mxcli does not read, so its presence ends the analysis. A
+		// nanoflow is not indexed with the microflows, so it can never be
+		// followed — treat every one the same way.
+		case *ast.CallJavaActionStmt, *ast.CallJavaScriptActionStmt,
+			*ast.CallWebServiceStmt, *ast.CallNanoflowStmt:
+			ev.opaque = true
+		case *ast.CallMicroflowStmt:
+			*callees = append(*callees, s.MicroflowName.String())
+		}
+		walkForPaging(v.Elem(), ev, callees)
+	case reflect.Slice, reflect.Array:
+		for i := 0; i < v.Len(); i++ {
+			walkForPaging(v.Index(i), ev, callees)
+		}
+	case reflect.Map:
+		for _, k := range v.MapKeys() {
+			walkForPaging(v.MapIndex(k), ev, callees)
+		}
+	case reflect.Struct:
+		t := v.Type()
+		for i := 0; i < v.NumField(); i++ {
+			// Prose about the microflow is not behaviour of the microflow. An
+			// @annotation reading "$top is not applied here" must not be read as
+			// applying it.
+			switch t.Field(i).Name {
+			case "Annotations", "Documentation", "Comment":
+				continue
+			}
+			if !t.Field(i).IsExported() {
+				continue
+			}
+			walkForPaging(v.Field(i), ev, callees)
+		}
+	case reflect.String:
+		s := strings.ToLower(v.String())
+		if strings.Contains(s, "$top") {
+			ev.top = true
+		}
+		if strings.Contains(s, "$skip") {
+			ev.skip = true
+		}
+	}
+}
+
 // microflowsByName indexes the microflows this script defines, lower-cased.
 func microflowsByName(prog *ast.Program) map[string]*ast.CreateMicroflowStmt {
 	out := map[string]*ast.CreateMicroflowStmt{}
diff --git a/mdl/executor/validate_odata_read_contract_test.go b/mdl/executor/validate_odata_read_contract_test.go
index 5c1cb75a3..f62206ade 100644
--- a/mdl/executor/validate_odata_read_contract_test.go
+++ b/mdl/executor/validate_odata_read_contract_test.go
@@ -12,13 +12,21 @@ import (
 // readContractScript builds a service whose read microflow takes params and
 // whose published entity carries entityProps and members.
 func readContractScript(params, entityProps, members string) string {
+	return readContractScriptBody(params, entityProps, members, "", "")
+}
+
+// readContractScriptBody additionally injects statements into the read
+// microflow's body, and extra top-level declarations before the service — what
+// MDL-ODATA03 now reads to decide whether an advertised option is implemented.
+func readContractScriptBody(params, entityProps, members, body, extra string) string {
 	return `create module T;
 create non-persistent entity T.Row (K: string(20));
-
+` + extra + `
 CREATE MICROFLOW T.Read_Rows (` + params + `)
   RETURNS List of T.Row AS $Rows
 BEGIN
   $Rows = CREATE LIST OF T.Row;
+` + body + `
   RETURN $Rows;
 END;
 
@@ -87,14 +95,109 @@ func TestODataReadContract_FlagsCapabilitiesNothingImplements(t *testing.T) {
 	}
 }
 
-// A microflow that takes the request gets the benefit of the doubt. Proving
-// WHICH options it parses would need real analysis, and a rule that guesses is
-// a rule people switch off.
-func TestODataReadContract_SilentWhenTheMicroflowSeesTheRequest(t *testing.T) {
+// The request parameter is shared between two unrelated concerns, and it used to
+// be the whole test. Adding it to answer the KEY (MDL-ODATA02) therefore
+// silenced the paging rule as a side effect, while nothing about the paging
+// changed — a false negative exactly on a half-fixed resource, which is the one
+// place the warning is still worth having (mxcli-formula1 §42).
+func TestODataReadContract_FlagsPagingTheRequestAwareMicroflowNeverReads(t *testing.T) {
 	ids := odataReadRuleIDs(t, readContractScript(
 		"$Request: System.HttpRequest, $Response: System.ODataResponse", "", "K as 'k' (KEY)"))
+	if !hasODataReadRule(ids, "MDL-ODATA03") {
+		t.Errorf("having the request but never reading $top/$skip was not flagged, got %v", ids)
+	}
+	// The key rule is a separate concern and the parameter genuinely answers it.
+	if hasODataReadRule(ids, "MDL-ODATA02") {
+		t.Errorf("the request parameter answers the KEY concern: %v", ids)
+	}
+}
+
+// The rule reports the absence of the option's name, so naming it has to be
+// enough to silence it — otherwise a correctly paged resource is warned about
+// forever and the rule gets switched off.
+func TestODataReadContract_SilentWhenTheMicroflowReadsBothOptions(t *testing.T) {
+	ids := odataReadRuleIDs(t, readContractScriptBody(
+		"$Request: System.HttpRequest", "", "K as 'k'",
+		"  declare $Paging string = find($Request/Uri, '$top=') + find($Request/Uri, '$skip=');", ""))
+	if len(ids) != 0 {
+		t.Errorf("a microflow that reads both options must not be flagged, got %v", ids)
+	}
+}
+
+// Half-implemented is the shape §42 is about, so the warning has to name the
+// half that is missing and leave the half that works alone — telling an author
+// to withdraw working $top support would be a regression dressed as advice.
+func TestODataReadContract_FlagsOnlyTheUnreadOption(t *testing.T) {
+	prog, errs := visitor.Build(readContractScriptBody(
+		"$Request: System.HttpRequest", "", "K as 'k'",
+		"  declare $Paging string = find($Request/Uri, '$top=');", ""))
+	if len(errs) > 0 {
+		t.Fatalf("parsing the script: %v", errs)
+	}
+	vs := ValidateODataReadContract(prog)
+	if len(vs) != 1 {
+		t.Fatalf("want one violation, got %d: %v", len(vs), vs)
+	}
+	if strings.Contains(vs[0].Message, "TopSupported") {
+		t.Errorf("$top IS read, so TopSupported must not be flagged: %s", vs[0].Message)
+	}
+	if !strings.Contains(vs[0].Message, "SkipSupported") {
+		t.Errorf("$skip is never read, so SkipSupported must be flagged: %s", vs[0].Message)
+	}
+}
+
+// A Java action parses the URI in a language mxcli cannot read. Absence of the
+// literal proves nothing there, so the rule says nothing — the same stance it
+// already takes toward a microflow defined outside the script.
+func TestODataReadContract_SilentWhenPagingCouldBeInAJavaAction(t *testing.T) {
+	ids := odataReadRuleIDs(t, readContractScriptBody(
+		"$Request: System.HttpRequest", "", "K as 'k'",
+		"  $Ignored = call java action T.ApplyPaging (Request = $Request);", ""))
+	if len(ids) != 0 {
+		t.Errorf("an opaque Java action must suppress the rule, got %v", ids)
+	}
+}
+
+// Real code factors paging out into a helper, so the analysis follows calls into
+// microflows the script defines rather than stopping at the resource's own body.
+func TestODataReadContract_FollowsCallsIntoHelpersItCanRead(t *testing.T) {
+	helper := `
+CREATE MICROFLOW T.Apply_Paging ($Request: System.HttpRequest)
+  RETURNS String AS $Out
+BEGIN
+  declare $Out string = find($Request/Uri, '$top=') + find($Request/Uri, '$skip=');
+  RETURN $Out;
+END;
+`
+	ids := odataReadRuleIDs(t, readContractScriptBody(
+		"$Request: System.HttpRequest", "", "K as 'k'",
+		"  $P = call microflow T.Apply_Paging (Request = $Request);", helper))
+	if len(ids) != 0 {
+		t.Errorf("paging done in a readable helper must not be flagged, got %v", ids)
+	}
+}
+
+// The converse: a helper that exists somewhere else in the project cannot be
+// read, so its call is as opaque as a Java action's.
+func TestODataReadContract_SilentWhenAHelperIsOutsideTheScript(t *testing.T) {
+	ids := odataReadRuleIDs(t, readContractScriptBody(
+		"$Request: System.HttpRequest", "", "K as 'k'",
+		"  $P = call microflow Other.Apply_Paging (Request = $Request);", ""))
 	if len(ids) != 0 {
-		t.Errorf("a request-aware microflow must not be flagged, got %v", ids)
+		t.Errorf("an unreadable helper must suppress the rule, got %v", ids)
+	}
+}
+
+// Prose about the microflow is not behaviour of the microflow. An annotation
+// documenting the limitation names `$top` while implementing nothing, and
+// reading it as evidence would silence the rule on precisely the resource that
+// admits the defect in writing.
+func TestODataReadContract_DoesNotReadAnnotationsAsImplementation(t *testing.T) {
+	ids := odataReadRuleIDs(t, readContractScriptBody(
+		"$Request: System.HttpRequest", "", "K as 'k'",
+		"  @annotation '$top and $skip are not applied here'\n  $Rows = CREATE LIST OF T.Row;", ""))
+	if !hasODataReadRule(ids, "MDL-ODATA03") {
+		t.Errorf("an annotation is documentation, not paging, got %v", ids)
 	}
 }
 

From 4c78200a42a7ed08c63e5456ac67d7fa9c5d36fe Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 9 Aug 2026 19:00:43 +0000
Subject: [PATCH 22/29] fix(run): name the process holding the port instead of
 guessing
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`run --local` refused to boot with "a previous 'mxcli run --local' … is
likely still serving on it" and told the user to go hunting with pgrep.
The guess was wrong as often as right, and one of the suggested
patterns — `pgrep -f 'mxcli run'` — matches the shell it is typed into.

The guard now resolves the listener through /proc (inode from
/proc/net/tcp{,6}, owner from /proc/<pid>/fd) and prints its pid and
command line. No lsof/ss: both are routinely missing from slim
containers.

It also separates two cases that had shared one message and need
opposite remedies. A leftover of a previous run — which can only happen
after a kill -9, a crash, or a reaped container, since a graceful stop
already reaps the whole process group — gets a ready-to-paste
`kill <pid>`. A foreign listener gets told it is foreign and pointed at
--app-port, with no kill offered.

Detection-only is unchanged: reaping someone else's process stays the
user's call.

mxcli-formula1 suggested issue 8
---
 .claude/skills/fix-issue.md              |   1 +
 .claude/skills/mendix/run-local.md       |  23 ++-
 cmd/mxcli/docker/localapp.go             |   3 +-
 cmd/mxcli/docker/portguard.go            |  60 ++++++
 cmd/mxcli/docker/portowner_linux.go      | 201 +++++++++++++++++++
 cmd/mxcli/docker/portowner_linux_test.go | 239 +++++++++++++++++++++++
 cmd/mxcli/docker/portowner_other.go      |  17 ++
 cmd/mxcli/docker/runlocal.go             |   9 +-
 docs-site/src/tools/run-local.md         |  40 +++-
 9 files changed, 574 insertions(+), 19 deletions(-)
 create mode 100644 cmd/mxcli/docker/portguard.go
 create mode 100644 cmd/mxcli/docker/portowner_linux.go
 create mode 100644 cmd/mxcli/docker/portowner_linux_test.go
 create mode 100644 cmd/mxcli/docker/portowner_other.go

diff --git a/.claude/skills/fix-issue.md b/.claude/skills/fix-issue.md
index 0e44661ed..5dfd4f6b9 100644
--- a/.claude/skills/fix-issue.md
+++ b/.claude/skills/fix-issue.md
@@ -443,3 +443,4 @@ extracting `OffsetExpression`/`LimitExpression`.
 | MDL cannot declare an OData action. `publish microflow …`, `publish action …` and every variant is a parse error at `missing ENTITY`, so a service's `$metadata` has an `EntityContainer` with `EntitySet` elements and no `ActionImport` — and every parameterised resource has to be modelled as an entity set that echoes its own arguments back as columns | `createODataServiceStatement` admitted `publishEntityBlock*` and nothing else. Unlike the custom-auth gap the write path was missing too: neither `sdk/mpr/writer_odata.go` nor `mdl/backend/modelsdk/odata_write.go` had a single reference to `PublishedMicroflow`, though `modelsdk/gen/odatapublish` has `NewPublishedMicroflow()`/`NewPublishedMicroflowParameter()` with every setter wired | `mdl/grammar/domains/MDLService.g4` (`publishMicroflowBlock`, reusing `exposeClause`), `mdl/ast/ast_odata.go`, `mdl/visitor/visitor_odata.go`, `model/types.go` (`PublishedMicroflow`/`…Parameter`), `mdl/executor/cmd_odata_actions.go` (resolve the microflow, derive types), `sdk/mpr/writer_odata.go` + `parser_odata.go`, `mdl/backend/modelsdk/odata_write.go` + `odata_read_detail.go` + `integration_read.go`, `mdl/executor/cmd_odata.go` (`printPublishedMicroflowMDL`) | **With no Studio Pro reference available, derive every shape from something already proven rather than stopping.** Property names/kinds came from the generated metamodel; the `Module.Microflow.Param` form of the `MicroflowParameter` by-name ref from `published_rest_write.go`, which already ships it; the `DataTypes$ObjectType`/`ListType` `Entity` key and `EnumerationType` `Enumeration` key from `serializeMicroflowDataType`. **Do not restate what the model already declares** — parameter types and the return type are read off the microflow, so they cannot drift. Store a data type as **kind + ref, never one string**: `Module.X` cannot say whether X is an entity or an enumeration. **`mx check` reporting 0 errors is near-worthless for a NEW element type** (mxbuild ignores unknown properties); the test that settles it is to delete the referent — dropping the microflow makes mxbuild answer `CE1613 … at Published microflow parameter DriverId from published microflow RecordPrediction`, naming the elements back in its own vocabulary. **A test that calls the emitter helper directly does not prove the emitter is wired**: reverting the loop in `outputPublishedODataServiceMDL` left every `printPublishedMicroflowMDL` test green, so the DESCRIBE test goes through the real entry point. Also note the replay control does NOT reproduce a missing emitter, because `create or replace` preserves microflows when the statement supplies none — the defect is an incomplete description, not in-place loss. Tests `mdl/visitor/visitor_odata_action_test.go`, `mdl/executor/odata_auth_microflow_test.go`; example `mdl-examples/doctype-tests/10-odata-examples.mdl`. mxcli-formula1 §47.1 |
 | A service that correctly declares `TopSupported: No` cannot be consumed: `sql <alias> generate connector` / contract import produces an app whose external entity says `Supports $top = True`, and the **consumer** build fails **CE6630** "'Seasons' is marked supports $top=False in the OData service, but True in the app". The publisher is right, the contract is right, and only the generated consumer is wrong | Two layers, and the first hid the second. `applyCapabilityAnnotations` began with `if ann.Record == nil { continue }` — but `TopSupported`/`SkipSupported` are **standalone boolean terms** (`<Annotation Bool="false" Term="Org.OData.Capabilities.V1.TopSupported"/>`), not the record shape that `InsertRestrictions` and friends use, so the parser discarded them and `EdmEntitySet` had no field to hold them. `applyExternalEntityFields` then hardcoded `ent.SkipSupported = true; ent.TopSupported = true` — directly beside `Countable`, which *was* derived, and under a comment explaining the CE6630 mechanism the hardcode went on to trigger | `mdl/types/edmx.go` (`EdmEntitySet.TopSupported`/`SkipSupported`, `xmlCapabilitiesAnnotation.Bool`, standalone branch in `applyCapabilityAnnotations`), `mdl/executor/cmd_contract.go` (`applyExternalEntityFields`) | **The OData capabilities vocabulary has two annotation shapes, and a parser written against one silently drops the other.** Record terms (`InsertRestrictions`, `CountRestrictions`) wrap a `<Record>`; scalar terms (`TopSupported`, `SkipSupported`) carry `Bool` on the annotation element itself. The `Record == nil` guard read as "malformed, skip" when it actually meant "different, valid shape" — grep any capability parser for that guard before adding a term. **Absent must stay `true`, not `false`**: OData's own default is supported, so a tri-state `*bool` resolved as `p == nil || *p` is load-bearing — defaulting to false would invert CE6630 for every unannotated service, i.e. every service that worked before the fix. **This is the prerequisite for MDL-ODATA03's advice being followable**: the rule tells an author to declare `TopSupported: No` on a read-microflow resource, which was previously a trap that broke consumers. A fixture for this is worth capturing from a live `$metadata` rather than hand-written — the standalone shape is what made the bug, so a hand-built record-shaped fixture would have tested the wrong thing. Tests `mdl/types/edmx_test.go` (`TestParseEdmx_StandaloneTopAndSkipSupported`, plus a control proving record terms still parse), `mdl/executor/cmd_contract_capabilities_test.go`. mxcli-formula1 §42 |
 | `MDL-ODATA03` ("advertises TopSupported … so no paging is applied") is silenced by giving the read microflow a `System.HttpRequest` parameter — even when the parameter was added for the **KEY** and no paging was implemented. The half-fixed resource, which is the one still shipping unpaged 200s, is exactly the one the rule stops warning about | MDL-ODATA02 (KEY) and MDL-ODATA03 (paging) shared a single test — `takesHTTPRequest(decl)` — and answering either concern satisfied both. The rule could see whether the microflow *could* read the request, not whether it *did* | `mdl/executor/validate_odata_read_contract.go` (`capabilityViolations` now takes the declaration; `pagingEvidence`/`walkForPaging` reflect-walk the reachable body), `mdl-examples/doctype-tests/10-odata-examples.mdl` | **When one input satisfies two rules, the rules will silence each other.** The tell is a shared precondition that means something different to each check — grep for other validators keyed on the same `takesX()` helper before adding one. **The wire spelling is the evidence.** An OData query option is literally named `$top`, so a microflow implementing it must contain that text; presence of the text is weak evidence of handling, absence is strong evidence against — which is the only direction a rule that reports absences needs. **Reflect-walk, do not type-switch per statement**: MDL gains activity types regularly and a walker that misses one converts a false negative into a false *positive* ("nothing reads $top" about a body it never looked at). Reflection also picks up new nesting — loop bodies, if-branches, error handlers — for free. **Exclude `Annotations`/`Documentation`/`Comment` fields from the walk**: an `@annotation '$top is not applied here'` is prose admitting the defect, and counting it as implementation silences the rule on the one resource that documents the bug. **Keep an escape hatch and make it outrank the evidence**: a call into a Java action, a JavaScript action, a nanoflow, or a microflow the script does not define ends the analysis with silence — same stance the rule already took toward out-of-script read microflows. Follow calls into helpers the script *does* define, since real code factors paging out. **Report per option, not per resource** — flagging `SkipSupported` while `$top` is genuinely handled avoids advising an author to withdraw working support. **Shipped examples are part of the blast radius**: the doctype example's variant (a) was written to the old rationale ("taking `$Request` is enough to earn its silence") and started warning the moment the rule tightened — a changed rule needs `mxcli check` over `mdl-examples/` and then the integration gate, not just its own unit tests. Each guard has its own revert control (restore benefit-of-the-doubt / drop the annotation skip / drop `opaque` / stop following helpers), and all four reproduce. Tests `mdl/executor/validate_odata_read_contract_test.go`. mxcli-formula1 §42 |
+| `mxcli run --local` refuses to boot — *"port 6643 is already in use — a previous 'mxcli run --local' … is likely still serving on it"* — and names a process the user already killed. The guard is right to refuse; the diagnosis is a guess, and the recovery it suggests is a three-command `pgrep` hunt whose own pattern (`pgrep -f 'mxcli run'`) matches the shell it is typed into | Two different situations printed one message. mxcli **does** reap its children on Ctrl-C/SIGTERM (`procgroup_unix.go` puts mxbuild's JVM, the runtime and the bundler each in their own process group and signals the group), so a held port after a graceful stop is a *foreign* listener. But `kill -9`, a crash, or a reaped container runs no handler at all, and then it really is the previous run's orphan. The guard could not tell them apart because it never asked who held the port | `cmd/mxcli/docker/portowner_linux.go` (`listenerOnPort`, `parseListeningInodes`, `pidForSocketInode`), `portowner_other.go` (non-Linux stub), `portguard.go` (`portCulpritAdvice`), wired into `checkTargetPortsFree` (`runlocal.go`) and `checkLocalAppPortsFree` (`localapp.go`) | **Resolve the port owner from `/proc`, never by shelling out to `lsof`/`ss`** — both are routinely absent from slim containers, and needing a subprocess to explain why a boot failed is its own failure mode. `/proc/net/tcp{,6}` gives the socket inode; scanning `/proc/<pid>/fd` for `socket:[<inode>]` gives the pid. **Read `tcp6` as well as `tcp`**: a JVM binding "localhost" lands on `[::1]` or dual-stack `[::]` as often as `127.0.0.1`, and its local_address is a 128-bit hex blob, not the 32-bit one. **Filter on state `0A` (TCP_LISTEN)** — an ESTABLISHED socket on that port is a *client*, and naming it would tell the user to kill their own browser. **Report the two cases differently**: a leftover of a previous run gets `kill <pid>`, a foreign listener gets "pick another port" and no kill suggestion, because offering to kill a stranger's process is worse advice than the vague message it replaced. Keep the guard **detection-only** — reaping someone else's process stays the user's call. **Three test traps hit in a row here.** (1) The live-IPv6 test only ever *skipped* (no IPv6 in the container), so the tcp6 parser was effectively untested — assert against captured kernel output instead. (2) A parser test calling `parseListeningInodes` directly does not prove `listeningInodes` *opens* both files: deleting `/proc/net/tcp6` from the list left every test green. (3) Making the list a `var` so a test can point it at fixtures then means the test no longer covers the **shipped** default either — assert the default's contents before overriding it. Only the third version of that control failed. The best test in the file is the cheapest: bind a port in the test process and demand `listenerOnPort` return `os.Getpid()` — it cannot pass by accident. Tests `cmd/mxcli/docker/portowner_linux_test.go`. mxcli-formula1 suggested issue 8 |
diff --git a/.claude/skills/mendix/run-local.md b/.claude/skills/mendix/run-local.md
index 626f3a132..c9513672a 100644
--- a/.claude/skills/mendix/run-local.md
+++ b/.claude/skills/mendix/run-local.md
@@ -107,13 +107,26 @@ background-color: rgba($cf-over, 0.1);
 because a leftover `run --local` / `mxbuild --serve` / runtime would otherwise be
 silently adopted and keep serving old output (it looks like a cache but is a stale
 **process**). If a background `run --local` died while its serve+runtime kept serving,
-recover with:
+**the refusal names the pid** — on Linux it resolves the listener through `/proc`, so
+recovery is one command:
 
-```bash
-pgrep -af 'mxbuild --serve|runtimelauncher|mxcli run'   # find them
-kill <pid>                                              # stop each
-curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080  # want 000
 ```
+port 8080 (app) is already in use.
+  Held by pid 11893: /root/.mxcli/mxbuild/11.13.0/modeler/mxbuild --serve …
+  That is a leftover from an earlier run that did not shut down cleanly
+  (a kill -9 or a reaped container skips mxcli's own teardown).
+    kill 11893
+```
+
+It also distinguishes the two cases, which need opposite remedies: a leftover of a
+previous run is safe to kill, while a **foreign** listener (someone else's server on
+8080) is not — for that it says so and points at `--app-port`.
+
+Note that a *graceful* stop already reaps everything: `run --local` puts each child
+(mxbuild's JVM, the runtime, the rollup bundler) in its own process group and kills the
+group on Ctrl-C/SIGTERM. Reaching this error means the previous run was killed with
+`kill -9`, crashed, or had its container reaped — none of which run any handler. Do
+**not** `pkill -f 'mxcli run'`: that pattern also matches the shell you type it in.
 
 Launch `run --local` as the **sole** command in its invocation (don't chain a trailing
 `sleep`/`curl` whose non-zero exit can kill the backgrounded run); poll separately.
diff --git a/cmd/mxcli/docker/localapp.go b/cmd/mxcli/docker/localapp.go
index 8842a9c4b..2c4e3e029 100644
--- a/cmd/mxcli/docker/localapp.go
+++ b/cmd/mxcli/docker/localapp.go
@@ -271,7 +271,8 @@ func checkLocalAppPortsFree(o LocalAppOptions) error {
 	for _, p := range ports {
 		if err := pingTCP(fmt.Sprintf("127.0.0.1:%d", p.port), 300*time.Millisecond); err == nil {
 			return fmt.Errorf("port %d (%s) is already in use — stop the running instance first, "+
-				"or pass a different port", p.port, p.what)
+				"or pass a different port.\n%s",
+				p.port, p.what, portCulpritAdvice(p.port, "127.0.0.1", o.AppPort))
 		}
 	}
 	return nil
diff --git a/cmd/mxcli/docker/portguard.go b/cmd/mxcli/docker/portguard.go
new file mode 100644
index 000000000..16dd4f0c5
--- /dev/null
+++ b/cmd/mxcli/docker/portguard.go
@@ -0,0 +1,60 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package docker
+
+import (
+	"fmt"
+	"strings"
+)
+
+// portCulpritAdvice renders the "how do I get out of this" half of a
+// port-already-in-use error, naming the offending process when it can be
+// resolved (see portowner_linux.go).
+//
+// Why this is worth the code: the guard's diagnosis used to be a guess ("a
+// previous 'mxcli run --local' … is likely still serving on it") followed by a
+// pgrep hunt. The guess is wrong as often as it is right — an orphan of a
+// previous run and a colleague's unrelated server on 8080 need opposite
+// remedies — and one of the suggested commands, `pgrep -f 'mxcli run'`, matches
+// the shell it is typed into, so following the advice literally can kill your
+// own session. Naming the pid turns three commands into one.
+//
+// Every line is indented two spaces to sit under the error's first line.
+func portCulpritAdvice(port int, host string, appPort int) string {
+	confirm := fmt.Sprintf(
+		"    # confirm it is gone: curl -s -o /dev/null -w '%%{http_code}' http://%s:%d   (want 000)\n",
+		host, appPort)
+
+	owner, ok := listenerOnPort(port)
+	if !ok {
+		// Could not resolve — another user's process, or not Linux. Keep the
+		// generic hunt, minus the pgrep pattern that matches the caller's own
+		// shell.
+		return "  Find and stop whatever is holding it, then retry:\n" +
+			"    pgrep -af 'mxbuild|runtimelauncher'   # a previous run's orphans, if any\n" +
+			"    kill <pid>\n" + confirm
+	}
+
+	var b strings.Builder
+	fmt.Fprintf(&b, "  Held by pid %d", owner.PID)
+	if owner.Cmdline != "" {
+		fmt.Fprintf(&b, ": %s", owner.Cmdline)
+	}
+	b.WriteString("\n")
+
+	if owner.Ours {
+		// mxcli reaps its own children on Ctrl-C/SIGTERM, so reaching this state
+		// means the previous run did not exit gracefully (kill -9, a crash, or a
+		// reaped container). Saying so stops the user looking for a bug in the
+		// guard.
+		b.WriteString("  That is a leftover from an earlier run that did not shut down cleanly " +
+			"(a kill -9 or a reaped container skips mxcli's own teardown).\n")
+		fmt.Fprintf(&b, "    kill %d\n", owner.PID)
+		b.WriteString(confirm)
+		return b.String()
+	}
+
+	b.WriteString("  That is not a process mxcli started, so it is not a leftover run — " +
+		"pick another port rather than killing it.\n")
+	return b.String()
+}
diff --git a/cmd/mxcli/docker/portowner_linux.go b/cmd/mxcli/docker/portowner_linux.go
new file mode 100644
index 000000000..f47517519
--- /dev/null
+++ b/cmd/mxcli/docker/portowner_linux.go
@@ -0,0 +1,201 @@
+// SPDX-License-Identifier: Apache-2.0
+
+//go:build linux
+
+package docker
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+)
+
+// portowner_linux.go answers "which process is holding this port?" so the warm
+// loop's port guard can name it.
+//
+// The guard itself is correct and stays detection-only — reaping someone else's
+// process is the user's call. What was missing is the diagnosis. `mxcli run
+// --local` reaps its children on SIGINT/SIGTERM (see procgroup_unix.go), so a
+// held port after a *graceful* stop is someone else's process; but a `kill -9`,
+// a crash, or a reaped container runs no handler at all, and then the offender
+// is the previous run's orphaned mxbuild/JVM. Both cases print the same message
+// today, and it tells the user to go hunting with pgrep — three commands, one of
+// which (`pgrep -f 'mxcli run'`) matches the shell you typed it in.
+//
+// Resolution is via /proc, not lsof/ss: those are frequently absent from slim
+// containers, and shelling out to find out why a boot failed is its own failure
+// mode. /proc/net/tcp gives the socket inode of the listener; scanning
+// /proc/<pid>/fd for a link to that inode gives the owner.
+
+// portOwner describes the process listening on a local port.
+type portOwner struct {
+	PID     int
+	Cmdline string // argv joined with spaces, truncated
+	Ours    bool   // command line looks like a process mxcli spawns
+}
+
+// listenerOnPort identifies the process listening on 127.0.0.1:port (or on
+// 0.0.0.0/[::]:port). Returns ok=false when nothing can be resolved — a listener
+// owned by another user is the common case, since /proc/<pid>/fd is unreadable
+// then. Callers must degrade to the generic message rather than assert.
+func listenerOnPort(port int) (portOwner, bool) {
+	inodes := listeningInodes(port)
+	if len(inodes) == 0 {
+		return portOwner{}, false
+	}
+	pid, ok := pidForSocketInode(inodes)
+	if !ok {
+		return portOwner{}, false
+	}
+	cmd := processCmdline(pid)
+	return portOwner{PID: pid, Cmdline: cmd, Ours: looksLikeWarmLoopChild(cmd)}, true
+}
+
+// listeningInodes returns the socket inodes of every LISTEN socket bound to
+// port, across IPv4 and IPv6. Both are checked because a JVM binding "localhost"
+// usually lands on [::1] or a dual-stack [::], not 127.0.0.1.
+// procNetTCPFiles are the kernel tables listeningInodes reads. A var, not a
+// literal, so a test can prove BOTH are consulted — parsing tcp6 correctly is
+// worth nothing if the file is never opened, and a test that calls the parser
+// directly cannot tell the difference.
+var procNetTCPFiles = []string{"/proc/net/tcp", "/proc/net/tcp6"}
+
+func listeningInodes(port int) map[string]bool {
+	out := map[string]bool{}
+	for _, f := range procNetTCPFiles {
+		data, err := os.ReadFile(f)
+		if err != nil {
+			continue
+		}
+		for ino := range parseListeningInodes(string(data), port) {
+			out[ino] = true
+		}
+	}
+	return out
+}
+
+// parseListeningInodes extracts the socket inodes of LISTEN sockets on port from
+// the contents of /proc/net/tcp or /proc/net/tcp6.
+//
+// Split out from the file reading so both address families can be tested
+// wherever the suite runs: this container has no IPv6, and a test that only ever
+// skips proves nothing about the tcp6 path — which is the one that matters, since
+// a JVM binding "localhost" usually lands on [::1] or a dual-stack [::].
+func parseListeningInodes(contents string, port int) map[string]bool {
+	out := map[string]bool{}
+	lines := strings.Split(contents, "\n")
+	if len(lines) > 0 {
+		lines = lines[1:] // header
+	}
+	for _, line := range lines {
+		fields := strings.Fields(line)
+		// sl(0) local_address(1) remote_address(2) st(3) … inode(9)
+		if len(fields) < 10 {
+			continue
+		}
+		// 0A is TCP_LISTEN. An established connection *to* the port is not the
+		// owner of it, and counting one would name a client as the culprit.
+		if fields[3] != "0A" {
+			continue
+		}
+		if p, ok := hexPort(fields[1]); !ok || p != port {
+			continue
+		}
+		out[fields[9]] = true
+	}
+	return out
+}
+
+// hexPort extracts the port from a /proc/net/tcp local_address ("0100007F:1F90").
+func hexPort(addr string) (int, bool) {
+	i := strings.LastIndex(addr, ":")
+	if i < 0 {
+		return 0, false
+	}
+	n, err := strconv.ParseUint(addr[i+1:], 16, 32)
+	if err != nil {
+		return 0, false
+	}
+	return int(n), true
+}
+
+// pidForSocketInode finds the process holding any of the given socket inodes.
+//
+// A socket may be shared by several processes (a forked pre-forking server), and
+// any of them will do for the message — the user needs a thread to pull, not a
+// census. The lowest PID is chosen so repeated runs name the same one.
+func pidForSocketInode(inodes map[string]bool) (int, bool) {
+	want := map[string]bool{}
+	for ino := range inodes {
+		want["socket:["+ino+"]"] = true
+	}
+	entries, err := os.ReadDir("/proc")
+	if err != nil {
+		return 0, false
+	}
+	best := 0
+	for _, e := range entries {
+		pid, err := strconv.Atoi(e.Name())
+		if err != nil {
+			continue // not a pid directory
+		}
+		fds, err := os.ReadDir(filepath.Join("/proc", e.Name(), "fd"))
+		if err != nil {
+			continue // another user's process, or it exited mid-scan
+		}
+		for _, fd := range fds {
+			link, err := os.Readlink(filepath.Join("/proc", e.Name(), "fd", fd.Name()))
+			if err != nil {
+				continue
+			}
+			if want[link] {
+				if best == 0 || pid < best {
+					best = pid
+				}
+				break
+			}
+		}
+	}
+	return best, best != 0
+}
+
+// processCmdline reads a process's argv, NUL-separated in /proc, and renders it
+// on one line. Long Java command lines are truncated: the JVM's is thousands of
+// characters of classpath, and printing it buries the error it is attached to.
+func processCmdline(pid int) string {
+	data, err := os.ReadFile(fmt.Sprintf("/proc/%d/cmdline", pid))
+	if err != nil {
+		return ""
+	}
+	args := strings.FieldsFunc(string(data), func(r rune) bool { return r == 0 })
+	line := strings.Join(args, " ")
+	const max = 120
+	if len(line) > max {
+		line = line[:max] + "…"
+	}
+	return line
+}
+
+// looksLikeWarmLoopChild reports whether a command line matches something the
+// warm loop starts. This decides which advice to print, and the two are
+// genuinely different: an orphan of a previous run is safe to kill, while a
+// foreign listener means the port is simply taken and the right move is
+// --app-port.
+func looksLikeWarmLoopChild(cmdline string) bool {
+	if cmdline == "" {
+		return false
+	}
+	for _, sig := range []string{
+		"mxbuild",         // the serve process (a wrapper script, or its JVM)
+		"runtimelauncher", // the standalone runtime
+		"RuntimeLauncher",
+		"mxcli", // a previous run still alive
+	} {
+		if strings.Contains(cmdline, sig) {
+			return true
+		}
+	}
+	return false
+}
diff --git a/cmd/mxcli/docker/portowner_linux_test.go b/cmd/mxcli/docker/portowner_linux_test.go
new file mode 100644
index 000000000..507106104
--- /dev/null
+++ b/cmd/mxcli/docker/portowner_linux_test.go
@@ -0,0 +1,239 @@
+// SPDX-License-Identifier: Apache-2.0
+
+//go:build linux
+
+package docker
+
+import (
+	"fmt"
+	"net"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+// listenOnLoopback binds an ephemeral port and returns it, closing on cleanup.
+func listenOnLoopback(t *testing.T, network, addr string) int {
+	t.Helper()
+	ln, err := net.Listen(network, addr)
+	if err != nil {
+		t.Skipf("cannot bind %s %s here: %v", network, addr, err)
+	}
+	t.Cleanup(func() { _ = ln.Close() })
+	_, portStr, err := net.SplitHostPort(ln.Addr().String())
+	if err != nil {
+		t.Fatalf("splitting %s: %v", ln.Addr(), err)
+	}
+	var port int
+	if _, err := fmt.Sscanf(portStr, "%d", &port); err != nil {
+		t.Fatalf("parsing port %q: %v", portStr, err)
+	}
+	return port
+}
+
+// The whole point of the lookup is to name a real pid, so the test holds the
+// port itself and demands its own — an assertion that cannot pass by accident.
+//
+// mxcli-formula1 suggested issue 8: the guard was right to refuse, but told the
+// user to go hunting with pgrep, and one of the suggested patterns
+// (`pgrep -f 'mxcli run'`) matches the shell it is typed into.
+func TestListenerOnPort_IdentifiesThisProcess(t *testing.T) {
+	port := listenOnLoopback(t, "tcp", "127.0.0.1:0")
+
+	owner, ok := listenerOnPort(port)
+	if !ok {
+		t.Fatalf("port %d is held by this test process but no owner was resolved", port)
+	}
+	if owner.PID != os.Getpid() {
+		t.Errorf("owner pid = %d, want this process (%d)", owner.PID, os.Getpid())
+	}
+	if owner.Cmdline == "" {
+		t.Error("no command line resolved; the message would name a bare pid")
+	}
+}
+
+// A Mendix runtime binding "localhost" lands on IPv6 as often as not, so
+// /proc/net/tcp6 has to be parsed too — and its local_address is a 128-bit hex
+// blob, not the 32-bit one in /proc/net/tcp. Both are asserted against captured
+// kernel output rather than a live socket, because this container has no IPv6
+// and a test that only skips proves nothing about the path it names.
+//
+// 8090 is 0x1F9A; 6543 is 0x198F.
+func TestParseListeningInodes_BothAddressFamilies(t *testing.T) {
+	const tcp4 = `  sl  local_address rem_address   st tx_queue rx_queue tr tm->when retrnsmt   uid  timeout inode
+   0: 0100007F:198F 00000000:0000 0A 00000000:00000000 00:00000000 00000000     0        0 4242 1 0000000000000000 100 0 0 10 0
+`
+	const tcp6 = `  sl  local_address                         remote_address                        st tx_queue rx_queue tr tm->when retrnsmt   uid  timeout inode
+   0: 00000000000000000000000000000000:1F9A 00000000000000000000000000000000:0000 0A 00000000:00000000 00:00000000 00000000     0        0 9999 1 0000000000000000 100 0 0 10 0
+`
+	if got := parseListeningInodes(tcp4, 6543); !got["4242"] {
+		t.Errorf("IPv4 listener on 6543 not found, got %v", got)
+	}
+	if got := parseListeningInodes(tcp6, 8090); !got["9999"] {
+		t.Errorf("IPv6 listener on 8090 not found — the 128-bit local_address is not being parsed, got %v", got)
+	}
+}
+
+// An established connection to a port is not the owner of it. Without the
+// TCP_LISTEN filter, a client of the app would be named as the culprit and the
+// advice would tell the user to kill their own browser.
+func TestParseListeningInodes_IgnoresEstablishedConnections(t *testing.T) {
+	// 01 is TCP_ESTABLISHED. Same port (0x1F90 = 8080), different state.
+	const established = `  sl  local_address rem_address   st tx_queue rx_queue tr tm->when retrnsmt   uid  timeout inode
+   0: 0100007F:1F90 0100007F:C001 01 00000000:00000000 00:00000000 00000000     0        0 7777 1 0000000000000000 100 0 0 10 0
+`
+	if got := parseListeningInodes(established, 8080); len(got) != 0 {
+		t.Errorf("an ESTABLISHED socket was treated as the port's owner: %v", got)
+	}
+}
+
+// Parsing tcp6 correctly is worth nothing if the file is never opened, and the
+// parser tests above cannot tell the difference — dropping "/proc/net/tcp6" from
+// the list left every one of them green. This points the reader at fixtures and
+// asserts an inode is picked up from EACH table.
+func TestListeningInodes_ReadsBothKernelTables(t *testing.T) {
+	dir := t.TempDir()
+	v4 := filepath.Join(dir, "tcp")
+	v6 := filepath.Join(dir, "tcp6")
+	// Same port (0x198F = 6543) in both tables, distinct inodes.
+	if err := os.WriteFile(v4, []byte(
+		"  sl  local_address rem_address   st … inode\n"+
+			"   0: 0100007F:198F 00000000:0000 0A 00000000:00000000 00:00000000 00000000 0 0 4242 1 0 100 0 0 10 0\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.WriteFile(v6, []byte(
+		"  sl  local_address                         remote_address                        st … inode\n"+
+			"   0: 00000000000000000000000000000000:198F 00000000000000000000000000000000:0000 0A 00000000:00000000 00:00000000 00000000 0 0 9999 1 0 100 0 0 10 0\n"), 0o600); err != nil {
+		t.Fatal(err)
+	}
+
+	orig := procNetTCPFiles
+	// Overriding the list is what makes the rest of this testable, and it is also
+	// what stops the override from proving anything about the SHIPPED list — so
+	// the default is asserted first. Dropping "/proc/net/tcp6" from it left every
+	// other test here green.
+	for _, want := range []string{"/proc/net/tcp", "/proc/net/tcp6"} {
+		found := false
+		for _, f := range orig {
+			if f == want {
+				found = true
+			}
+		}
+		if !found {
+			t.Errorf("procNetTCPFiles does not include %s, so that family is never read: %v", want, orig)
+		}
+	}
+
+	procNetTCPFiles = []string{v4, v6}
+	t.Cleanup(func() { procNetTCPFiles = orig })
+
+	got := listeningInodes(6543)
+	if !got["4242"] {
+		t.Errorf("/proc/net/tcp is not being read, got %v", got)
+	}
+	if !got["9999"] {
+		t.Errorf("/proc/net/tcp6 is not being read — an IPv6-bound runtime would go unnamed, got %v", got)
+	}
+}
+
+// A live IPv6 listener, where the environment has one. Skipped here (no IPv6),
+// which is why the parser and wiring tests above carry the real weight.
+func TestListenerOnPort_FindsAnIPv6Listener(t *testing.T) {
+	port := listenOnLoopback(t, "tcp6", "[::1]:0")
+
+	owner, ok := listenerOnPort(port)
+	if !ok {
+		t.Fatalf("IPv6 listener on %d not resolved — /proc/net/tcp6 is not being read", port)
+	}
+	if owner.PID != os.Getpid() {
+		t.Errorf("owner pid = %d, want this process (%d)", owner.PID, os.Getpid())
+	}
+}
+
+// Nothing listening must resolve to nothing. If any socket state matched, a free
+// port would name some unrelated process and the advice would be worse than the
+// generic message it replaced.
+func TestListenerOnPort_QuietWhenNothingIsListening(t *testing.T) {
+	port := listenOnLoopback(t, "tcp", "127.0.0.1:0")
+	// Re-resolve after the listener is closed: the port is now free.
+	owner, ok := listenerOnPort(port)
+	if ok {
+		// Only fail if it resolved to something while the port is still ours to
+		// claim — a racing process could legitimately take it.
+		if ln, err := net.Listen("tcp", fmt.Sprintf("127.0.0.1:%d", port)); err == nil {
+			_ = ln.Close()
+			t.Errorf("free port %d resolved to pid %d (%s)", port, owner.PID, owner.Cmdline)
+		}
+	}
+}
+
+func TestLooksLikeWarmLoopChild(t *testing.T) {
+	for _, tc := range []struct {
+		name    string
+		cmdline string
+		want    bool
+	}{
+		{"mxbuild serve", "/root/.mxcli/mxbuild/11.13.0/modeler/mxbuild --serve", true},
+		{"runtime launcher", "java -cp … com.mendix.runtimelauncher.RuntimeLauncher", true},
+		{"a previous mxcli", "mxcli run --local -p app.mpr", true},
+		{"someone else's server", "python3 -m http.server 8080", false},
+		{"unresolvable", "", false},
+	} {
+		t.Run(tc.name, func(t *testing.T) {
+			if got := looksLikeWarmLoopChild(tc.cmdline); got != tc.want {
+				t.Errorf("looksLikeWarmLoopChild(%q) = %v, want %v", tc.cmdline, got, tc.want)
+			}
+		})
+	}
+}
+
+// The advice is the deliverable, not the lookup, so it is asserted through the
+// same function the error message calls.
+func TestPortCulpritAdvice_NamesThePidAndGivesOneCommand(t *testing.T) {
+	port := listenOnLoopback(t, "tcp", "127.0.0.1:0")
+
+	advice := portCulpritAdvice(port, "127.0.0.1", port)
+	if !strings.Contains(advice, fmt.Sprintf("pid %d", os.Getpid())) {
+		t.Errorf("advice does not name the holding pid %d:\n%s", os.Getpid(), advice)
+	}
+	if strings.Contains(advice, "pgrep") {
+		t.Errorf("the pid is known, so the pgrep hunt must be gone:\n%s", advice)
+	}
+}
+
+// A foreign listener and a leftover child need opposite remedies — kill it, or
+// leave it alone and move ports — so the advice must not offer `kill` for a
+// process mxcli did not start.
+func TestPortCulpritAdvice_DoesNotOfferToKillAForeignProcess(t *testing.T) {
+	port := listenOnLoopback(t, "tcp", "127.0.0.1:0")
+	owner, ok := listenerOnPort(port)
+	if !ok {
+		t.Skip("owner not resolvable here")
+	}
+	if owner.Ours {
+		// The test binary happens to match the warm-loop signature (it can, when
+		// run from a path containing "mxcli"); this case cannot be exercised.
+		t.Skipf("test process looks like a warm-loop child: %s", owner.Cmdline)
+	}
+	advice := portCulpritAdvice(port, "127.0.0.1", port)
+	if strings.Contains(advice, fmt.Sprintf("kill %d", os.Getpid())) {
+		t.Errorf("offered to kill a foreign process:\n%s", advice)
+	}
+	if !strings.Contains(advice, "not a process mxcli started") {
+		t.Errorf("advice does not say the holder is foreign:\n%s", advice)
+	}
+}
+
+// End to end through the real guard: the error a user sees carries the pid.
+func TestCheckTargetPortsFree_ErrorNamesTheHolder(t *testing.T) {
+	port := listenOnLoopback(t, "tcp", "127.0.0.1:0")
+
+	err := checkTargetPortsFree(LocalRunOptions{AppPort: port, AdminPort: 0, ServePort: 0})
+	if err == nil {
+		t.Fatal("a held app port must be refused")
+	}
+	if !strings.Contains(err.Error(), fmt.Sprintf("pid %d", os.Getpid())) {
+		t.Errorf("the refusal does not name the holder:\n%v", err)
+	}
+}
diff --git a/cmd/mxcli/docker/portowner_other.go b/cmd/mxcli/docker/portowner_other.go
new file mode 100644
index 000000000..0976d4900
--- /dev/null
+++ b/cmd/mxcli/docker/portowner_other.go
@@ -0,0 +1,17 @@
+// SPDX-License-Identifier: Apache-2.0
+
+//go:build !linux
+
+package docker
+
+// portOwner describes the process listening on a local port. Only Linux can
+// resolve it from /proc without shelling out, so elsewhere the port guard keeps
+// its generic wording rather than depending on lsof being installed.
+type portOwner struct {
+	PID     int
+	Cmdline string
+	Ours    bool
+}
+
+// listenerOnPort always reports "unknown" off Linux.
+func listenerOnPort(port int) (portOwner, bool) { return portOwner{}, false }
diff --git a/cmd/mxcli/docker/runlocal.go b/cmd/mxcli/docker/runlocal.go
index a8725dc66..8911a41b0 100644
--- a/cmd/mxcli/docker/runlocal.go
+++ b/cmd/mxcli/docker/runlocal.go
@@ -423,14 +423,11 @@ func checkTargetPortsFree(o LocalRunOptions) error {
 	} {
 		hostPort := fmt.Sprintf("%s:%d", host, c.port)
 		if err := pingTCP(hostPort, 500*time.Millisecond); err == nil {
-			return fmt.Errorf("port %d (%s) is already in use — a previous 'mxcli run --local' "+
-				"or a stray mxbuild --serve/runtime is likely still serving on it.\n"+
+			return fmt.Errorf("port %d (%s) is already in use.\n"+
 				"  A stale process is silently adopted otherwise, so edits appear to do nothing (looks like a stale cache — it isn't).\n"+
-				"  Free the ports, then retry:\n"+
-				"    pgrep -af 'mxbuild --serve|runtimelauncher|mxcli run'   # find them\n"+
-				"    kill <pid>                                             # stop each; confirm with: curl -s -o /dev/null -w '%%{http_code}' http://%s:%d  (want 000)\n"+
+				"%s"+
 				"  Or run on different ports with %s (and --admin-port/--serve-port).",
-				c.port, c.role, host, o.AppPort, c.flag)
+				c.port, c.role, portCulpritAdvice(c.port, host, o.AppPort), c.flag)
 		}
 	}
 	return nil
diff --git a/docs-site/src/tools/run-local.md b/docs-site/src/tools/run-local.md
index d5de0f008..f08e2153c 100644
--- a/docs-site/src/tools/run-local.md
+++ b/docs-site/src/tools/run-local.md
@@ -282,16 +282,42 @@ If you started `run --local` in the background and the wrapping shell exited non
 (e.g. a chained `sleep`/`curl` that failed), the `run --local` process can die while
 its `mxbuild --serve` + runtime keep serving on `:8080`. Launch `run --local` as the
 **sole** command in its own invocation — don't chain a `sleep`/status check after it in
-the same shell — and poll separately. To recover from a stale process:
+the same shell — and poll separately.
+
+**The refusal names the offending process.** On Linux mxcli resolves the port's
+listener through `/proc` and prints its pid and command line, so recovery is one
+command rather than a `pgrep` hunt:
+
+```
+port 8080 (app) is already in use.
+  A stale process is silently adopted otherwise, so edits appear to do nothing
+  (looks like a stale cache — it isn't).
+  Held by pid 11893: /root/.mxcli/mxbuild/11.13.0/modeler/mxbuild --serve …
+  That is a leftover from an earlier run that did not shut down cleanly
+  (a kill -9 or a reaped container skips mxcli's own teardown).
+    kill 11893
+    # confirm it is gone: curl -s -o /dev/null -w '%{http_code}' http://127.0.0.1:8080   (want 000)
+  Or run on different ports with --app-port (and --admin-port/--serve-port).
+```
+
+The two cases need opposite remedies, so they are reported differently. A **leftover
+of a previous run** is safe to kill, as above. A **foreign** listener — anything mxcli
+did not start — is not, and mxcli says so instead of offering a `kill`:
 
-```bash
-pgrep -af 'mxbuild --serve|runtimelauncher|mxcli run'   # find them
-kill <pid>                                              # stop each
-curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:8080  # want 000 (port free)
 ```
+  Held by pid 4820: python3 -m http.server 8080
+  That is not a process mxcli started, so it is not a leftover run —
+  pick another port rather than killing it.
+```
+
+Off Linux, or when the listener belongs to another user (so `/proc/<pid>/fd` cannot be
+read), it falls back to a generic hint.
 
-Then start `run --local` again. Or run on different ports with `--app-port` /
-`--admin-port` / `--serve-port`.
+A *graceful* stop needs none of this: each child — mxbuild's JVM, the runtime, the
+rollup bundler — is started in its own process group and the whole group is killed on
+Ctrl-C/SIGTERM. Seeing this error means the previous run never got to run its teardown:
+`kill -9`, a crash, or a reaped container. Avoid `pkill -f 'mxcli run'` — that pattern
+also matches the shell you type it into.
 
 ## Pages render in the browser
 

From 66c938b0ef84a9305da81f22559a38c2af5474af Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 9 Aug 2026 20:05:45 +0000
Subject: [PATCH 23/29] fix(odata): honour the whole-set form of Filter/Sort
 restrictions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

FilterRestrictions and SortRestrictions have two shapes and only one was
read. The parser pulled NonFilterableProperties out of the record and
ignored the record's own Bool property, so `Filterable:
!nonFilterable[p.Name]` was true for every property of a set that had
declared nothing filterable — 28 × CE6630 on one service:

    'message' is marked Sortable=False in the OData service,
    but True in the app.

Mendix picks the shape by arithmetic, not preference: it lists
NonFilterableProperties when SOME attributes are filterable, and emits a
bare `Bool="false" Property="Filterable"` when NONE are, because then
there is no list to write. Both appear in one document, on different
entity sets — an entity exposing only a KEY produces the whole-set form.

Both shapes now sit behind EdmEntitySet.AttrFilterable/AttrSortable, so
a caller cannot consult one and forget the other, which is how this
arose. The accessors are nil-safe, which also removes the entitySet !=
nil dance at the call site. Absent still means true: OData's default is
allowed.

This is the sibling of the Top/Skip fix in 27ea1da — same vocabulary,
same two-shapes cause, found because a consuming app failed to build.

mxcli-formula1 §48
---
 .claude/skills/fix-issue.md                 |  1 +
 .claude/skills/mendix/odata-data-sharing.md | 25 ++++--
 mdl/executor/cmd_contract.go                | 17 ++--
 mdl/types/edmx.go                           | 95 ++++++++++++++++++++-
 mdl/types/edmx_test.go                      | 93 ++++++++++++++++++++
 5 files changed, 211 insertions(+), 20 deletions(-)

diff --git a/.claude/skills/fix-issue.md b/.claude/skills/fix-issue.md
index 5dfd4f6b9..bfe655dfa 100644
--- a/.claude/skills/fix-issue.md
+++ b/.claude/skills/fix-issue.md
@@ -444,3 +444,4 @@ extracting `OffsetExpression`/`LimitExpression`.
 | A service that correctly declares `TopSupported: No` cannot be consumed: `sql <alias> generate connector` / contract import produces an app whose external entity says `Supports $top = True`, and the **consumer** build fails **CE6630** "'Seasons' is marked supports $top=False in the OData service, but True in the app". The publisher is right, the contract is right, and only the generated consumer is wrong | Two layers, and the first hid the second. `applyCapabilityAnnotations` began with `if ann.Record == nil { continue }` — but `TopSupported`/`SkipSupported` are **standalone boolean terms** (`<Annotation Bool="false" Term="Org.OData.Capabilities.V1.TopSupported"/>`), not the record shape that `InsertRestrictions` and friends use, so the parser discarded them and `EdmEntitySet` had no field to hold them. `applyExternalEntityFields` then hardcoded `ent.SkipSupported = true; ent.TopSupported = true` — directly beside `Countable`, which *was* derived, and under a comment explaining the CE6630 mechanism the hardcode went on to trigger | `mdl/types/edmx.go` (`EdmEntitySet.TopSupported`/`SkipSupported`, `xmlCapabilitiesAnnotation.Bool`, standalone branch in `applyCapabilityAnnotations`), `mdl/executor/cmd_contract.go` (`applyExternalEntityFields`) | **The OData capabilities vocabulary has two annotation shapes, and a parser written against one silently drops the other.** Record terms (`InsertRestrictions`, `CountRestrictions`) wrap a `<Record>`; scalar terms (`TopSupported`, `SkipSupported`) carry `Bool` on the annotation element itself. The `Record == nil` guard read as "malformed, skip" when it actually meant "different, valid shape" — grep any capability parser for that guard before adding a term. **Absent must stay `true`, not `false`**: OData's own default is supported, so a tri-state `*bool` resolved as `p == nil || *p` is load-bearing — defaulting to false would invert CE6630 for every unannotated service, i.e. every service that worked before the fix. **This is the prerequisite for MDL-ODATA03's advice being followable**: the rule tells an author to declare `TopSupported: No` on a read-microflow resource, which was previously a trap that broke consumers. A fixture for this is worth capturing from a live `$metadata` rather than hand-written — the standalone shape is what made the bug, so a hand-built record-shaped fixture would have tested the wrong thing. Tests `mdl/types/edmx_test.go` (`TestParseEdmx_StandaloneTopAndSkipSupported`, plus a control proving record terms still parse), `mdl/executor/cmd_contract_capabilities_test.go`. mxcli-formula1 §42 |
 | `MDL-ODATA03` ("advertises TopSupported … so no paging is applied") is silenced by giving the read microflow a `System.HttpRequest` parameter — even when the parameter was added for the **KEY** and no paging was implemented. The half-fixed resource, which is the one still shipping unpaged 200s, is exactly the one the rule stops warning about | MDL-ODATA02 (KEY) and MDL-ODATA03 (paging) shared a single test — `takesHTTPRequest(decl)` — and answering either concern satisfied both. The rule could see whether the microflow *could* read the request, not whether it *did* | `mdl/executor/validate_odata_read_contract.go` (`capabilityViolations` now takes the declaration; `pagingEvidence`/`walkForPaging` reflect-walk the reachable body), `mdl-examples/doctype-tests/10-odata-examples.mdl` | **When one input satisfies two rules, the rules will silence each other.** The tell is a shared precondition that means something different to each check — grep for other validators keyed on the same `takesX()` helper before adding one. **The wire spelling is the evidence.** An OData query option is literally named `$top`, so a microflow implementing it must contain that text; presence of the text is weak evidence of handling, absence is strong evidence against — which is the only direction a rule that reports absences needs. **Reflect-walk, do not type-switch per statement**: MDL gains activity types regularly and a walker that misses one converts a false negative into a false *positive* ("nothing reads $top" about a body it never looked at). Reflection also picks up new nesting — loop bodies, if-branches, error handlers — for free. **Exclude `Annotations`/`Documentation`/`Comment` fields from the walk**: an `@annotation '$top is not applied here'` is prose admitting the defect, and counting it as implementation silences the rule on the one resource that documents the bug. **Keep an escape hatch and make it outrank the evidence**: a call into a Java action, a JavaScript action, a nanoflow, or a microflow the script does not define ends the analysis with silence — same stance the rule already took toward out-of-script read microflows. Follow calls into helpers the script *does* define, since real code factors paging out. **Report per option, not per resource** — flagging `SkipSupported` while `$top` is genuinely handled avoids advising an author to withdraw working support. **Shipped examples are part of the blast radius**: the doctype example's variant (a) was written to the old rationale ("taking `$Request` is enough to earn its silence") and started warning the moment the rule tightened — a changed rule needs `mxcli check` over `mdl-examples/` and then the integration gate, not just its own unit tests. Each guard has its own revert control (restore benefit-of-the-doubt / drop the annotation skip / drop `opaque` / stop following helpers), and all four reproduce. Tests `mdl/executor/validate_odata_read_contract_test.go`. mxcli-formula1 §42 |
 | `mxcli run --local` refuses to boot — *"port 6643 is already in use — a previous 'mxcli run --local' … is likely still serving on it"* — and names a process the user already killed. The guard is right to refuse; the diagnosis is a guess, and the recovery it suggests is a three-command `pgrep` hunt whose own pattern (`pgrep -f 'mxcli run'`) matches the shell it is typed into | Two different situations printed one message. mxcli **does** reap its children on Ctrl-C/SIGTERM (`procgroup_unix.go` puts mxbuild's JVM, the runtime and the bundler each in their own process group and signals the group), so a held port after a graceful stop is a *foreign* listener. But `kill -9`, a crash, or a reaped container runs no handler at all, and then it really is the previous run's orphan. The guard could not tell them apart because it never asked who held the port | `cmd/mxcli/docker/portowner_linux.go` (`listenerOnPort`, `parseListeningInodes`, `pidForSocketInode`), `portowner_other.go` (non-Linux stub), `portguard.go` (`portCulpritAdvice`), wired into `checkTargetPortsFree` (`runlocal.go`) and `checkLocalAppPortsFree` (`localapp.go`) | **Resolve the port owner from `/proc`, never by shelling out to `lsof`/`ss`** — both are routinely absent from slim containers, and needing a subprocess to explain why a boot failed is its own failure mode. `/proc/net/tcp{,6}` gives the socket inode; scanning `/proc/<pid>/fd` for `socket:[<inode>]` gives the pid. **Read `tcp6` as well as `tcp`**: a JVM binding "localhost" lands on `[::1]` or dual-stack `[::]` as often as `127.0.0.1`, and its local_address is a 128-bit hex blob, not the 32-bit one. **Filter on state `0A` (TCP_LISTEN)** — an ESTABLISHED socket on that port is a *client*, and naming it would tell the user to kill their own browser. **Report the two cases differently**: a leftover of a previous run gets `kill <pid>`, a foreign listener gets "pick another port" and no kill suggestion, because offering to kill a stranger's process is worse advice than the vague message it replaced. Keep the guard **detection-only** — reaping someone else's process stays the user's call. **Three test traps hit in a row here.** (1) The live-IPv6 test only ever *skipped* (no IPv6 in the container), so the tcp6 parser was effectively untested — assert against captured kernel output instead. (2) A parser test calling `parseListeningInodes` directly does not prove `listeningInodes` *opens* both files: deleting `/proc/net/tcp6` from the list left every test green. (3) Making the list a `var` so a test can point it at fixtures then means the test no longer covers the **shipped** default either — assert the default's contents before overriding it. Only the third version of that control failed. The best test in the file is the cheapest: bind a port in the test process and demand `listenerOnPort` return `os.Getpid()` — it cannot pass by accident. Tests `cmd/mxcli/docker/portowner_linux_test.go`. mxcli-formula1 suggested issue 8 |
+| `create external entities from` a service where an entity set is wholly unfilterable/unsortable generates an app the contract contradicts: **28 × CE6630** on one service — "'message' is marked Sortable=False in the OData service, but True in the app". The publisher is right, the `$metadata` is right, only the generated consumer is wrong | `FilterRestrictions`/`SortRestrictions` have **two shapes**, and only one was read. `applyCapabilityAnnotations` pulled `NonFilterableProperties` out of the record and ignored the record's own `Bool` property value, so `Filterable: !nonFilterable[p.Name]` evaluated `true` for every property of a set that had declared nothing filterable. This is the §42 Top/Skip bug one layer along — same vocabulary, same two-shapes cause, different term | `mdl/types/edmx.go` (`EdmEntitySet.Filterable`/`Sortable`, the `Filterable`/`Sortable` cases in `applyCapabilityAnnotations`, and the `AttrFilterable`/`AttrSortable` accessors), `mdl/executor/cmd_contract.go` (`createExternalEntities` calls the accessors) | **Mendix picks the annotation shape by arithmetic, not preference.** It lists `NonFilterableProperties` when SOME attributes are filterable and emits a bare `<PropertyValue Bool="false" Property="Filterable"/>` when NONE are, because then there is no list to write — so both shapes appear in **one document** on different entity sets, and an entity exposing only a KEY reliably produces the whole-set form. A fixture with just the list shape tests the half that already worked. **After fixing one term in a vocabulary, sweep the siblings**: §42 fixed Top/Skip by teaching the parser about standalone booleans and stopped there; Filterable/Sortable had the same defect and were found only because a consumer app failed to build. Grep the whole `applyCapabilityAnnotations` switch for terms whose Bool is never read. **Put both shapes behind one accessor** (`AttrFilterable`) rather than two fields the caller must remember to AND together — the caller then cannot consult one and forget the other, which is exactly how this arose, and the nil-safe receiver deletes the `entitySet != nil` dance at the call site. Absent still means `true`: OData's default is allowed, and defaulting to false would invert CE6630 for every unannotated service. Tests `mdl/types/edmx_test.go` (`TestParseEdmx_WholeSetFilterAndSortRestrictions`, plus a control proving the list shape still parses); both controls reproduce (ignore the record Bool → the whole-set test fails with the CE6630 message; drop the check inside `AttrFilterable` → same). mxcli-formula1 §48 |
diff --git a/.claude/skills/mendix/odata-data-sharing.md b/.claude/skills/mendix/odata-data-sharing.md
index 3b605b6f8..627322a13 100644
--- a/.claude/skills/mendix/odata-data-sharing.md
+++ b/.claude/skills/mendix/odata-data-sharing.md
@@ -542,12 +542,25 @@ publish entity Api.Row as 'Rows' (
 ```
 
 Declaring `No` is the read path's substitute for the `400` it cannot send. It is
-also safe to declare: the contract carries `TopSupported`/`SkipSupported` as
-standalone boolean annotations, and `sql <alias> generate connector` reads them,
-so a consuming app generated from this service says `No` too. (Until mxcli
-learned to read them it always generated `Yes`, and the consumer failed to build
-with **CE6630** "'Rows' is marked supports $top=False in the OData service, but
-True in the app" — if you hit that against an older mxcli, that is the cause.)
+also safe to declare: mxcli reads these capabilities off the contract, so a
+consuming app generated from this service says `No` too. (Until it learned to,
+the generator always said `Yes`, and the consumer failed to build with **CE6630**
+"'Rows' is marked supports $top=False in the OData service, but True in the app"
+— if you hit that against an older mxcli, that is the cause.)
+
+**The capabilities vocabulary has two annotation shapes**, and it is worth knowing
+which you are looking at when reading a `$metadata` by hand:
+
+| Capability | Shape |
+|---|---|
+| `TopSupported`, `SkipSupported` | standalone: `<Annotation Bool="false" Term="…TopSupported"/>` |
+| `Insertable`, `Updatable`, `Deletable`, `Countable` | a `<Record>` with a `Bool` property value |
+| `Filterable`, `Sortable` | **either** — a record listing `NonFilterableProperties` when *some* attributes are filterable, or a bare `Bool="false"` on the record when *none* are |
+
+That last row is the trap. Mendix picks the shape by arithmetic (there is no list
+to write when nothing is filterable), so both appear in one document on different
+entity sets, and a service where an entity exposes only a KEY emits the whole-set
+form.
 
 `mxcli check` enforces this as **MDL-ODATA03**, and it looks for the option
 *names* in the microflow body, not just for a `System.HttpRequest` parameter —
diff --git a/mdl/executor/cmd_contract.go b/mdl/executor/cmd_contract.go
index 5df71619c..f733c63d1 100644
--- a/mdl/executor/cmd_contract.go
+++ b/mdl/executor/cmd_contract.go
@@ -612,8 +612,11 @@ func createExternalEntities(ctx *ExecContext, s *ast.CreateExternalEntitiesStmt)
 			// ("'latitude' is marked Filterable=False in the OData service, but
 			// True in the app") — one per property, on an import whose whole job
 			// is to match the contract.
-			nonFilterable := make(map[string]bool)
-			nonSortable := make(map[string]bool)
+			// Both restrictions have two shapes — a per-property exclusion list and
+			// a whole-set boolean — so they are resolved by EdmEntitySet rather
+			// than read field by field here; consulting one shape and not the
+			// other is what produced 28 × CE6630 on a single service
+			// (mxcli-formula1 §48). AttrFilterable/AttrSortable are nil-safe.
 			if entitySet != nil {
 				for _, name := range entitySet.NonInsertableProperties {
 					nonInsertable[name] = true
@@ -621,12 +624,6 @@ func createExternalEntities(ctx *ExecContext, s *ast.CreateExternalEntitiesStmt)
 				for _, name := range entitySet.NonUpdatableProperties {
 					nonUpdatable[name] = true
 				}
-				for _, name := range entitySet.NonFilterableProperties {
-					nonFilterable[name] = true
-				}
-				for _, name := range entitySet.NonSortableProperties {
-					nonSortable[name] = true
-				}
 			}
 
 			// Build attributes from merged properties
@@ -669,8 +666,8 @@ func createExternalEntities(ctx *ExecContext, s *ast.CreateExternalEntitiesStmt)
 					Type:       edmToDomainModelAttrType(p, keyPropSet[p.Name]),
 					RemoteName: p.Name,
 					RemoteType: p.Type,
-					Filterable: !nonFilterable[p.Name],
-					Sortable:   !nonSortable[p.Name],
+					Filterable: entitySet.AttrFilterable(p.Name),
+					Sortable:   entitySet.AttrSortable(p.Name),
 					Creatable:  creatable,
 					Updatable:  updatable,
 				}
diff --git a/mdl/types/edmx.go b/mdl/types/edmx.go
index 2c21d236b..e57f526e3 100644
--- a/mdl/types/edmx.go
+++ b/mdl/types/edmx.go
@@ -94,6 +94,25 @@ type EdmEntitySet struct {
 	NonFilterableProperties []string
 	NonSortableProperties   []string
 
+	// Filterable / Sortable are the WHOLE-SET form of the same two restrictions,
+	// carried as the record's own Bool property:
+	//
+	//	<Annotation Term="…FilterRestrictions"><Record>
+	//	  <PropertyValue Bool="false" Property="Filterable"/>
+	//	</Record></Annotation>
+	//
+	// Mendix picks the shape by arithmetic, not by preference: it lists
+	// NonFilterableProperties when SOME attributes are filterable, and emits the
+	// bare Bool when NONE are, because then there is no list to write. Both
+	// appear in one document. nil means unstated, which is OData's default of
+	// true (mxcli-formula1 §48).
+	Filterable *bool
+	Sortable   *bool
+
+	// Use AttrFilterable / AttrSortable rather than reading the four fields
+	// above: a consumer that consults only one shape generates an app the
+	// publisher's own contract contradicts.
+
 	// Navigation property names listed under
 	// Org.OData.Capabilities.V1.{Insert,Update}Restrictions/Non*NavigationProperties.
 	NonInsertableNavigationProperties []string
@@ -445,14 +464,35 @@ func applyCapabilityAnnotations(es *EdmEntitySet, annotations []xmlCapabilitiesA
 			}
 		case "Org.OData.Capabilities.V1.FilterRestrictions":
 			for _, pv := range ann.Record.PropertyValues {
-				if pv.Property == "NonFilterableProperties" && pv.Collection != nil {
-					es.NonFilterableProperties = pv.Collection.PropertyPaths
+				switch pv.Property {
+				case "Filterable":
+					// The whole-set form. Mendix emits this INSTEAD of a
+					// NonFilterableProperties list when NO attribute is
+					// filterable — there is nothing to enumerate — so reading
+					// only the list makes an entirely unfilterable set look
+					// entirely filterable.
+					if pv.Bool != "" {
+						v := pv.Bool == "true"
+						es.Filterable = &v
+					}
+				case "NonFilterableProperties":
+					if pv.Collection != nil {
+						es.NonFilterableProperties = pv.Collection.PropertyPaths
+					}
 				}
 			}
 		case "Org.OData.Capabilities.V1.SortRestrictions":
 			for _, pv := range ann.Record.PropertyValues {
-				if pv.Property == "NonSortableProperties" && pv.Collection != nil {
-					es.NonSortableProperties = pv.Collection.PropertyPaths
+				switch pv.Property {
+				case "Sortable":
+					if pv.Bool != "" {
+						v := pv.Bool == "true"
+						es.Sortable = &v
+					}
+				case "NonSortableProperties":
+					if pv.Collection != nil {
+						es.NonSortableProperties = pv.Collection.PropertyPaths
+					}
 				}
 			}
 		}
@@ -629,3 +669,50 @@ type xmlEnumMember struct {
 	Name  string `xml:"Name,attr"`
 	Value string `xml:"Value,attr"`
 }
+
+// AttrFilterable reports whether a client may filter on the named property.
+//
+// FilterRestrictions has TWO shapes and a consumer must honour both. Mendix
+// chooses between them by arithmetic rather than preference: it lists
+// NonFilterableProperties when SOME attributes are filterable, and emits a bare
+// `Bool="false" Property="Filterable"` when NONE are, because then there is no
+// list to write. Both shapes appear in one document, on different entity sets.
+//
+// Reading only the list marks every property of a wholly-unfilterable set as
+// filterable, and the consuming app then fails to build — one CE6630 per
+// property ("'message' is marked Sortable=False in the OData service, but True
+// in the app"), 28 of them on one service (mxcli-formula1 §48). This is §42 one
+// layer along, so the two live behind one call to keep them from drifting apart
+// again.
+//
+// A nil receiver, or an unstated restriction, means OData's default: allowed.
+func (es *EdmEntitySet) AttrFilterable(property string) bool {
+	if es == nil {
+		return true
+	}
+	if es.Filterable != nil && !*es.Filterable {
+		return false
+	}
+	return !containsString(es.NonFilterableProperties, property)
+}
+
+// AttrSortable reports whether a client may order by the named property. See
+// AttrFilterable — SortRestrictions carries the identical pair of shapes.
+func (es *EdmEntitySet) AttrSortable(property string) bool {
+	if es == nil {
+		return true
+	}
+	if es.Sortable != nil && !*es.Sortable {
+		return false
+	}
+	return !containsString(es.NonSortableProperties, property)
+}
+
+func containsString(haystack []string, needle string) bool {
+	for _, s := range haystack {
+		if s == needle {
+			return true
+		}
+	}
+	return false
+}
diff --git a/mdl/types/edmx_test.go b/mdl/types/edmx_test.go
index 3a13b4b01..4d1a963af 100644
--- a/mdl/types/edmx_test.go
+++ b/mdl/types/edmx_test.go
@@ -590,3 +590,96 @@ func TestParseEdmx_StandaloneHandlingKeepsRecordAnnotations(t *testing.T) {
 		t.Errorf("Countable = %v — the record arm regressed", es.Countable)
 	}
 }
+
+// edmxWithAnnotations wraps entity-set annotations in a minimal but real EDMX
+// document, so the assertions run through ParseEdmx rather than a hand-built
+// struct.
+func edmxWithAnnotations(setName, annotations string) string {
+	return `<?xml version="1.0" encoding="utf-8"?>
+<edmx:Edmx Version="4.0" xmlns:edmx="http://docs.oasis-open.org/odata/ns/edmx">
+  <edmx:DataServices>
+    <Schema Namespace="F1OpsApi" xmlns="http://docs.oasis-open.org/odata/ns/edm">
+      <EntityType Name="Row"><Key><PropertyRef Name="k"/></Key>
+        <Property Name="k" Type="Edm.String"/>
+        <Property Name="message" Type="Edm.String"/>
+      </EntityType>
+      <EntityContainer Name="Entities">
+        <EntitySet Name="` + setName + `" EntityType="F1OpsApi.Row">
+` + annotations + `
+        </EntitySet>
+      </EntityContainer>
+    </Schema>
+  </edmx:DataServices>
+</edmx:Edmx>`
+}
+
+// mxcli-formula1 §48: FilterRestrictions/SortRestrictions carry the SAME
+// two-shape problem §42 had. Mendix emits the bare record boolean when NO
+// attribute is filterable — there is no list to enumerate — and mxcli read only
+// the list, so a wholly-unfilterable set generated a wholly-filterable app:
+// 28 × CE6630 on one service.
+func TestParseEdmx_WholeSetFilterAndSortRestrictions(t *testing.T) {
+	doc, err := ParseEdmx(edmxWithAnnotations("Predictions", `
+          <Annotation Term="Org.OData.Capabilities.V1.FilterRestrictions"><Record>
+            <PropertyValue Bool="false" Property="Filterable"/>
+          </Record></Annotation>
+          <Annotation Term="Org.OData.Capabilities.V1.SortRestrictions"><Record>
+            <PropertyValue Bool="false" Property="Sortable"/>
+          </Record></Annotation>`))
+	if err != nil {
+		t.Fatalf("parsing: %v", err)
+	}
+	es := doc.EntitySets[0]
+	if es.Filterable == nil || *es.Filterable {
+		t.Errorf("Filterable = %v, want an explicit false", es.Filterable)
+	}
+	if es.Sortable == nil || *es.Sortable {
+		t.Errorf("Sortable = %v, want an explicit false", es.Sortable)
+	}
+	// The whole point: no property escapes a whole-set restriction.
+	if es.AttrFilterable("message") {
+		t.Error("'message' is filterable against a set that says nothing is — CE6630")
+	}
+	if es.AttrSortable("message") {
+		t.Error("'message' is sortable against a set that says nothing is — CE6630")
+	}
+}
+
+// The list shape is the one that already worked, and it has to keep working —
+// Mendix emits BOTH, in one document, on different entity sets.
+func TestParseEdmx_PerPropertyFilterRestrictionsStillHonoured(t *testing.T) {
+	doc, err := ParseEdmx(edmxWithAnnotations("DriverForm", `
+          <Annotation Term="Org.OData.Capabilities.V1.FilterRestrictions"><Record>
+            <PropertyValue Bool="true" Property="Filterable"/>
+            <PropertyValue Property="NonFilterableProperties"><Collection>
+              <PropertyPath>message</PropertyPath>
+            </Collection></PropertyValue>
+          </Record></Annotation>`))
+	if err != nil {
+		t.Fatalf("parsing: %v", err)
+	}
+	es := doc.EntitySets[0]
+	if got := es.NonFilterableProperties; len(got) != 1 || got[0] != "message" {
+		t.Errorf("NonFilterableProperties = %v, want [message]", got)
+	}
+	if es.AttrFilterable("message") {
+		t.Error("'message' is named non-filterable and must not be filterable")
+	}
+	if !es.AttrFilterable("k") {
+		t.Error("'k' is not named, and the set says Filterable=true, so it must stay filterable")
+	}
+}
+
+// Unstated is OData's default of allowed. Defaulting the other way would invert
+// CE6630 for every service that annotates nothing — i.e. every one that worked
+// before this change.
+func TestEdmEntitySet_UnrestrictedByDefault(t *testing.T) {
+	var nilSet *EdmEntitySet
+	if !nilSet.AttrFilterable("anything") || !nilSet.AttrSortable("anything") {
+		t.Error("a nil entity set must not restrict anything")
+	}
+	empty := &EdmEntitySet{Name: "Rows"}
+	if !empty.AttrFilterable("k") || !empty.AttrSortable("k") {
+		t.Error("an unannotated set must not restrict anything")
+	}
+}

From 5a7780fa1170f67c9b7f617bf6970edeae5464ba Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 9 Aug 2026 20:32:52 +0000
Subject: [PATCH 24/29] feat(lint): QUAL002 covers Java actions and their
 parameters
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A generated project can have documentation nowhere and nothing says so:
`mxcli check` and the build both pass, because documentation is never
load-bearing. QUAL002 was the reminder, but it reached only entities and
microflows.

Java actions were not reachable from Starlark at all, and their
parameters were not reachable from anywhere — the catalog kept a
parameter count and discarded each parameter's Description. That is the
field Studio Pro shows to whoever wires up the call, where an
undocumented parameter is a blank next to a name like `pInput` at
exactly the moment a caller has to decide what to pass.

- catalog: java_action_parameters table + view, registered in Tables()
- linter: JavaActions() carries its parameters, so a rule naming a
  parameter can name its action without re-joining; Marketplace and
  System modules excluded as every sibling iterator does
- starlark: java_actions() builtin, parameters nested on each action
- QUAL002: Java actions, their parameters, and (off by default, on
  request) entity attributes — every target switchable via get_option

CatalogSchemaVersion 8 -> 9. Without the bump an existing cache keeps
its old schema, the query fails, the error is swallowed, and the rule
reports zero parameters — silent under-reporting that looks exactly like
a documented project.
---
 .claude/lint-rules/missing_documentation.star | 151 +++++++++----
 .claude/skills/fix-issue.md                   |   1 +
 cmd/mxcli/cmd_lint.go                         |   3 +-
 docs-site/src/tools/starlark-rules.md         |  38 +++-
 mdl/catalog/builder_modules.go                |  41 ++++
 mdl/catalog/catalog.go                        |   1 +
 mdl/catalog/tables.go                         |  26 ++-
 mdl/linter/context.go                         |  98 ++++++++
 mdl/linter/starlark.go                        |  48 ++++
 mdl/linter/starlark_javaactions_test.go       | 210 ++++++++++++++++++
 10 files changed, 567 insertions(+), 50 deletions(-)
 create mode 100644 mdl/linter/starlark_javaactions_test.go

diff --git a/.claude/lint-rules/missing_documentation.star b/.claude/lint-rules/missing_documentation.star
index da8697dcb..0259737b3 100644
--- a/.claude/lint-rules/missing_documentation.star
+++ b/.claude/lint-rules/missing_documentation.star
@@ -1,66 +1,123 @@
 # Starlark Lint Rule: Missing Documentation
 #
-# This rule checks that entities and microflows have documentation.
-# Good documentation helps with maintainability and onboarding new developers.
+# Undocumented model elements are invisible to `mxcli check` and to the build —
+# nothing fails, so nothing reminds you. This rule is the reminder.
 #
-# Checks:
-#   - Entities should have a description explaining their purpose
-#   - Microflows should have a description explaining what they do
+# Checks, each independently switchable (see Options):
+#   - Entities              .description
+#   - Microflows            .description   (nanoflows and trivial flows exempt)
+#   - Java actions          .documentation
+#   - Java action params    .description   <- the one Studio Pro shows a CALLER
+#   - Entity attributes     .description   (off by default: high volume)
 #
-# Entity properties:
-#   .description     - Documentation text
+# Why parameters matter more than they look: Studio Pro renders a Java action's
+# parameter descriptions in the dialog where someone wires up the call. An
+# undocumented parameter is a blank field next to a name like `pInput`, at
+# exactly the moment a caller has to decide what to pass.
 #
-# Microflow properties:
-#   .description     - Documentation text
+# Options (lint config `options:` block for QUAL002):
+#   check_entities             bool, default True
+#   check_microflows           bool, default True
+#   check_java_actions         bool, default True
+#   check_java_action_params   bool, default True
+#   check_attributes           bool, default False
+#   min_activities             int,  default 3   (microflows below this are exempt)
 
 RULE_ID = "QUAL002"
 RULE_NAME = "Missing Documentation"
-DESCRIPTION = "Entities and microflows should have documentation describing their purpose"
+DESCRIPTION = "Model elements should have documentation describing their purpose"
 CATEGORY = "quality"
 SEVERITY = "info"
 
+def _blank(text):
+    """True when a documentation field is absent or whitespace-only."""
+    return not text or text.strip() == ""
+
+def _flag(violations, module, doc_type, doc_name, message, suggestion):
+    violations.append(violation(
+        message = message,
+        location = location(
+            module = module,
+            document_type = doc_type,
+            document_name = doc_name,
+        ),
+        suggestion = suggestion,
+    ))
+
 def check():
-    """
-    Check that entities and microflows have documentation.
-    """
     violations = []
 
-    # Check entities
-    for entity in entities():
-        if not entity.description or entity.description.strip() == "":
-            loc = location(
-                module=entity.module_name,
-                document_type="Entity",
-                document_name=entity.qualified_name
-            )
-            v = violation(
-                message="Entity '{}' has no documentation.".format(entity.name),
-                location=loc,
-                suggestion="Add a description explaining the entity's purpose and what data it represents."
-            )
-            violations.append(v)
+    if get_option("check_entities", True):
+        for entity in entities():
+            if _blank(entity.description):
+                _flag(
+                    violations,
+                    entity.module_name,
+                    "Entity",
+                    entity.qualified_name,
+                    "Entity '{}' has no documentation.".format(entity.name),
+                    "Add a description explaining the entity's purpose and what data it represents.",
+                )
 
-    # Check microflows (skip nanoflows as they're often simple)
-    for mf in microflows():
-        # Only check microflows, not nanoflows
-        if mf.microflow_type != "MICROFLOW":
-            continue
+    if get_option("check_attributes", False):
+        for entity in entities():
+            for attr in attributes_for(entity.qualified_name):
+                if _blank(attr.description):
+                    _flag(
+                        violations,
+                        entity.module_name,
+                        "Entity",
+                        entity.qualified_name,
+                        "Attribute '{}.{}' has no documentation.".format(entity.name, attr.name),
+                        "Add a description, or switch this off with `check_attributes: false` if " +
+                        "attribute names are self-describing in this project.",
+                    )
 
-        # Skip very simple microflows (1-2 activities)
-        if mf.activity_count <= 2:
-            continue
+    if get_option("check_microflows", True):
+        # Nanoflows are excluded: they are usually a couple of client-side steps
+        # whose name says everything a description would.
+        min_activities = get_option("min_activities", 3)
+        for mf in microflows():
+            if mf.microflow_type != "MICROFLOW":
+                continue
+            if mf.activity_count < min_activities:
+                continue
+            if _blank(mf.description):
+                _flag(
+                    violations,
+                    mf.module_name,
+                    "Microflow",
+                    mf.qualified_name,
+                    "Microflow '{}' has no documentation.".format(mf.name),
+                    "Add a description explaining what this microflow does and when it should be called.",
+                )
 
-        if not mf.description or mf.description.strip() == "":
-            loc = location(
-                module=mf.module_name,
-                document_type="Microflow",
-                document_name=mf.qualified_name
-            )
-            v = violation(
-                message="Microflow '{}' has no documentation.".format(mf.name),
-                location=loc,
-                suggestion="Add a description explaining what this microflow does and when it should be called."
-            )
-            violations.append(v)
+    check_actions = get_option("check_java_actions", True)
+    check_params = get_option("check_java_action_params", True)
+    if check_actions or check_params:
+        for ja in java_actions():
+            if check_actions and _blank(ja.documentation):
+                _flag(
+                    violations,
+                    ja.module_name,
+                    "JavaAction",
+                    ja.qualified_name,
+                    "Java action '{}' has no documentation.".format(ja.name),
+                    "Add documentation explaining what the action does, and what it returns. " +
+                    "Unlike a microflow, its body is Java that the model cannot show a reader.",
+                )
+            if not check_params:
+                continue
+            for p in ja.parameters:
+                if _blank(p.description):
+                    _flag(
+                        violations,
+                        ja.module_name,
+                        "JavaAction",
+                        ja.qualified_name,
+                        "Java action parameter '{}.{}' has no description.".format(ja.name, p.name),
+                        "Add a description: Studio Pro shows it to whoever wires up the call, " +
+                        "where the parameter name is all they otherwise have to go on.",
+                    )
 
     return violations
diff --git a/.claude/skills/fix-issue.md b/.claude/skills/fix-issue.md
index bfe655dfa..612c2cf1d 100644
--- a/.claude/skills/fix-issue.md
+++ b/.claude/skills/fix-issue.md
@@ -445,3 +445,4 @@ extracting `OffsetExpression`/`LimitExpression`.
 | `MDL-ODATA03` ("advertises TopSupported … so no paging is applied") is silenced by giving the read microflow a `System.HttpRequest` parameter — even when the parameter was added for the **KEY** and no paging was implemented. The half-fixed resource, which is the one still shipping unpaged 200s, is exactly the one the rule stops warning about | MDL-ODATA02 (KEY) and MDL-ODATA03 (paging) shared a single test — `takesHTTPRequest(decl)` — and answering either concern satisfied both. The rule could see whether the microflow *could* read the request, not whether it *did* | `mdl/executor/validate_odata_read_contract.go` (`capabilityViolations` now takes the declaration; `pagingEvidence`/`walkForPaging` reflect-walk the reachable body), `mdl-examples/doctype-tests/10-odata-examples.mdl` | **When one input satisfies two rules, the rules will silence each other.** The tell is a shared precondition that means something different to each check — grep for other validators keyed on the same `takesX()` helper before adding one. **The wire spelling is the evidence.** An OData query option is literally named `$top`, so a microflow implementing it must contain that text; presence of the text is weak evidence of handling, absence is strong evidence against — which is the only direction a rule that reports absences needs. **Reflect-walk, do not type-switch per statement**: MDL gains activity types regularly and a walker that misses one converts a false negative into a false *positive* ("nothing reads $top" about a body it never looked at). Reflection also picks up new nesting — loop bodies, if-branches, error handlers — for free. **Exclude `Annotations`/`Documentation`/`Comment` fields from the walk**: an `@annotation '$top is not applied here'` is prose admitting the defect, and counting it as implementation silences the rule on the one resource that documents the bug. **Keep an escape hatch and make it outrank the evidence**: a call into a Java action, a JavaScript action, a nanoflow, or a microflow the script does not define ends the analysis with silence — same stance the rule already took toward out-of-script read microflows. Follow calls into helpers the script *does* define, since real code factors paging out. **Report per option, not per resource** — flagging `SkipSupported` while `$top` is genuinely handled avoids advising an author to withdraw working support. **Shipped examples are part of the blast radius**: the doctype example's variant (a) was written to the old rationale ("taking `$Request` is enough to earn its silence") and started warning the moment the rule tightened — a changed rule needs `mxcli check` over `mdl-examples/` and then the integration gate, not just its own unit tests. Each guard has its own revert control (restore benefit-of-the-doubt / drop the annotation skip / drop `opaque` / stop following helpers), and all four reproduce. Tests `mdl/executor/validate_odata_read_contract_test.go`. mxcli-formula1 §42 |
 | `mxcli run --local` refuses to boot — *"port 6643 is already in use — a previous 'mxcli run --local' … is likely still serving on it"* — and names a process the user already killed. The guard is right to refuse; the diagnosis is a guess, and the recovery it suggests is a three-command `pgrep` hunt whose own pattern (`pgrep -f 'mxcli run'`) matches the shell it is typed into | Two different situations printed one message. mxcli **does** reap its children on Ctrl-C/SIGTERM (`procgroup_unix.go` puts mxbuild's JVM, the runtime and the bundler each in their own process group and signals the group), so a held port after a graceful stop is a *foreign* listener. But `kill -9`, a crash, or a reaped container runs no handler at all, and then it really is the previous run's orphan. The guard could not tell them apart because it never asked who held the port | `cmd/mxcli/docker/portowner_linux.go` (`listenerOnPort`, `parseListeningInodes`, `pidForSocketInode`), `portowner_other.go` (non-Linux stub), `portguard.go` (`portCulpritAdvice`), wired into `checkTargetPortsFree` (`runlocal.go`) and `checkLocalAppPortsFree` (`localapp.go`) | **Resolve the port owner from `/proc`, never by shelling out to `lsof`/`ss`** — both are routinely absent from slim containers, and needing a subprocess to explain why a boot failed is its own failure mode. `/proc/net/tcp{,6}` gives the socket inode; scanning `/proc/<pid>/fd` for `socket:[<inode>]` gives the pid. **Read `tcp6` as well as `tcp`**: a JVM binding "localhost" lands on `[::1]` or dual-stack `[::]` as often as `127.0.0.1`, and its local_address is a 128-bit hex blob, not the 32-bit one. **Filter on state `0A` (TCP_LISTEN)** — an ESTABLISHED socket on that port is a *client*, and naming it would tell the user to kill their own browser. **Report the two cases differently**: a leftover of a previous run gets `kill <pid>`, a foreign listener gets "pick another port" and no kill suggestion, because offering to kill a stranger's process is worse advice than the vague message it replaced. Keep the guard **detection-only** — reaping someone else's process stays the user's call. **Three test traps hit in a row here.** (1) The live-IPv6 test only ever *skipped* (no IPv6 in the container), so the tcp6 parser was effectively untested — assert against captured kernel output instead. (2) A parser test calling `parseListeningInodes` directly does not prove `listeningInodes` *opens* both files: deleting `/proc/net/tcp6` from the list left every test green. (3) Making the list a `var` so a test can point it at fixtures then means the test no longer covers the **shipped** default either — assert the default's contents before overriding it. Only the third version of that control failed. The best test in the file is the cheapest: bind a port in the test process and demand `listenerOnPort` return `os.Getpid()` — it cannot pass by accident. Tests `cmd/mxcli/docker/portowner_linux_test.go`. mxcli-formula1 suggested issue 8 |
 | `create external entities from` a service where an entity set is wholly unfilterable/unsortable generates an app the contract contradicts: **28 × CE6630** on one service — "'message' is marked Sortable=False in the OData service, but True in the app". The publisher is right, the `$metadata` is right, only the generated consumer is wrong | `FilterRestrictions`/`SortRestrictions` have **two shapes**, and only one was read. `applyCapabilityAnnotations` pulled `NonFilterableProperties` out of the record and ignored the record's own `Bool` property value, so `Filterable: !nonFilterable[p.Name]` evaluated `true` for every property of a set that had declared nothing filterable. This is the §42 Top/Skip bug one layer along — same vocabulary, same two-shapes cause, different term | `mdl/types/edmx.go` (`EdmEntitySet.Filterable`/`Sortable`, the `Filterable`/`Sortable` cases in `applyCapabilityAnnotations`, and the `AttrFilterable`/`AttrSortable` accessors), `mdl/executor/cmd_contract.go` (`createExternalEntities` calls the accessors) | **Mendix picks the annotation shape by arithmetic, not preference.** It lists `NonFilterableProperties` when SOME attributes are filterable and emits a bare `<PropertyValue Bool="false" Property="Filterable"/>` when NONE are, because then there is no list to write — so both shapes appear in **one document** on different entity sets, and an entity exposing only a KEY reliably produces the whole-set form. A fixture with just the list shape tests the half that already worked. **After fixing one term in a vocabulary, sweep the siblings**: §42 fixed Top/Skip by teaching the parser about standalone booleans and stopped there; Filterable/Sortable had the same defect and were found only because a consumer app failed to build. Grep the whole `applyCapabilityAnnotations` switch for terms whose Bool is never read. **Put both shapes behind one accessor** (`AttrFilterable`) rather than two fields the caller must remember to AND together — the caller then cannot consult one and forget the other, which is exactly how this arose, and the nil-safe receiver deletes the `entitySet != nil` dance at the call site. Absent still means `true`: OData's default is allowed, and defaulting to false would invert CE6630 for every unannotated service. Tests `mdl/types/edmx_test.go` (`TestParseEdmx_WholeSetFilterAndSortRestrictions`, plus a control proving the list shape still parses); both controls reproduce (ignore the record Bool → the whole-set test fails with the CE6630 message; drop the check inside `AttrFilterable` → same). mxcli-formula1 §48 |
+| A project is generated with no documentation anywhere — Java actions, Java action parameters, entities, microflows — and nothing says so. `mxcli check` and the build both pass, because documentation is never load-bearing | `QUAL002` existed but reached only entities and microflows. Java actions were not reachable from Starlark **at all** (no `java_actions()` builtin), and a Java action's parameters were not reachable from anywhere: the catalog stored a parameter *count* and discarded each parameter's `Description` | `mdl/catalog/tables.go` (`java_action_parameters_data` + view, `CatalogSchemaVersion` bump), `mdl/catalog/catalog.go` (`Tables()` registry), `mdl/catalog/builder_modules.go` (insert parameters), `mdl/linter/context.go` (`JavaActions()` with parameters attached), `mdl/linter/starlark.go` (`java_actions()` builtin, `javaActionToStarlark`), `.claude/lint-rules/missing_documentation.star` | **Adding a catalog table has three obligations beyond the `CREATE TABLE`.** (1) Bump `CatalogSchemaVersion` — otherwise every existing `.mxcli/catalog.db` keeps its old schema, the new query fails, the error is swallowed, and the rule silently reports *zero* of the new findings. Silent under-reporting from a stale cache is indistinguishable from a clean project. (2) Register the view in `Tables()` — `catalog_test.go` enforces this and will fail with "add CATALOG.X so SHOW CATALOG TABLES includes it"; let that test tell you rather than discovering it from a user. (3) Exclude Marketplace/System modules in the iterator's `WHERE COALESCE(m.Source,'') = ''`, as every sibling iterator does — reporting undocumented Community Commons actions buries the findings the user can act on. **Attach children to their parent in the projection, not as a second iterator**: a rule reporting an undocumented parameter must name the action it belongs to, and pairing them in `JavaActions()` saves every rule from re-joining. **Load the shipped `.star` from disk in tests** — an inlined copy proves the builtin works and says nothing about whether the rule uses it. **Make each target switchable via `get_option`** before widening a rule: attribute-level checks are hundreds of findings on a real domain model, so `check_attributes` defaults off while the rest default on. Watch the whitespace when writing revert controls for Starlark: a `perl` pattern with `\t` silently matches nothing in a space-indented `.star`, so the control passes and proves nothing — it was the second attempt that failed correctly. Tests `mdl/linter/starlark_javaactions_test.go`; five controls reproduce. mxcli-formula1 (missing documentation) |
diff --git a/cmd/mxcli/cmd_lint.go b/cmd/mxcli/cmd_lint.go
index b984463e1..7d5173853 100644
--- a/cmd/mxcli/cmd_lint.go
+++ b/cmd/mxcli/cmd_lint.go
@@ -47,7 +47,8 @@ Bundled Starlark rules (in .claude/lint-rules/):
   - Entity business key (ARCH003) - persistent entities need a unique key
   Quality:
   - McCabe complexity (QUAL001) - microflow cyclomatic complexity threshold
-  - Missing documentation (QUAL002) - entities/microflows need documentation
+  - Missing documentation (QUAL002) - entities, microflows, Java actions and their
+      parameters need documentation (attributes too, via check_attributes)
   - Long microflows (QUAL003) - microflows with too many activities
   - Orphaned elements (QUAL004) - unreferenced elements in the project
   Design:
diff --git a/docs-site/src/tools/starlark-rules.md b/docs-site/src/tools/starlark-rules.md
index bec2d5af3..9f91c4280 100644
--- a/docs-site/src/tools/starlark-rules.md
+++ b/docs-site/src/tools/starlark-rules.md
@@ -28,7 +28,7 @@ In addition to the built-in Go rules, mxcli bundles 27 Starlark-based lint rules
 | Rule | Description |
 |------|-------------|
 | **QUAL001** | McCabe complexity -- Flags microflows with high cyclomatic complexity |
-| **QUAL002** | Documentation -- Checks for missing documentation on public elements |
+| **QUAL002** | Documentation -- Missing documentation on entities, microflows, Java actions and Java action parameters ([options](#qual002-options)) |
 | **QUAL003** | Long microflows -- Warns about microflows with too many activities |
 | **QUAL004** | Orphaned elements -- Detects unused entities, microflows, or pages |
 
@@ -49,6 +49,42 @@ In addition to the built-in Go rules, mxcli bundles 27 Starlark-based lint rules
 
 Additional convention rules cover access rule constraints, role mapping, microflow size and content.
 
+### QUAL002 options {#qual002-options}
+
+Undocumented model elements are invisible to `mxcli check` and to the build —
+nothing fails, so nothing reminds you. QUAL002 is that reminder, and it covers
+more than the domain model:
+
+| Option | Default | Checks |
+|---|---|---|
+| `check_entities` | `true` | entity descriptions |
+| `check_microflows` | `true` | microflow descriptions (nanoflows always exempt) |
+| `check_java_actions` | `true` | Java action documentation |
+| `check_java_action_params` | `true` | Java action **parameter** descriptions |
+| `check_attributes` | `false` | entity attribute descriptions |
+| `min_activities` | `3` | microflows with fewer activities are exempt |
+
+Parameter descriptions are worth more than they look: Studio Pro renders them in
+the dialog where someone wires up the call, so an undocumented parameter is a
+blank field next to a name like `pInput` at exactly the moment a caller has to
+decide what to pass. Java actions matter for the same reason one step up — unlike
+a microflow, the body is Java the model cannot show a reader.
+
+`check_attributes` is off by default only because of volume: a real domain model
+has hundreds of attributes, and turning it on at `info` severity is a long list.
+Turn it on when you are actually working through documentation debt.
+
+Set options in the lint config:
+
+```yaml
+rules:
+  QUAL002:
+    enabled: true
+    options:
+      check_attributes: true
+      min_activities: 5
+```
+
 ## Where Starlark Rules Live
 
 When you run `mxcli init`, Starlark rules are installed to:
diff --git a/mdl/catalog/builder_modules.go b/mdl/catalog/builder_modules.go
index 23fab80a1..438d25c5c 100644
--- a/mdl/catalog/builder_modules.go
+++ b/mdl/catalog/builder_modules.go
@@ -309,7 +309,19 @@ func (b *Builder) buildJavaActions() error {
 	}
 	defer stmt.Close()
 
+	paramStmt, err := b.tx.Prepare(`
+		INSERT INTO java_action_parameters_data (Id, JavaActionId, JavaActionName,
+			QualifiedName, ModuleName, Name, Description, ParameterType, IsRequired,
+			Ordinal, ProjectId, SnapshotId)
+		VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+	`)
+	if err != nil {
+		return err
+	}
+	defer paramStmt.Close()
+
 	projectID, snapshotID := b.snapshotMeta()
+	paramCount := 0
 
 	for _, ja := range actions {
 		moduleID := b.hierarchy.findModuleID(ja.ContainerID)
@@ -337,9 +349,38 @@ func (b *Builder) buildJavaActions() error {
 		if err != nil {
 			return err
 		}
+
+		for i, p := range ja.Parameters {
+			if p == nil {
+				continue
+			}
+			paramType := ""
+			if p.ParameterType != nil {
+				paramType = p.ParameterType.TypeString()
+			}
+			if _, err := paramStmt.Exec(
+				string(p.ID),
+				string(ja.ID),
+				ja.Name,
+				qualifiedName+"."+p.Name,
+				moduleName,
+				p.Name,
+				p.Description,
+				paramType,
+				boolToInt(p.IsRequired),
+				i,
+				projectID, snapshotID,
+			); err != nil {
+				return err
+			}
+			paramCount++
+		}
 	}
 
 	b.report("Java Actions", len(actions))
+	if paramCount > 0 {
+		b.report("Java Action Parameters", paramCount)
+	}
 	return nil
 }
 
diff --git a/mdl/catalog/catalog.go b/mdl/catalog/catalog.go
index 528f97a7f..07383a3d7 100644
--- a/mdl/catalog/catalog.go
+++ b/mdl/catalog/catalog.go
@@ -112,6 +112,7 @@ func (c *Catalog) Tables() []string {
 		"CATALOG.LAYOUTS",
 		"CATALOG.ENUMERATIONS",
 		"CATALOG.JAVA_ACTIONS",
+		"CATALOG.JAVA_ACTION_PARAMETERS",
 		"CATALOG.JAVASCRIPT_ACTIONS",
 		"CATALOG.IMAGE_COLLECTIONS",
 		"CATALOG.DATA_TRANSFORMERS",
diff --git a/mdl/catalog/tables.go b/mdl/catalog/tables.go
index 8d1dcbfab..b39426c6b 100644
--- a/mdl/catalog/tables.go
+++ b/mdl/catalog/tables.go
@@ -7,12 +7,16 @@ package catalog
 //
 // History:
 //
+//	9 — java_action_parameters_data + view: a Java action's parameters, each
+//	    with its own Description. Without the bump a cached catalog silently
+//	    reports zero parameters, so QUAL002 would under-report rather than
+//	    fail (mxcli-formula1: missing documentation on Java actions).
 //	2 — split each domain table into <name>_data + <name> view that JOINs
 //	    snapshots, removing the denormalized ProjectName / SnapshotDate /
 //	    SnapshotSource / SourceId / SourceBranch / SourceRevision columns
 //	    from every row (issue #576).
 //	1 — initial flat schema with denormalized snapshot columns on every row.
-const CatalogSchemaVersion = "8"
+const CatalogSchemaVersion = "9"
 
 // MetaSchemaVersion is the catalog_meta key that records the schema version
 // the cache was built against.
@@ -262,6 +266,26 @@ func (c *Catalog) createTables() error {
 		)`,
 		viewWithFullSnapshot("java_actions"),
 
+		// java_action_parameters — one row per parameter of a Java action.
+		// Separate from java_actions (which only counts them) because a
+		// parameter carries its own Description, and an undocumented parameter
+		// is the thing a caller actually sees in Studio Pro's action dialog.
+		`CREATE TABLE IF NOT EXISTS java_action_parameters_data (
+			Id TEXT PRIMARY KEY,
+			JavaActionId TEXT,
+			JavaActionName TEXT,
+			QualifiedName TEXT,
+			ModuleName TEXT,
+			Name TEXT,
+			Description TEXT,
+			ParameterType TEXT,
+			IsRequired INTEGER DEFAULT 0,
+			Ordinal INTEGER DEFAULT 0,
+			ProjectId TEXT,
+			SnapshotId TEXT
+		)`,
+		viewWithFullSnapshot("java_action_parameters"),
+
 		// javascript_actions
 		`CREATE TABLE IF NOT EXISTS javascript_actions_data (
 			Id TEXT PRIMARY KEY,
diff --git a/mdl/linter/context.go b/mdl/linter/context.go
index 8ed515f3d..898537ffd 100644
--- a/mdl/linter/context.go
+++ b/mdl/linter/context.go
@@ -1200,3 +1200,101 @@ func (ctx *LintContext) ModuleDependencies() map[string][]string {
 
 	return deps
 }
+
+// JavaActionParameter represents one parameter of a Java action.
+type JavaActionParameter struct {
+	Name          string
+	Description   string
+	ParameterType string
+	IsRequired    bool
+}
+
+// JavaAction represents a Java action from the catalog, with its parameters.
+//
+// Parameters are carried on the action rather than offered as a separate
+// iterator: a rule that reports an undocumented parameter has to name the action
+// it belongs to, and pairing them here keeps a rule from having to join.
+type JavaAction struct {
+	ID            string
+	Name          string
+	QualifiedName string
+	ModuleName    string
+	Folder        string
+	Documentation string
+	ExportLevel   string
+	ReturnType    string
+	Parameters    []JavaActionParameter
+}
+
+// JavaActions returns an iterator over all Java actions (excluding system and
+// marketplace modules, as every other document iterator here does — a rule must
+// not report undocumented code the user did not write).
+func (ctx *LintContext) JavaActions() iter.Seq[JavaAction] {
+	return func(yield func(JavaAction) bool) {
+		params := ctx.javaActionParameters()
+
+		rows, err := ctx.db.Query(`
+			SELECT ja.Id, ja.Name, ja.QualifiedName, ja.ModuleName, ja.Folder,
+			       ja.Documentation, ja.ExportLevel, ja.ReturnType
+			FROM java_actions ja
+			LEFT JOIN modules m ON ja.ModuleName = m.Name
+			WHERE COALESCE(m.Source, '') = ''
+			ORDER BY ja.ModuleName, ja.Name
+		`)
+		if err != nil {
+			return
+		}
+		defer rows.Close()
+
+		for rows.Next() {
+			var ja JavaAction
+			var folder, doc, exportLevel, retType sql.NullString
+			if err := rows.Scan(&ja.ID, &ja.Name, &ja.QualifiedName, &ja.ModuleName,
+				&folder, &doc, &exportLevel, &retType); err != nil {
+				continue
+			}
+			ja.Folder = folder.String
+			ja.Documentation = doc.String
+			ja.ExportLevel = exportLevel.String
+			ja.ReturnType = retType.String
+			ja.Parameters = params[ja.ID]
+
+			if ctx.IsExcluded(ja.ModuleName) {
+				continue
+			}
+			if !yield(ja) {
+				return
+			}
+		}
+	}
+}
+
+// javaActionParameters indexes every parameter by its owning action's ID, in
+// declaration order.
+func (ctx *LintContext) javaActionParameters() map[string][]JavaActionParameter {
+	out := map[string][]JavaActionParameter{}
+	rows, err := ctx.db.Query(`
+		SELECT JavaActionId, Name, Description, ParameterType, IsRequired
+		FROM java_action_parameters
+		ORDER BY JavaActionId, Ordinal
+	`)
+	if err != nil {
+		return out
+	}
+	defer rows.Close()
+
+	for rows.Next() {
+		var actionID string
+		var p JavaActionParameter
+		var desc, ptype sql.NullString
+		var required int
+		if err := rows.Scan(&actionID, &p.Name, &desc, &ptype, &required); err != nil {
+			continue
+		}
+		p.Description = desc.String
+		p.ParameterType = ptype.String
+		p.IsRequired = required != 0
+		out[actionID] = append(out[actionID], p)
+	}
+	return out
+}
diff --git a/mdl/linter/starlark.go b/mdl/linter/starlark.go
index 716b6f73a..423681224 100644
--- a/mdl/linter/starlark.go
+++ b/mdl/linter/starlark.go
@@ -316,6 +316,7 @@ func (r *StarlarkRule) buildPredeclared() starlark.StringDict {
 		// Query functions
 		"entities":         starlark.NewBuiltin("entities", r.builtinEntities),
 		"microflows":       starlark.NewBuiltin("microflows", r.builtinMicroflows),
+		"java_actions":     starlark.NewBuiltin("java_actions", r.builtinJavaActions),
 		"pages":            starlark.NewBuiltin("pages", r.builtinPages),
 		"enumerations":     starlark.NewBuiltin("enumerations", r.builtinEnumerations),
 		"constants":        starlark.NewBuiltin("constants", r.builtinConstants),
@@ -394,6 +395,22 @@ func (r *StarlarkRule) builtinMicroflows(_ *starlark.Thread, _ *starlark.Builtin
 	return starlark.NewList(microflows), nil
 }
 
+// builtinJavaActions returns an iterator over Java actions. Each carries its
+// parameters, so a rule reporting an undocumented parameter can name its action
+// without a second lookup.
+func (r *StarlarkRule) builtinJavaActions(_ *starlark.Thread, _ *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error) {
+	if r.ctx == nil {
+		return starlark.NewList(nil), nil
+	}
+
+	var actions []starlark.Value
+	for ja := range r.ctx.JavaActions() {
+		actions = append(actions, javaActionToStarlark(ja))
+	}
+
+	return starlark.NewList(actions), nil
+}
+
 // builtinPages returns an iterator over pages.
 func (r *StarlarkRule) builtinPages(_ *starlark.Thread, _ *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error) {
 	if r.ctx == nil {
@@ -745,6 +762,37 @@ func microflowToStarlark(mf Microflow) starlark.Value {
 	})
 }
 
+// javaActionToStarlark converts a JavaAction to a Starlark struct.
+//
+// The doc field is exposed as BOTH `documentation` (the Mendix term, and what
+// the metamodel calls it) and `description` (what every other document struct
+// here calls it), so a rule that loops over mixed document kinds can read one
+// field name throughout.
+func javaActionToStarlark(ja JavaAction) starlark.Value {
+	params := make([]starlark.Value, 0, len(ja.Parameters))
+	for _, p := range ja.Parameters {
+		params = append(params, starlarkstruct.FromStringDict(starlark.String("java_action_parameter"), starlark.StringDict{
+			"name":           starlark.String(p.Name),
+			"description":    starlark.String(p.Description),
+			"parameter_type": starlark.String(p.ParameterType),
+			"is_required":    starlark.Bool(p.IsRequired),
+		}))
+	}
+	return starlarkstruct.FromStringDict(starlark.String("java_action"), starlark.StringDict{
+		"id":              starlark.String(ja.ID),
+		"name":            starlark.String(ja.Name),
+		"qualified_name":  starlark.String(ja.QualifiedName),
+		"module_name":     starlark.String(ja.ModuleName),
+		"folder":          starlark.String(ja.Folder),
+		"documentation":   starlark.String(ja.Documentation),
+		"description":     starlark.String(ja.Documentation),
+		"export_level":    starlark.String(ja.ExportLevel),
+		"return_type":     starlark.String(ja.ReturnType),
+		"parameter_count": starlark.MakeInt(len(ja.Parameters)),
+		"parameters":      starlark.NewList(params),
+	})
+}
+
 // pageToStarlark converts a Page to a Starlark struct.
 func pageToStarlark(p Page) starlark.Value {
 	return starlarkstruct.FromStringDict(starlark.String("page"), starlark.StringDict{
diff --git a/mdl/linter/starlark_javaactions_test.go b/mdl/linter/starlark_javaactions_test.go
new file mode 100644
index 000000000..3931fd55d
--- /dev/null
+++ b/mdl/linter/starlark_javaactions_test.go
@@ -0,0 +1,210 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package linter_test
+
+import (
+	"database/sql"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/mendixlabs/mxcli/mdl/catalog"
+	"github.com/mendixlabs/mxcli/mdl/linter"
+)
+
+// javaActionFixture builds a catalog holding one module, two Java actions (one
+// documented, one not) and three parameters (one documented, two not).
+//
+// Rows are inserted directly rather than round-tripped through a reader because
+// the subject here is the query + Starlark surface, not the MPR parser.
+func javaActionFixture(t *testing.T) *catalog.Catalog {
+	t.Helper()
+
+	cat, err := catalog.NewFromFile(filepath.Join(t.TempDir(), "cat.db"))
+	if err != nil {
+		t.Fatalf("NewFromFile: %v", err)
+	}
+	t.Cleanup(func() { cat.Close() })
+	db := cat.CatalogDB()
+
+	exec := func(q string, args ...any) {
+		t.Helper()
+		if _, err := db.Exec(q, args...); err != nil {
+			t.Fatalf("exec %s: %v", q, err)
+		}
+	}
+
+	exec(`INSERT INTO modules_data (Id, Name, ProjectId, SnapshotId) VALUES (?,?,?,?)`,
+		"mod-1", "Formula1Backend", "default", "s1")
+
+	insertAction := func(id, name, doc string) {
+		exec(`INSERT INTO java_actions_data
+			(Id, Name, QualifiedName, ModuleName, Folder, Documentation, ExportLevel,
+			 ReturnType, ParameterCount, ProjectId, SnapshotId)
+			VALUES (?,?,?,?,?,?,?,?,?,?,?)`,
+			id, name, "Formula1Backend."+name, "Formula1Backend", "", doc, "Hidden",
+			"String", 0, "default", "s1")
+	}
+	insertParam := func(id, actionID, actionName, name, desc string, ordinal int) {
+		exec(`INSERT INTO java_action_parameters_data
+			(Id, JavaActionId, JavaActionName, QualifiedName, ModuleName, Name,
+			 Description, ParameterType, IsRequired, Ordinal, ProjectId, SnapshotId)
+			VALUES (?,?,?,?,?,?,?,?,?,?,?,?)`,
+			id, actionID, actionName, "Formula1Backend."+actionName+"."+name,
+			"Formula1Backend", name, desc, "String", 1, ordinal, "default", "s1")
+	}
+
+	insertAction("ja-1", "ParseTop", "")                         // undocumented
+	insertAction("ja-2", "FormatLapTime", "Renders a lap time.") // documented
+	insertParam("p-1", "ja-1", "ParseTop", "pUri", "", 0)        // undocumented
+	insertParam("p-2", "ja-1", "ParseTop", "pDefault", "", 1)    // undocumented
+	insertParam("p-3", "ja-2", "FormatLapTime", "pMillis", "Elapsed milliseconds.", 0)
+
+	return cat
+}
+
+// The catalog stored only a parameter COUNT, so nothing downstream could see a
+// parameter's description — the field a caller reads in Studio Pro's action
+// dialog. This asserts the rows land and arrive attached to their action, in
+// declaration order.
+func TestJavaActions_CarryTheirParameters(t *testing.T) {
+	ctx := linter.NewLintContext(javaActionFixture(t), &minimalReader{})
+
+	byName := map[string]linter.JavaAction{}
+	for ja := range ctx.JavaActions() {
+		byName[ja.Name] = ja
+	}
+	if len(byName) != 2 {
+		t.Fatalf("got %d Java actions, want 2: %v", len(byName), byName)
+	}
+
+	parse := byName["ParseTop"]
+	if parse.Documentation != "" {
+		t.Errorf("ParseTop documentation = %q, want empty", parse.Documentation)
+	}
+	if len(parse.Parameters) != 2 {
+		t.Fatalf("ParseTop has %d parameters, want 2", len(parse.Parameters))
+	}
+	// Ordinal, not alphabetical: a signature read out of order is misleading.
+	if parse.Parameters[0].Name != "pUri" || parse.Parameters[1].Name != "pDefault" {
+		t.Errorf("parameters out of declaration order: %v", parse.Parameters)
+	}
+	if parse.Parameters[0].ParameterType != "String" || !parse.Parameters[0].IsRequired {
+		t.Errorf("parameter metadata lost: %+v", parse.Parameters[0])
+	}
+
+	fmtLap := byName["FormatLapTime"]
+	if fmtLap.Documentation == "" {
+		t.Error("FormatLapTime documentation was dropped")
+	}
+	if len(fmtLap.Parameters) != 1 || fmtLap.Parameters[0].Description == "" {
+		t.Errorf("FormatLapTime parameter description lost: %+v", fmtLap.Parameters)
+	}
+}
+
+// Marketplace and system modules carry code the user did not write, and every
+// other document iterator here excludes them. Reporting "the Community Commons
+// Java actions are undocumented" would bury the findings that are actionable.
+func TestJavaActions_ExcludeMarketplaceModules(t *testing.T) {
+	cat := javaActionFixture(t)
+	db := cat.CatalogDB()
+	if _, err := db.Exec(
+		`INSERT INTO modules_data (Id, Name, Source, ProjectId, SnapshotId) VALUES (?,?,?,?,?)`,
+		"mod-2", "CommunityCommons", "Marketplace", "default", "s1"); err != nil {
+		t.Fatalf("insert module: %v", err)
+	}
+	if _, err := db.Exec(`INSERT INTO java_actions_data
+		(Id, Name, QualifiedName, ModuleName, Folder, Documentation, ExportLevel,
+		 ReturnType, ParameterCount, ProjectId, SnapshotId)
+		VALUES (?,?,?,?,?,?,?,?,?,?,?)`,
+		"ja-9", "StringUtil", "CommunityCommons.StringUtil", "CommunityCommons", "",
+		"", "Hidden", "String", 0, "default", "s1"); err != nil {
+		t.Fatalf("insert action: %v", err)
+	}
+
+	ctx := linter.NewLintContext(cat, &minimalReader{})
+	for ja := range ctx.JavaActions() {
+		if ja.ModuleName == "CommunityCommons" {
+			t.Errorf("a Marketplace module's Java action was reported: %s", ja.QualifiedName)
+		}
+	}
+}
+
+// The rule under test is the one that ships, loaded from disk — not a copy
+// inlined here. A test against an inlined copy proves the Starlark builtin works
+// and says nothing about whether QUAL002 uses it.
+func runMissingDocRule(t *testing.T, cat *catalog.Catalog, options map[string]any) []linter.Violation {
+	t.Helper()
+	rule, err := linter.LoadStarlarkRule("../../.claude/lint-rules/missing_documentation.star")
+	if err != nil {
+		t.Fatalf("loading the shipped QUAL002: %v", err)
+	}
+	if options != nil {
+		rule.Configure(options)
+	}
+	return rule.Check(linter.NewLintContext(cat, &minimalReader{}))
+}
+
+// mxcli-formula1: entities and microflows were covered; Java actions and their
+// parameters were not reachable from Starlark at all.
+func TestQUAL002_FlagsUndocumentedJavaActionsAndParameters(t *testing.T) {
+	vs := runMissingDocRule(t, javaActionFixture(t), nil)
+
+	var messages []string
+	for _, v := range vs {
+		messages = append(messages, v.Message)
+	}
+	joined := strings.Join(messages, "\n")
+
+	for _, want := range []string{
+		"Java action 'ParseTop' has no documentation.",
+		"Java action parameter 'ParseTop.pUri' has no description.",
+		"Java action parameter 'ParseTop.pDefault' has no description.",
+	} {
+		if !strings.Contains(joined, want) {
+			t.Errorf("QUAL002 did not report %q; got:\n%s", want, joined)
+		}
+	}
+	// The documented action and its documented parameter must stay quiet,
+	// otherwise the rule is noise rather than a signal.
+	if strings.Contains(joined, "FormatLapTime") {
+		t.Errorf("a documented action was flagged:\n%s", joined)
+	}
+}
+
+// Each target is switchable, so a project that has decided Java actions are
+// self-describing can silence just that half without losing the rest.
+func TestQUAL002_TargetsAreIndividuallySwitchable(t *testing.T) {
+	cat := javaActionFixture(t)
+
+	noParams := runMissingDocRule(t, cat, map[string]any{"check_java_action_params": false})
+	for _, v := range noParams {
+		if strings.Contains(v.Message, "parameter") {
+			t.Errorf("check_java_action_params=false still reported: %s", v.Message)
+		}
+	}
+	if len(noParams) == 0 {
+		t.Error("switching off parameters must not switch off the actions too")
+	}
+
+	noActions := runMissingDocRule(t, cat, map[string]any{"check_java_actions": false})
+	for _, v := range noActions {
+		if strings.Contains(v.Message, "Java action '") {
+			t.Errorf("check_java_actions=false still reported: %s", v.Message)
+		}
+	}
+}
+
+// A guard against the fixture silently rotting: if the schema loses the
+// parameters table, every assertion above would pass by reporting nothing.
+func TestJavaActionParametersTableExists(t *testing.T) {
+	cat := javaActionFixture(t)
+	var n int
+	if err := cat.CatalogDB().QueryRow(
+		`SELECT COUNT(*) FROM java_action_parameters`).Scan(&n); err != nil && err != sql.ErrNoRows {
+		t.Fatalf("java_action_parameters is not queryable: %v", err)
+	}
+	if n != 3 {
+		t.Errorf("java_action_parameters holds %d rows, want 3", n)
+	}
+}

From fbb1609b57d6a9ed82a9415257443d145d6c766e Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 9 Aug 2026 21:07:10 +0000
Subject: [PATCH 25/29] feat(lint): QUAL002 sweeps every document type; stop
 reporting System
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Extends the previous commit from four targets to all of them. Nineteen
document types are now swept by one table-driven projection rather than
nineteen bespoke builtins, so covering a new Mendix document type is two
rows: one in documentableSources naming the catalog table and its
documentation column, one in _DOC_KINDS giving the option and suggestion.

On by default, one option each: Module, Entity, Page, Snippet, Building
block, Layout, Enumeration, JavaScript action, Image collection, Data
transformer, Workflow, Business event service, REST client, Published
REST service, Constant, JSON structure, Import mapping, Export mapping.
Off by default: attributes and associations — a domain model has hundreds
and the same check there is a wall of text rather than a signal. Java
action parameters stay on: an action has a handful, and Studio Pro shows
each description to whoever wires up the call.

Also fixes a leak the sweep made impossible to ignore. modules.Source
carries "Marketplace ..." for downloaded modules and is empty for System
exactly as it is for the user's own, so the usual
`WHERE COALESCE(m.Source,'') = ''` excludes Marketplace and lets all of
System through. On a blank 9.24 project that was 52 findings, of which 47
were FileDocument, HttpRequest and friends. Filtering additionally on the
sentinel module id leaves the 5 that are the user's. Around ten other
LintContext iterators still carry the Source-only filter and leak System
into their own rules; those are left alone here rather than silently
changing every rule's output in a documentation commit.

The documentation column is not uniform — Mendix says Documentation for
Java actions, REST and mappings, Description for the rest — and a revert
control confirms assuming one spelling silently drops five kinds.

Verified end to end, not only in unit tests: exec'd MDL against a real
.mpr creating documented and undocumented elements, rebuilt the catalog
and ran the CLI, which reports the undocumented ones and stays silent on
the documented ones. Unit fixtures insert catalog rows directly and so
cannot see a builder that never populates a column.
---
 .claude/lint-rules/missing_documentation.star | 212 ++++++++++++----
 .claude/skills/fix-issue.md                   |   1 +
 cmd/mxcli/cmd_lint.go                         |   6 +-
 docs-site/src/tools/starlark-rules.md         |  84 +++++--
 mdl/linter/context.go                         | 152 ++++++++++-
 mdl/linter/starlark.go                        |  50 +++-
 mdl/linter/starlark_javaactions_test.go       | 235 ++++++++++++++++++
 7 files changed, 657 insertions(+), 83 deletions(-)

diff --git a/.claude/lint-rules/missing_documentation.star b/.claude/lint-rules/missing_documentation.star
index 0259737b3..745cf2da0 100644
--- a/.claude/lint-rules/missing_documentation.star
+++ b/.claude/lint-rules/missing_documentation.star
@@ -1,27 +1,34 @@
 # Starlark Lint Rule: Missing Documentation
 #
 # Undocumented model elements are invisible to `mxcli check` and to the build —
-# nothing fails, so nothing reminds you. This rule is the reminder.
+# nothing fails, so nothing reminds you. This rule is the reminder, and it
+# covers every document type a user authors, not just the domain model.
 #
-# Checks, each independently switchable (see Options):
-#   - Entities              .description
-#   - Microflows            .description   (nanoflows and trivial flows exempt)
-#   - Java actions          .documentation
-#   - Java action params    .description   <- the one Studio Pro shows a CALLER
-#   - Entity attributes     .description   (off by default: high volume)
+# Documents swept generically (one option each, all default True):
+#   Module, Entity, Page, Snippet, BuildingBlock, Layout, Enumeration,
+#   JavaScriptAction, ImageCollection, DataTransformer, Workflow,
+#   BusinessEventService, RestClient, PublishedRestService, Constant,
+#   JsonStructure, ImportMapping, ExportMapping
 #
-# Why parameters matter more than they look: Studio Pro renders a Java action's
-# parameter descriptions in the dialog where someone wires up the call. An
-# undocumented parameter is a blank field next to a name like `pInput`, at
-# exactly the moment a caller has to decide what to pass.
+# Handled separately, because they carry exemptions or children a uniform
+# sweep cannot express:
+#   Microflow          .description   (nanoflows and trivial flows exempt)
+#   JavaAction         .documentation
+#   JavaAction params  .description   <- the one Studio Pro shows a CALLER
 #
-# Options (lint config `options:` block for QUAL002):
-#   check_entities             bool, default True
-#   check_microflows           bool, default True
-#   check_java_actions         bool, default True
-#   check_java_action_params   bool, default True
-#   check_attributes           bool, default False
-#   min_activities             int,  default 3   (microflows below this are exempt)
+# Members, off by default purely because of volume:
+#   Attribute          .description
+#   Association        .description
+#
+# Why Java action parameters default ON while attributes default OFF: an action
+# has a handful of parameters and Studio Pro renders each description in the
+# dialog where someone wires up the call — an undocumented parameter is a blank
+# field next to a name like `pInput` at exactly the moment a caller has to
+# decide what to pass. A domain model has hundreds of attributes and
+# associations, so the same check there is a wall of text rather than a signal.
+#
+# Every kind is individually switchable; see the table in _DOC_KINDS and the
+# options listed under docs-site/src/tools/starlark-rules.md.
 
 RULE_ID = "QUAL002"
 RULE_NAME = "Missing Documentation"
@@ -29,6 +36,113 @@ DESCRIPTION = "Model elements should have documentation describing their purpose
 CATEGORY = "quality"
 SEVERITY = "info"
 
+# kind (as emitted by documentable_elements) -> (option, noun, suggestion)
+#
+# A new Mendix document type is covered by adding a row in Go's
+# documentableSources and a row here — not by writing another loop.
+_DOC_KINDS = {
+    "Module": (
+        "check_modules",
+        "Module",
+        "Document what the module is for: it is the first thing a newcomer opens.",
+    ),
+    "Entity": (
+        "check_entities",
+        "Entity",
+        "Add a description explaining the entity's purpose and what data it represents.",
+    ),
+    "Page": (
+        "check_pages",
+        "Page",
+        "Describe what the page shows and who reaches it.",
+    ),
+    "Snippet": (
+        "check_snippets",
+        "Snippet",
+        "Describe what the snippet renders and what context it expects, since it is reused across pages.",
+    ),
+    "BuildingBlock": (
+        "check_building_blocks",
+        "Building block",
+        "Describe what the building block is for: it exists to be dropped in by someone who did not write it.",
+    ),
+    "Layout": (
+        "check_layouts",
+        "Layout",
+        "Describe the layout's intended use and its placeholders.",
+    ),
+    "Enumeration": (
+        "check_enumerations",
+        "Enumeration",
+        "Describe what the enumeration models, especially where the values map to something external.",
+    ),
+    "JavaScriptAction": (
+        "check_javascript_actions",
+        "JavaScript action",
+        "Document what the action does and what it returns. Like a Java action, its body is code the model cannot show a reader.",
+    ),
+    "ImageCollection": (
+        "check_image_collections",
+        "Image collection",
+        "Describe what the collection is for and where its images are used.",
+    ),
+    "DataTransformer": (
+        "check_data_transformers",
+        "Data transformer",
+        "Describe the transformation applied and the shape it expects.",
+    ),
+    "Workflow": (
+        "check_workflows",
+        "Workflow",
+        "Describe the process the workflow models and who its user tasks are for.",
+    ),
+    "BusinessEventService": (
+        "check_business_event_services",
+        "Business event service",
+        "Document the events published or consumed, since other applications depend on them.",
+    ),
+    "RestClient": (
+        "check_rest_clients",
+        "REST client",
+        "Document which external service is consumed and what it is used for.",
+    ),
+    "PublishedRestService": (
+        "check_published_rest_services",
+        "Published REST service",
+        "Document the contract: this is the description external consumers read.",
+    ),
+    "Constant": (
+        "check_constants",
+        "Constant",
+        "Describe what the constant configures and what a valid value looks like — it is set per environment by someone who cannot see the code.",
+    ),
+    "JsonStructure": (
+        "check_json_structures",
+        "JSON structure",
+        "Note which payload the structure was captured from.",
+    ),
+    "ImportMapping": (
+        "check_import_mappings",
+        "Import mapping",
+        "Describe the source payload and what it maps onto.",
+    ),
+    "ExportMapping": (
+        "check_export_mappings",
+        "Export mapping",
+        "Describe the target payload and what it is produced for.",
+    ),
+    "Association": (
+        # Off by default with attributes: a real domain model has as many
+        # associations as entities, and none of them are documented.
+        "check_associations",
+        "Association",
+        "Add a description, or switch this off with `check_associations: false` if the names are self-describing here.",
+    ),
+}
+
+# Kinds whose option defaults to False. Everything else defaults to True.
+_OFF_BY_DEFAULT = {"check_associations": True}
+
 def _blank(text):
     """True when a documentation field is absent or whitespace-only."""
     return not text or text.strip() == ""
@@ -47,32 +161,28 @@ def _flag(violations, module, doc_type, doc_name, message, suggestion):
 def check():
     violations = []
 
-    if get_option("check_entities", True):
-        for entity in entities():
-            if _blank(entity.description):
-                _flag(
-                    violations,
-                    entity.module_name,
-                    "Entity",
-                    entity.qualified_name,
-                    "Entity '{}' has no documentation.".format(entity.name),
-                    "Add a description explaining the entity's purpose and what data it represents.",
-                )
-
-    if get_option("check_attributes", False):
-        for entity in entities():
-            for attr in attributes_for(entity.qualified_name):
-                if _blank(attr.description):
-                    _flag(
-                        violations,
-                        entity.module_name,
-                        "Entity",
-                        entity.qualified_name,
-                        "Attribute '{}.{}' has no documentation.".format(entity.name, attr.name),
-                        "Add a description, or switch this off with `check_attributes: false` if " +
-                        "attribute names are self-describing in this project.",
-                    )
+    # ---- every document type, one sweep -------------------------------------
+    for el in documentable_elements():
+        entry = _DOC_KINDS.get(el.kind)
+        if entry == None:
+            # A kind Go knows about but this table does not. Staying silent is
+            # right: a rule inventing a message for an element it cannot
+            # describe is worse than not reporting it.
+            continue
+        option, noun, suggestion = entry
+        if not get_option(option, not _OFF_BY_DEFAULT.get(option, False)):
+            continue
+        if _blank(el.description):
+            _flag(
+                violations,
+                el.module_name,
+                el.kind,
+                el.qualified_name,
+                "{} '{}' has no documentation.".format(noun, el.name),
+                suggestion,
+            )
 
+    # ---- microflows: exempt nanoflows and trivial flows ---------------------
     if get_option("check_microflows", True):
         # Nanoflows are excluded: they are usually a couple of client-side steps
         # whose name says everything a description would.
@@ -92,6 +202,7 @@ def check():
                     "Add a description explaining what this microflow does and when it should be called.",
                 )
 
+    # ---- Java actions and their parameters ----------------------------------
     check_actions = get_option("check_java_actions", True)
     check_params = get_option("check_java_action_params", True)
     if check_actions or check_params:
@@ -120,4 +231,19 @@ def check():
                         "where the parameter name is all they otherwise have to go on.",
                     )
 
+    # ---- entity attributes (off by default: high volume) --------------------
+    if get_option("check_attributes", False):
+        for entity in entities():
+            for attr in attributes_for(entity.qualified_name):
+                if _blank(attr.description):
+                    _flag(
+                        violations,
+                        entity.module_name,
+                        "Entity",
+                        entity.qualified_name,
+                        "Attribute '{}.{}' has no documentation.".format(entity.name, attr.name),
+                        "Add a description, or switch this off with `check_attributes: false` if " +
+                        "attribute names are self-describing in this project.",
+                    )
+
     return violations
diff --git a/.claude/skills/fix-issue.md b/.claude/skills/fix-issue.md
index 612c2cf1d..fb1bd7f5a 100644
--- a/.claude/skills/fix-issue.md
+++ b/.claude/skills/fix-issue.md
@@ -446,3 +446,4 @@ extracting `OffsetExpression`/`LimitExpression`.
 | `mxcli run --local` refuses to boot — *"port 6643 is already in use — a previous 'mxcli run --local' … is likely still serving on it"* — and names a process the user already killed. The guard is right to refuse; the diagnosis is a guess, and the recovery it suggests is a three-command `pgrep` hunt whose own pattern (`pgrep -f 'mxcli run'`) matches the shell it is typed into | Two different situations printed one message. mxcli **does** reap its children on Ctrl-C/SIGTERM (`procgroup_unix.go` puts mxbuild's JVM, the runtime and the bundler each in their own process group and signals the group), so a held port after a graceful stop is a *foreign* listener. But `kill -9`, a crash, or a reaped container runs no handler at all, and then it really is the previous run's orphan. The guard could not tell them apart because it never asked who held the port | `cmd/mxcli/docker/portowner_linux.go` (`listenerOnPort`, `parseListeningInodes`, `pidForSocketInode`), `portowner_other.go` (non-Linux stub), `portguard.go` (`portCulpritAdvice`), wired into `checkTargetPortsFree` (`runlocal.go`) and `checkLocalAppPortsFree` (`localapp.go`) | **Resolve the port owner from `/proc`, never by shelling out to `lsof`/`ss`** — both are routinely absent from slim containers, and needing a subprocess to explain why a boot failed is its own failure mode. `/proc/net/tcp{,6}` gives the socket inode; scanning `/proc/<pid>/fd` for `socket:[<inode>]` gives the pid. **Read `tcp6` as well as `tcp`**: a JVM binding "localhost" lands on `[::1]` or dual-stack `[::]` as often as `127.0.0.1`, and its local_address is a 128-bit hex blob, not the 32-bit one. **Filter on state `0A` (TCP_LISTEN)** — an ESTABLISHED socket on that port is a *client*, and naming it would tell the user to kill their own browser. **Report the two cases differently**: a leftover of a previous run gets `kill <pid>`, a foreign listener gets "pick another port" and no kill suggestion, because offering to kill a stranger's process is worse advice than the vague message it replaced. Keep the guard **detection-only** — reaping someone else's process stays the user's call. **Three test traps hit in a row here.** (1) The live-IPv6 test only ever *skipped* (no IPv6 in the container), so the tcp6 parser was effectively untested — assert against captured kernel output instead. (2) A parser test calling `parseListeningInodes` directly does not prove `listeningInodes` *opens* both files: deleting `/proc/net/tcp6` from the list left every test green. (3) Making the list a `var` so a test can point it at fixtures then means the test no longer covers the **shipped** default either — assert the default's contents before overriding it. Only the third version of that control failed. The best test in the file is the cheapest: bind a port in the test process and demand `listenerOnPort` return `os.Getpid()` — it cannot pass by accident. Tests `cmd/mxcli/docker/portowner_linux_test.go`. mxcli-formula1 suggested issue 8 |
 | `create external entities from` a service where an entity set is wholly unfilterable/unsortable generates an app the contract contradicts: **28 × CE6630** on one service — "'message' is marked Sortable=False in the OData service, but True in the app". The publisher is right, the `$metadata` is right, only the generated consumer is wrong | `FilterRestrictions`/`SortRestrictions` have **two shapes**, and only one was read. `applyCapabilityAnnotations` pulled `NonFilterableProperties` out of the record and ignored the record's own `Bool` property value, so `Filterable: !nonFilterable[p.Name]` evaluated `true` for every property of a set that had declared nothing filterable. This is the §42 Top/Skip bug one layer along — same vocabulary, same two-shapes cause, different term | `mdl/types/edmx.go` (`EdmEntitySet.Filterable`/`Sortable`, the `Filterable`/`Sortable` cases in `applyCapabilityAnnotations`, and the `AttrFilterable`/`AttrSortable` accessors), `mdl/executor/cmd_contract.go` (`createExternalEntities` calls the accessors) | **Mendix picks the annotation shape by arithmetic, not preference.** It lists `NonFilterableProperties` when SOME attributes are filterable and emits a bare `<PropertyValue Bool="false" Property="Filterable"/>` when NONE are, because then there is no list to write — so both shapes appear in **one document** on different entity sets, and an entity exposing only a KEY reliably produces the whole-set form. A fixture with just the list shape tests the half that already worked. **After fixing one term in a vocabulary, sweep the siblings**: §42 fixed Top/Skip by teaching the parser about standalone booleans and stopped there; Filterable/Sortable had the same defect and were found only because a consumer app failed to build. Grep the whole `applyCapabilityAnnotations` switch for terms whose Bool is never read. **Put both shapes behind one accessor** (`AttrFilterable`) rather than two fields the caller must remember to AND together — the caller then cannot consult one and forget the other, which is exactly how this arose, and the nil-safe receiver deletes the `entitySet != nil` dance at the call site. Absent still means `true`: OData's default is allowed, and defaulting to false would invert CE6630 for every unannotated service. Tests `mdl/types/edmx_test.go` (`TestParseEdmx_WholeSetFilterAndSortRestrictions`, plus a control proving the list shape still parses); both controls reproduce (ignore the record Bool → the whole-set test fails with the CE6630 message; drop the check inside `AttrFilterable` → same). mxcli-formula1 §48 |
 | A project is generated with no documentation anywhere — Java actions, Java action parameters, entities, microflows — and nothing says so. `mxcli check` and the build both pass, because documentation is never load-bearing | `QUAL002` existed but reached only entities and microflows. Java actions were not reachable from Starlark **at all** (no `java_actions()` builtin), and a Java action's parameters were not reachable from anywhere: the catalog stored a parameter *count* and discarded each parameter's `Description` | `mdl/catalog/tables.go` (`java_action_parameters_data` + view, `CatalogSchemaVersion` bump), `mdl/catalog/catalog.go` (`Tables()` registry), `mdl/catalog/builder_modules.go` (insert parameters), `mdl/linter/context.go` (`JavaActions()` with parameters attached), `mdl/linter/starlark.go` (`java_actions()` builtin, `javaActionToStarlark`), `.claude/lint-rules/missing_documentation.star` | **Adding a catalog table has three obligations beyond the `CREATE TABLE`.** (1) Bump `CatalogSchemaVersion` — otherwise every existing `.mxcli/catalog.db` keeps its old schema, the new query fails, the error is swallowed, and the rule silently reports *zero* of the new findings. Silent under-reporting from a stale cache is indistinguishable from a clean project. (2) Register the view in `Tables()` — `catalog_test.go` enforces this and will fail with "add CATALOG.X so SHOW CATALOG TABLES includes it"; let that test tell you rather than discovering it from a user. (3) Exclude Marketplace/System modules in the iterator's `WHERE COALESCE(m.Source,'') = ''`, as every sibling iterator does — reporting undocumented Community Commons actions buries the findings the user can act on. **Attach children to their parent in the projection, not as a second iterator**: a rule reporting an undocumented parameter must name the action it belongs to, and pairing them in `JavaActions()` saves every rule from re-joining. **Load the shipped `.star` from disk in tests** — an inlined copy proves the builtin works and says nothing about whether the rule uses it. **Make each target switchable via `get_option`** before widening a rule: attribute-level checks are hundreds of findings on a real domain model, so `check_attributes` defaults off while the rest default on. Watch the whitespace when writing revert controls for Starlark: a `perl` pattern with `\t` silently matches nothing in a space-indented `.star`, so the control passes and proves nothing — it was the second attempt that failed correctly. Tests `mdl/linter/starlark_javaactions_test.go`; five controls reproduce. mxcli-formula1 (missing documentation) |
+| QUAL002 reports ~40 platform elements (`FileDocument`, `HttpRequest`, `System`) as undocumented, burying the handful of real findings; or a whole document type (pages, workflows, constants, REST services, mappings) is never reported at all no matter how undocumented it is | Two separate causes. (1) **Coverage**: QUAL002 only ever looked at entities and microflows — every other document type was unreachable from Starlark. (2) **The System leak**: `modules.Source` is `"Marketplace …"` for downloaded modules and **empty for System — exactly as it is for the user's own modules**, so the near-universal `WHERE COALESCE(m.Source,'') = ''` filter excludes Marketplace and lets all of System through | `mdl/linter/context.go` (`documentableSources`, `DocumentableElements()`, `notPlatformModule()`, `systemModuleID`), `mdl/linter/starlark.go` (`documentable_elements()` builtin), `.claude/lint-rules/missing_documentation.star` (`_DOC_KINDS`) | **Source alone does not exclude System** — only the sentinel Id `00000000-0000-0000-0000-000000000001` does (`modelsdk/meta.SystemModuleID`). Use `notPlatformModule(alias)`; ~10 other `LintContext` iterators still carry the Source-only filter and leak System into their rules the same way. **One projection beats N builtins**: a rule that wants "every document" should get one `documentable_elements()` sweep driven by a table, so a new Mendix document type is two rows (one in `documentableSources`, one in `_DOC_KINDS`) rather than another builtin nobody remembers to call. **The documentation column is NOT uniform** — Mendix says `Documentation` for Java actions / REST / mappings / JSON structures and `Description` for everything else; assuming one spelling silently reports the other half as undocumented (a revert control confirmed 5 kinds go dark). **Test the catalog BUILDER, not just the query**: unit tests that INSERT rows directly cannot see that a builder never populates a column, which would flood the user with false positives — an end-to-end `exec` + `lint` on a real `.mpr` is what proved the constant/entity paths actually work. Three tables (`json_structures`, `import_mappings`, `export_mappings`) use `Id INTEGER PRIMARY KEY AUTOINCREMENT` while the rest use `Id TEXT PRIMARY KEY`, so a synthetic string id is a "datatype mismatch" on exactly those. Beware: MDL `COMMENT` and `DOCUMENTATION` are **different fields** on an entity — `CREATE ENTITY … COMMENT 'x'` does not set documentation, `ALTER ENTITY … SET DOCUMENTATION 'x'` does; a test using the wrong one looks exactly like a write-path bug. Tests `mdl/linter/starlark_javaactions_test.go`; controls reproduce for the sweep, each kind list, the doc-column split, Marketplace (both join shapes) and System |
diff --git a/cmd/mxcli/cmd_lint.go b/cmd/mxcli/cmd_lint.go
index 7d5173853..9f6c79320 100644
--- a/cmd/mxcli/cmd_lint.go
+++ b/cmd/mxcli/cmd_lint.go
@@ -47,8 +47,10 @@ Bundled Starlark rules (in .claude/lint-rules/):
   - Entity business key (ARCH003) - persistent entities need a unique key
   Quality:
   - McCabe complexity (QUAL001) - microflow cyclomatic complexity threshold
-  - Missing documentation (QUAL002) - entities, microflows, Java actions and their
-      parameters need documentation (attributes too, via check_attributes)
+  - Missing documentation (QUAL002) - every document type (modules, entities,
+      pages, microflows, workflows, Java/JavaScript actions and their parameters,
+      REST services, mappings, constants, ...). Attributes and associations are
+      off by default; see the check_* options.
   - Long microflows (QUAL003) - microflows with too many activities
   - Orphaned elements (QUAL004) - unreferenced elements in the project
   Design:
diff --git a/docs-site/src/tools/starlark-rules.md b/docs-site/src/tools/starlark-rules.md
index 9f91c4280..fc5a5ac53 100644
--- a/docs-site/src/tools/starlark-rules.md
+++ b/docs-site/src/tools/starlark-rules.md
@@ -28,7 +28,7 @@ In addition to the built-in Go rules, mxcli bundles 27 Starlark-based lint rules
 | Rule | Description |
 |------|-------------|
 | **QUAL001** | McCabe complexity -- Flags microflows with high cyclomatic complexity |
-| **QUAL002** | Documentation -- Missing documentation on entities, microflows, Java actions and Java action parameters ([options](#qual002-options)) |
+| **QUAL002** | Documentation -- Missing documentation across every document type: modules, entities, pages, microflows, workflows, Java/JavaScript actions and their parameters, REST services, mappings, constants ([options](#qual002-options)) |
 | **QUAL003** | Long microflows -- Warns about microflows with too many activities |
 | **QUAL004** | Orphaned elements -- Detects unused entities, microflows, or pages |
 
@@ -52,29 +52,53 @@ Additional convention rules cover access rule constraints, role mapping, microfl
 ### QUAL002 options {#qual002-options}
 
 Undocumented model elements are invisible to `mxcli check` and to the build —
-nothing fails, so nothing reminds you. QUAL002 is that reminder, and it covers
-more than the domain model:
-
-| Option | Default | Checks |
-|---|---|---|
-| `check_entities` | `true` | entity descriptions |
-| `check_microflows` | `true` | microflow descriptions (nanoflows always exempt) |
-| `check_java_actions` | `true` | Java action documentation |
-| `check_java_action_params` | `true` | Java action **parameter** descriptions |
-| `check_attributes` | `false` | entity attribute descriptions |
-| `min_activities` | `3` | microflows with fewer activities are exempt |
-
-Parameter descriptions are worth more than they look: Studio Pro renders them in
-the dialog where someone wires up the call, so an undocumented parameter is a
-blank field next to a name like `pInput` at exactly the moment a caller has to
-decide what to pass. Java actions matter for the same reason one step up — unlike
-a microflow, the body is Java the model cannot show a reader.
-
-`check_attributes` is off by default only because of volume: a real domain model
-has hundreds of attributes, and turning it on at `info` severity is a long list.
-Turn it on when you are actually working through documentation debt.
-
-Set options in the lint config:
+nothing fails, so nothing reminds you. QUAL002 is that reminder, and it sweeps
+**every document type a user authors**, not just the domain model.
+
+**On by default** — one option per document type:
+
+| Option | Element |
+|---|---|
+| `check_modules` | Module |
+| `check_entities` | Entity |
+| `check_pages` | Page |
+| `check_snippets` | Snippet |
+| `check_building_blocks` | Building block |
+| `check_layouts` | Layout |
+| `check_enumerations` | Enumeration |
+| `check_microflows` | Microflow (nanoflows always exempt) |
+| `check_java_actions` | Java action |
+| `check_java_action_params` | Java action **parameter** |
+| `check_javascript_actions` | JavaScript action |
+| `check_workflows` | Workflow |
+| `check_constants` | Constant |
+| `check_image_collections` | Image collection |
+| `check_data_transformers` | Data transformer |
+| `check_business_event_services` | Business event service |
+| `check_rest_clients` | Consumed REST client |
+| `check_published_rest_services` | Published REST service |
+| `check_json_structures` | JSON structure |
+| `check_import_mappings` | Import mapping |
+| `check_export_mappings` | Export mapping |
+
+**Off by default** — members, suppressed for volume rather than for being
+unimportant:
+
+| Option | Element |
+|---|---|
+| `check_attributes` | Entity attribute |
+| `check_associations` | Association |
+
+Plus `min_activities` (default `3`): microflows with fewer activities are exempt,
+on the grounds that a three-step flow's name says what a description would.
+
+Why the split. A Java action has a handful of parameters, and Studio Pro renders
+each description in the dialog where someone wires up the call — an undocumented
+parameter is a blank field next to a name like `pInput` at exactly the moment a
+caller has to decide what to pass. A domain model, by contrast, has hundreds of
+attributes and associations, so the same check there is a wall of text rather
+than a signal. Turn those two on when you are actively working through
+documentation debt:
 
 ```yaml
 rules:
@@ -82,9 +106,21 @@ rules:
     enabled: true
     options:
       check_attributes: true
+      check_associations: true
+      check_pages: false        # e.g. if page names are the convention here
       min_activities: 5
 ```
 
+Elements in System and Marketplace modules are never reported — that is code you
+did not write, and flagging Community Commons would bury the findings you can
+act on.
+
+Adding a document type to the sweep is two rows: one in `documentableSources`
+(`mdl/linter/context.go`) naming the catalog table and its documentation column,
+and one in `_DOC_KINDS` (`missing_documentation.star`) giving the option name and
+the suggestion text. `TestQUAL002_SweepsEveryAdvertisedDocumentType` fails if the
+Go side advertises a kind the tests do not cover.
+
 ## Where Starlark Rules Live
 
 When you run `mxcli init`, Starlark rules are installed to:
diff --git a/mdl/linter/context.go b/mdl/linter/context.go
index 898537ffd..36939d315 100644
--- a/mdl/linter/context.go
+++ b/mdl/linter/context.go
@@ -4,6 +4,7 @@ package linter
 
 import (
 	"database/sql"
+	"fmt"
 	"iter"
 
 	"github.com/mendixlabs/mxcli/mdl/catalog"
@@ -1233,14 +1234,14 @@ func (ctx *LintContext) JavaActions() iter.Seq[JavaAction] {
 	return func(yield func(JavaAction) bool) {
 		params := ctx.javaActionParameters()
 
-		rows, err := ctx.db.Query(`
+		rows, err := ctx.db.Query(fmt.Sprintf(`
 			SELECT ja.Id, ja.Name, ja.QualifiedName, ja.ModuleName, ja.Folder,
 			       ja.Documentation, ja.ExportLevel, ja.ReturnType
 			FROM java_actions ja
 			LEFT JOIN modules m ON ja.ModuleName = m.Name
-			WHERE COALESCE(m.Source, '') = ''
+			WHERE %s
 			ORDER BY ja.ModuleName, ja.Name
-		`)
+		`, notPlatformModule("m")))
 		if err != nil {
 			return
 		}
@@ -1298,3 +1299,148 @@ func (ctx *LintContext) javaActionParameters() map[string][]JavaActionParameter
 	}
 	return out
 }
+
+// systemModuleID is the fixed sentinel Mendix gives the built-in System module
+// (mirrors modelsdk/meta.SystemModuleID, not imported to keep the linter free of
+// an engine dependency).
+//
+// System is NOT distinguishable by modules.Source — that column carries
+// "Marketplace …" for downloaded modules and is empty for System exactly as it
+// is for the user's own modules. Filtering on Source alone therefore lets every
+// System element through, which is how QUAL002 came to report FileDocument,
+// HttpRequest and 35 other platform entities as undocumented.
+const systemModuleID = "00000000-0000-0000-0000-000000000001"
+
+// notPlatformModule is the WHERE fragment that keeps a query to modules the user
+// actually owns: not downloaded from the Marketplace, and not System.
+//
+// `alias` is the modules-table alias to test.
+func notPlatformModule(alias string) string {
+	return fmt.Sprintf(
+		`COALESCE(%[1]s.Source, '') = '' AND COALESCE(%[1]s.Id, '') <> '%[2]s'`,
+		alias, systemModuleID)
+}
+
+// Documentable is one model element that can carry documentation, projected
+// uniformly across catalog tables so a rule can sweep every document type
+// without a query per kind.
+type Documentable struct {
+	Kind          string // Mendix term: "Page", "Enumeration", "Workflow", …
+	Name          string
+	QualifiedName string
+	ModuleName    string
+	Description   string
+}
+
+// documentableSource maps a catalog table to the Mendix term for what it holds
+// and the column its documentation lives in.
+//
+// The doc column is NOT uniform — Mendix says "Documentation" for some element
+// types and "Description" for others, and the catalog faithfully mirrors that.
+// A sweep that assumes one spelling silently reports every element of the other
+// half as undocumented.
+type documentableSource struct {
+	Table  string
+	Kind   string
+	DocCol string
+}
+
+// documentableSources is every document type a user authors and can document.
+//
+// Deliberately absent, and why:
+//   - microflows, java_actions — swept by the rule separately, because they
+//     carry exemptions (activity thresholds) and children (parameters) that a
+//     uniform projection cannot express.
+//   - attributes, java_action_parameters — members of a document, not
+//     documents; the rule checks them under their own options.
+//   - activities, widgets, widget_definition_properties, xpath_expressions —
+//     sub-elements INSIDE a document. Mendix offers no documentation field for
+//     most of them, and flagging every widget would drown the rule.
+//   - contract_entities — generated from a remote service's $metadata. Not the
+//     user's text to write, so not the user's omission to report.
+var documentableSources = []documentableSource{
+	{"modules", "Module", "Description"},
+	{"entities", "Entity", "Description"},
+	{"associations", "Association", "Description"},
+	{"pages", "Page", "Description"},
+	{"snippets", "Snippet", "Description"},
+	{"building_blocks", "BuildingBlock", "Description"},
+	{"layouts", "Layout", "Description"},
+	{"enumerations", "Enumeration", "Description"},
+	{"javascript_actions", "JavaScriptAction", "Description"},
+	{"image_collections", "ImageCollection", "Description"},
+	{"data_transformers", "DataTransformer", "Description"},
+	{"workflows", "Workflow", "Description"},
+	{"business_event_services", "BusinessEventService", "Documentation"},
+	{"rest_clients", "RestClient", "Documentation"},
+	{"published_rest_services", "PublishedRestService", "Documentation"},
+	{"constants", "Constant", "Description"},
+	{"json_structures", "JsonStructure", "Documentation"},
+	{"import_mappings", "ImportMapping", "Documentation"},
+	{"export_mappings", "ExportMapping", "Documentation"},
+}
+
+// DocumentableKinds returns the Kind of every source, for tests and for the
+// `mxcli lint` help text to stay in step with the code.
+func DocumentableKinds() []string {
+	kinds := make([]string, 0, len(documentableSources))
+	for _, s := range documentableSources {
+		kinds = append(kinds, s.Kind)
+	}
+	return kinds
+}
+
+// DocumentableElements iterates every documentable element across all document
+// types, excluding System and Marketplace modules.
+//
+// Each source is queried separately rather than UNIONed so that a catalog
+// missing one table (an older cache, or a Mendix version without that document
+// type) loses only that kind instead of the whole sweep.
+func (ctx *LintContext) DocumentableElements() iter.Seq[Documentable] {
+	return func(yield func(Documentable) bool) {
+		for _, src := range documentableSources {
+			// The modules table has no module to join to — it IS the module
+			// list — so it filters on its own Source column.
+			query := fmt.Sprintf(`
+				SELECT t.Name, t.QualifiedName, t.ModuleName, COALESCE(t.%s, '')
+				FROM %s t
+				LEFT JOIN modules m ON t.ModuleName = m.Name
+				WHERE %s
+				ORDER BY t.ModuleName, t.Name
+			`, src.DocCol, src.Table, notPlatformModule("m"))
+			if src.Table == "modules" {
+				query = fmt.Sprintf(`
+					SELECT t.Name, t.QualifiedName, t.Name, COALESCE(t.%s, '')
+					FROM %s t
+					WHERE %s
+					ORDER BY t.Name
+				`, src.DocCol, src.Table, notPlatformModule("t"))
+			}
+
+			rows, err := ctx.db.Query(query)
+			if err != nil {
+				continue // table absent in this catalog: skip this kind only
+			}
+			for rows.Next() {
+				d := Documentable{Kind: src.Kind}
+				var qn, mod sql.NullString
+				if err := rows.Scan(&d.Name, &qn, &mod, &d.Description); err != nil {
+					continue
+				}
+				d.QualifiedName = qn.String
+				d.ModuleName = mod.String
+				if d.QualifiedName == "" {
+					d.QualifiedName = d.Name
+				}
+				if ctx.IsExcluded(d.ModuleName) {
+					continue
+				}
+				if !yield(d) {
+					rows.Close()
+					return
+				}
+			}
+			rows.Close()
+		}
+	}
+}
diff --git a/mdl/linter/starlark.go b/mdl/linter/starlark.go
index 423681224..88623fa7f 100644
--- a/mdl/linter/starlark.go
+++ b/mdl/linter/starlark.go
@@ -314,17 +314,18 @@ func LoadStarlarkRule(path string) (*StarlarkRule, error) {
 func (r *StarlarkRule) buildPredeclared() starlark.StringDict {
 	return starlark.StringDict{
 		// Query functions
-		"entities":         starlark.NewBuiltin("entities", r.builtinEntities),
-		"microflows":       starlark.NewBuiltin("microflows", r.builtinMicroflows),
-		"java_actions":     starlark.NewBuiltin("java_actions", r.builtinJavaActions),
-		"pages":            starlark.NewBuiltin("pages", r.builtinPages),
-		"enumerations":     starlark.NewBuiltin("enumerations", r.builtinEnumerations),
-		"constants":        starlark.NewBuiltin("constants", r.builtinConstants),
-		"widgets":          starlark.NewBuiltin("widgets", r.builtinWidgets),
-		"refs_to":          starlark.NewBuiltin("refs_to", r.builtinRefsTo),
-		"refs_from":        starlark.NewBuiltin("refs_from", r.builtinRefsFrom),
-		"attributes_for":   starlark.NewBuiltin("attributes_for", r.builtinAttributesFor),
-		"scheduled_events": starlark.NewBuiltin("scheduled_events", r.builtinScheduledEvents),
+		"entities":              starlark.NewBuiltin("entities", r.builtinEntities),
+		"microflows":            starlark.NewBuiltin("microflows", r.builtinMicroflows),
+		"java_actions":          starlark.NewBuiltin("java_actions", r.builtinJavaActions),
+		"documentable_elements": starlark.NewBuiltin("documentable_elements", r.builtinDocumentableElements),
+		"pages":                 starlark.NewBuiltin("pages", r.builtinPages),
+		"enumerations":          starlark.NewBuiltin("enumerations", r.builtinEnumerations),
+		"constants":             starlark.NewBuiltin("constants", r.builtinConstants),
+		"widgets":               starlark.NewBuiltin("widgets", r.builtinWidgets),
+		"refs_to":               starlark.NewBuiltin("refs_to", r.builtinRefsTo),
+		"refs_from":             starlark.NewBuiltin("refs_from", r.builtinRefsFrom),
+		"attributes_for":        starlark.NewBuiltin("attributes_for", r.builtinAttributesFor),
+		"scheduled_events":      starlark.NewBuiltin("scheduled_events", r.builtinScheduledEvents),
 
 		// Graph-analysis facts (populated by `refresh catalog communities`).
 		"community_of":         starlark.NewBuiltin("community_of", r.builtinCommunityOf),
@@ -411,6 +412,33 @@ func (r *StarlarkRule) builtinJavaActions(_ *starlark.Thread, _ *starlark.Builti
 	return starlark.NewList(actions), nil
 }
 
+// builtinDocumentableElements returns every element that can carry
+// documentation, across all document types, as a uniform (kind, name,
+// qualified_name, module_name, description) projection.
+//
+// One builtin rather than nineteen: a rule sweeping for missing documentation
+// wants "every document", and a new Mendix document type should be covered by
+// adding a row to documentableSources, not by writing another builtin and
+// remembering to call it.
+func (r *StarlarkRule) builtinDocumentableElements(_ *starlark.Thread, _ *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error) {
+	if r.ctx == nil {
+		return starlark.NewList(nil), nil
+	}
+
+	var out []starlark.Value
+	for d := range r.ctx.DocumentableElements() {
+		out = append(out, starlarkstruct.FromStringDict(starlark.String("documentable"), starlark.StringDict{
+			"kind":           starlark.String(d.Kind),
+			"name":           starlark.String(d.Name),
+			"qualified_name": starlark.String(d.QualifiedName),
+			"module_name":    starlark.String(d.ModuleName),
+			"description":    starlark.String(d.Description),
+		}))
+	}
+
+	return starlark.NewList(out), nil
+}
+
 // builtinPages returns an iterator over pages.
 func (r *StarlarkRule) builtinPages(_ *starlark.Thread, _ *starlark.Builtin, args starlark.Tuple, kwargs []starlark.Tuple) (starlark.Value, error) {
 	if r.ctx == nil {
diff --git a/mdl/linter/starlark_javaactions_test.go b/mdl/linter/starlark_javaactions_test.go
index 3931fd55d..09fb292c9 100644
--- a/mdl/linter/starlark_javaactions_test.go
+++ b/mdl/linter/starlark_javaactions_test.go
@@ -4,6 +4,7 @@ package linter_test
 
 import (
 	"database/sql"
+	"fmt"
 	"path/filepath"
 	"strings"
 	"testing"
@@ -208,3 +209,237 @@ func TestJavaActionParametersTableExists(t *testing.T) {
 		t.Errorf("java_action_parameters holds %d rows, want 3", n)
 	}
 }
+
+// allKindsFixture inserts exactly one undocumented element of every kind the
+// generic sweep claims to cover, driven off DocumentableKinds() so a kind added
+// in Go without a test row fails here rather than shipping unswept.
+func allKindsFixture(t *testing.T) (*catalog.Catalog, map[string]string) {
+	t.Helper()
+
+	cat, err := catalog.NewFromFile(filepath.Join(t.TempDir(), "cat.db"))
+	if err != nil {
+		t.Fatalf("NewFromFile: %v", err)
+	}
+	t.Cleanup(func() { cat.Close() })
+	db := cat.CatalogDB()
+
+	// table -> doc column, mirroring documentableSources.
+	tables := map[string]struct {
+		kind   string
+		docCol string
+	}{
+		"entities":                {"Entity", "Description"},
+		"associations":            {"Association", "Description"},
+		"pages":                   {"Page", "Description"},
+		"snippets":                {"Snippet", "Description"},
+		"building_blocks":         {"BuildingBlock", "Description"},
+		"layouts":                 {"Layout", "Description"},
+		"enumerations":            {"Enumeration", "Description"},
+		"javascript_actions":      {"JavaScriptAction", "Description"},
+		"image_collections":       {"ImageCollection", "Description"},
+		"data_transformers":       {"DataTransformer", "Description"},
+		"workflows":               {"Workflow", "Description"},
+		"business_event_services": {"BusinessEventService", "Documentation"},
+		"rest_clients":            {"RestClient", "Documentation"},
+		"published_rest_services": {"PublishedRestService", "Documentation"},
+		"constants":               {"Constant", "Description"},
+		"json_structures":         {"JsonStructure", "Documentation"},
+		"import_mappings":         {"ImportMapping", "Documentation"},
+		"export_mappings":         {"ExportMapping", "Documentation"},
+	}
+
+	if _, err := db.Exec(
+		`INSERT INTO modules_data (Id, Name, QualifiedName, ModuleName, Description, ProjectId, SnapshotId)
+		 VALUES (?,?,?,?,?,?,?)`,
+		"mod-1", "Racing", "Racing", "Racing", "", "default", "s1"); err != nil {
+		t.Fatalf("insert module: %v", err)
+	}
+
+	// kind -> the element name the sweep should report.
+	//
+	// Id is omitted deliberately: json_structures, import_mappings and
+	// export_mappings declare `Id INTEGER PRIMARY KEY AUTOINCREMENT` while every
+	// other table uses `Id TEXT PRIMARY KEY`, so a synthetic string id is a
+	// datatype mismatch on exactly those three.
+	want := map[string]string{"Module": "Racing"}
+	for table, meta := range tables {
+		name := meta.kind + "X"
+		q := fmt.Sprintf(
+			`INSERT INTO %s_data (Name, QualifiedName, ModuleName, %s, ProjectId, SnapshotId)
+			 VALUES (?,?,?,?,?,?)`, table, meta.docCol)
+		if _, err := db.Exec(q, name, "Racing."+name, "Racing",
+			"", "default", "s1"); err != nil {
+			t.Fatalf("insert into %s: %v", table, err)
+		}
+		want[meta.kind] = name
+	}
+	return cat, want
+}
+
+// Every kind the Go side advertises must actually be swept. Without this, a new
+// documentableSources row that the .star table does not know about is silently
+// skipped by the rule's `entry == None` guard — covered in Go, invisible in
+// practice.
+func TestQUAL002_SweepsEveryAdvertisedDocumentType(t *testing.T) {
+	cat, want := allKindsFixture(t)
+
+	// The Go-side list and the fixture must agree, or the assertion below is
+	// only as complete as whichever is shorter.
+	for _, kind := range linter.DocumentableKinds() {
+		if _, ok := want[kind]; !ok {
+			t.Fatalf("DocumentableKinds() advertises %q but the fixture inserts no such row — "+
+				"add it here, or the sweep for that kind is untested", kind)
+		}
+	}
+
+	var msgs []string
+	for _, v := range runMissingDocRule(t, cat, map[string]any{"check_associations": true}) {
+		msgs = append(msgs, v.Message)
+	}
+	joined := strings.Join(msgs, "\n")
+
+	for kind, name := range want {
+		if !strings.Contains(joined, "'"+name+"'") {
+			t.Errorf("kind %s (element %q) was not reported by QUAL002; got:\n%s", kind, name, joined)
+		}
+	}
+}
+
+// A documented element of every kind must produce silence. A sweep that reports
+// regardless of content would pass the test above just as well.
+func TestQUAL002_DocumentedElementsAreSilent(t *testing.T) {
+	cat, _ := allKindsFixture(t)
+	db := cat.CatalogDB()
+	for _, tbl := range []string{"modules", "pages", "workflows", "constants"} {
+		col := "Description"
+		if _, err := db.Exec(fmt.Sprintf(
+			`UPDATE %s_data SET %s = 'Documented.'`, tbl, col)); err != nil {
+			t.Fatalf("update %s: %v", tbl, err)
+		}
+	}
+
+	var msgs []string
+	for _, v := range runMissingDocRule(t, cat, nil) {
+		msgs = append(msgs, v.Message)
+	}
+	joined := strings.Join(msgs, "\n")
+
+	for _, quiet := range []string{"'Racing'", "'PageX'", "'WorkflowX'", "'ConstantX'"} {
+		if strings.Contains(joined, quiet) {
+			t.Errorf("a documented element %s was still flagged:\n%s", quiet, joined)
+		}
+	}
+	// ...while the ones left blank must still be reported, proving the run
+	// itself was not simply empty.
+	if !strings.Contains(joined, "'LayoutX'") {
+		t.Errorf("the sweep went quiet altogether; expected LayoutX:\n%s", joined)
+	}
+}
+
+// Associations default OFF, like attributes: a real domain model has as many
+// associations as entities and none are documented, so defaulting them on would
+// double the rule's output with findings nobody asked for.
+func TestQUAL002_AssociationsDefaultOff(t *testing.T) {
+	cat, _ := allKindsFixture(t)
+
+	var off []string
+	for _, v := range runMissingDocRule(t, cat, nil) {
+		off = append(off, v.Message)
+	}
+	if strings.Contains(strings.Join(off, "\n"), "AssociationX") {
+		t.Error("associations were reported without being switched on")
+	}
+
+	var on []string
+	for _, v := range runMissingDocRule(t, cat, map[string]any{"check_associations": true}) {
+		on = append(on, v.Message)
+	}
+	if !strings.Contains(strings.Join(on, "\n"), "AssociationX") {
+		t.Error("check_associations: true did not switch associations on")
+	}
+}
+
+// The generic sweep needs its own Marketplace test: TestJavaActions_Exclude…
+// covers only the Java action query, so dropping the filter from
+// DocumentableElements left every other kind unguarded with a green suite.
+func TestQUAL002_SweepExcludesMarketplaceModules(t *testing.T) {
+	cat, _ := allKindsFixture(t)
+	db := cat.CatalogDB()
+
+	if _, err := db.Exec(
+		`INSERT INTO modules_data (Id, Name, QualifiedName, ModuleName, Source, Description, ProjectId, SnapshotId)
+		 VALUES (?,?,?,?,?,?,?,?)`,
+		"mod-mp", "CommunityCommons", "CommunityCommons", "CommunityCommons",
+		"Marketplace", "", "default", "s1"); err != nil {
+		t.Fatalf("insert module: %v", err)
+	}
+	// One element per shape: a page (joins modules by name) and the Marketplace
+	// module row itself (filters on its own Source column — a different code
+	// path, and the one an all-tables loop is most likely to forget).
+	if _, err := db.Exec(
+		`INSERT INTO pages_data (Id, Name, QualifiedName, ModuleName, Description, ProjectId, SnapshotId)
+		 VALUES (?,?,?,?,?,?,?)`,
+		"pg-mp", "CommonsPage", "CommunityCommons.CommonsPage", "CommunityCommons",
+		"", "default", "s1"); err != nil {
+		t.Fatalf("insert page: %v", err)
+	}
+
+	var msgs []string
+	for _, v := range runMissingDocRule(t, cat, map[string]any{"check_associations": true}) {
+		msgs = append(msgs, v.Message)
+	}
+	joined := strings.Join(msgs, "\n")
+
+	for _, leaked := range []string{"CommonsPage", "CommunityCommons"} {
+		if strings.Contains(joined, leaked) {
+			t.Errorf("Marketplace element %q was reported:\n%s", leaked, joined)
+		}
+	}
+	// The user's own elements must still come through, or this passes trivially.
+	if !strings.Contains(joined, "PageX") {
+		t.Errorf("the sweep excluded everything, not just Marketplace:\n%s", joined)
+	}
+}
+
+// System is the trap that Source-based filtering does not catch: the built-in
+// module's Source is empty, exactly like a user module's, so a WHERE on Source
+// alone lets all ~40 platform entities through. QUAL002 shipped that way before
+// this sweep existed — FileDocument and HttpRequest were reported as
+// undocumented on every project.
+func TestQUAL002_ExcludesTheSystemModule(t *testing.T) {
+	cat, _ := allKindsFixture(t)
+	db := cat.CatalogDB()
+
+	// Note the empty Source: System is indistinguishable from a user module on
+	// that column alone. Only the sentinel Id separates them.
+	if _, err := db.Exec(
+		`INSERT INTO modules_data (Id, Name, QualifiedName, ModuleName, Source, Description, ProjectId, SnapshotId)
+		 VALUES (?,?,?,?,?,?,?,?)`,
+		"00000000-0000-0000-0000-000000000001", "System", "System", "System",
+		"", "", "default", "s1"); err != nil {
+		t.Fatalf("insert System module: %v", err)
+	}
+	if _, err := db.Exec(
+		`INSERT INTO entities_data (Id, Name, QualifiedName, ModuleName, Description, ProjectId, SnapshotId)
+		 VALUES (?,?,?,?,?,?,?)`,
+		"sys-e1", "FileDocument", "System.FileDocument", "System",
+		"", "default", "s1"); err != nil {
+		t.Fatalf("insert System entity: %v", err)
+	}
+
+	var msgs []string
+	for _, v := range runMissingDocRule(t, cat, map[string]any{"check_associations": true}) {
+		msgs = append(msgs, v.Message)
+	}
+	joined := strings.Join(msgs, "\n")
+
+	if strings.Contains(joined, "FileDocument") {
+		t.Errorf("a System entity was reported:\n%s", joined)
+	}
+	if strings.Contains(joined, "'System'") {
+		t.Errorf("the System module itself was reported:\n%s", joined)
+	}
+	if !strings.Contains(joined, "'Racing'") {
+		t.Errorf("the user's own module stopped being reported:\n%s", joined)
+	}
+}

From 4ccf8e5c7d8e671495659867a023bc3072785595 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 9 Aug 2026 21:16:34 +0000
Subject: [PATCH 26/29] fix(lint): exclude the System module from every rule,
 not just QUAL002
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Follow-up to fbb1609b, which fixed the leak only in the iterators it
introduced. The same Source-only filter appeared in eleven more places,
so every rule that walks entities, pages, microflows, enumerations,
constants, snippets, widgets or database connections — plus all three
FindUnused kinds — reported platform elements the user cannot change.

On a blank Mendix 9.24 project the whole run goes from 60 findings to 8.
Removed: CONV001 asking to rename System booleans (User.Active ->
IsActive), SEC001 demanding access rules on 38 System entities, DESIGN001
splitting QueuedTask, SEC006 on System.User, MPR003 splitting the System
module itself. Verified by diffing full lint output before and after: 52
findings removed, every one of them System, and the ADDED set empty —
the predicate only ever narrows, so it cannot invent a finding.

TestIterators_ExcludePlatformModules drives all twelve iterators against
a catalog holding System, Marketplace and user rows, and asserts each
returns the user's element and neither platform one. The third assertion
matters most: an iterator returning nothing would satisfy the first two.

Also fixes drift in setupModuleFilterDB, whose hand-rolled modules table
lacked the Id column the sentinel check reads. Because these iterators
swallow query errors and return no rows, that surfaced as four "expected
ModA entities to be yielded" failures rather than "no such column".
---
 .claude/skills/fix-issue.md             |   3 +-
 docs-site/src/tools/starlark-rules.md   |   6 +-
 mdl/linter/context.go                   |  66 ++++++------
 mdl/linter/context_systemmodule_test.go | 136 ++++++++++++++++++++++++
 mdl/linter/context_test.go              |  10 +-
 5 files changed, 184 insertions(+), 37 deletions(-)
 create mode 100644 mdl/linter/context_systemmodule_test.go

diff --git a/.claude/skills/fix-issue.md b/.claude/skills/fix-issue.md
index fb1bd7f5a..b6f127f45 100644
--- a/.claude/skills/fix-issue.md
+++ b/.claude/skills/fix-issue.md
@@ -446,4 +446,5 @@ extracting `OffsetExpression`/`LimitExpression`.
 | `mxcli run --local` refuses to boot — *"port 6643 is already in use — a previous 'mxcli run --local' … is likely still serving on it"* — and names a process the user already killed. The guard is right to refuse; the diagnosis is a guess, and the recovery it suggests is a three-command `pgrep` hunt whose own pattern (`pgrep -f 'mxcli run'`) matches the shell it is typed into | Two different situations printed one message. mxcli **does** reap its children on Ctrl-C/SIGTERM (`procgroup_unix.go` puts mxbuild's JVM, the runtime and the bundler each in their own process group and signals the group), so a held port after a graceful stop is a *foreign* listener. But `kill -9`, a crash, or a reaped container runs no handler at all, and then it really is the previous run's orphan. The guard could not tell them apart because it never asked who held the port | `cmd/mxcli/docker/portowner_linux.go` (`listenerOnPort`, `parseListeningInodes`, `pidForSocketInode`), `portowner_other.go` (non-Linux stub), `portguard.go` (`portCulpritAdvice`), wired into `checkTargetPortsFree` (`runlocal.go`) and `checkLocalAppPortsFree` (`localapp.go`) | **Resolve the port owner from `/proc`, never by shelling out to `lsof`/`ss`** — both are routinely absent from slim containers, and needing a subprocess to explain why a boot failed is its own failure mode. `/proc/net/tcp{,6}` gives the socket inode; scanning `/proc/<pid>/fd` for `socket:[<inode>]` gives the pid. **Read `tcp6` as well as `tcp`**: a JVM binding "localhost" lands on `[::1]` or dual-stack `[::]` as often as `127.0.0.1`, and its local_address is a 128-bit hex blob, not the 32-bit one. **Filter on state `0A` (TCP_LISTEN)** — an ESTABLISHED socket on that port is a *client*, and naming it would tell the user to kill their own browser. **Report the two cases differently**: a leftover of a previous run gets `kill <pid>`, a foreign listener gets "pick another port" and no kill suggestion, because offering to kill a stranger's process is worse advice than the vague message it replaced. Keep the guard **detection-only** — reaping someone else's process stays the user's call. **Three test traps hit in a row here.** (1) The live-IPv6 test only ever *skipped* (no IPv6 in the container), so the tcp6 parser was effectively untested — assert against captured kernel output instead. (2) A parser test calling `parseListeningInodes` directly does not prove `listeningInodes` *opens* both files: deleting `/proc/net/tcp6` from the list left every test green. (3) Making the list a `var` so a test can point it at fixtures then means the test no longer covers the **shipped** default either — assert the default's contents before overriding it. Only the third version of that control failed. The best test in the file is the cheapest: bind a port in the test process and demand `listenerOnPort` return `os.Getpid()` — it cannot pass by accident. Tests `cmd/mxcli/docker/portowner_linux_test.go`. mxcli-formula1 suggested issue 8 |
 | `create external entities from` a service where an entity set is wholly unfilterable/unsortable generates an app the contract contradicts: **28 × CE6630** on one service — "'message' is marked Sortable=False in the OData service, but True in the app". The publisher is right, the `$metadata` is right, only the generated consumer is wrong | `FilterRestrictions`/`SortRestrictions` have **two shapes**, and only one was read. `applyCapabilityAnnotations` pulled `NonFilterableProperties` out of the record and ignored the record's own `Bool` property value, so `Filterable: !nonFilterable[p.Name]` evaluated `true` for every property of a set that had declared nothing filterable. This is the §42 Top/Skip bug one layer along — same vocabulary, same two-shapes cause, different term | `mdl/types/edmx.go` (`EdmEntitySet.Filterable`/`Sortable`, the `Filterable`/`Sortable` cases in `applyCapabilityAnnotations`, and the `AttrFilterable`/`AttrSortable` accessors), `mdl/executor/cmd_contract.go` (`createExternalEntities` calls the accessors) | **Mendix picks the annotation shape by arithmetic, not preference.** It lists `NonFilterableProperties` when SOME attributes are filterable and emits a bare `<PropertyValue Bool="false" Property="Filterable"/>` when NONE are, because then there is no list to write — so both shapes appear in **one document** on different entity sets, and an entity exposing only a KEY reliably produces the whole-set form. A fixture with just the list shape tests the half that already worked. **After fixing one term in a vocabulary, sweep the siblings**: §42 fixed Top/Skip by teaching the parser about standalone booleans and stopped there; Filterable/Sortable had the same defect and were found only because a consumer app failed to build. Grep the whole `applyCapabilityAnnotations` switch for terms whose Bool is never read. **Put both shapes behind one accessor** (`AttrFilterable`) rather than two fields the caller must remember to AND together — the caller then cannot consult one and forget the other, which is exactly how this arose, and the nil-safe receiver deletes the `entitySet != nil` dance at the call site. Absent still means `true`: OData's default is allowed, and defaulting to false would invert CE6630 for every unannotated service. Tests `mdl/types/edmx_test.go` (`TestParseEdmx_WholeSetFilterAndSortRestrictions`, plus a control proving the list shape still parses); both controls reproduce (ignore the record Bool → the whole-set test fails with the CE6630 message; drop the check inside `AttrFilterable` → same). mxcli-formula1 §48 |
 | A project is generated with no documentation anywhere — Java actions, Java action parameters, entities, microflows — and nothing says so. `mxcli check` and the build both pass, because documentation is never load-bearing | `QUAL002` existed but reached only entities and microflows. Java actions were not reachable from Starlark **at all** (no `java_actions()` builtin), and a Java action's parameters were not reachable from anywhere: the catalog stored a parameter *count* and discarded each parameter's `Description` | `mdl/catalog/tables.go` (`java_action_parameters_data` + view, `CatalogSchemaVersion` bump), `mdl/catalog/catalog.go` (`Tables()` registry), `mdl/catalog/builder_modules.go` (insert parameters), `mdl/linter/context.go` (`JavaActions()` with parameters attached), `mdl/linter/starlark.go` (`java_actions()` builtin, `javaActionToStarlark`), `.claude/lint-rules/missing_documentation.star` | **Adding a catalog table has three obligations beyond the `CREATE TABLE`.** (1) Bump `CatalogSchemaVersion` — otherwise every existing `.mxcli/catalog.db` keeps its old schema, the new query fails, the error is swallowed, and the rule silently reports *zero* of the new findings. Silent under-reporting from a stale cache is indistinguishable from a clean project. (2) Register the view in `Tables()` — `catalog_test.go` enforces this and will fail with "add CATALOG.X so SHOW CATALOG TABLES includes it"; let that test tell you rather than discovering it from a user. (3) Exclude Marketplace/System modules in the iterator's `WHERE COALESCE(m.Source,'') = ''`, as every sibling iterator does — reporting undocumented Community Commons actions buries the findings the user can act on. **Attach children to their parent in the projection, not as a second iterator**: a rule reporting an undocumented parameter must name the action it belongs to, and pairing them in `JavaActions()` saves every rule from re-joining. **Load the shipped `.star` from disk in tests** — an inlined copy proves the builtin works and says nothing about whether the rule uses it. **Make each target switchable via `get_option`** before widening a rule: attribute-level checks are hundreds of findings on a real domain model, so `check_attributes` defaults off while the rest default on. Watch the whitespace when writing revert controls for Starlark: a `perl` pattern with `\t` silently matches nothing in a space-indented `.star`, so the control passes and proves nothing — it was the second attempt that failed correctly. Tests `mdl/linter/starlark_javaactions_test.go`; five controls reproduce. mxcli-formula1 (missing documentation) |
-| QUAL002 reports ~40 platform elements (`FileDocument`, `HttpRequest`, `System`) as undocumented, burying the handful of real findings; or a whole document type (pages, workflows, constants, REST services, mappings) is never reported at all no matter how undocumented it is | Two separate causes. (1) **Coverage**: QUAL002 only ever looked at entities and microflows — every other document type was unreachable from Starlark. (2) **The System leak**: `modules.Source` is `"Marketplace …"` for downloaded modules and **empty for System — exactly as it is for the user's own modules**, so the near-universal `WHERE COALESCE(m.Source,'') = ''` filter excludes Marketplace and lets all of System through | `mdl/linter/context.go` (`documentableSources`, `DocumentableElements()`, `notPlatformModule()`, `systemModuleID`), `mdl/linter/starlark.go` (`documentable_elements()` builtin), `.claude/lint-rules/missing_documentation.star` (`_DOC_KINDS`) | **Source alone does not exclude System** — only the sentinel Id `00000000-0000-0000-0000-000000000001` does (`modelsdk/meta.SystemModuleID`). Use `notPlatformModule(alias)`; ~10 other `LintContext` iterators still carry the Source-only filter and leak System into their rules the same way. **One projection beats N builtins**: a rule that wants "every document" should get one `documentable_elements()` sweep driven by a table, so a new Mendix document type is two rows (one in `documentableSources`, one in `_DOC_KINDS`) rather than another builtin nobody remembers to call. **The documentation column is NOT uniform** — Mendix says `Documentation` for Java actions / REST / mappings / JSON structures and `Description` for everything else; assuming one spelling silently reports the other half as undocumented (a revert control confirmed 5 kinds go dark). **Test the catalog BUILDER, not just the query**: unit tests that INSERT rows directly cannot see that a builder never populates a column, which would flood the user with false positives — an end-to-end `exec` + `lint` on a real `.mpr` is what proved the constant/entity paths actually work. Three tables (`json_structures`, `import_mappings`, `export_mappings`) use `Id INTEGER PRIMARY KEY AUTOINCREMENT` while the rest use `Id TEXT PRIMARY KEY`, so a synthetic string id is a "datatype mismatch" on exactly those. Beware: MDL `COMMENT` and `DOCUMENTATION` are **different fields** on an entity — `CREATE ENTITY … COMMENT 'x'` does not set documentation, `ALTER ENTITY … SET DOCUMENTATION 'x'` does; a test using the wrong one looks exactly like a write-path bug. Tests `mdl/linter/starlark_javaactions_test.go`; controls reproduce for the sweep, each kind list, the doc-column split, Marketplace (both join shapes) and System |
+| QUAL002 reports ~40 platform elements (`FileDocument`, `HttpRequest`, `System`) as undocumented, burying the handful of real findings; or a whole document type (pages, workflows, constants, REST services, mappings) is never reported at all no matter how undocumented it is | Two separate causes. (1) **Coverage**: QUAL002 only ever looked at entities and microflows — every other document type was unreachable from Starlark. (2) **The System leak**: `modules.Source` is `"Marketplace …"` for downloaded modules and **empty for System — exactly as it is for the user's own modules**, so the near-universal `WHERE COALESCE(m.Source,'') = ''` filter excludes Marketplace and lets all of System through | `mdl/linter/context.go` (`documentableSources`, `DocumentableElements()`, `notPlatformModule()`, `systemModuleID`), `mdl/linter/starlark.go` (`documentable_elements()` builtin), `.claude/lint-rules/missing_documentation.star` (`_DOC_KINDS`) | **Source alone does not exclude System** — only the sentinel Id `00000000-0000-0000-0000-000000000001` does (`modelsdk/meta.SystemModuleID`). Use `notPlatformModule(alias)` — **every** `LintContext` iterator now routes through it (Entities, Microflows, Pages, Enumerations, Constants, Snippets, Widgets, DatabaseConnections, JavaActions, DocumentableElements and all three `FindUnused` kinds), and `TestIterators_ExcludePlatformModules` fails if a new one is added without it. The leak was not confined to QUAL002: on a blank 9.24 project it inflated the whole run from 8 findings to 60 — CONV001 renaming System booleans, SEC001 demanding access rules on 38 System entities, DESIGN001 splitting `QueuedTask`, MPR003 splitting the System module itself. Adding the predicate can only ever narrow a result set, so the change cannot invent a finding; prove that by diffing full lint output before/after and asserting the ADDED set is empty. **One projection beats N builtins**: a rule that wants "every document" should get one `documentable_elements()` sweep driven by a table, so a new Mendix document type is two rows (one in `documentableSources`, one in `_DOC_KINDS`) rather than another builtin nobody remembers to call. **The documentation column is NOT uniform** — Mendix says `Documentation` for Java actions / REST / mappings / JSON structures and `Description` for everything else; assuming one spelling silently reports the other half as undocumented (a revert control confirmed 5 kinds go dark). **Test the catalog BUILDER, not just the query**: unit tests that INSERT rows directly cannot see that a builder never populates a column, which would flood the user with false positives — an end-to-end `exec` + `lint` on a real `.mpr` is what proved the constant/entity paths actually work. Three tables (`json_structures`, `import_mappings`, `export_mappings`) use `Id INTEGER PRIMARY KEY AUTOINCREMENT` while the rest use `Id TEXT PRIMARY KEY`, so a synthetic string id is a "datatype mismatch" on exactly those. Beware: MDL `COMMENT` and `DOCUMENTATION` are **different fields** on an entity — `CREATE ENTITY … COMMENT 'x'` does not set documentation, `ALTER ENTITY … SET DOCUMENTATION 'x'` does; a test using the wrong one looks exactly like a write-path bug. Tests `mdl/linter/starlark_javaactions_test.go`; controls reproduce for the sweep, each kind list, the doc-column split, Marketplace (both join shapes) and System |
+| A `LintContext` iterator suddenly yields nothing and the test says "expected ModA entities to be yielded" — no SQL error, no log line, just an empty result | The iterator's query failed (typically `no such column`) and the iterator swallows it: `rows, err := ctx.db.Query(...); if err != nil { return }`. A hand-rolled test double whose schema has drifted from the real catalog view produces exactly this. Hit when platform filtering started reading `modules.Id` and `context_test.go`'s minimal `modules` table had only `(Name, Source)` | `mdl/linter/context.go` (the `if err != nil { return }` in every iterator), `mdl/linter/context_test.go` (`setupModuleFilterDB`) | Read the failure as **"the query broke"**, not "the filter is too strict" — the two are indistinguishable from the assertion text, and the second reading sends you rewriting correct logic. Confirm by running the query by hand against the fixture DB. Test doubles that hand-roll a `CREATE TABLE` instead of using `catalog.NewFromFile` drift silently from the real schema; prefer the real schema builder for anything that joins. The swallowed error is the root problem — an iterator that cannot run its query is not the same as one with no results, and today nothing distinguishes them |
diff --git a/docs-site/src/tools/starlark-rules.md b/docs-site/src/tools/starlark-rules.md
index fc5a5ac53..8dffbaabe 100644
--- a/docs-site/src/tools/starlark-rules.md
+++ b/docs-site/src/tools/starlark-rules.md
@@ -113,7 +113,11 @@ rules:
 
 Elements in System and Marketplace modules are never reported — that is code you
 did not write, and flagging Community Commons would bury the findings you can
-act on.
+act on. This applies to **every** rule, not just QUAL002: the `System` module is
+not distinguishable by its `Source` (which is empty, exactly like your own
+modules), so it used to slip past the Marketplace filter into every rule that
+walks entities, pages, microflows or widgets. On a blank Mendix 9.24 project that
+was the difference between 60 findings and 8.
 
 Adding a document type to the sweep is two rows: one in `documentableSources`
 (`mdl/linter/context.go`) naming the catalog table and its documentation column,
diff --git a/mdl/linter/context.go b/mdl/linter/context.go
index 36939d315..4bfbea4d7 100644
--- a/mdl/linter/context.go
+++ b/mdl/linter/context.go
@@ -165,7 +165,7 @@ type Entity struct {
 // Entities returns an iterator over all entities (excluding system modules).
 func (ctx *LintContext) Entities() iter.Seq[Entity] {
 	return func(yield func(Entity) bool) {
-		rows, err := ctx.db.Query(`
+		rows, err := ctx.db.Query(fmt.Sprintf(`
 			SELECT e.Id, e.Name, e.QualifiedName, e.ModuleName, e.Folder,
 			       CASE e.EntityType
 			           WHEN 'PERSISTENT' THEN 'Persistent'
@@ -178,9 +178,9 @@ func (ctx *LintContext) Entities() iter.Seq[Entity] {
 			       e.HasEventHandlers, e.IsExternal
 			FROM entities e
 			LEFT JOIN modules m ON e.ModuleName = m.Name
-			WHERE COALESCE(m.Source, '') = ''
+			WHERE %s
 			ORDER BY e.ModuleName, e.Name
-		`)
+		`, notPlatformModule("m")))
 		if err != nil {
 			return
 		}
@@ -482,15 +482,15 @@ type Microflow struct {
 // Microflows returns an iterator over all microflows (excluding system modules).
 func (ctx *LintContext) Microflows() iter.Seq[Microflow] {
 	return func(yield func(Microflow) bool) {
-		rows, err := ctx.db.Query(`
+		rows, err := ctx.db.Query(fmt.Sprintf(`
 			SELECT mf.Id, mf.Name, mf.QualifiedName, mf.ModuleName, mf.Folder,
 			       mf.MicroflowType, mf.Description, mf.ReturnType,
 			       mf.ParameterCount, mf.ActivityCount, mf.Complexity
 			FROM microflows mf
 			LEFT JOIN modules m ON mf.ModuleName = m.Name
-			WHERE COALESCE(m.Source, '') = ''
+			WHERE %s
 			ORDER BY mf.ModuleName, mf.Name
-		`)
+		`, notPlatformModule("m")))
 		if err != nil {
 			return
 		}
@@ -535,14 +535,14 @@ type Page struct {
 // Pages returns an iterator over all pages (excluding system modules).
 func (ctx *LintContext) Pages() iter.Seq[Page] {
 	return func(yield func(Page) bool) {
-		rows, err := ctx.db.Query(`
+		rows, err := ctx.db.Query(fmt.Sprintf(`
 			SELECT p.Id, p.Name, p.QualifiedName, p.ModuleName, p.Folder,
 			       p.Title, p.URL, p.Description, p.WidgetCount
 			FROM pages p
 			LEFT JOIN modules m ON p.ModuleName = m.Name
-			WHERE COALESCE(m.Source, '') = ''
+			WHERE %s
 			ORDER BY p.ModuleName, p.Name
-		`)
+		`, notPlatformModule("m")))
 		if err != nil {
 			return
 		}
@@ -588,14 +588,14 @@ type Enumeration struct {
 // Enumerations returns an iterator over all enumerations (excluding system modules).
 func (ctx *LintContext) Enumerations() iter.Seq[Enumeration] {
 	return func(yield func(Enumeration) bool) {
-		rows, err := ctx.db.Query(`
+		rows, err := ctx.db.Query(fmt.Sprintf(`
 			SELECT en.Id, en.Name, en.QualifiedName, en.ModuleName, en.Folder,
 			       en.Description, en.ValueCount
 			FROM enumerations en
 			LEFT JOIN modules m ON en.ModuleName = m.Name
-			WHERE COALESCE(m.Source, '') = ''
+			WHERE %s
 			ORDER BY en.ModuleName, en.Name
-		`)
+		`, notPlatformModule("m")))
 		if err != nil {
 			return
 		}
@@ -638,14 +638,14 @@ type LintConstant struct {
 // Constants returns an iterator over all constants (excluding system modules).
 func (ctx *LintContext) Constants() iter.Seq[LintConstant] {
 	return func(yield func(LintConstant) bool) {
-		rows, err := ctx.db.Query(`
+		rows, err := ctx.db.Query(fmt.Sprintf(`
 			SELECT c.Id, c.Name, c.QualifiedName, c.ModuleName, c.Folder,
 			       c.Description, c.DefaultValue, c.ExposedToClient
 			FROM constants c
 			LEFT JOIN modules m ON c.ModuleName = m.Name
-			WHERE COALESCE(m.Source, '') = ''
+			WHERE %s
 			ORDER BY c.ModuleName, c.Name
-		`)
+		`, notPlatformModule("m")))
 		if err != nil {
 			return
 		}
@@ -694,15 +694,15 @@ type Widget struct {
 // Widgets returns an iterator over all widgets (excluding system modules).
 func (ctx *LintContext) Widgets() iter.Seq[Widget] {
 	return func(yield func(Widget) bool) {
-		rows, err := ctx.db.Query(`
+		rows, err := ctx.db.Query(fmt.Sprintf(`
 			SELECT w.Id, w.Name, w.WidgetType, w.ContainerId, w.ContainerQualifiedName,
 			       w.ContainerType, w.ModuleName, w.EntityRef, w.AttributeRef,
 			       w.MicroflowRef, w.NanoflowRef
 			FROM widgets w
 			LEFT JOIN modules m ON w.ModuleName = m.Name
-			WHERE COALESCE(m.Source, '') = ''
+			WHERE %s
 			ORDER BY w.ModuleName, w.ContainerQualifiedName, w.Name
-		`)
+		`, notPlatformModule("m")))
 		if err != nil {
 			return
 		}
@@ -748,13 +748,13 @@ type Snippet struct {
 // Snippets returns an iterator over all snippets (excluding system modules).
 func (ctx *LintContext) Snippets() iter.Seq[Snippet] {
 	return func(yield func(Snippet) bool) {
-		rows, err := ctx.db.Query(`
+		rows, err := ctx.db.Query(fmt.Sprintf(`
 			SELECT s.Id, s.Name, s.QualifiedName, s.ModuleName, s.Folder, s.WidgetCount
 			FROM snippets s
 			LEFT JOIN modules m ON s.ModuleName = m.Name
-			WHERE COALESCE(m.Source, '') = ''
+			WHERE %s
 			ORDER BY s.ModuleName, s.Name
-		`)
+		`, notPlatformModule("m")))
 		if err != nil {
 			return
 		}
@@ -950,14 +950,14 @@ type DatabaseConnection struct {
 // DatabaseConnections returns an iterator over all database connections (excluding system modules).
 func (ctx *LintContext) DatabaseConnections() iter.Seq[DatabaseConnection] {
 	return func(yield func(DatabaseConnection) bool) {
-		rows, err := ctx.db.Query(`
+		rows, err := ctx.db.Query(fmt.Sprintf(`
 			SELECT dc.Id, dc.Name, dc.QualifiedName, dc.ModuleName, dc.Folder,
 			       dc.DatabaseType, dc.QueryCount
 			FROM database_connections dc
 			LEFT JOIN modules m ON dc.ModuleName = m.Name
-			WHERE COALESCE(m.Source, '') = ''
+			WHERE %s
 			ORDER BY dc.ModuleName, dc.Name
-		`)
+		`, notPlatformModule("m")))
 		if err != nil {
 			return
 		}
@@ -1111,35 +1111,35 @@ func (ctx *LintContext) FindUnused(kind string) []string {
 	var query string
 	switch kind {
 	case "entity":
-		query = `
+		query = fmt.Sprintf(`
 			SELECT e.QualifiedName
 			FROM entities e
 			LEFT JOIN modules m ON e.ModuleName = m.Name
-			WHERE COALESCE(m.Source, '') = ''
+			WHERE %s
 			AND e.QualifiedName NOT IN (
 				SELECT DISTINCT TargetName FROM refs WHERE TargetType = 'ENTITY'
 			)
-		`
+		`, notPlatformModule("m"))
 	case "microflow":
-		query = `
+		query = fmt.Sprintf(`
 			SELECT mf.QualifiedName
 			FROM microflows mf
 			LEFT JOIN modules m ON mf.ModuleName = m.Name
-			WHERE COALESCE(m.Source, '') = ''
+			WHERE %s
 			AND mf.QualifiedName NOT IN (
 				SELECT DISTINCT TargetName FROM refs WHERE TargetType IN ('MICROFLOW', 'NANOFLOW')
 			)
-		`
+		`, notPlatformModule("m"))
 	case "page":
-		query = `
+		query = fmt.Sprintf(`
 			SELECT p.QualifiedName
 			FROM pages p
 			LEFT JOIN modules m ON p.ModuleName = m.Name
-			WHERE COALESCE(m.Source, '') = ''
+			WHERE %s
 			AND p.QualifiedName NOT IN (
 				SELECT DISTINCT TargetName FROM refs WHERE TargetType = 'PAGE'
 			)
-		`
+		`, notPlatformModule("m"))
 	default:
 		return unused
 	}
diff --git a/mdl/linter/context_systemmodule_test.go b/mdl/linter/context_systemmodule_test.go
new file mode 100644
index 000000000..d6d13275a
--- /dev/null
+++ b/mdl/linter/context_systemmodule_test.go
@@ -0,0 +1,136 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package linter_test
+
+import (
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/mendixlabs/mxcli/mdl/catalog"
+	"github.com/mendixlabs/mxcli/mdl/linter"
+)
+
+// systemModuleID is the sentinel Mendix gives the built-in System module.
+// Restated here rather than exported from the linter: a test that reads the
+// constant under test cannot detect that constant being wrong.
+const systemModuleID = "00000000-0000-0000-0000-000000000001"
+
+// systemLeakFixture builds a catalog holding one user module and the System
+// module, each with one element in every table the LintContext iterates.
+//
+// The System rows carry an EMPTY Source, which is the whole point: that column
+// cannot distinguish System from a user module, so a filter written only against
+// it lets all of System through.
+func systemLeakFixture(t *testing.T) *catalog.Catalog {
+	t.Helper()
+
+	cat, err := catalog.NewFromFile(filepath.Join(t.TempDir(), "cat.db"))
+	if err != nil {
+		t.Fatalf("NewFromFile: %v", err)
+	}
+	t.Cleanup(func() { cat.Close() })
+	db := cat.CatalogDB()
+
+	exec := func(q string, args ...any) {
+		t.Helper()
+		if _, err := db.Exec(q, args...); err != nil {
+			t.Fatalf("exec: %v\n%s", err, q)
+		}
+	}
+
+	exec(`INSERT INTO modules_data (Id, Name, QualifiedName, ModuleName, Source, ProjectId, SnapshotId)
+	      VALUES (?,?,?,?,?,?,?)`, "mod-user", "Racing", "Racing", "Racing", "", "default", "s1")
+	exec(`INSERT INTO modules_data (Id, Name, QualifiedName, ModuleName, Source, ProjectId, SnapshotId)
+	      VALUES (?,?,?,?,?,?,?)`, systemModuleID, "System", "System", "System", "", "default", "s1")
+	exec(`INSERT INTO modules_data (Id, Name, QualifiedName, ModuleName, Source, ProjectId, SnapshotId)
+	      VALUES (?,?,?,?,?,?,?)`, "mod-mp", "CommunityCommons", "CommunityCommons",
+		"CommunityCommons", "Marketplace v1.0", "default", "s1")
+
+	// One row per module in each iterated table. Names are suffixed with the
+	// module so a leak is identifiable from the value alone.
+	for _, mod := range []string{"Racing", "System", "CommunityCommons"} {
+		exec(`INSERT INTO entities_data (Id, Name, QualifiedName, ModuleName, EntityType, ProjectId, SnapshotId)
+		      VALUES (?,?,?,?,?,?,?)`, "e-"+mod, "Entity"+mod, mod+".Entity"+mod, mod, "PERSISTENT", "default", "s1")
+		exec(`INSERT INTO microflows_data (Id, Name, QualifiedName, ModuleName, MicroflowType, ProjectId, SnapshotId)
+		      VALUES (?,?,?,?,?,?,?)`, "mf-"+mod, "MF"+mod, mod+".MF"+mod, mod, "MICROFLOW", "default", "s1")
+		exec(`INSERT INTO pages_data (Id, Name, QualifiedName, ModuleName, ProjectId, SnapshotId)
+		      VALUES (?,?,?,?,?,?)`, "pg-"+mod, "Page"+mod, mod+".Page"+mod, mod, "default", "s1")
+		exec(`INSERT INTO enumerations_data (Id, Name, QualifiedName, ModuleName, ProjectId, SnapshotId)
+		      VALUES (?,?,?,?,?,?)`, "en-"+mod, "Enum"+mod, mod+".Enum"+mod, mod, "default", "s1")
+		exec(`INSERT INTO constants_data (Id, Name, QualifiedName, ModuleName, ProjectId, SnapshotId)
+		      VALUES (?,?,?,?,?,?)`, "c-"+mod, "Const"+mod, mod+".Const"+mod, mod, "default", "s1")
+		exec(`INSERT INTO snippets_data (Id, Name, QualifiedName, ModuleName, ProjectId, SnapshotId)
+		      VALUES (?,?,?,?,?,?)`, "sn-"+mod, "Snip"+mod, mod+".Snip"+mod, mod, "default", "s1")
+		exec(`INSERT INTO java_actions_data (Id, Name, QualifiedName, ModuleName, ProjectId, SnapshotId)
+		      VALUES (?,?,?,?,?,?)`, "ja-"+mod, "JA"+mod, mod+".JA"+mod, mod, "default", "s1")
+		exec(`INSERT INTO widgets_data (Id, Name, WidgetType, ModuleName, ProjectId, SnapshotId)
+		      VALUES (?,?,?,?,?,?)`, "w-"+mod, "Widget"+mod, "TextBox", mod, "default", "s1")
+	}
+
+	return cat
+}
+
+// Every LintContext iterator must exclude both platform sources. System is the
+// one that Source-based filtering misses, and it is by far the larger leak: a
+// blank project ships ~40 System entities, so a rule over entities reported 40
+// findings the user could do nothing about.
+func TestIterators_ExcludePlatformModules(t *testing.T) {
+	cat := systemLeakFixture(t)
+	ctx := linter.NewLintContext(cat, &minimalReader{})
+
+	// name -> the qualified names that iterator yielded.
+	got := map[string][]string{}
+	collect := func(name string, qn ...string) { got[name] = append(got[name], qn...) }
+
+	for e := range ctx.Entities() {
+		collect("Entities", e.QualifiedName)
+	}
+	for mf := range ctx.Microflows() {
+		collect("Microflows", mf.QualifiedName)
+	}
+	for p := range ctx.Pages() {
+		collect("Pages", p.QualifiedName)
+	}
+	for en := range ctx.Enumerations() {
+		collect("Enumerations", en.QualifiedName)
+	}
+	for c := range ctx.Constants() {
+		collect("Constants", c.QualifiedName)
+	}
+	for s := range ctx.Snippets() {
+		collect("Snippets", s.QualifiedName)
+	}
+	for ja := range ctx.JavaActions() {
+		collect("JavaActions", ja.QualifiedName)
+	}
+	for w := range ctx.Widgets() {
+		collect("Widgets", w.ModuleName+".w")
+	}
+	for d := range ctx.DocumentableElements() {
+		collect("DocumentableElements", d.QualifiedName)
+	}
+	for _, kind := range []string{"entity", "microflow", "page"} {
+		collect("FindUnused("+kind+")", ctx.FindUnused(kind)...)
+	}
+
+	if len(got) == 0 {
+		t.Fatal("no iterators were exercised")
+	}
+
+	for name, names := range got {
+		joined := strings.Join(names, " ")
+		if strings.Contains(joined, "System") {
+			t.Errorf("%s leaked a System element: %v", name, names)
+		}
+		if strings.Contains(joined, "CommunityCommons") {
+			t.Errorf("%s leaked a Marketplace element: %v", name, names)
+		}
+		// Guard against the trivial pass: an iterator that returns nothing
+		// satisfies both assertions above.
+		if !strings.Contains(joined, "Racing") {
+			t.Errorf("%s returned no user elements at all (%v) — the assertions above "+
+				"would pass even with the filter broken", name, names)
+		}
+	}
+}
diff --git a/mdl/linter/context_test.go b/mdl/linter/context_test.go
index 9ad51f18c..72c973132 100644
--- a/mdl/linter/context_test.go
+++ b/mdl/linter/context_test.go
@@ -20,7 +20,13 @@ func setupModuleFilterDB(t *testing.T) catalog.CatalogDB {
 		t.Fatalf("open db: %v", err)
 	}
 
-	_, err = db.Exec(`CREATE TABLE modules (Name TEXT PRIMARY KEY, Source TEXT)`)
+	// Id is part of the real `modules` view and is load-bearing: platform
+	// filtering keys off the System module's sentinel Id, because Source cannot
+	// tell System apart from a user module (both empty). Omitting it here made
+	// every iterator query error out — and these iterators swallow query errors
+	// and yield nothing, so the drift surfaced as "no entities were returned"
+	// rather than "no such column".
+	_, err = db.Exec(`CREATE TABLE modules (Id TEXT, Name TEXT PRIMARY KEY, Source TEXT)`)
 	if err != nil {
 		t.Fatalf("create modules table: %v", err)
 	}
@@ -44,7 +50,7 @@ func setupModuleFilterDB(t *testing.T) catalog.CatalogDB {
 
 	modules := []string{"ModA", "ModB", "ModC"}
 	for _, mod := range modules {
-		if _, err := db.Exec(`INSERT INTO modules VALUES (?, '')`, mod); err != nil {
+		if _, err := db.Exec(`INSERT INTO modules VALUES (?, ?, '')`, mod+"-id", mod); err != nil {
 			t.Fatalf("insert module %s: %v", mod, err)
 		}
 		if _, err := db.Exec(`INSERT INTO entities VALUES (?, ?, ?, ?, '', 'PERSISTENT', '', '', 0, 0, 0, 0, 0)`,

From 7a37cde8bc6551c12c366133f5f703ebbb107629 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 9 Aug 2026 21:21:30 +0000
Subject: [PATCH 27/29] fix(lint): add modules.Id to the rules-package test
 doubles

Same schema drift as setupModuleFilterDB, in two more hand-rolled
fixtures. I ran ./mdl/linter/ before committing 4ccf8e5c but not
./mdl/linter/rules/, so four tests in that package were left red.

The failure text is misleading in the same way: because the iterators
swallow query errors, "no such column: m.Id" reaches the test as
"expected 1 violation, got 0".
---
 mdl/linter/rules/empty_test.go   | 8 ++++++--
 mdl/linter/rules/helpers_test.go | 8 ++++++--
 2 files changed, 12 insertions(+), 4 deletions(-)

diff --git a/mdl/linter/rules/empty_test.go b/mdl/linter/rules/empty_test.go
index 6df2611ef..7a2660e06 100644
--- a/mdl/linter/rules/empty_test.go
+++ b/mdl/linter/rules/empty_test.go
@@ -21,7 +21,11 @@ func setupMicroflowsDB(t *testing.T, rows [][]any) catalog.CatalogDB {
 		t.Fatalf("failed to open in-memory db: %v", err)
 	}
 
-	_, err = db.Exec(`CREATE TABLE modules (Name TEXT PRIMARY KEY, Source TEXT)`)
+	// Id mirrors the real `modules` view. Platform filtering keys off the System
+	// module's sentinel Id — Source is empty for System exactly as it is for a
+	// user module — and these iterators swallow query errors, so a missing
+	// column shows up as "no rows" rather than "no such column".
+	_, err = db.Exec(`CREATE TABLE modules (Id TEXT, Name TEXT PRIMARY KEY, Source TEXT)`)
 	if err != nil {
 		t.Fatalf("failed to create modules table: %v", err)
 	}
@@ -43,7 +47,7 @@ func setupMicroflowsDB(t *testing.T, rows [][]any) catalog.CatalogDB {
 		}
 		// Ensure module exists
 		moduleName := row[3].(string)
-		if _, err := db.Exec(`INSERT OR IGNORE INTO modules (Name, Source) VALUES (?, '')`, moduleName); err != nil {
+		if _, err := db.Exec(`INSERT OR IGNORE INTO modules (Id, Name, Source) VALUES (?, ?, '')`, moduleName+"-id", moduleName); err != nil {
 			t.Fatalf("failed to insert module: %v", err)
 		}
 	}
diff --git a/mdl/linter/rules/helpers_test.go b/mdl/linter/rules/helpers_test.go
index dae123b98..7b233342e 100644
--- a/mdl/linter/rules/helpers_test.go
+++ b/mdl/linter/rules/helpers_test.go
@@ -30,7 +30,11 @@ func setupEntitiesDB(t *testing.T, entities [][]any) catalog.CatalogDB {
 		t.Fatalf("failed to open in-memory db: %v", err)
 	}
 
-	_, err = db.Exec(`CREATE TABLE modules (Name TEXT PRIMARY KEY, Source TEXT)`)
+	// Id mirrors the real `modules` view. Platform filtering keys off the System
+	// module's sentinel Id — Source is empty for System exactly as it is for a
+	// user module — and these iterators swallow query errors, so a missing
+	// column shows up as "no rows" rather than "no such column".
+	_, err = db.Exec(`CREATE TABLE modules (Id TEXT, Name TEXT PRIMARY KEY, Source TEXT)`)
 	if err != nil {
 		t.Fatalf("failed to create modules table: %v", err)
 	}
@@ -52,7 +56,7 @@ func setupEntitiesDB(t *testing.T, entities [][]any) catalog.CatalogDB {
 			t.Fatalf("failed to insert entity: %v", err)
 		}
 		moduleName := row[3].(string)
-		if _, err := db.Exec(`INSERT OR IGNORE INTO modules (Name, Source) VALUES (?, '')`, moduleName); err != nil {
+		if _, err := db.Exec(`INSERT OR IGNORE INTO modules (Id, Name, Source) VALUES (?, ?, '')`, moduleName+"-id", moduleName); err != nil {
 			t.Fatalf("failed to insert module: %v", err)
 		}
 	}

From c9245e87ba47561a7bdc1b40797ea92667bc485b Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 9 Aug 2026 21:36:10 +0000
Subject: [PATCH 28/29] fix(lint): report failed catalog queries instead of
 swallowing them
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

An iterator whose query failed returned no rows and said nothing:
`if err != nil { return }` inside an iter.Seq[T], which has no error
channel. For a linter that is the worst shape of failure — the entire
output is "here is what I found", so a dead query is indistinguishable
from a clean project, and CI goes green on a run that checked nothing.
This is how three fixtures' missing modules.Id column surfaced as
"expected 1 violation, got 0" rather than "no such column".

LintContext now collects QueryErrors. Iterators still degrade to "no
rows" so one broken query cannot take down the run, but the failure is
recorded, and `mxcli lint` prints each one and exits 1.

All 34 sites: Query+return, Query+continue, bare and inline rows.Scan,
the `return unused` in FindUnused that a bare-return sweep misses, and
the reader-backed ListScheduledEvents. Errors dedupe on iterator+cause,
since several rules iterate the same accessor.

Verified end to end by dropping and recreating a view in a real cached
catalog: the run names the iterator and the cause, exits 1, and the
remedy it prints — delete .mxcli/catalog.db — was run and does clear it.
The healthy path is unchanged: no output, exit 0, same findings.
---
 .claude/skills/fix-issue.md           |   1 +
 cmd/mxcli/cmd_lint.go                 |  18 +++
 mdl/linter/context.go                 |  94 ++++++++++++++-
 mdl/linter/context_queryerror_test.go | 166 ++++++++++++++++++++++++++
 mdl/linter/linter.go                  |  13 ++
 mdl/linter/linter_test.go             |  10 +-
 6 files changed, 296 insertions(+), 6 deletions(-)
 create mode 100644 mdl/linter/context_queryerror_test.go

diff --git a/.claude/skills/fix-issue.md b/.claude/skills/fix-issue.md
index b6f127f45..1910e45ae 100644
--- a/.claude/skills/fix-issue.md
+++ b/.claude/skills/fix-issue.md
@@ -448,3 +448,4 @@ extracting `OffsetExpression`/`LimitExpression`.
 | A project is generated with no documentation anywhere — Java actions, Java action parameters, entities, microflows — and nothing says so. `mxcli check` and the build both pass, because documentation is never load-bearing | `QUAL002` existed but reached only entities and microflows. Java actions were not reachable from Starlark **at all** (no `java_actions()` builtin), and a Java action's parameters were not reachable from anywhere: the catalog stored a parameter *count* and discarded each parameter's `Description` | `mdl/catalog/tables.go` (`java_action_parameters_data` + view, `CatalogSchemaVersion` bump), `mdl/catalog/catalog.go` (`Tables()` registry), `mdl/catalog/builder_modules.go` (insert parameters), `mdl/linter/context.go` (`JavaActions()` with parameters attached), `mdl/linter/starlark.go` (`java_actions()` builtin, `javaActionToStarlark`), `.claude/lint-rules/missing_documentation.star` | **Adding a catalog table has three obligations beyond the `CREATE TABLE`.** (1) Bump `CatalogSchemaVersion` — otherwise every existing `.mxcli/catalog.db` keeps its old schema, the new query fails, the error is swallowed, and the rule silently reports *zero* of the new findings. Silent under-reporting from a stale cache is indistinguishable from a clean project. (2) Register the view in `Tables()` — `catalog_test.go` enforces this and will fail with "add CATALOG.X so SHOW CATALOG TABLES includes it"; let that test tell you rather than discovering it from a user. (3) Exclude Marketplace/System modules in the iterator's `WHERE COALESCE(m.Source,'') = ''`, as every sibling iterator does — reporting undocumented Community Commons actions buries the findings the user can act on. **Attach children to their parent in the projection, not as a second iterator**: a rule reporting an undocumented parameter must name the action it belongs to, and pairing them in `JavaActions()` saves every rule from re-joining. **Load the shipped `.star` from disk in tests** — an inlined copy proves the builtin works and says nothing about whether the rule uses it. **Make each target switchable via `get_option`** before widening a rule: attribute-level checks are hundreds of findings on a real domain model, so `check_attributes` defaults off while the rest default on. Watch the whitespace when writing revert controls for Starlark: a `perl` pattern with `\t` silently matches nothing in a space-indented `.star`, so the control passes and proves nothing — it was the second attempt that failed correctly. Tests `mdl/linter/starlark_javaactions_test.go`; five controls reproduce. mxcli-formula1 (missing documentation) |
 | QUAL002 reports ~40 platform elements (`FileDocument`, `HttpRequest`, `System`) as undocumented, burying the handful of real findings; or a whole document type (pages, workflows, constants, REST services, mappings) is never reported at all no matter how undocumented it is | Two separate causes. (1) **Coverage**: QUAL002 only ever looked at entities and microflows — every other document type was unreachable from Starlark. (2) **The System leak**: `modules.Source` is `"Marketplace …"` for downloaded modules and **empty for System — exactly as it is for the user's own modules**, so the near-universal `WHERE COALESCE(m.Source,'') = ''` filter excludes Marketplace and lets all of System through | `mdl/linter/context.go` (`documentableSources`, `DocumentableElements()`, `notPlatformModule()`, `systemModuleID`), `mdl/linter/starlark.go` (`documentable_elements()` builtin), `.claude/lint-rules/missing_documentation.star` (`_DOC_KINDS`) | **Source alone does not exclude System** — only the sentinel Id `00000000-0000-0000-0000-000000000001` does (`modelsdk/meta.SystemModuleID`). Use `notPlatformModule(alias)` — **every** `LintContext` iterator now routes through it (Entities, Microflows, Pages, Enumerations, Constants, Snippets, Widgets, DatabaseConnections, JavaActions, DocumentableElements and all three `FindUnused` kinds), and `TestIterators_ExcludePlatformModules` fails if a new one is added without it. The leak was not confined to QUAL002: on a blank 9.24 project it inflated the whole run from 8 findings to 60 — CONV001 renaming System booleans, SEC001 demanding access rules on 38 System entities, DESIGN001 splitting `QueuedTask`, MPR003 splitting the System module itself. Adding the predicate can only ever narrow a result set, so the change cannot invent a finding; prove that by diffing full lint output before/after and asserting the ADDED set is empty. **One projection beats N builtins**: a rule that wants "every document" should get one `documentable_elements()` sweep driven by a table, so a new Mendix document type is two rows (one in `documentableSources`, one in `_DOC_KINDS`) rather than another builtin nobody remembers to call. **The documentation column is NOT uniform** — Mendix says `Documentation` for Java actions / REST / mappings / JSON structures and `Description` for everything else; assuming one spelling silently reports the other half as undocumented (a revert control confirmed 5 kinds go dark). **Test the catalog BUILDER, not just the query**: unit tests that INSERT rows directly cannot see that a builder never populates a column, which would flood the user with false positives — an end-to-end `exec` + `lint` on a real `.mpr` is what proved the constant/entity paths actually work. Three tables (`json_structures`, `import_mappings`, `export_mappings`) use `Id INTEGER PRIMARY KEY AUTOINCREMENT` while the rest use `Id TEXT PRIMARY KEY`, so a synthetic string id is a "datatype mismatch" on exactly those. Beware: MDL `COMMENT` and `DOCUMENTATION` are **different fields** on an entity — `CREATE ENTITY … COMMENT 'x'` does not set documentation, `ALTER ENTITY … SET DOCUMENTATION 'x'` does; a test using the wrong one looks exactly like a write-path bug. Tests `mdl/linter/starlark_javaactions_test.go`; controls reproduce for the sweep, each kind list, the doc-column split, Marketplace (both join shapes) and System |
 | A `LintContext` iterator suddenly yields nothing and the test says "expected ModA entities to be yielded" — no SQL error, no log line, just an empty result | The iterator's query failed (typically `no such column`) and the iterator swallows it: `rows, err := ctx.db.Query(...); if err != nil { return }`. A hand-rolled test double whose schema has drifted from the real catalog view produces exactly this. Hit when platform filtering started reading `modules.Id` and `context_test.go`'s minimal `modules` table had only `(Name, Source)` | `mdl/linter/context.go` (the `if err != nil { return }` in every iterator), `mdl/linter/context_test.go` (`setupModuleFilterDB`) | Read the failure as **"the query broke"**, not "the filter is too strict" — the two are indistinguishable from the assertion text, and the second reading sends you rewriting correct logic. Confirm by running the query by hand against the fixture DB. Test doubles that hand-roll a `CREATE TABLE` instead of using `catalog.NewFromFile` drift silently from the real schema; prefer the real schema builder for anything that joins. The swallowed error is the root problem — an iterator that cannot run its query is not the same as one with no results, and today nothing distinguishes them |
+| A lint run reports fewer findings than expected, or a rule that clearly should fire reports nothing — and there is no error, no warning, no log line | An iterator's catalog query failed and the failure was swallowed: `if err != nil { return }` inside an `iter.Seq[T]`, which has no error channel. The run looks successful because a linter's whole output is "here is what I found", and "found nothing" is what both a clean project and a dead query produce | `mdl/linter/context.go` (`QueryError`, `recordQueryError`, `QueryErrors`), `mdl/linter/linter.go` (`Linter.QueryErrors`), `cmd/mxcli/cmd_lint.go` (report + exit 1) | Iterators still degrade to "no rows" — one broken query must not take down the run — but they now **record** the failure, and `mxcli lint` prints it and exits 1, because silently passing CI on a run that could not read the model is the worst available outcome. All 34 sites are covered: `Query` + `return`, `Query` + `continue`, bare and inline `rows.Scan` forms, `return unused` (the non-bare return that a naive regex sweep misses — `TestQueryError_AllIteratorsReport` is what caught it), and the reader-backed `ListScheduledEvents`. **Dedupe on iterator+cause**: several rules iterate the same accessor, so one broken view is otherwise reported once per rule. Keying on the iterator alone instead hides a second, distinct failure in the same accessor. When adding an error message with a remedy, **run the remedy** — the first draft here suggested `mxcli lint --refresh`, a flag that does not exist; the shipped message names `.mxcli/catalog.db` and deleting it was verified to clear the error. Tests `mdl/linter/context_queryerror_test.go`; controls: no-op recorder (every iterator goes silent) and a single reverted iterator (only that one) |
diff --git a/cmd/mxcli/cmd_lint.go b/cmd/mxcli/cmd_lint.go
index 9f6c79320..56c137e99 100644
--- a/cmd/mxcli/cmd_lint.go
+++ b/cmd/mxcli/cmd_lint.go
@@ -250,6 +250,24 @@ Examples:
 			os.Exit(1)
 		}
 
+		// A failed catalog query means some iterator yielded nothing and the
+		// findings above are incomplete. Reported on stderr so it survives
+		// `| jq` on the results, and treated as a failure: silently passing CI
+		// on a lint run that could not read the model is the worst outcome.
+		queryErrs := lint.QueryErrors()
+		for _, qe := range queryErrs {
+			fmt.Fprintf(os.Stderr,
+				"Error: lint could not read the catalog for %s: %v\n", qe.Iterator, qe.Err)
+		}
+		if len(queryErrs) > 0 {
+			fmt.Fprintf(os.Stderr,
+				"Results are INCOMPLETE (%d failed %s). The cached catalog is usually the cause; "+
+					"delete %s and re-run.\n",
+				len(queryErrs), map[bool]string{true: "query", false: "queries"}[len(queryErrs) == 1],
+				filepath.Join(projectDir, ".mxcli", "catalog.db"))
+			os.Exit(1)
+		}
+
 		// Exit with error if there are errors
 		summary := linter.Summarize(violations)
 		if summary.Errors > 0 {
diff --git a/mdl/linter/context.go b/mdl/linter/context.go
index 4bfbea4d7..e38e774fb 100644
--- a/mdl/linter/context.go
+++ b/mdl/linter/context.go
@@ -6,6 +6,7 @@ import (
 	"database/sql"
 	"fmt"
 	"iter"
+	"sync"
 
 	"github.com/mendixlabs/mxcli/mdl/catalog"
 	"github.com/mendixlabs/mxcli/mdl/types"
@@ -42,6 +43,12 @@ type LintContext struct {
 	fullMFCache  map[model.ID]*microflows.Microflow
 	fullMFErr    error
 	fullMFLoaded bool
+
+	// queryErrors collects catalog queries that failed, so an iterator that
+	// could not run is distinguishable from one that legitimately found
+	// nothing. See QueryError.
+	queryErrors []QueryError
+	queryErrMu  sync.Mutex
 }
 
 // FullMicroflow returns the fully-parsed microflow (with its object collection)
@@ -182,6 +189,7 @@ func (ctx *LintContext) Entities() iter.Seq[Entity] {
 			ORDER BY e.ModuleName, e.Name
 		`, notPlatformModule("m")))
 		if err != nil {
+			ctx.recordQueryError("Entities", err)
 			return
 		}
 		defer rows.Close()
@@ -195,6 +203,7 @@ func (ctx *LintContext) Entities() iter.Seq[Entity] {
 				&e.AccessRuleCount, &e.ValidationRuleCount,
 				&hasEventHandlers, &isExternal)
 			if err != nil {
+				ctx.recordQueryError("Entities (row scan)", err)
 				continue
 			}
 			e.Folder = folder.String
@@ -242,6 +251,7 @@ func (ctx *LintContext) AttributesFor(entityQualifiedName string) iter.Seq[Attri
 			ORDER BY Name
 		`, entityQualifiedName)
 		if err != nil {
+			ctx.recordQueryError("AttributesFor", err)
 			return
 		}
 		defer rows.Close()
@@ -255,6 +265,7 @@ func (ctx *LintContext) AttributesFor(entityQualifiedName string) iter.Seq[Attri
 				&a.ModuleName, &dataType, &length, &isUnique, &isRequired, &defaultVal,
 				&isCalculated, &desc)
 			if err != nil {
+				ctx.recordQueryError("AttributesFor (row scan)", err)
 				continue
 			}
 			a.DataType = dataType.String
@@ -293,6 +304,7 @@ func (ctx *LintContext) PermissionsFor(entityQualifiedName string) iter.Seq[Perm
 			ORDER BY ModuleRoleName, AccessType
 		`, entityQualifiedName)
 		if err != nil {
+			ctx.recordQueryError("PermissionsFor", err)
 			return
 		}
 		defer rows.Close()
@@ -302,6 +314,7 @@ func (ctx *LintContext) PermissionsFor(entityQualifiedName string) iter.Seq[Perm
 			var memberName, xpathConstraint, moduleName sql.NullString
 			err := rows.Scan(&p.ModuleRoleName, &p.EntityName, &memberName, &p.AccessType, &xpathConstraint, &moduleName)
 			if err != nil {
+				ctx.recordQueryError("PermissionsFor (row scan)", err)
 				continue
 			}
 			p.MemberName = memberName.String
@@ -342,6 +355,7 @@ func (ctx *LintContext) Permissions() iter.Seq[AllPermission] {
 			ORDER BY ElementType, ElementName, ModuleRoleName, AccessType
 		`)
 		if err != nil {
+			ctx.recordQueryError("Permissions", err)
 			return
 		}
 		defer rows.Close()
@@ -408,12 +422,14 @@ func (ctx *LintContext) RoleMappings() iter.Seq[RoleMappingInfo] {
 			ORDER BY UserRoleName, ModuleRoleName
 		`)
 		if err != nil {
+			ctx.recordQueryError("RoleMappings", err)
 			return
 		}
 		defer rows.Close()
 		for rows.Next() {
 			var rm RoleMappingInfo
 			if err := rows.Scan(&rm.UserRoleName, &rm.ModuleRoleName, &rm.ModuleName); err != nil {
+				ctx.recordQueryError("RoleMappings (row scan)", err)
 				continue
 			}
 			if ctx.IsExcluded(rm.ModuleName) {
@@ -446,12 +462,14 @@ func (ctx *LintContext) ModuleRoles() iter.Seq[ModuleRoleInfo] {
 			ORDER BY ModuleName, ModuleRoleName
 		`)
 		if err != nil {
+			ctx.recordQueryError("ModuleRoles", err)
 			return
 		}
 		defer rows.Close()
 		for rows.Next() {
 			var mr ModuleRoleInfo
 			if err := rows.Scan(&mr.Name, &mr.ModuleName); err != nil {
+				ctx.recordQueryError("ModuleRoles (row scan)", err)
 				continue
 			}
 			if ctx.IsExcluded(mr.ModuleName) {
@@ -492,6 +510,7 @@ func (ctx *LintContext) Microflows() iter.Seq[Microflow] {
 			ORDER BY mf.ModuleName, mf.Name
 		`, notPlatformModule("m")))
 		if err != nil {
+			ctx.recordQueryError("Microflows", err)
 			return
 		}
 		defer rows.Close()
@@ -502,6 +521,7 @@ func (ctx *LintContext) Microflows() iter.Seq[Microflow] {
 			err := rows.Scan(&mf.ID, &mf.Name, &mf.QualifiedName, &mf.ModuleName, &folder,
 				&mf.MicroflowType, &desc, &retType, &mf.ParameterCount, &mf.ActivityCount, &mf.Complexity)
 			if err != nil {
+				ctx.recordQueryError("Microflows (row scan)", err)
 				continue
 			}
 			mf.Folder = folder.String
@@ -544,6 +564,7 @@ func (ctx *LintContext) Pages() iter.Seq[Page] {
 			ORDER BY p.ModuleName, p.Name
 		`, notPlatformModule("m")))
 		if err != nil {
+			ctx.recordQueryError("Pages", err)
 			return
 		}
 		defer rows.Close()
@@ -555,6 +576,7 @@ func (ctx *LintContext) Pages() iter.Seq[Page] {
 			err := rows.Scan(&pg.ID, &pg.Name, &pg.QualifiedName, &pg.ModuleName, &folder,
 				&title, &url, &desc, &widgetCount)
 			if err != nil {
+				ctx.recordQueryError("Pages (row scan)", err)
 				continue
 			}
 			pg.Folder = folder.String
@@ -597,6 +619,7 @@ func (ctx *LintContext) Enumerations() iter.Seq[Enumeration] {
 			ORDER BY en.ModuleName, en.Name
 		`, notPlatformModule("m")))
 		if err != nil {
+			ctx.recordQueryError("Enumerations", err)
 			return
 		}
 		defer rows.Close()
@@ -607,6 +630,7 @@ func (ctx *LintContext) Enumerations() iter.Seq[Enumeration] {
 			err := rows.Scan(&en.ID, &en.Name, &en.QualifiedName, &en.ModuleName, &folder,
 				&desc, &en.ValueCount)
 			if err != nil {
+				ctx.recordQueryError("Enumerations (row scan)", err)
 				continue
 			}
 			en.Folder = folder.String
@@ -647,6 +671,7 @@ func (ctx *LintContext) Constants() iter.Seq[LintConstant] {
 			ORDER BY c.ModuleName, c.Name
 		`, notPlatformModule("m")))
 		if err != nil {
+			ctx.recordQueryError("Constants", err)
 			return
 		}
 		defer rows.Close()
@@ -658,6 +683,7 @@ func (ctx *LintContext) Constants() iter.Seq[LintConstant] {
 			err := rows.Scan(&c.ID, &c.Name, &c.QualifiedName, &c.ModuleName,
 				&folder, &desc, &defaultVal, &exposedToClient)
 			if err != nil {
+				ctx.recordQueryError("Constants (row scan)", err)
 				continue
 			}
 			c.Folder = folder.String
@@ -704,6 +730,7 @@ func (ctx *LintContext) Widgets() iter.Seq[Widget] {
 			ORDER BY w.ModuleName, w.ContainerQualifiedName, w.Name
 		`, notPlatformModule("m")))
 		if err != nil {
+			ctx.recordQueryError("Widgets", err)
 			return
 		}
 		defer rows.Close()
@@ -714,6 +741,7 @@ func (ctx *LintContext) Widgets() iter.Seq[Widget] {
 			err := rows.Scan(&w.ID, &w.Name, &w.WidgetType, &containerID, &containerQName,
 				&containerType, &w.ModuleName, &entityRef, &attrRef, &mfRef, &nfRef)
 			if err != nil {
+				ctx.recordQueryError("Widgets (row scan)", err)
 				continue
 			}
 			w.ContainerID = containerID.String
@@ -756,6 +784,7 @@ func (ctx *LintContext) Snippets() iter.Seq[Snippet] {
 			ORDER BY s.ModuleName, s.Name
 		`, notPlatformModule("m")))
 		if err != nil {
+			ctx.recordQueryError("Snippets", err)
 			return
 		}
 		defer rows.Close()
@@ -766,6 +795,7 @@ func (ctx *LintContext) Snippets() iter.Seq[Snippet] {
 			var widgetCount sql.NullInt64
 			err := rows.Scan(&s.ID, &s.Name, &s.QualifiedName, &s.ModuleName, &folder, &widgetCount)
 			if err != nil {
+				ctx.recordQueryError("Snippets (row scan)", err)
 				continue
 			}
 			s.Folder = folder.String
@@ -846,6 +876,7 @@ func (ctx *LintContext) ScheduledEvents() iter.Seq[ScheduledEvent] {
 
 		events, err := ctx.reader.ListScheduledEvents()
 		if err != nil {
+			ctx.recordQueryError("ScheduledEvents", err)
 			return
 		}
 
@@ -902,6 +933,7 @@ func (ctx *LintContext) XPathExpressions() iter.Seq[XPathExpressionEntry] {
 			ORDER BY ModuleName, DocumentQualifiedName
 		`)
 		if err != nil {
+			ctx.recordQueryError("XPathExpressions", err)
 			return
 		}
 		defer rows.Close()
@@ -917,6 +949,7 @@ func (ctx *LintContext) XPathExpressions() iter.Seq[XPathExpressionEntry] {
 				&isParam, &e.UsageType, &moduleName,
 			)
 			if err != nil {
+				ctx.recordQueryError("XPathExpressions (row scan)", err)
 				continue
 			}
 			e.ComponentName = componentName.String
@@ -959,6 +992,7 @@ func (ctx *LintContext) DatabaseConnections() iter.Seq[DatabaseConnection] {
 			ORDER BY dc.ModuleName, dc.Name
 		`, notPlatformModule("m")))
 		if err != nil {
+			ctx.recordQueryError("DatabaseConnections", err)
 			return
 		}
 		defer rows.Close()
@@ -969,6 +1003,7 @@ func (ctx *LintContext) DatabaseConnections() iter.Seq[DatabaseConnection] {
 			err := rows.Scan(&dc.ID, &dc.Name, &dc.QualifiedName, &dc.ModuleName, &folder,
 				&dc.DatabaseType, &dc.QueryCount)
 			if err != nil {
+				ctx.recordQueryError("DatabaseConnections (row scan)", err)
 				continue
 			}
 			dc.Folder = folder.String
@@ -1008,6 +1043,7 @@ func (ctx *LintContext) ActivitiesFor(microflowQualifiedName string) iter.Seq[Ac
 			ORDER BY Sequence
 		`, microflowQualifiedName)
 		if err != nil {
+			ctx.recordQueryError("ActivitiesFor", err)
 			return
 		}
 		defer rows.Close()
@@ -1018,6 +1054,7 @@ func (ctx *LintContext) ActivitiesFor(microflowQualifiedName string) iter.Seq[Ac
 			err := rows.Scan(&a.ID, &name, &caption, &a.ActivityType, &actionType,
 				&a.MicroflowID, &a.MicroflowQualifiedName, &a.ModuleName, &entityRef)
 			if err != nil {
+				ctx.recordQueryError("ActivitiesFor (row scan)", err)
 				continue
 			}
 			a.Name = name.String
@@ -1095,6 +1132,7 @@ func (ctx *LintContext) FindReferences(targetName string) []Reference {
 		err := rows.Scan(&r.SourceType, &srcID, &r.SourceName, &r.TargetType,
 			&tgtID, &r.TargetName, &r.RefKind, &r.ModuleName)
 		if err != nil {
+			ctx.recordQueryError("FindReferences (row scan)", err)
 			continue
 		}
 		r.SourceID = srcID.String
@@ -1146,6 +1184,7 @@ func (ctx *LintContext) FindUnused(kind string) []string {
 
 	rows, err := ctx.db.Query(query)
 	if err != nil {
+		ctx.recordQueryError("FindUnused("+kind+")", err)
 		return unused
 	}
 	defer rows.Close()
@@ -1243,6 +1282,7 @@ func (ctx *LintContext) JavaActions() iter.Seq[JavaAction] {
 			ORDER BY ja.ModuleName, ja.Name
 		`, notPlatformModule("m")))
 		if err != nil {
+			ctx.recordQueryError("JavaActions", err)
 			return
 		}
 		defer rows.Close()
@@ -1290,6 +1330,7 @@ func (ctx *LintContext) javaActionParameters() map[string][]JavaActionParameter
 		var desc, ptype sql.NullString
 		var required int
 		if err := rows.Scan(&actionID, &p.Name, &desc, &ptype, &required); err != nil {
+			ctx.recordQueryError("javaActionParameters (row scan)", err)
 			continue
 		}
 		p.Description = desc.String
@@ -1300,6 +1341,51 @@ func (ctx *LintContext) javaActionParameters() map[string][]JavaActionParameter
 	return out
 }
 
+// QueryError records a catalog query that failed inside an iterator.
+//
+// The iterators return iter.Seq[T] with no error channel, so a failed query
+// used to be indistinguishable from an empty result: `if err != nil { return }`
+// yielded nothing and said nothing. That is the worst shape for a linter, whose
+// entire output is "here is what I found" — a broken query reads as a clean
+// project. Errors are collected here and surfaced by the runner instead.
+type QueryError struct {
+	Iterator string // the iterator that failed, e.g. "Entities"
+	Err      error
+}
+
+func (e QueryError) Error() string { return e.Iterator + ": " + e.Err.Error() }
+
+// recordQueryError notes a failed query. Iterators still degrade to "no rows"
+// so one broken query cannot take down the whole run, but the failure is no
+// longer silent.
+//
+// The mutex is not currently required (Linter.Run is sequential) but the Linter
+// carries a maxWorkers knob, so this stays safe if rules ever run in parallel.
+func (ctx *LintContext) recordQueryError(iterator string, err error) {
+	if err == nil {
+		return
+	}
+	ctx.queryErrMu.Lock()
+	defer ctx.queryErrMu.Unlock()
+	// Deduplicate: several rules iterate the same accessor, so one broken view
+	// would otherwise be reported once per rule. The fact matters, not how many
+	// rules tripped over it.
+	for _, existing := range ctx.queryErrors {
+		if existing.Iterator == iterator && existing.Err.Error() == err.Error() {
+			return
+		}
+	}
+	ctx.queryErrors = append(ctx.queryErrors, QueryError{Iterator: iterator, Err: err})
+}
+
+// QueryErrors returns every catalog query that failed during this lint run.
+// A non-empty result means the findings are incomplete.
+func (ctx *LintContext) QueryErrors() []QueryError {
+	ctx.queryErrMu.Lock()
+	defer ctx.queryErrMu.Unlock()
+	return append([]QueryError(nil), ctx.queryErrors...)
+}
+
 // systemModuleID is the fixed sentinel Mendix gives the built-in System module
 // (mirrors modelsdk/meta.SystemModuleID, not imported to keep the linter free of
 // an engine dependency).
@@ -1419,12 +1505,18 @@ func (ctx *LintContext) DocumentableElements() iter.Seq[Documentable] {
 
 			rows, err := ctx.db.Query(query)
 			if err != nil {
-				continue // table absent in this catalog: skip this kind only
+				// Skip this kind only — one absent table must not take down the
+				// whole sweep — but say so, because "this document type has no
+				// undocumented elements" and "this document type could not be
+				// read" look identical in the output otherwise.
+				ctx.recordQueryError("DocumentableElements("+src.Table+")", err)
+				continue
 			}
 			for rows.Next() {
 				d := Documentable{Kind: src.Kind}
 				var qn, mod sql.NullString
 				if err := rows.Scan(&d.Name, &qn, &mod, &d.Description); err != nil {
+					ctx.recordQueryError("DocumentableElements("+src.Table+") row scan", err)
 					continue
 				}
 				d.QualifiedName = qn.String
diff --git a/mdl/linter/context_queryerror_test.go b/mdl/linter/context_queryerror_test.go
new file mode 100644
index 000000000..6dc4279ff
--- /dev/null
+++ b/mdl/linter/context_queryerror_test.go
@@ -0,0 +1,166 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package linter
+
+import (
+	"database/sql"
+	"strings"
+	"testing"
+
+	"github.com/mendixlabs/mxcli/mdl/catalog"
+)
+
+// brokenCatalogDB is a catalog whose `modules` table is missing the Id column
+// that platform filtering reads, so every joined query fails with
+// "no such column". This is not hypothetical: three test fixtures in this repo
+// drifted exactly this way, and the failure reached the tests as
+// "expected 1 violation, got 0".
+func brokenCatalogDB(t *testing.T) catalog.CatalogDB {
+	t.Helper()
+	db, err := sql.Open("sqlite", ":memory:")
+	if err != nil {
+		t.Fatalf("open: %v", err)
+	}
+	t.Cleanup(func() { db.Close() })
+
+	for _, q := range []string{
+		`CREATE TABLE modules (Name TEXT PRIMARY KEY, Source TEXT)`, // no Id
+		`CREATE TABLE entities (Id TEXT, Name TEXT, QualifiedName TEXT, ModuleName TEXT,
+			Folder TEXT, EntityType TEXT, Description TEXT, Generalization TEXT,
+			AttributeCount INTEGER, AccessRuleCount INTEGER, ValidationRuleCount INTEGER,
+			HasEventHandlers INTEGER, IsExternal INTEGER)`,
+		`INSERT INTO modules VALUES ('ModA', '')`,
+		`INSERT INTO entities VALUES ('e1','E','ModA.E','ModA','','PERSISTENT','','',0,0,0,0,0)`,
+	} {
+		if _, err := db.Exec(q); err != nil {
+			t.Fatalf("exec %s: %v", q, err)
+		}
+	}
+	return catalog.WrapSqlDB(db)
+}
+
+// The defect: an iterator that cannot run its query returned no rows and said
+// nothing, so "the catalog is broken" and "your project is clean" produced
+// identical output. For a linter that is the worst possible failure — the tool
+// reports success precisely when it has checked nothing.
+func TestQueryError_BrokenQueryIsReportedNotSilent(t *testing.T) {
+	ctx := NewLintContextFromDB(brokenCatalogDB(t))
+
+	var n int
+	for range ctx.Entities() {
+		n++
+	}
+	if n != 0 {
+		t.Fatalf("fixture is not broken: Entities() yielded %d rows", n)
+	}
+
+	errs := ctx.QueryErrors()
+	if len(errs) == 0 {
+		t.Fatal("Entities() failed and reported nothing — a broken query is " +
+			"indistinguishable from a clean project")
+	}
+	if errs[0].Iterator != "Entities" {
+		t.Errorf("Iterator = %q, want %q — the report must name what failed", errs[0].Iterator, "Entities")
+	}
+	if !strings.Contains(errs[0].Err.Error(), "no such column") {
+		t.Errorf("underlying cause was lost: %v", errs[0].Err)
+	}
+	// The message a user sees has to carry both halves.
+	if msg := errs[0].Error(); !strings.Contains(msg, "Entities") || !strings.Contains(msg, "no such column") {
+		t.Errorf("QueryError.Error() = %q, want it to name the iterator and the cause", msg)
+	}
+}
+
+// A healthy catalog must not report anything, or the signal is worthless.
+func TestQueryError_HealthyCatalogReportsNothing(t *testing.T) {
+	ctx := NewLintContextFromDB(setupModuleFilterDB(t))
+
+	var n int
+	for range ctx.Entities() {
+		n++
+	}
+	if n == 0 {
+		t.Fatal("healthy fixture yielded no entities")
+	}
+	if errs := ctx.QueryErrors(); len(errs) != 0 {
+		t.Errorf("healthy catalog reported query errors: %v", errs)
+	}
+}
+
+// Every iterator must report, not just the one that happened to be fixed first.
+// A partial rollout leaves the same silent hole behind a different accessor.
+func TestQueryError_AllIteratorsReport(t *testing.T) {
+	ctx := NewLintContextFromDB(brokenCatalogDB(t))
+
+	// Drain the iterators that join modules. Each should fail and say so.
+	for range ctx.Entities() {
+	}
+	for range ctx.Microflows() {
+	}
+	for range ctx.Pages() {
+	}
+	for range ctx.Enumerations() {
+	}
+	for range ctx.Constants() {
+	}
+	for range ctx.Snippets() {
+	}
+	for range ctx.JavaActions() {
+	}
+	for range ctx.DocumentableElements() {
+	}
+	ctx.FindUnused("entity")
+
+	seen := map[string]bool{}
+	for _, e := range ctx.QueryErrors() {
+		// DocumentableElements labels per table; collapse to the iterator name.
+		name := e.Iterator
+		if i := strings.IndexByte(name, '('); i > 0 {
+			name = name[:i]
+		}
+		seen[name] = true
+	}
+
+	for _, want := range []string{
+		"Entities", "Microflows", "Pages", "Enumerations", "Constants",
+		"Snippets", "JavaActions", "DocumentableElements", "FindUnused",
+	} {
+		if !seen[want] {
+			t.Errorf("%s failed silently — no QueryError recorded (have: %v)", want, seen)
+		}
+	}
+}
+
+// Several rules iterate the same accessor. Without dedup, one broken view is
+// reported once per rule that touched it, so the user counts failures instead
+// of reading them.
+func TestQueryError_DeduplicatesRepeatedFailures(t *testing.T) {
+	ctx := NewLintContextFromDB(brokenCatalogDB(t))
+
+	for i := 0; i < 3; i++ {
+		for range ctx.Entities() {
+		}
+	}
+
+	errs := ctx.QueryErrors()
+	if len(errs) != 1 {
+		t.Errorf("draining Entities() 3 times recorded %d errors, want 1: %v", len(errs), errs)
+	}
+}
+
+// Dedup must key on the cause, not just the iterator, or a second distinct
+// failure in the same accessor is dropped.
+func TestQueryError_DistinctCausesBothRecorded(t *testing.T) {
+	ctx := NewLintContextFromDB(brokenCatalogDB(t))
+	ctx.recordQueryError("X", errStub("first"))
+	ctx.recordQueryError("X", errStub("second"))
+	ctx.recordQueryError("X", errStub("first"))
+
+	if got := len(ctx.QueryErrors()); got != 2 {
+		t.Errorf("recorded %d errors, want 2 (two distinct causes): %v", got, ctx.QueryErrors())
+	}
+}
+
+type errStub string
+
+func (e errStub) Error() string { return string(e) }
diff --git a/mdl/linter/linter.go b/mdl/linter/linter.go
index 6faffbedc..aba20fe3c 100644
--- a/mdl/linter/linter.go
+++ b/mdl/linter/linter.go
@@ -181,6 +181,19 @@ func (l *Linter) Run(ctx context.Context) ([]Violation, error) {
 	return allViolations, nil
 }
 
+// QueryErrors returns the catalog queries that failed during the run.
+//
+// A non-empty result means the findings are INCOMPLETE: some iterator could not
+// read the catalog and yielded nothing, which is indistinguishable from a clean
+// project in the violation list alone. Callers should report these rather than
+// present the run as successful.
+func (l *Linter) QueryErrors() []QueryError {
+	if l.ctx == nil {
+		return nil
+	}
+	return l.ctx.QueryErrors()
+}
+
 // Summary holds counts of violations by severity.
 type Summary struct {
 	Errors   int
diff --git a/mdl/linter/linter_test.go b/mdl/linter/linter_test.go
index f023e8a18..1182c3daa 100644
--- a/mdl/linter/linter_test.go
+++ b/mdl/linter/linter_test.go
@@ -12,11 +12,11 @@ type stubRule struct {
 	id string
 }
 
-func (r *stubRule) ID() string                      { return r.id }
-func (r *stubRule) Name() string                    { return r.id }
-func (r *stubRule) Description() string             { return "" }
-func (r *stubRule) DefaultSeverity() Severity       { return SeverityWarning }
-func (r *stubRule) Category() string                { return "test" }
+func (r *stubRule) ID() string                { return r.id }
+func (r *stubRule) Name() string              { return r.id }
+func (r *stubRule) Description() string       { return "" }
+func (r *stubRule) DefaultSeverity() Severity { return SeverityWarning }
+func (r *stubRule) Category() string          { return "test" }
 func (r *stubRule) Check(_ *LintContext) []Violation {
 	return []Violation{{RuleID: r.id, Severity: SeverityWarning, Message: "hit"}}
 }

From 7a1bc0f38a45d0e71de881e0c4d2962d59d6f958 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Sun, 9 Aug 2026 21:55:34 +0000
Subject: [PATCH 29/29] fix(odata): stop create-external-entities duplicating
 suffixed associations
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

mxcli-formula1 §50. Re-running `create external entities from` added two
associations every time, without bound: `season_2`, `season_3`, then
`season_4`, `season_5`, and so on. One project had reached `season_15`
before anyone noticed — `mx check` clean, every test passing, the only
symptom duplicate links in Studio Pro's domain model.

Association names are unique per module, so the second entity with a
`season` nav property is stored as `season_2`. The dedup looks for an
association matching the nav property it is about to import, and
`season_2` can never match `season` by name. The index that WOULD have
matched it is keyed on RemoteParentNavigationProperty — and the modelsdk
reader never read the OData association source back, so that index was
always empty on the default engine. The write path set the field and the
legacy reader read it; only the default read dropped it, so it survived
one save and vanished on the next load.

assocFromGen now reads Rest$ODataRemoteAssociationSource back
(nav properties, navigability, and the four capability flags). The dedup
index moves into indexExistingAssociations so it can be tested directly.

Not fixed by stripping a trailing _<n> from names: that would also match
a user's genuine `season_2`, and the model already records the true
origin. Existing damage is not cleaned up here — those associations are
referenced by external-entity access rules, so deleting one raises CE1613.
---
 .claude/skills/fix-issue.md                   |   1 +
 .../modelsdk/association_odata_source_test.go | 143 ++++++++++++++++++
 mdl/backend/modelsdk/domainmodel.go           |  18 +++
 mdl/executor/cmd_contract.go                  |  50 ++++--
 mdl/executor/cmd_contract_reimport_test.go    | 109 +++++++++++++
 5 files changed, 307 insertions(+), 14 deletions(-)
 create mode 100644 mdl/backend/modelsdk/association_odata_source_test.go
 create mode 100644 mdl/executor/cmd_contract_reimport_test.go

diff --git a/.claude/skills/fix-issue.md b/.claude/skills/fix-issue.md
index 1910e45ae..1068db708 100644
--- a/.claude/skills/fix-issue.md
+++ b/.claude/skills/fix-issue.md
@@ -449,3 +449,4 @@ extracting `OffsetExpression`/`LimitExpression`.
 | QUAL002 reports ~40 platform elements (`FileDocument`, `HttpRequest`, `System`) as undocumented, burying the handful of real findings; or a whole document type (pages, workflows, constants, REST services, mappings) is never reported at all no matter how undocumented it is | Two separate causes. (1) **Coverage**: QUAL002 only ever looked at entities and microflows — every other document type was unreachable from Starlark. (2) **The System leak**: `modules.Source` is `"Marketplace …"` for downloaded modules and **empty for System — exactly as it is for the user's own modules**, so the near-universal `WHERE COALESCE(m.Source,'') = ''` filter excludes Marketplace and lets all of System through | `mdl/linter/context.go` (`documentableSources`, `DocumentableElements()`, `notPlatformModule()`, `systemModuleID`), `mdl/linter/starlark.go` (`documentable_elements()` builtin), `.claude/lint-rules/missing_documentation.star` (`_DOC_KINDS`) | **Source alone does not exclude System** — only the sentinel Id `00000000-0000-0000-0000-000000000001` does (`modelsdk/meta.SystemModuleID`). Use `notPlatformModule(alias)` — **every** `LintContext` iterator now routes through it (Entities, Microflows, Pages, Enumerations, Constants, Snippets, Widgets, DatabaseConnections, JavaActions, DocumentableElements and all three `FindUnused` kinds), and `TestIterators_ExcludePlatformModules` fails if a new one is added without it. The leak was not confined to QUAL002: on a blank 9.24 project it inflated the whole run from 8 findings to 60 — CONV001 renaming System booleans, SEC001 demanding access rules on 38 System entities, DESIGN001 splitting `QueuedTask`, MPR003 splitting the System module itself. Adding the predicate can only ever narrow a result set, so the change cannot invent a finding; prove that by diffing full lint output before/after and asserting the ADDED set is empty. **One projection beats N builtins**: a rule that wants "every document" should get one `documentable_elements()` sweep driven by a table, so a new Mendix document type is two rows (one in `documentableSources`, one in `_DOC_KINDS`) rather than another builtin nobody remembers to call. **The documentation column is NOT uniform** — Mendix says `Documentation` for Java actions / REST / mappings / JSON structures and `Description` for everything else; assuming one spelling silently reports the other half as undocumented (a revert control confirmed 5 kinds go dark). **Test the catalog BUILDER, not just the query**: unit tests that INSERT rows directly cannot see that a builder never populates a column, which would flood the user with false positives — an end-to-end `exec` + `lint` on a real `.mpr` is what proved the constant/entity paths actually work. Three tables (`json_structures`, `import_mappings`, `export_mappings`) use `Id INTEGER PRIMARY KEY AUTOINCREMENT` while the rest use `Id TEXT PRIMARY KEY`, so a synthetic string id is a "datatype mismatch" on exactly those. Beware: MDL `COMMENT` and `DOCUMENTATION` are **different fields** on an entity — `CREATE ENTITY … COMMENT 'x'` does not set documentation, `ALTER ENTITY … SET DOCUMENTATION 'x'` does; a test using the wrong one looks exactly like a write-path bug. Tests `mdl/linter/starlark_javaactions_test.go`; controls reproduce for the sweep, each kind list, the doc-column split, Marketplace (both join shapes) and System |
 | A `LintContext` iterator suddenly yields nothing and the test says "expected ModA entities to be yielded" — no SQL error, no log line, just an empty result | The iterator's query failed (typically `no such column`) and the iterator swallows it: `rows, err := ctx.db.Query(...); if err != nil { return }`. A hand-rolled test double whose schema has drifted from the real catalog view produces exactly this. Hit when platform filtering started reading `modules.Id` and `context_test.go`'s minimal `modules` table had only `(Name, Source)` | `mdl/linter/context.go` (the `if err != nil { return }` in every iterator), `mdl/linter/context_test.go` (`setupModuleFilterDB`) | Read the failure as **"the query broke"**, not "the filter is too strict" — the two are indistinguishable from the assertion text, and the second reading sends you rewriting correct logic. Confirm by running the query by hand against the fixture DB. Test doubles that hand-roll a `CREATE TABLE` instead of using `catalog.NewFromFile` drift silently from the real schema; prefer the real schema builder for anything that joins. The swallowed error is the root problem — an iterator that cannot run its query is not the same as one with no results, and today nothing distinguishes them |
 | A lint run reports fewer findings than expected, or a rule that clearly should fire reports nothing — and there is no error, no warning, no log line | An iterator's catalog query failed and the failure was swallowed: `if err != nil { return }` inside an `iter.Seq[T]`, which has no error channel. The run looks successful because a linter's whole output is "here is what I found", and "found nothing" is what both a clean project and a dead query produce | `mdl/linter/context.go` (`QueryError`, `recordQueryError`, `QueryErrors`), `mdl/linter/linter.go` (`Linter.QueryErrors`), `cmd/mxcli/cmd_lint.go` (report + exit 1) | Iterators still degrade to "no rows" — one broken query must not take down the run — but they now **record** the failure, and `mxcli lint` prints it and exits 1, because silently passing CI on a run that could not read the model is the worst available outcome. All 34 sites are covered: `Query` + `return`, `Query` + `continue`, bare and inline `rows.Scan` forms, `return unused` (the non-bare return that a naive regex sweep misses — `TestQueryError_AllIteratorsReport` is what caught it), and the reader-backed `ListScheduledEvents`. **Dedupe on iterator+cause**: several rules iterate the same accessor, so one broken view is otherwise reported once per rule. Keying on the iterator alone instead hides a second, distinct failure in the same accessor. When adding an error message with a remedy, **run the remedy** — the first draft here suggested `mxcli lint --refresh`, a flag that does not exist; the shipped message names `.mxcli/catalog.db` and deleting it was verified to clear the error. Tests `mdl/linter/context_queryerror_test.go`; controls: no-op recorder (every iterator goes silent) and a single reverted iterator (only that one) |
+| Re-running `create external entities from` adds two more associations every time — `season_2`, `season_3`, then `season_4`, `season_5`, … unbounded. `mx check` is clean, every test passes, and the only symptom is duplicate links in Studio Pro's domain model | The re-import dedup matches an existing association by the OData **nav-property** name, but association names are unique per MODULE, so the second entity with a `season` nav property is stored as `season_2` — which can never match `season`. The nav-property index that would have matched it is keyed on `RemoteParentNavigationProperty`, and the **modelsdk reader never read the OData source back**, so that index was always empty under the default engine. The legacy reader did read it, which is why this only bit the default path | `mdl/backend/modelsdk/domainmodel.go` (`assocFromGen` now reads `*genRest.ODataRemoteAssociationSource`), `mdl/executor/cmd_contract.go` (`indexExistingAssociations`) | **A field that the write path sets and the read path drops survives exactly one save.** Grep both directions when a round-trip matters — `RemoteParentNavigationProperty` appeared in `domainmodel_write.go`, in gen, and in the legacy parser, and was missing only from the modelsdk read, which is invisible if you only grep for the identifier. **Do not "fix" this by stripping a trailing `_<n>` from names**: that heuristic also swallows a user's genuine `season_2`, and the model already records the true origin. Damage is cumulative and pre-existing: a project that ran the import N times carries 2N spurious associations, and they cannot simply be deleted — external-entity access rules reference them, so removing one leaves CE1613 "The selected association no longer exists". Tests `mdl/backend/modelsdk/association_odata_source_test.go` (round-trip, plus a control that a plain association is not stamped as external) and `mdl/executor/cmd_contract_reimport_test.go` (the index, incl. the assertion that the suffixed ones match via the nav index and NOT the name index — otherwise the guard passes for the wrong reason). mxcli-formula1 §50 |
diff --git a/mdl/backend/modelsdk/association_odata_source_test.go b/mdl/backend/modelsdk/association_odata_source_test.go
new file mode 100644
index 000000000..1d5726799
--- /dev/null
+++ b/mdl/backend/modelsdk/association_odata_source_test.go
@@ -0,0 +1,143 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package modelsdkbackend
+
+import (
+	"testing"
+
+	"github.com/mendixlabs/mxcli/sdk/domainmodel"
+)
+
+// RemoteParentNavigationProperty is the only durable link from an association
+// back to the OData navigation property it was generated from, and
+// CREATE EXTERNAL ENTITIES dedupes a re-import on it. The write path set it and
+// the read path dropped it, so the field survived one save and vanished on the
+// next load.
+//
+// The consequence was unbounded: association names must be unique per module, so
+// a second entity with a `season` nav property gets `season_2`. On a re-import
+// the dedup looked for an association *named* `season` on that parent, found
+// `season_2`, and created `season_4`. Two more every run, clean under
+// `mx check`, visible only as duplicate links in Studio Pro. One real project
+// reached `season_15` before anyone noticed (mxcli-formula1 §50).
+func TestAssociation_ODataSourceRoundTrips(t *testing.T) {
+	proj := copyFixture(t)
+	b := New()
+	if err := b.Connect(proj); err != nil {
+		t.Fatalf("connect: %v", err)
+	}
+	t.Cleanup(func() { _ = b.Disconnect() })
+
+	mod, err := b.GetModuleByName("MyFirstModule")
+	if err != nil || mod == nil {
+		t.Fatalf("GetModuleByName: %v", err)
+	}
+	dm, err := b.GetDomainModel(mod.ID)
+	if err != nil {
+		t.Fatalf("GetDomainModel: %v", err)
+	}
+
+	parent := &domainmodel.Entity{Name: "ZzStanding", Persistable: false}
+	child := &domainmodel.Entity{Name: "ZzSeason", Persistable: false}
+	if err := b.CreateEntity(dm.ID, parent); err != nil {
+		t.Fatalf("CreateEntity parent: %v", err)
+	}
+	if err := b.CreateEntity(dm.ID, child); err != nil {
+		t.Fatalf("CreateEntity child: %v", err)
+	}
+
+	// Named with a suffix on purpose: this is exactly the association the
+	// re-import failed to recognise, because its name no longer equals the nav
+	// property it came from.
+	want := &domainmodel.Association{
+		Name:                           "season_2",
+		ParentID:                       parent.ID,
+		ChildID:                        child.ID,
+		Type:                           "Reference",
+		Owner:                          "Default",
+		Source:                         "Rest$ODataRemoteAssociationSource",
+		Navigability2:                  "ParentToChild",
+		RemoteParentNavigationProperty: "season",
+		RemoteChildNavigationProperty:  "standings",
+		CreatableFromParent:            true,
+		UpdatableFromParent:            true,
+	}
+	if err := b.CreateAssociation(dm.ID, want); err != nil {
+		t.Fatalf("CreateAssociation: %v", err)
+	}
+
+	dm2, err := b.GetDomainModel(mod.ID)
+	if err != nil {
+		t.Fatalf("GetDomainModel(2): %v", err)
+	}
+	var got *domainmodel.Association
+	for _, a := range dm2.Associations {
+		if a.Name == "season_2" {
+			got = a
+			break
+		}
+	}
+	if got == nil {
+		t.Fatal("association season_2 not found after reload")
+	}
+
+	if got.RemoteParentNavigationProperty != "season" {
+		t.Errorf("RemoteParentNavigationProperty = %q, want %q — a re-import "+
+			"cannot recognise this association without it, and will duplicate it",
+			got.RemoteParentNavigationProperty, "season")
+	}
+	if got.Source != "Rest$ODataRemoteAssociationSource" {
+		t.Errorf("Source = %q, want Rest$ODataRemoteAssociationSource", got.Source)
+	}
+	if got.RemoteChildNavigationProperty != "standings" {
+		t.Errorf("RemoteChildNavigationProperty = %q, want %q",
+			got.RemoteChildNavigationProperty, "standings")
+	}
+	if got.Navigability2 != "ParentToChild" {
+		t.Errorf("Navigability2 = %q, want ParentToChild", got.Navigability2)
+	}
+	if !got.CreatableFromParent || !got.UpdatableFromParent {
+		t.Errorf("capability flags lost: CreatableFromParent=%v UpdatableFromParent=%v",
+			got.CreatableFromParent, got.UpdatableFromParent)
+	}
+}
+
+// A plain association must not acquire an OData source it never had — the read
+// has to branch on the stored type, not stamp every association.
+func TestAssociation_PlainAssociationHasNoODataSource(t *testing.T) {
+	proj := copyFixture(t)
+	b := New()
+	if err := b.Connect(proj); err != nil {
+		t.Fatalf("connect: %v", err)
+	}
+	t.Cleanup(func() { _ = b.Disconnect() })
+
+	mod, _ := b.GetModuleByName("MyFirstModule")
+	dm, err := b.GetDomainModel(mod.ID)
+	if err != nil {
+		t.Fatalf("GetDomainModel: %v", err)
+	}
+	parent := &domainmodel.Entity{Name: "ZzPlainA", Persistable: true}
+	child := &domainmodel.Entity{Name: "ZzPlainB", Persistable: true}
+	_ = b.CreateEntity(dm.ID, parent)
+	_ = b.CreateEntity(dm.ID, child)
+	if err := b.CreateAssociation(dm.ID, &domainmodel.Association{
+		Name: "ZzPlainB_ZzPlainA", ParentID: child.ID, ChildID: parent.ID,
+		Type: "Reference", Owner: "Default",
+	}); err != nil {
+		t.Fatalf("CreateAssociation: %v", err)
+	}
+
+	dm2, _ := b.GetDomainModel(mod.ID)
+	for _, a := range dm2.Associations {
+		if a.Name != "ZzPlainB_ZzPlainA" {
+			continue
+		}
+		if a.Source != "" || a.RemoteParentNavigationProperty != "" {
+			t.Errorf("a plain association was stamped as external: Source=%q nav=%q",
+				a.Source, a.RemoteParentNavigationProperty)
+		}
+		return
+	}
+	t.Fatal("plain association not found after reload")
+}
diff --git a/mdl/backend/modelsdk/domainmodel.go b/mdl/backend/modelsdk/domainmodel.go
index 23260e7e7..c247975d4 100644
--- a/mdl/backend/modelsdk/domainmodel.go
+++ b/mdl/backend/modelsdk/domainmodel.go
@@ -472,6 +472,24 @@ func assocFromGen(a *genDm.Association) *domainmodel.Association {
 		out.ParentDeleteBehavior = &domainmodel.DeleteBehavior{Type: domainmodel.DeleteBehaviorType(db.ParentDeleteBehavior())}
 		out.ChildDeleteBehavior = &domainmodel.DeleteBehavior{Type: domainmodel.DeleteBehaviorType(db.ChildDeleteBehavior())}
 	}
+
+	// Read the external (OData) source back. RemoteParentNavigationProperty in
+	// particular is the only durable link from an association to the OData
+	// navigation property it was generated from, and CREATE EXTERNAL ENTITIES
+	// dedupes on it. Dropping it here meant a re-import could not recognise an
+	// association it had itself created once the name carried a numeric suffix
+	// (module-wide uniqueness turns a second `season` into `season_2`), so every
+	// re-run appended two more — unbounded, and invisible to `mx check`.
+	if src, ok := a.Source().(*genRest.ODataRemoteAssociationSource); ok && src != nil {
+		out.Source = "Rest$ODataRemoteAssociationSource"
+		out.Navigability2 = src.Navigability2()
+		out.RemoteParentNavigationProperty = src.RemoteParentNavigationProperty()
+		out.RemoteChildNavigationProperty = src.RemoteChildNavigationProperty()
+		out.CreatableFromParent = src.CreatableFromParent()
+		out.CreatableFromChild = src.CreatableFromChild()
+		out.UpdatableFromParent = src.UpdatableFromParent()
+		out.UpdatableFromChild = src.UpdatableFromChild()
+	}
 	return out
 }
 
diff --git a/mdl/executor/cmd_contract.go b/mdl/executor/cmd_contract.go
index f733c63d1..d66fc3dde 100644
--- a/mdl/executor/cmd_contract.go
+++ b/mdl/executor/cmd_contract.go
@@ -1007,20 +1007,7 @@ func createNavigationAssociations(
 	// nav-property key relies on RemoteParentNavigationProperty, which the
 	// legacy read preserves; the modelsdk read does not, so the natural
 	// association name (== nav-property name) is the fallback skip signal.
-	existingAssocs := make(map[assocKey]bool)
-	existingNav := make(map[assocKey]bool)
-	for _, a := range dm.Associations {
-		// Find parent entity name for this association
-		for _, ent := range dm.Entities {
-			if ent.ID == a.ParentID {
-				existingAssocs[assocKey{ent.Name, a.Name}] = true
-				if a.RemoteParentNavigationProperty != "" {
-					existingNav[assocKey{ent.Name, a.RemoteParentNavigationProperty}] = true
-				}
-				break
-			}
-		}
-	}
+	existingAssocs, existingNav := indexExistingAssociations(dm)
 
 	count := 0
 	for _, schema := range doc.Schemas {
@@ -1134,6 +1121,41 @@ func createNavigationAssociations(
 	return count
 }
 
+// indexExistingAssociations builds the two lookup tables the re-import dedup
+// needs, both keyed by (parent entity name, name):
+//
+//   - byName — the association's own name.
+//   - byNav  — the OData navigation property it was generated from.
+//
+// byNav is the one that matters, and it is not a convenience. Association names
+// are unique per MODULE, so the second entity with a `season` nav property gets
+// `season_2`. Such an association can never match itself by name, so without
+// byNav a re-import recreates it — computing a fresh suffix each time, two more
+// per run, unbounded and invisible to `mx check` (mxcli-formula1 §50).
+//
+// byNav is only populated for associations that carry
+// RemoteParentNavigationProperty, which is why the modelsdk reader must read the
+// OData source back; dropping it there silently reduced this to the name match.
+func indexExistingAssociations(dm *domainmodel.DomainModel) (byName, byNav map[assocKey]bool) {
+	byName = make(map[assocKey]bool)
+	byNav = make(map[assocKey]bool)
+	parentName := make(map[model.ID]string, len(dm.Entities))
+	for _, ent := range dm.Entities {
+		parentName[ent.ID] = ent.Name
+	}
+	for _, a := range dm.Associations {
+		p, ok := parentName[a.ParentID]
+		if !ok {
+			continue
+		}
+		byName[assocKey{p, a.Name}] = true
+		if a.RemoteParentNavigationProperty != "" {
+			byNav[assocKey{p, a.RemoteParentNavigationProperty}] = true
+		}
+	}
+	return byName, byNav
+}
+
 // uniqueAssocName returns a Mendix-safe association name for an OData nav
 // property. If the requested name collides with an existing entity name OR an
 // already-created association name, append a numeric suffix.
diff --git a/mdl/executor/cmd_contract_reimport_test.go b/mdl/executor/cmd_contract_reimport_test.go
new file mode 100644
index 000000000..160078a2b
--- /dev/null
+++ b/mdl/executor/cmd_contract_reimport_test.go
@@ -0,0 +1,109 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package executor
+
+import (
+	"testing"
+
+	"github.com/mendixlabs/mxcli/model"
+	"github.com/mendixlabs/mxcli/sdk/domainmodel"
+)
+
+// f1CachedModel mirrors the shape that made the bug unbounded: three entities
+// each with a `season` navigation property. Association names are unique per
+// module, so only the first can be called `season`; the others carry a numeric
+// suffix and no longer match the nav property they came from.
+func f1CachedModel() *domainmodel.DomainModel {
+	races := &domainmodel.Entity{Name: "Races"}
+	races.ID = model.ID("e-races")
+	ds := &domainmodel.Entity{Name: "DriverStandings"}
+	ds.ID = model.ID("e-ds")
+	cs := &domainmodel.Entity{Name: "ConstructorStandings"}
+	cs.ID = model.ID("e-cs")
+	season := &domainmodel.Entity{Name: "Seasons"}
+	season.ID = model.ID("e-season")
+
+	mk := func(id, name string, parent model.ID, nav string) *domainmodel.Association {
+		a := &domainmodel.Association{
+			Name: name, ParentID: parent, ChildID: season.ID,
+			RemoteParentNavigationProperty: nav,
+		}
+		a.ID = model.ID(id)
+		return a
+	}
+
+	return &domainmodel.DomainModel{
+		Entities: []*domainmodel.Entity{races, ds, cs, season},
+		Associations: []*domainmodel.Association{
+			mk("a1", "season", races.ID, "season"),
+			mk("a2", "season_2", ds.ID, "season"),
+			mk("a3", "season_3", cs.ID, "season"),
+		},
+	}
+}
+
+// The dedup must recognise a suffixed association as the nav property it was
+// generated from. Matching on the association name alone cannot: `season_2` is
+// not `season`, so a re-import recreates it as `season_4`, then `season_6`, for
+// ever (mxcli-formula1 §50 — one project reached season_15).
+func TestIndexExistingAssociations_SuffixedAssociationMatchesItsNavProperty(t *testing.T) {
+	byName, byNav := indexExistingAssociations(f1CachedModel())
+
+	// This is the lookup the import performs, for each parent that has a
+	// `season` nav property. All three must be recognised as already imported.
+	for _, parent := range []string{"Races", "DriverStandings", "ConstructorStandings"} {
+		k := assocKey{parent, "season"}
+		if !byNav[k] && !byName[k] {
+			t.Errorf("%s.season is not recognised as already imported — a re-import "+
+				"will create a duplicate with a fresh suffix", parent)
+		}
+	}
+
+	// Specifically: the two suffixed ones are matched via the nav index, not the
+	// name index. If that ever inverts, the name match is doing work it cannot
+	// actually do and the guard above would pass for the wrong reason.
+	for _, parent := range []string{"DriverStandings", "ConstructorStandings"} {
+		if byName[assocKey{parent, "season"}] {
+			t.Errorf("%s: name index unexpectedly holds the unsuffixed name", parent)
+		}
+		if !byNav[assocKey{parent, "season"}] {
+			t.Errorf("%s: nav index missing — this is the entry that prevents the duplicate", parent)
+		}
+	}
+}
+
+// Legacy data (and Studio Pro-authored associations) may carry no nav property.
+// The name index must still cover the unsuffixed case, so those do not duplicate
+// either.
+func TestIndexExistingAssociations_FallsBackToNameWhenNavAbsent(t *testing.T) {
+	dm := f1CachedModel()
+	for _, a := range dm.Associations {
+		a.RemoteParentNavigationProperty = ""
+	}
+	byName, byNav := indexExistingAssociations(dm)
+
+	if len(byNav) != 0 {
+		t.Errorf("nav index should be empty when no association carries a nav property: %v", byNav)
+	}
+	if !byName[assocKey{"Races", "season"}] {
+		t.Error("the unsuffixed association is not matched by name either")
+	}
+}
+
+// An association whose parent is not in this domain model (a cross-module
+// association) must not index under an empty parent name, which would collide
+// with every other orphan and could suppress a legitimate import.
+func TestIndexExistingAssociations_SkipsAssociationsWithUnknownParent(t *testing.T) {
+	dm := f1CachedModel()
+	orphan := &domainmodel.Association{
+		Name: "elsewhere", ParentID: model.ID("not-in-this-module"),
+		RemoteParentNavigationProperty: "elsewhere",
+	}
+	orphan.ID = model.ID("a9")
+	dm.Associations = append(dm.Associations, orphan)
+
+	byName, byNav := indexExistingAssociations(dm)
+	if byName[assocKey{"", "elsewhere"}] || byNav[assocKey{"", "elsewhere"}] {
+		t.Error("an association with an unresolvable parent was indexed under the empty name")
+	}
+}