Skip to main content

Stability — what will not break

1.0 is not the completion of features. It is the fixing of the surfaces promised not to break.

Three version lines​

There are three versions, counted independently. Mixing them makes it impossible to say which promise was broken.

VersionWhat it attaches toCurrently
The muro versionthe language, its semantics and the rules of composition. "A file written this way keeps meaning this"1.0
The koyu versionthe implementation. "This implementation's surfaces will not break." It declares which muro it implements0.16.0
The canonical JSON format versionthe spelling. The set of keys, their order, collation, normalisation, number notationkoyu-canonical/1.0

A .muro file declares only the language version. It announces semantics, not the maturity of a processor.

koyu 1.0

A separate format version is needed because the same semantics can be respelled with different keys. Adding the a key, which preserves the written direction of a boundary, changed the spelling without changing one word of the language. The converse also happens: a language version can rise without the spelling moving.

The two lines need not arrive together​

As things stand, muro has reached 1.0 and koyu is still 0.x.

That is not a lag; it is what having two promises means. muro 1.0 says "what could be read at this version stays readable with the same meaning"; koyu 1.0 would say "this implementation's surfaces will not break". The language is settled and the implementation has promised no freeze at all — the first can settle first, and it did.

Outside viewers carry their own versions and declare which muro they follow. The validation face has no version and grows by addition.

What "meaning-preserving" means​

Whether a change raises the language version depends on whether it is meaning-preserving. The word has a fixed meaning here.

Meaning-preserving means the derived artefacts — canonical JSON, the graph, the tallies, the SVG — are unchanged. It does not cover the number of diagnostics.

So adding a check never moves the language version. If the derived artefacts of an unambiguous source do not change by a single byte, the change is inside the definition. Conversely, a change that makes the same text mean a different building always raises the version.

An older declared version is accepted only where the meaning is preserved. Combinations where the same text would mean a different building are stopped as errors by VER01–04, which offer two ways out: write the meaning explicitly, or raise the version.

The eight surfaces that freeze​

SurfaceWhat is promised
The grammar and semantics of muro 1.0what could be read at this version stays readable with the same meaning
The rules of compositionlayer strength order, resolution of single values, editing of sets, provenance. The same input always gives the same result
Identitysame uid, same thing. The rules for paths and names
The three attribute tiers and namespacesincluding the promise that the carried tier is not read
The machine formatit announces its format version. The same input gives the same bytes — collation and normalisation are fixed. It holds the result of composition and holds no shape
The derivation ruleswritten out, with a reference implementation offered as API
Structural diagnosticscodes and severities. The meaning of green matches the definition of scope
The public API and the CLIparse, compose, canonicalise, question, derive. Commands (14 of them), arguments, exit codes

One point about diagnostics deserves emphasis. Severity is an immutable property of a code. The same code is never an error in one case and a warning in another. To change the weight, a new code is cut and the old spelling is retired.

What does not freeze​

These may exist; it is explicit that they are outside the freeze.

  • Shape generation and drawing — svgPlan, svgAxo, the CLI plan and axo, the MCP plan_svg. The CLI surface (subcommand names, arguments, exit codes) freezes; the contents of the SVG do not
  • Architectural judgement — the fifteen rules and the output of koyu validate. This face grows
  • The MCP toolset (12 tools) — treated as a face that grows by addition
  • Round-tripping with and importing external formats
  • Surfaces for people — editor support, authoring
  • The meaning of carried-tier attributes

What must not change is the Form, not the SVG​

Drawing only draws Form. So the look of the SVG may change at any time. Colour, line weight, line style, drafting conventions for symbols, page margins — none of that is on a frozen surface.

What freezes is Form — coordinates, thickness, z ranges, direction, subject identity, plan classification. Two Forms out of one composition is a defect; two SVGs out of one Form is not.

That drawing only draws is machine-enforced. Tests check that the drawing side pulls in none of the parts that assemble shape, that no derivation constant is spelled inside the drawing code, and that the black bands in a plan are exactly the "cut intervals" of Form.

Neighbouring pages​