new(skill): rest-between-mendix-apps — contract, consumer honesty, cross-app test ladder

[MendixMau]

What

A new skill, skills/rest-between-mendix-apps.md, for two or more Mendix apps you build yourself that read each other over REST (app-to-app, microservices).

The existing rest-integration-first-time-right.md covers the single-app mechanics (JSON structure, import mapping, the all range flag, a REST-fed DataGrid). This one covers what sits between apps, so it is a sibling rather than an extension. The two files link to each other.

Sections

1. Before the first script: write the contract down. A decision table: pull vs push, versioned path, record key + version rule, cursor paging, since with overlap, X-Correlation-Id, error shape (including the runtime's 560 that arrives before your microflow runs), auth, a fixed port per app, one owner per fact, and dates kept as String on the wire. Rationales that are not backed by a recorded failure are marked (design choice). Secrets are constants with no value in the model.
2. Building it. 17 rules:
   • Publisher: auth inside the operation microflow (as of mxcli v0.24, BUG-152); '' vs empty; 422 vs 560; every payload change bumps both version and updatedAt.
   • Consumer: an endpoint row; non-2xx handled without rollback; LastError = '' vs empty; "as of" plus stale and "never read" states; status cards fed by the real call path, not a probe; an ordering guard; prune only after a complete read; a full-read button; retry for checks that run once; never invent the owner's fact; size columns from the real feed.
3. The test ladder, cheapest first: publisher contract tests (mxcli test), consumer logic tests, a fixture server per upstream with modes, a mock-vs-live contract diff, a curl status matrix, a cross-app consistency check (recommendation; the apps had none), cross-app journeys. Cadence per change, per slice and per release, and how to keep it cheap: one mxcli test --local at a time on the machine (ports 8081/8091), --attach counted as a model write; exec.sh locks per project since feat(exec): per-project exec lock, --commit-first, watch-compat verdict, scoped app restart, scratch mxcli test #304, never stop a test run with a signal (BUG-157), @cleanup, fixture resets, SKIPPED instead of passed, one hostname per app.
4. Definition of done for one API.
5. What the evidence says about the ladder: a short summary. The 26-row failure register itself now lives in process/rest-between-mendix-apps-register-2026-10.md.

Evidence

Three demo apps built with mxcli v0.24–v0.26 on Mendix 11.15 between 2026-10-07 and 2026-10-12: nine published APIs and five consumer directions. 22 register rows cite a FINDINGS line, 4 a proof document or the UX scan. Domain names, record ids and hostnames are replaced by generic placeholders (order/stock/customer apps, ORD-0001/ITEM-B/WH-A, localhost ports). No new instrument; field evidence for the skill text is the three apps above.

Routing

One row in bin/lib/skill-routing.tsv: ondemand, build/integration, roles architect, mdl, test and review, stages 3–6, trigger front-loaded on "App-to-app REST or microservices". bin/render-routing.sh --check and bin/check-skill-routing.sh pass; baseline 75,225 words (unchanged, budget 80,000).

Review

Independent review returned MERGE-AFTER-FIX. Addressed in e0ecd0b (after merging origin/master in 8da715d; the bin/gate-check.sh stage-map conflict was resolved by taking master and re-rendering):

1. CHANGELOG line added under ## Unreleased.
2. The StackOverflowError rule now cites BUG-157 and its mechanism (a signal-stopped test run leaves after-startup on the injected MxTest flow, and the next injection chains it to itself). The advice to run test --attach in parallel is gone: --attach is a model write (testing-shape.md).
3. Auth is pinned to "as of mxcli v0.24" (BUG-152), with a note that Studio Pro can set the published service's own authentication and that auth done only in the microflow leaves the endpoint anonymous at runtime.
4. The testing-shape.md citation no longer claims @cleanup content (it now cites the test ports and --attach).
5. The evidence claim is narrowed to §2 rules and §3 results. In §1, correlation id, error shape, push needing all three (now named: an outbox, a retry queue and an inbound write endpoint) and cursor encoding are marked (design choice). The 401-stops / 5xx-continues rule is marked (recommendation). The rung-1 cost reads as two measured runs, with the wall time attributed to injection and build.
6. Routing row trigger: "App-to-app REST or microservices".
7. The §5 register moved to process/ (skill rule 6). A five-line summary stays in the skill.
8. Domain wording is generic now: supplier, change notices, service bulletins, fleet and part numbers are replaced by order/stock/customer examples.

Skill size (on-demand): 3,593 → 3,090 words. Checks: check-scripts, check-portability, leak guard, check-no-private-citations, check-pr-discipline, render-routing --check and check-skill-routing are all clean. Fixtures: test-render-routing 5/5, test-routing-tier 12/12, test-baseline-pack 16/16.

Update 2026-10-16

• Stale rule fixed: the skill said exec.sh refuses while another project writes. Since feat(exec): per-project exec lock, --commit-first, watch-compat verdict, scoped app restart, scratch mxcli test #304 exec.sh locks per project, so the rule now says another app's exec.sh no longer blocks yours, a raw mxcli exec takes no lock, and --attach still counts as a model write. Register row 24 is annotated as fixed by feat(exec): per-project exec lock, --commit-first, watch-compat verdict, scoped app restart, scratch mxcli test #304.
• Merged origin/master (1ed7c99), resolved the CHANGELOG (kept both sides) and took bin/gate-check.sh and agents/test-agent.md from master before re-rendering routing.
• Name check: bin/check-no-client-data.sh with the real denylist is clean on the head; the added text uses only generic order/stock/customer examples.

Impact

Row	Answer
Process	None. One on-demand skill and a register under process/; no gate, no new human step, nothing new blocks.
Dependencies	bin/lib/skill-routing.tsv and its re-render (README.md, ROUTING.md, agent stubs architect/mdl/review/test, bin/gate-check.sh stage map), skills/rest-integration-first-time-right.md (cross-link). Merges clean onto master 1ed7c99. Reads no artifact (prose; cites BUG-152, BUG-157, testing-shape.md).
Context cost	Unchanged. bin/render-routing.sh --check on master (d1cbd41) and on this head: baseline 75,225 → 75,225 words (budget 80,000); Stage 5 lead 26,443 → 26,443, mdl 30,965 → 30,965, review 31,435 → 31,435; Stage 3 architect 24,779 → 24,779. On-demand skill, 0 here.
Behaviour	NOT RUN: on-demand row only (one generated routing row in four agent stubs, Context cost 0). The skill is situational text; its evidence is the register of real failures.
Runtime	n/a: stage-map data only in gate-check.

🤖 Generated with Claude Code