Monedula
monedula-sim-link docs menu

Self-validation before printing

Why monedula-sim-link refuses to print a link it cannot prove safe: the lossless round-trip check, the 2048-character limit and the compressed form.

Concepts 3 of 3

2 min read

Updated 5 October 2026

Markdown

On this page

The playground’s decoder drops malformed entries silently, so a subtly wrong link opens a session that looks fine and shows something other than your cluster. connect, demo and the MCP tools refuse to print a link that fails the checks below.

The two checks

  1. The action log must round-trip. The tool encodes the action log, decodes the result and encodes it again, and the two encodings must be identical. This check is never overridable: a link that would lose an action never ships.
  2. The link must be at most 2048 characters. Browsers and chat clients truncate longer links, and a truncated actions parameter loses actions without any error. --force downgrades this check to a warning, for the case where you accept the risk.

When the second check fails, the message gives the length and the way out: lower --max-records-per-partition, narrow the topic selection, or pass --force. Handle large clusters shows the first two.

The tool keeps the action log in its plain, human-readable form while it is under the 1500-character compression threshold. Past that, the log is emitted in the compressed form, which starts with ~1. A compressed link passes the checks like a plain one.

The playground writes compressed links in a different ~1 layout from the tool’s, and decodes both. The tool decodes both as well, so validate_actions reads a link that the playground made.

The MCP tools

The MCP tools validate every action field one by one, check config_change paths against the whitelist of the playground URL format, and enforce the action cap and the free-play size limits. They return no link unless its actions value decodes back to the identical list, and they return that decoded list next to the link, in decodedActions, so the caller can compare it with its input. A validation error names the offending field, separator or config path, so a calling agent can fix its input.